Safeguarding the past, present and future of RISC OS for everyone

WindowManager Applications And Documents (changes)

Showing changes from revision #6 to #7: Added | ~~Removed~~ | ~~Chan~~ged

» Applications and Documents

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

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 Icon Bar page.

Application icons should always respond to the menu mouse button by opening a menu.

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 event code, as this gives the application an opportunity to ‘respond’ to the application quitting or even the computer shutting down.

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 event code. Applications wishing to load the file should respond with Message_DataLoadAck.

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.

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?~~Close_Window_Request event code. Applications should respond to this event code within their 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.

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_GetPointer?~~Wimp_GetPointerInfo directly after it responds to the ~~Close_Window?~~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.

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

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 for details.

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_Send_Message?~~Wimp_SendMessage that the application should respond to within its Wimp_Poll routine.

Search the Wiki

Social

and

ROOL Store

Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.

Donate! Why?

Help ROOL make things happen – please consider donating!

RISC OS IPR

RISC OS is an Open Source operating system owned by RISC OS Developments Ltd and licensed primarily under the Apache 2.0 license.