WindowManager Application Resource Files (changes)

» WindowManagerPart 7 - The Desktop?

» The Technical Window Details Manager

» Application FilesTechnical Details

Overview

RISC OS stores applications in a manner different from that of most other operating systems. Instead of having application files and resource files spread across multiple folders, all application related files are stored within the application’s own ‘folder’. This is called the ‘Application Directory’. All information relating to how an application functions is stored within the application directory.

Applications are readily identified by their ‘!’ suffix; often pronounced as a ‘Pling’. e.g !Edit, !Draw, !Boot.

Applications are loaded by double-clicking the application’s icon, but double-clicking with the shift key depressed opens the application directory, thereby showing all the files that make up the application.

Applications are made up of several special files; the following table describes them.

The names !Boot, !Run, !Sprites and !Help are fixed. The other names are merely traditional, and can be whatever the user chooses.

!Boot File

!Boot files are automatically executed by the Wimp when the application is initially seen by the Filer.

An example of a !Boot file for a typical application called !Foo is shown below.

Set Foo$Dir <Obey$Dir>
IconSprites <Foo$Dir>.!Sprites
Set Alias$RunType_f00 Run <Foo$Dir>.!Run %%*0
Set File$Type_f00 FOO
…

This example code sets a system variable, in line 1, holding the application directory’s pathname and loads the sprite file into the system spritearea in line 2. In line 3 it defines the run-action for a file of type &f00: that its pathname is passed as a command-line argument to the application. In line 4 the textual designation for filetype &f00 is defined.

The setting of the run-action for FOO files, in line 3, will have the effect that when a file of type FOO is double-clicked, if no running task responds to the Wimp’s message that a file of this type has been double-clicked, then the file will be passed to a new invocation of the application.

Annotations

fn1. The Wimp will add a suffix to the sprite file depending on the screen mode in use at the time.

!Run File

The !Run file is executed when the user double-clicks the application’s icon, or when a command to run the application is executed. The !Run file should ensure that the resources which the application needs are available before issuing the command to start it running.

An example of the !Run file for our mythical Foo application is shown below.

| Has the application been booted yet?
If "<Foo$Dir>" = "" then run <Obey$Dir>.!Boot

| Now we can use Foo$Dir safely. 
| If no commandline arguments display help.
if "%*0" = "" then filer_run <Foo$Dir>.!Help

| Required versions of modules to load application
RMEnsure FPEmulator 4.03 RMLoad System:Modules.FPEmulator
RMEnsure FPEmulator 4.03 Error You need FPEmulator 4.03 or Later

| Memory Management
WimpSlot –min 256K –max 512K

| Run the application code
Run <Foo$Dir>.!RunImage %*0

The !Boot file copied the value of Obey$Dir into Foo$Dir. Other Obey files could change the setting of Obey$Dir so it is safer to make a copy and use that instead. This new reference to the application’s path can then be safely used within the application itself.

In the !Run file the application checks to see if it has been booted, and boots itself if it has not. Then it checks to see if any arguments have been passed to it. In this case it displays its Help service if none have.

The application then checks that any required modules are present and loaded by using *RMEnsure. The first use of RMEnsure checks to see if the right version of the module is loaded, and loads it if not. The second issues an error message if it is still not loaded. Some applications which need to ensure the presence of many modules use a dedicated Obey file !Modules to deal with this, which is called from the !Run file.

The Application then tries to assign a dedicated amount of memory for the application using *WimpSlot. More memory can always be set aside if required by the application if required.

Finally, it then tries to execute the !!RunImage file. Only one % sign is required this time, and there must be no CR/LF after this line, else the file will remain open until the application is quit.

Notes:

• *WimpSlot must be called after loading modules. This is because loading modules requires memory too, so should be loaded first.

• If shared system resources are required, then the application should check the System$Path is defined and produce an error if it is not. e.g.

*If "<System$Path>" = "" Then Error 0 System resources is not found

!RunImage File

This file is conventionally used to store the main code of the application. The !Run file calls this file after it has checked that the system can load the application successfully.

The date stamp on this file is also used as the date stamp of the application, if the Filer is displaying in ‘Full Info’ mode.

!Sprites File

This file is used to store several important sprites used by the application. In actual use, the Wimp may use a different file depending on the screen mode in use. See Icon Sets for more details.

The Wimp can assign a different sprite to any type of file type. Many common file types have already pre-assigned sprites. If an application handles a file type that is not already handled natively by RISC OS, then it should specify a sprite that represents that particular file type.

The following sprites should be available within the relevant !Sprites file.

!Choices File

Applications that allow for the Applications settings to be changed by the user used to store the settings in the !Choices file. The data format used to store the settings can range from a simple text file to a proprietary data format. Because this makes it easy for the settings to be overwritten when the application is updated, nowadays settings are kept separately in !Boot.Choices.Foo.

!Help File

The !Help file is typically text file (filetype &FFF), or an HTML file (filetype &FAF)that is used to convey the purpose of the application and any other important information. In principle any displayable document type could be used. Alternatively it is an Obey file that checks which document types are available and issues appropriate commands for displaying the information.

If the !Help file is present it will appear as a sub-menu option, if the user clicks the Menu button over the applications icon within the filer window.

!Messages File

This is a file that is often used to store text to be used by an application. i.e. windows, dialog boxes and menus. This enables a developer to quickly customize the application for different languages by supplying different message files for each language supported.

Resource files, such as message files should be loaded from removable storage at the same time as the application. This ensures that the application does not have to request access later when the path may no longer be accessible. e.g. application was loaded from a CD, that is no longer present.

Template Files

Template files are used to store window definitions that the application can load and display. For a full description please see Template Files.

See also

• *RMEnsure
• *WimpSlot
• Icon Sets
• Template Files

RISC OS has many guidelines on the appropriate use of resource files. For a complete detailed guide on resource files, please see the RISC OS Style Guide.