Topic : The GFA-Basic Compendium
Author : GFA Systemtechnik GmbH
Version : GFABasic.HYP v2.98 (12/31/2023)
Subject : Documentation/Programming
Nodes : 899
Index Size : 28056
HCP-Version : 3
Compiled on : Atari
@charset : atarist
@lang :
@default : Document not found
@help : Help
@options : +g -i -s +z
@width : 75
@hostname : STRNGSRV
@hostname : CAB
@hostname : HIGHWIRE
@hostname : THING
View Ref-FileThe structure of accessories
An accessory is a program which is installed in RAM after power-on or a reset.
There it waits until it receives an instruction to become active. This
instruction is sent when the user has selected it, usually from the GEM Desktop
menu.
From this simple description you can figure out the rough structure of an
accessory. First we said that an accessory had to be installed. To this end,
the programmer must declare the accessory as a GEM application and pass its
name to GEM so that it can be entered as an item in the first of the dropdown
menus.
Declaration as a GEM application is performed with the APPL_INIT() function,
the return value of which is known as the applications ID.
The value returned by APPL_INIT() can also be used to determine whether a
program was started as an accessory or as a normal program. If the return value
is 0, the program was not started as an accessory, but as a normal program. You
can thus write programs in 3.0 which are executable both as normal
programs and as accessories.
The applications ID number is also required for passing the accessory name.
This is done with MENU_REGISTER(ap_id,text$).
MENU_REGISTER() returns the accessory number of the current program (0 to 5).
This value is called the menu identification number. A return value of -1 means
that 6 accessories have already been installed, the maximum for GEM, and
therefore there is no room for another one. The two parameters are the
application ID and the accessory name.
Now the accessory has been installed, the next step consists of waiting for it
to be called. An accessory must be programmed as an endless loop within which
the message buffer is scanned.
This scanning can be done, for instance, with the EVNT_MESAG() function. If a 0
is passed to this function, it will write messages coming from GEM into
's own message buffer which can then be read using MENU(1) to MENU(8).
The most important message type for an accessory is MENU(1)=40 (AC_OPEN). This
message means that the user has selected an accessory. If, however, the
accessory runs in a window, the other messages relating to the selection of
other elements and to the redraw are also of interest.
An accessory normally offers the user the option to remove it again from the
screen. In terms of the program's internal structure this means that the
accessory must return to the endless loop by means of the EVNT_MESAG(10)
instruction. There must be no END or a similar command in an accessory because
that would make the computer "hang".
This description needs one further point to be added. programs
attempt to claim all free memory space for themselves after they have been
started. You can, of course, release space again with RESERVE, but before the
RESERVE command is executed the initialisation routine of a compiled program
will already have performed the reservation of memory space.
To prevent this, a accessory must include a line which tells the
compiler that the program to be generated must not claim all the free memory.
This is what the compiler option $mx does, with x being the number of bytes to
be claimed by the compiled program.
The screen area occupied by an accessory must be restored. This is called
redraw. If, for example, you are using dialog boxes, this redraw can be
performed from within your accessory, using GET and PUT to read in the screen
area and then writing it back again.