[[!redirects The Window Manager Applications And Documents]] h6. [[WindowManager]] h6(. » [[WindowManager Technical Details|Technical Details]] h6((. » Applications and Documents h2(#overview). Overview In addition to loading, editing and saving documents, applications must also know how to load and quit themselves. This page details how they should load and quit and successfully integrate document handling. The term 'Document' is used in this part to denote files that an application can handle; e.g. text file for a text editor h2(#loading_an_application). Loading an Application There are two standard ways for an application to be loaded by a user. |_<^. # |_<^. Methods | |<^. 1 |<^. Double-click on the application's icon within a filer window. Upon loading, the application icon should be displayed on the icon bar, and *no* application windows should be displayed. | |<^. 2 |<^. Double-click an appropriate document icon using either the Select or Adjust mouse buttons. Upon loading, the application icon should appear on the icon bar, and a window should appear with the file contents being displayed. | Icons that appear on the icon bar should have a width and height of 68 OS units square. More information on this topic is available in the [[The Window Manager The Icon Bar|Icon Bar]] page. Application icons should always respond to the menu mouse button by opening a menu. h2(#quitting_an_application). Quitting an Application Applications must have a ‘Quit’ option available on the icon bar menu. To adhere to RISC OS guidelines, it should also be the last menu item. Applications should also respond to the [[Message_PreQuit|Message_PreQuit]] event code, as this gives the application an opportunity to ‘respond’ to the application quitting or even the computer shutting down. h2(#loading_documents). Loading Documents There are two standard ways for a document to be loaded by an application. |_<^. # |_<^. Methods of Loading a File | |<^. 1 |<^. Double-click an appropriate document icon using either the Select or Adjust mouse buttons. Upon loading, the application icon should appear on the Icon bar, and a window should open to display the document. | |<^. 2 |<^. Drag a document from a filer window onto the application’s icon that is displayed on the Icon bar. This assumes that the application has been already been loaded. | When a document icon has been double-clicked, the Wimp issues a [[Message_DataOpen|Message_DataOpen]] event code. Applications wishing to load the file should respond with [[Message_DataLoadAck|Message_DataLoadAck]]. h2(#saving_documents). Saving Documents RISC OS manages the saving of documents in a different way from that of many other Operating Systems. Instead of the more traditional ‘Save As’ Dialog box where the user has to choose where to save the document, RISC OS uses a ‘Save As’ window consisting of an icon representing the document and a writeable text box. Three methods of saving a file are available to the user. |_<^. # |_<^. Methods of Saving a File | |<^. 1 |<^. Entering appropriate file name, then dragging the document icon to any filer window. | |<^. 2 |<^. Clicking the OK button if the file has already been saved. | |<^. 3 |<^. Using hot keys or function keys to display the ‘Save As’ window. | *Note:* All file related actions should be available as a sub-menu within the ‘File’ menu option. For more details on how to open and close menus, please see [[Wimp_CreateMenu|Wimp_CreateMenu]]. h2(#closing_documents). Closing Documents The most common method of a user requesting to close a document is by clicking on the window's close icon with the Select mouse button. Upon any close icon being clicked, the Wimp issues a [[Close_Window_Request]] event code. Applications should respond to this event code within their [[Wimp_Poll|Wimp_Poll]] routine. If the document has been changed since it was last saved then it should open a window asking if the document should be saved or discarded. An application should cater for the following scenarios. |_<^. # |_<^. Response |_<^. Action | |<^. 1 |<^. Yes |<^. Open ‘Save As’ window, and if the document is saved then close the documents window. | |<^. 2 |<^. No |<^. Close the documents window. | |<^. 3 |<^. Cancelled. |<^. Do nothing. | Depending on the mouse button used when clicking on the close icon, two different outcomes are possible. h4. Mouse Button Differences |<^. Select |<^. As above. | |<^. Adjust |<^. As above, but should open the document filer window if not already on the screen after closing the documents window. | To determine which mouse button was used when clicking the close icon, the application should call [[Wimp_GetPointerInfo]] directly after it responds to the [[Close_Window_Request]] event code. To obtain the document's path name, applications should remove the leafname from the document’s file name. An application can open a filer window using [[Message_FilerOpenDir|Message_FilerOpenDir]]. h2(#creating_documents). Creating Documents Documents created by being loaded, or by an application itself, should be displayed to the user in a consistent manner. The guidelines are: |_<^. Guideline |_<^. Description | |<^. Initial window |<^. Should be both vertically and horizontally centred on the screen. | |<^. Subsequent window |<^. Should be horizontally centred on the screen, but 48 OS units under the previous window, unless the bottom of the window would overlap the icon bar. | |<^. Overlapped Icon bar |<^. Windows that would overlap the icon bar, should be displayed at the same horizontal and vertical co-ordinates as the initial window. All subsequent windows would then be displayed as above. | The size of window when opened should follow the guidelines below: |_<^. Attribute |_<^. Maximum Size | |<^. Width |<^. 700 OS units | |<^. Height |<^. 500 OS units | h2(#editing_documents). Editing Documents Applications should know whether a document has been changed since it was last saved. This is often referred to as the update flag. A document that has been edited since it was loaded should have an asterisk appended to the end of the windows Title text. You do not need to update the entire window to update a window title bar. See [[Wimp_ForceRedraw|Wimp_ForceRedraw]] for details. h2(#inserting_documents). Inserting Documents The Wimp also allows for a document to be inserted into an existing document by dragging a document’s icon from within a filer window into an already open document window. It is the applications responsibility to handle this task. The Wimp issues a [[Wimp_SendMessage]] that the application should respond to within its [[Wimp_Poll|Wimp_Poll]] routine. h4. See also * [[Wimp_CreateMenu|Wimp_CreateMenu]] * [[Wimp_Poll|Wimp_Poll]] * [[Close_Window_Request]] * [[Wimp_GetPointerInfo]] * [[Wimp_ForceRedraw|Wimp_ForceRedraw]] * [[Wimp_SendMessage]] * [[Message_PreQuit|Message_PreQuit]] * [[Message_DataOpen|Message_DataOpen]] * [[Message_DataLoadAck|Message_DataLoadAck]] * [[Message_FilerOpenDir|Message_FilerOpenDir]] * [[The Window Manager The Icon Bar|Icon Bar]] RISC OS has many guidelines on Application and documents. For a complete detailed guide on dialog boxes, please see the RISC OS [[Style Guide|Style Guide]]. [linkStyle]Style+Guide