Creating RISC OS Application Directories

Lee Calcraft looks into RISC OS Application Directories and the powerful new Obey files.

In RISC OS the whole Desktop concept has been revamped, and one of the new features to emerge as a result is the Application Directory. This is simply a directory in which all resource files for a given application are held, including boot files, sprites, and the application itself. But an application directory is no ordinary directory, it is a runnable object. Running an application directory by double-clicking on its icon will normally start up the application, or in certain cases, install its icon on the icon bar. Fortunately it is a relatively simple matter to set up applications directories.

First of all you need to create a suitable directory. Any name will do providing that its first character is "!". When you have done this, the directory display will register an "A" icon alongside the new name, indicating that it is of type "Application". The new directory will need to contain at least three files:


A file named !Run
A file usually named !RunImage
A sprite file named !Sprites

I will deal with the sprite file first. This should contain one or more icon sprites, and the name of one of these must be exactly the same as that used for the application directory. For example, if the directory name is !QUIZ, the corresponding sprite file (called !Sprites) should contain a sprite called !Quiz (as with all file and sprite names, case is ignored). This sprite is displayed by the Desktop together with the name of the application, whenever the parent directory of the application is opened.

A second sprite may be included for use with the small Desktop icon display. Its name must be the same as that of the main sprite, but preceded by the letters "sp" (e.g. Sp!quiz). Sprites for data files associated with the application may also be included in this file, but this is beyond the scope of the present article.

The easiest way to produce suitable sprites is to use ArcPaint. Icon sprites should normally be a maximum of 68x68 graphics units in size, and should conform to the standard Desktop palette. As a temporary measure, you could borrow one of those supplied on the RISC OS Applications discs. Just drag the appropriate sprite file into your new directory. If you need to change its name to match your new directory name, then proceed as follows:
*SNEW
*SLOAD !Sprite
*SRENAME !Puzzle !Quiz
*SSAVE !Sprite

In the above example we have changed the name of the sprite used for the application !PUZZLE to one suitable for a directory called !QUIZ. Now when you next look at the directory containing your application directory, the new user-defined (or user-borrowed) icon will appear.

OBEY FILES

Now for the !Run file. This will normally be a file of a new type called Obey (type &FEB). Obey files resemble Exec files in that they contain executable commands, and may be used to start up an application, just like !Boot files. But they have a number of advantages over Exec files. Firstly, the text which they contain is sent directly to the operating system, and does not rely on the current task sending keyboard input to the O.S. Obey files must therefore contain no Basic instructions, only commands acceptable to the operating system. Secondly the contents of Obey files are not echoed to the screen unless the command Echo is issued. And thirdly, Obey files remain in 'obeyance' when an application is running, and then take over once the application ends. This can be useful in different ways. For example, it could be used to make back-ups of data files after the user has terminated an application.

To test this property, use ArcEdit or another text editor to create a text file of type FEB containing the following:
Quit
Basic
Echo Why must you leave so soon?

If you *RUN this file, Basic will be started up, and you can then run any programs that you wish, and providing that you do not issue a *Close, or Close #0, the Obey file will remain active. At the point that you finally quit Basic, the Obey file will continue, and will display the message before closing. This will work just as well with a single Basic program, providing that it is *RUN. Thus:
QUIT
MyProg
Desktop

would run the Basic program MyProg, and as soon as the program ends (whether naturally, or by pressing Escape), the Desktop will be called.

An application must be able to work properly even if it has been transferred to a new parent directory (as it might be if it had been transferred to a network or to a hard disc). And one important use for the Obey file !Run in any application directory is to record the full path for the given application. The Filer automatically sets the variable Obey$Dir as soon as an Obey file is run, and one of the first tasks of !Run should be to store this information in a suitable environment variable. For example:
Set MyProg$Dir <Obey$Dir>
This holds the path in the variable MyProg$Dir for subsequent use. One of the final acts in the !Run Obey file is to *Run the file !RunImage. This will usually be the application itself.

A !Run Obey file for an application might therefore contain the following lines:
Set MyProg$Dir <Obey$Dir>
Run <MyProg$Dir>.!RunImage %*0

Note the way in which the last line uses the convention %*0. If the application is ever run by issuing the command:
*<DirectoryName> <parameters>
this will ensure that any parameters accompanying this instruction are passed to the application (i.e. passed to !RunImage).

If you examine some of the !Run files on the RISC OS applications discs, you will see that many of them contain additional instructions for setting RunType aliases to ensure that running data files for the application cause the application to start up. Others use the new star commands *RMEnsure and *WimpSlot to check the presence of important modules, and to claim workspace for the application. We will take a closer look at these in a forthcoming issue.

!BOOT

We have not as yet covered the new role of the !Boot file. Any application directory may contain a !Boot file. Again this will typically be an Obey file. This file is automatically run when it is first seen by the Filer. That is to say when a directory is displayed containing the parent directory of the application. Contrast this with the !Run file, which is only run when an application is selected by the user.

If a !Boot file is present it must contain the instruction:
*IconSprites !Sprites
because if a !Boot file exists, the !Sprite file will not be automatically loaded. One further point: the !Boot file will only be automatically executed providing the icon sprite pool does not contain a sprite whose name suggests that the application is already known to the Filer (i.e. the sprite called !<application name>).

The best way to get to grips with application directories is to experiment with some of your own, and the best source of examples are the directories supplied on the RISC OS Applications discs. In the mean time, a complete application is supplied on this month's disc for your perusal.