Open any application directory and you will probably find a fairly similar set of files/folders. This screenshot is typical:
These files/directories hold various 'resources' needed to allow the application to operate as intended. Typically, some of the following files/directories will be present: !Run, !Boot, !RunImage, !Sprites, !Sprites22, Templates, Modules, Fonts, Messages, !Help, but there may be others instead or in addition.
The reason why most applications use the same sort of structure for these resources is that RISC OS has in-built management arrangements which offer considerable advantages to the programmer if the resources conform to recommended practices - and the Acorn Style Guide contains the details.
To give a practical example, if you double-click on an application icon, RISC OS will automatically look inside that application's directory for a file called !Run, and run it. So, the standard way to make an application start via the usual Wimp method is to include a !Run file and put the necessary instructions in it. Other items offer their own advantages, as described below:
When you open a directory window, RISC OS looks to see if there are any applications inside it (i.e. directories with names starting with "!") and, if so, looks inside their directories for an Obey file called !Boot, which it then runs.
Typical of the contents of an application's !Boot file are the lines:
Set TestApp$Dir <Obey$Dir> IconSprites <TestApp$Dir>.!Sprites
The first line creates a 'system variable' called TestApp$Dir, and stores in it the application's current full path (i.e. the full path of the directory which was double-clicked - not the full path of the !Boot file).
The second line tells the Wimp to add the sprites in the sprite file !Sprites to the common pool, so that they can thereafter be accessed by any application (but particularly the Filer) - until the computer is switched off anyway.
Further, if the sprite file contains a sprite whose name is exactly the same (but all in lower case) as the application's name, then the Wimp will automatically display that as the application's identifying sprite in the directory window that it has opened.
Another typical item in this file is an instruction to tell the Wimp that certain filetypes 'belong' to this application - so that, for instance, double-clicking on such a file will cause this application to be run and for the file to be loaded into it.
By running an application's !Boot file, the Wimp is said to be 'seeing' the application - because it now knows where the application resides (and its sprite, usually) and can find it again if need be.
Although all this action goes on behind the scenes, it can take time and this often explains why some computer start-up sequences which open the hard disc root directory, for example, can take several extra seconds.
An application !Boot file isn't mandatory. If it doesn't exist, the application will still have been 'seen' if its parent directory window is opened, but will instead appear in the window with the default application sprite supplied by RISC OS.
Set TestApp$Dir <Obey$Dir> IconSprites <TestApp$Dir>.!Sprites WimpSlot -min 128K -max 128K Run <Obey$Dir>.!RunImage
and there can be many more.
Note, first of all, that some lines in the !Boot file are usually repeated in the !Run file. This is in case the application is started before it has been 'seen', e.g. from the Command Line.
The third line tells the Wimp how much memory to allocate, and this value will be reflected in the application's entry in the Task Display. If this line isn't included, the Wimp will allocate a default amount of memory shown by the Next item in the Task Display. (The Next value can be changed by dragging its bar in this display, or by using a third parameter with a WimpSlot command - usually in the start-up !Boot application.)
The last line tells it to run the !RunImage file, i.e. run the program.
It is essential to have a !Run file if you want an application to start in the usual way, i.e. by double-clicking on its application icon.
If the application needs certain Modules (see 11.12 p59) in order to operate correctly, then the !Run file is the place where a check is made to see if they are present - before the !RunImage is actually run. As you may recall, the star command *RMEnsure is used for this.
RISC OS provides a large number of standard sprites in a central resource which any application is free to use, in particular the Filer, but if you want the Filer to use some other sprites, e.g. to display your application and any of its special files with unique pictures, then these application sprite files are the place to store them ready for use.
Why three files? This is simply so that you can have the opportunity to provide sprites which will be best suited to the screen display mode in use, i.e. low resolution, high resolution, high resolution B&W. So, you design a set of sprites for each case, then name each of the files as follows:
!Spriteslow resolution colour (e.g. mode 12) !Sprites22high resolution colour (e.g. mode 20) !Sprites23high resolution Black (e.g. mode 23)
With these sprite files in place, the star command
*IconSprites <full directory path>.!Sprites
is called in the application's !Boot and/or !Run files (as described earlier).
The clever bit is that RISC OS then automatically takes just one of the three sprite files - the one appropriate to the screen mode in use - and adds its sprites to the common pool. (And if you change mode, it automatically swaps the set.)
If RISC OS cannot find the appropriate number-suffixed file, it will default to the unadorned sprite file i.e. !Sprites.
Only three such sprite files have been described above and these cater for most circumstances, but theoretically, there could be many more number suffixes because (apart from the special case of !Sprites23) the number is simply the concatenation of the OS units-per-pixel in the x and y directions, in that order. So, if you wanted your application to have a unique set of filer sprites specifically for, say, mode 9 (somebody, somewhere will!) you would need a !Sprites44 file.
When it comes to designing each set of sprites, the application and file sprites should ideally be provided for 'small icons' and pinboard use, as well as standard size versions. The Acorn Style Guide gives the rules for sizing/naming them and probably the most important ones to remember are:
It is important to appreciate that - to follow the Style Guide and to take advantage of the Wimp's automatic facilities - these sprite files are predominantly meant for use by the Filer. Consequently, any other special sprites intended for use solely by and within the application should strictly be held in a separate sprite file - often just called Sprites - and handled by creating a 'user sprite area'. By doing this, the memory taken by the user sprites can be released when the user quits the application.
If you want to take a look at the standard sprites in the sprite pool, open the Resources.Wimp directory in the Resources:$ system (accessed by <menu> over the Apps icon on the iconbar).
As you are no doubt aware, window templates are created in a template editor which prepares the window-plus-icons definition in a file format specified by Acorn in the PRM. The application !RunImage can then load these templates for use.
Traditionally, the file is named Templates but it can be anything you wish.
If an application has a need for such resources, they are usually stored in a directory within the application directory, traditionally called Modules (maybe itself in a directory called Resources). The usual procedure is then for the !Run file to include a check for their presence in the central pool - and any that aren't present are copied to the pool from the Modules folder, and initialised accordingly, before the !RunImage is run.
Sometimes this is done as part of an installation procedure the first time the application is used. In this case, copies of the module(s) are transferred to the !System application (which resides in the !Boot application) from where they are automatically placed in the central pool on start-up. The actual transfer to the !System application can be done by drag-and-drop to the !System.Resources .Modules folder or (probably safer) by using the often-provided 'System Merge' utility which does the same thing and also ensures that the highest version-numbers are used if a module of the same name already exists.
Once they are added to the central pools, it is usual for modules to stay there 'permanently' - because they tend to be resources which are useful for more than one application. (However, they can be removed if need be, e.g. if a module might be incompatible with another application and may need to be removed or disabled before it can operate.)
So, if an application contains its own Fonts directory (often within a Resources directory in the application directory) it is usually because it uses a font (or fonts) not in the basic set provided by Acorn. It is therefore necessary to transfer them to the !Fonts application. Again, this can be done by hand or with a 'Fonts Merge' utility.
When run on start-up, the !Fonts application cranks up a 'Font Manager' module that does all the clever stuff for us.
Fonts added in this way usually reside 'permanently' in the !Fonts application and therefore then become available to all applications, offering the user a choice of outline fonts - not just to the application which supplied them.
The Wimp has convenient facilities for handling the various message strings which appear in error/warning boxes, help files etc. Such messages can be placed in textfiles in a certain format and then accessed easily by an application's program.
The main advantage of doing this is that it makes it much easier to edit the messages and also to translate them into other languages (without the need for computer expertise).
The rough procedure is that the Messages file(s) are identified to the Wimp and then loaded into dynamic RAM after Wimp initialisation. Thereafter, the messages can be read for inclusion in displayed text etc, using SYS calls provided for the purpose.
Two further advantages are that 'text parameters' can be inserted into the filed messages as they are called (like passing parameters in Obey files) - and also menus can be created from Messages files.
The !Run file of an application might typically be used to set a system variable to hold the location of the Messages file, so that it can be used as a reference by the application.
If an application has a !Help file, the Help item on the Filer menu will automatically be enabled when <menu> is pressed over the application icon - and selecting this item will display the !Help file.
This shouldn't be confused with Acorn's !Help application (and others like it) which, when running, use the Wimp's Messaging system to provide interactive help information as you move the pointer over an object on the screen. Just to add more word-confusion, it is quite usual for a Messages file (nothing to do with 'Messaging') to hold the text used by !Help.
A directory with one of these names (or something akin to them) isn't a universal feature of application directories and it certainly has no special meaning as far as the Wimp is concerned. However, it is seen often enough to be worth a comment.
It is more a sign of good housekeeping, in that it usually holds text and/or data files representing the user's global choices for certain configurable features within the application, e.g. option settings, back-up file path, font choice(s), etc.
Many applications need a place to store files temporarily, e.g. when transferring a file to a printer, and the !Scrap application (provided by Acorn) is the most convenient way to effect this.
For hard disc users, a single copy of !Scrap is held within the !Boot application and, on start-up, the location of this 'local dump' is set into a system variable called Scrap$Dir or similar. All applications can then use it.
However, for users without a hard disc, if !Scrap is needed, the only option is to include it in the root directory of the same floppy disc - or within the application resources and activated by the !Run file. If more than one floppy disc is needed to operate the application, a copy of !Scrap on each disc is recommended, to avoid (even more!) disc swapping.
| Source: | Archive Magazine 12.2 - "Learners' Column" |
| Publication: | Archive Magazine |
| Contributor: | Ray Favre |