|
www.riscos.com Technical Support: |
The underlying technologies used in Acorn C/C++ have been designed in a way which allows third parties to add tools and applications, provided that they follow a number of rules and conventions which are given in this section. Unless you are a software developer, intending to use these technologies in your products, or intending to add further desktop tools, then you can skip this section. (Of course you may just be interested in how it all works, in which case read on!).
The FrontEnd module will act as a generic application, as described in the General features. It is assumed here that you are familiar with this chapter, and that you have a feel for how the non-interactive tools operate.
The extensions you can make fall roughly into the following categories:
In this chapter you will find further technical information on the following:
The purpose of the FrontEnd module is to ease the job of putting consistent Wimp frontends onto a number of simple tools which are normally driven from the command line (e.g. Link, CC, ObjAsm etc). A Wimp application can then be made by supplying a formal description of the mapping between the Wimp interface and command line options, a templates file, !Run, !Sprites and !Boot files, a message file, and a !Help file (also a !SetUp file if this is to be used by Make - see Make for more details).
To give you a feel for how the FrontEnd module interacts with your command line tool, here is a brief description of how it works. The FrontEnd module understands two star commands:
The former of these is used to invoke a Wimp front end for a tool, with an icon on the icon bar; the latter is used to allow Make options for the tool to be set using a Wimp interface.
When the FrontEnd module gets a *FrontEnd_Start command it creates a new instantiation of itself called FrontEnd%toolname where toolname is the name of the tool invoked; it then enters that instantiation as the current application, and does a SWI WimpInitialise to become a Wimp task. Because this task stops the Wimp from mapping out its application workspace, by responding to service call 0X11, the task appears in the applications task list of the Task Manager display. From this point on, the behaviour of the Wimp task is governed by the formal description file which was initially passed to the *FrontEnd_Start command.
The *FrontEnd_SetUp command is similar, except it calls its new instantiation FrontEnd%Mtoolname, and does not produce an icon on the icon bar. The templates for windows used by the application must be provided by you, and they must follow the conventions laid down later in the Template files.
When the user causes the command line tool to be run (for example by clicking on the Run icon in the application's dialogue box), the FrontEnd module starts up a task called toolname_task running under the control of the task window module; thus the tool is pre-emptively multitasked, and any output the tool produces is stored and will be displayed in a window, if this is what the user wishes. When the user quits the application, the FrontEnd module ensures that the relevant instantiation is also removed from the RISC OS module list.
To be suitable, your command line program has to be non-interactive. This means it should start with a command line, then run to error or completion without any further user interaction, outputting reports as screen text. A compiler such as CC fits this description, but an editor such as SrcEdit does not.
The tool ToANSI is a simple example of the non-interactive desktop tools. You may find it instructive to examine the file Desc in AcornC_C++.Tools.!toansi.
In order to produce a complete Wimp application you will need to provide the following:
These are described in more detail below.
Your !Boot file will be the same as for normal applications, including doing things like setting file types, and performing *IconSprites commands on your sprites.
A typical !Run file will look like any of those supplied with the desktop non-interactive tools, such as !Link, !Find, or !Diff. The size of Wimpslot does not depend in any way on the size of the command-line tool which is running under the FrontEnd module, but instead refers to the application workspace used by the module, when starting up as a Wimp task (currently a minimum of 16k). You should ensure that you have a command of the following form:
*Set toolname$Dir <Obey$Dir>
so that your resource files can be found. Having made sure that the FrontEnd and Task Window modules are loaded (by using *RMEnsure) you then issue the *FrontEnd_Start command with application name and full pathname of the description file as parameters. You may need the facilities provided by the DDEUtils module, in which case you should *RMEnsure it in your !Run file
For example for !Diff, the !Run file is:
*If "<System$Path>" = "" Then Error 0 System resources cannot be found *WimpSlot -Min 128k -Max 128k *IconSprites <Obey$Dir>.!Sprites *Set Diff$Dir <Obey$Dir> *RMEnsure UtilityModule 3.10 Error This application only runs on RISC OS 3 (version 3.10) or later *RMEnsure SharedCLibrary 3.99 Error This application requires the Shared C Library module (is it unplugged?) *RMEnsure FPEmulator 2.87 Error This application requires the FP Emulator module (is it unplugged?) *RMEnsure TaskWindow 0.47 Error This application requires the Task Window module (is it unplugged?) *RMEnsure FrontEnd 0 System:modules.frontend *RMEnsure Frontend 1.15 Error You need version 1.15 of the FrontEnd module to run !Diff *RMEnsure DDEUtils 0 System:modules.ddeutils *RMEnsure DDEUtils 1.52 Error You need version 1.52 of the DDEUtils module to run !Diff *WimpSlot -Min 32k -Max 32k *FrontEnd_Start -app Diff -desc <Diff$Dir>.desc
A typical !SetUp file is very similar to a !Run file, but will be used when the FrontEnd module gets a request from Make to start up the Wimp front end for a tool, to allow the user to set options from a dialogue box. This file should only need to do the following:
Again, examples of a !SetUp file can be found in the set of non-interactive desktop tools.
The !Sprites file will contain the sprite for the application icon on the icon bar, and also optionally a small sprite, both of which should comply with RISC OS style. The name of the large sprite should be the same as the application (e.g. !Link, !Find etc).
The set of window templates which you should supply in a file called Templates is as follows:
| Window name | Status | Details |
|---|---|---|
| progInfo | Mandatory | Should be as standard Acorn applications information boxes.
Icon #1 must be indirected text, with a buffer size large enough to accept the application name. Icon #4 must be indirected text, with a buffer size large enough to accept the version string. |
| SetUp | Mandatory | This dialogue box is used to set the most common options for the command line tool. Rarer options can be set from a menu by the user pressing the Menu button on this dialogue box. The title bar must be indirected text, and have a buffer size large enough to accept the application name.
Icon #0 must be indirected text (buffer size 12 bytes), and have a button type of Click, and should contain the text Run. It is used to invoke the command line tool with the chosen options. Icon #1 must be text, and have a button type of Click, and should contain the text Cancel. It is used to close the Options dialogue box, and revert to the options settings as they were when the dialogue box was last opened. Other icons are of your choice, and can be used to map to command line options. You must, however, follow the conventions described in the Writing an application description. |
| CmdLine | Mandatory | This dialogue box is used to show the command line equivalent of the options which the user has chosen. The title bar should contain some explanatory text like Command Line.
Icon #0 must be indirected text with buffer size 12 bytes, with button type Click, and containing the text Run. It is used to invoke the command line tool with the shown command line. Icon #1 must be indirected text with buffer size typically at least 256 bytes, and with a button type of Writeable. |
| Help | Optional | Used to display help text when the user selects Help from the application's main menu. The title bar should contain some appropriate text. The window should not have its Auto-redraw flag set. |
| query | Mandatory | Used to ask the user if they really want to kill off a task which is running.
Icon #0 must be text, button type Click, and is used to reply Yes. Icon #1 must be indirected text, buffer size 256 bytes. Icon #2 must be text, button type Click, and is used to reply No. |
| Output | Optional | Used to display in a scrolling window, the textual output of the command line tool. The window's Auto-redraw flag must not be set.
The title bar must be indirected text, and have a buffer size large enough to accept the application name, plus a space and the string (Completed). |
| Summary | Optional | Used to give a summary of the textual output produced by the command line tool.
Icon #2 must be text, with button type Click, containing the text Abort. It is used to abort the task. Icon #3 must be indirected text, with a buffer size large enough to hold strings Pause and Continue, button type Click. It is used to pause and continue the task. |
| xfer_send | Mandatory if the Tool produces output that the user is able to save | Used as a save dialogue box for the textual output of a tool.
Icon #0 must be text, with button type Click, containing the text OK. Icon #2 must be indirected text, with a buffer size of 256, and button type writeable. Icon #3 must be indirected text. |
| save | Mandatory if user is able to save anything | As for xfer_send, but is used to save the result file generated by running the tool. It should also have a close icon. |
As previously mentioned, your application running under the FrontEnd module is driven by a formal description written in a language whose EBNF (Extended Backus Naur Form) grammar is given in FrontEnd protocols. This section gives an explanation of the semantics of the language, and hence explains how to write your own description.
As can be seen from the EBNF rule in FrontEnd protocols for an application, the description file consists of 10 sections, with only the first section being mandatory (TOOLDETAILS). Each of these sections is described separately below.
The tool details section is the only section which you must have in the description. The section starts with the name of the tool, which must be the same as the string passed as the -app parameter to *FrontEnd_Start. This name will be used in window and menu title bars to identify the application.
Normally the tool will reside in your current library directory, and hence the command will be invoked using only the tool name. If you wish to change this you can specify a command_is entry, which gives a pathname for the tool. For example if you have an application called example, but the executable image for this application is held in !RunImage in the application directory, then you should have a line in the description file saying:
command_is "<example$Dir>.!RunImage";
The version entry will typically be a version number and optional date for the tool. These will be used in the Program Information dialogue box (progInfo).
If your tool understands a particular file-type, then this can be entered using the keyword filetype. This is used when the user double-clicks on a file of this type in a directory display. The effect is as if the user has dragged the file icon to your icon on the icon bar.
By default the tool is run in a Wimpslot of 640k, under the Task Window module. If you want this value to be different, then use the Wimpslot command in the description.
Since the limit on RISC OS command lines is 256 characters, you may find this to be an unnecessarily strict limit when passing a potentially large list of full pathnames to a tool on its command line. If you use the has_extended_cmdline keyword in the description, then the FrontEnd module will request space from the DDEUtils module to place the command line arguments in. If the tool is written in C (or runs under any other run-time environment which cooperates with DDEUtils) the tool will pick up the arguments from DDEUtils. Using this option, your command line is limited only by the size of the writable icons in your dialogue boxes. If written in C, the tool must have been linked with the stubs or ANSILib to use this feature.
The METAOPTIONS section refers to non-application-specific options.
If the has_auto_run keyword is used, the application's main menu option Auto Run will not be greyed out. In addition, if you include the keyword on, then this option will be enabled by default. Auto Run means that if a file is dragged to the application icon, then the tool will immediately be run, rather than first displaying the Options dialogue box.
The has_auto_save keyword refers to the Auto Save option in the application's main menu, and the keyword on turns this option on by default. If this option is on, then rather than producing a Save as dialogue box to save the file output of the tool, the tool is run to directly write to the desired output place. The location where output should be sent is given following the has_auto_save keyword; in order to specify this location, you must first give an icon number in the Options dialogue box, whose first entry will be used to determine the directory where the output will go (using the from icn <integer> keywords).
For example, if you have the line:
has_auto_save ^."!RunImage" from icn 3;
and icon 3 of the options dialogue box contains the text:
adfs::4.$.objects.file1 adfs::4.$.objects.file2
then the filename adfs::4.$.objects.file1 will be used to form the output filename. First the leafname file1 is stripped off to leave the directory name adfs::4.$.objects which will form the stub of the output filename. This stub is then manipulated by the string which is specified between the keyword has_auto_save and the keyword from. You can indicate parent directories using any (reasonable) number of ^.s and can refer to the original leafname using the keyword leafname (in this example leafname would map to file1). This leafname can have literal strings prepended or appended to it.
If the application is to have textual output, then you can specify that you want text and/or summary window(s) by using the keywords has_text_window and has_summary_window. Beware that if you don't have any output windows at all, then the user has no way of pausing/aborting/examining the running task. The default display mode is text, but this can be explicitly stated as text or summary using the keyword display_dft_is.
The FILEOUTPUT section deals with the production and saving of a single output object. To enable the user to then save this output, it is sent to a temporary file, which is then copied to a permanent file when the corresponding icon is dragged to a directory display - the icon can also be dragged to another application.
By default it is assumed that the output filename for a tool is that which appears last on the command line with no special preceding flag. If your command line tool requires a flag such as -o to go before the output filename, then this is specified using the output_option_is keyword.
Also by default, the name which appears in the Save as dialogue box is the string Output, assuming that no Auto Save string has been specified. This can be changed using the output_dft_string keyword.
Certain tools produce an output file, or not, depending on the combination of options on their command line. By using the output_dft_is keyword, you can specify whether the default mode of operation is to produce output or not. This state will then be changed as the user chooses options from the options dialogue box and menu which either turn output production on or off (see the DBOX section and the MENU section).
The DBOX section describes the properties of the main dialogue box used to set options for the command line tool.
The purpose of the icon definitions is to show how icon clicks and drags etc. map onto command line option strings, and how these affect the state of other icons and menu entries. Essentially, icon numbers correspond to those numbers used in the template for the dialogue box.
There are four types of icon definition:
The most complex of these is the icon which maps to a command line string. Such an icon can be of two Wimp types:
The former of these contributes to the command line, if it contains any text, and is generally used for specifying filenames to the command line tool. The latter is generally used to turn flags on and off, and contributes to the command line if it is selected. The mapping onto the command line is given after the keyword maps_to; this may begin with an optional string literal (e.g. -f), optionally followed by keywords string or number. These latter keywords are used for writable indirected text icons, and refer to their contents. If you want each item in the writable text icon to be preceded by a particular string, this can be specified using the prefix_by keyword.
You can also specify that selecting this icon causes the values of other icons to be used in the command line, by using the followed_by keyword. These items will be separated by the entry given after the separator_is keyword. As discussed in the FILEOUTPUT section, it is possible to specify whether a tool produces output by default; each icon can be made to toggle this state using the keywords produces_no_output and produces_output. The not_saved keyword should be used if the value of the particular icon should not be saved when the user picks the Save options entry from the application's main menu.
Some examples should make this clearer:
icn 3 maps_to "-c";
This would be used for a click icon, which when selected will result in -c being inserted into the command line.
icn 6 maps_to "-f " string not_saved;
This would be used for a writable indirected text icon, whose string contents should follow the literal -f on the command line. It would typically be used for specifying input filename(s). The contents of icon 6 would not be saved when the user chose the Save options menu entry.
Using the increases or decreases keyword is typically used for arrow icons, used to increase and decrease the numeric value of another icon. The default amount by which the increase or decrease is made is 1, but this can be changed using the keyword by. Minimum and maximum values can also be specified. The button type of such an arrow icon should be click or auto-repeat.
If an icon should just be used to insert a useful string in another writable indirected text icon, then this is specified using the keyword inserts. Whenever such an icon is clicked, the given string literal is inserted into the keyboard buffer, if the options dialogue box currently has the input focus. Its button type should be Click.
The extends keyword is used for an icon which is used to toggle the options dialogue box, from large to small and vice versa. The from icon number is the icon which is used to mark the bottom of the dialogue box when small; the to icon number is the icon which is used to mark the bottom of the dialogue box when large.
The list of icon definitions can optionally be followed by a list of icon default values, using the keyword defaults. Each icon can be listed with the keywords on and off for click icons, or a string or numeric literal value for writable indirected text icons. These defaults refer to those used when the tool is invoked via *FrontEnd_Start; if the tool has different options by default when invoked from Make, these are listed using the make_defaults keyword.
Following this in the description is an optional specification of what happens when drags occur, from the filer or from other applications. After the keyword imports_start, which begins this part of the description, you can optionally specify a wild_card_is string, which is used whenever a directory is dragged to your application. Typically this wildcard will be *. Hence a directory adfs::4.$.foo dragged onto the application will expand to adfs::4.$.foo.*. There then follows a list of drag_to specifications, each of which gives either a specific icon number in the dialogue box, or the keywords any or iconbar; the icon list following the word inserts is where the filenames of the dragged files will be inserted, with an optional separator string. If no separator string is given then a drag will overwrite the previous contents of the writable indirected text icon. Here are some examples:
drag_to icn 3 inserts icn 3;
This means that a drag onto icon 3, will insert the filename into icon 3, and subsequent drags to this icon will overwrite it.
drag_to icn 6 inserts icn 6 separator_is " ";
drag_to any inserts icn 6 separator_is " ";
drag_to iconbar inserts icn 6;
These means that a drag to icon 6, or anywhere else on the dialogue box, or to the icon bar will insert the filename of the dragged icon in icon number 6. In the case of the iconbar, the contents of icon 6 will be overwritten.
The MENU section is similar to the DBOX section, except that it is used to specify the way that menu entries on the menu attached to the options dialogue box map to command line option strings. This menu is typically for less commonly used options.
Each entry in the menu entry list begins with a literal string, which is used to give the text that will appear in that menu entry. This is followed, after the keyword maps_to, by string literal (which may be null) to which that menu entry maps in the command line. This is optionally followed by the keyword sub_menu, in which case this menu entry will be given a writable submenu with the given string literal as its title, and with a buffer size given by the supplied integer value. If you want each item in the submenu buffer to be preceded by a particular string, this can be specified using the prefix_by keyword. The produces_output, produces_no_output and not_saved keywords are as described above for the DBOX section.
Menu default values can be set in a similar manner to those for the dialogue box icons. This is done using the defaults keyword, and then following each menu entry with the keyword on or off depending on the desired default state of that entry. If the entry has a writable submenu, this can also be given a default string or integer value. Also a separate set of option defaults can be set for when the FrontEnd module is invoked from Make. Menu entries are numbered from 1 (ignoring the command line equivalent entry).
For example:
menu_start "First option" maps_to "-a"; "Second option" maps_to "-b " sub_menu "Value: " 8; defaults menu 1 off, menu 2 on sub_menu "42"; menu_end
will result in a menu with two entries (other than the command line equivalent, which is always the first entry). By default First option will not be ticked, but Second option will be ticked and its writable submenu will contain the value 42.
The DESELECTIONS section allows you to state which Options when enabled should disable other options. This can be done for both icons in the main options dialogue box and for entries in its attached menu. For example:
icn 3 deselects icn 4, icn 5, menu 3;
means that if icon 3 is selected, then icons 4 and 5 and menu entry 3 will be deselected.
The EXCLUSIONS section is similar to the DESELECTIONS section, except that the listed icons and menu entries are made unselectable (greyed out). When the icon or menu which caused this exclusion is deselected, then the excluded items become selectable again.
Certain tools require that some options are made unselectable when the FrontEnd module is invoked from Make. The MAKE_EXCLUSIONS section allows these icons and menu entries to be listed.
By default the command line for the tool is constructed in the following order:
If this ordering is not satisfactory, you can give another ordering by using the order_is keyword followed by a list of icon numbers, menu entries and string literals. This mechanism can be used to insert string literals which always appear on the command line.
The MAKE_ORDER section is similar to the ORDER section, except that it gives a way of specifying an alternative command line ordering, when invoked from Make.
There are a number of textual messages (warnings and errors and the like), which the FrontEnd module issues. The purpose of the messages file for an application is to allow internationalisation of the messages. A messages file is supplied with each of the non-interactive tools, which you can use for your application; it should be in a file called <toolname$Dir>.Messages. If no such file is present, then FrontEnd's internal default English messages are used.
Responses to interactive help requests are handled by the FrontEnd module. In each of the desktop non-interactive tools directories you will find a Messages file for the tool. In this file are help messages for the various dialogue boxes of the tools. In general a message whose tag field is the name of the dialogue box, is used when the pointer is not over an icon; when the pointer is over an icon, the icon number is used to distinguish the help message.
For example, an entry in the messages file of:
SETUP3:This is where you specify the input filenames
will result in the message
This is where you specify the input filenames
appearing in !Help's interactive help window, when the pointer is over icon number 3 of the SetUp dialogue box.
When the user selects Save choices from the application's main menu, the current setting of options is saved in a file <toolname$Dir>.!choices.
The DDEUtils module is intended for three purposes:
Further details are given in DDEUtils.
A language compiler needs to supply three lines of information about itself to SrcEdit when it is installed. It does this by appending these three lines to the file <SrcEdit$Dir>.choices.languages of the form shown in SrcEdit file formats.
The language help file is used when the user selects a portion of his text and requests language help on this. The format of entries in the help file is shown in SrcEdit file formats.
You will have noticed that when the user selects Menu on a project in Make, it is possible to select options for a tool, by picking the name of that tool from the Tool options menu. This is done by Make issuing the star command *FrontEnd_SetUp; the FrontEnd module then replies with a Wimp message (details of which are given in FrontEnd protocols) containing the desired command line.
In order to achieve this, a tool which is being added must append six lines to the file <Make$Dir>.choices.tools of the form:
| tool_name | |
| extension | the string used to identify a source written in this language; e.g. c for the C language |
| make_defaults | the default options for this tool when in a makefile |
| conversion_rule | i.e. how to convert source files to object files |
| description_file | full pathname of file containing application description |
| setup_file | full pathname of file containing SetUp actions for when tool is invoked via Make |