This is an old version from the tos.hyp. The new is on GitHub!

HomeAESAbout the AESApplication library

8.2 AES fundamentals

The AES(Application Environment Services forms the highest level of GEM. It deals with all those parts of GEM that go above elementary graphic output and input functions. As the AES works exclusively with VDI and GEMDOS calls, it is completely independent of the graphic hardware, of input devices as well as of file-systems.

The AES manages two types of user programs: Normal GEM applications with file extensions '.PRG', '.APP' or '.GTP', and desk accessories with file extensions '.ACC'.

Unless you are using a multitasking operating system such as MagiC, MiNT or MultiTOS, the AES can only run one application and six desk accessories at a time. Desk accessories (with an '.ACC' extension) allow quasi-multitasking even with plain TOS: They are usually special GEM programs loaded (wholly or partially) at boot-up from the root directory of the boot drive (normally C:\), which remain in memory and can be called at any time from GEM (and some TOS) programs by clicking on their entry in the first drop/pulldown menu. In other words, desk accessories can be called and used while another application is running and has its window(s) open, even with a single-tasking operating system such as TOS. Note that this is not real multi-tasking, as the main application is suspended while the accessory is executing and only resumes when the accessory is exited.

Unlike applications, desk accessories don't interact with the user immediately; most just initialize themselves and enter a message loop awaiting an AC_OPEN message. Some wait for timer events or special messages from other applications. Once triggered, they usually open a window where a user may interact with them. Under TOS, accessories should not use a menu bar and should never exit after a menu_register call. Loading of any resources should happen before the accessory calls menu_register, and these resources should be embedded in the desk accessory rather than being post-loaded, as on TOS versions earlier than 2.06 memory allocated to a desk accessory is not freed at a resolution change; thus memory allocated with rsrc_load is lost to the system after a change of resolution with the early TOS's.

When a desk accessory is closed under TOS, it is sent an AC_CLOSE message by the system. Following this it should perform any required cleanups to release sytem resources and close files opened at AC_OPEN (the AES closes the accessory's windows automatically). Following this it should reenter the event loop and wait for a later AC_OPEN message.

The following points are covered in this section:

For the AES too there have been some interesting developments, as various programmers have meanwhile announced their own AES clones; at present one can mention projects such as N.AES and XaAES. Besides constant evolution one may hope also for source texts of these GEM components.

See also: Style guidelines

8.2.1 Accessories

8.2.1.1 Startup-code for accessories

To test whether an application was launched as a program or as a desk accessory, one can proceed as follows:

Note: With this information there is no problem in creating the start- up code for a program in such a way that it recognizes automatically how the application was launched, and to continue the initialization appropriately. With most C compilers the external variable _app in the startup code is initialized automatically, which has the value 0 when the application was launched as a desk accessory. This makes it possible to develop applications so that they may be launched either as desk accessories or as normal programs.

See also:
About the AES   Accessories in MagiC   Program launch and TPA

8.2.1.2 Accessories in MagiC

Under MagiC, desk accessories are almost equal to programs. Their windows are maintained at program changes. They may have menus and desktop backgrounds, post-load programs, allocate memory, open/close/ delete/copy files etc.

As there is no longer any reason to close windows at program changes, there is no AC_CLOSE message any more. The system does not distinguish desk accessories from programs, apart from the fact that they may not terminate themselves. As under GEM/2, accessories can also deregister themselves in the menu, using the AES call menu_unregister.

In place of accessories, under MagiC it is more sensible to use applications that simply register one menu bar with one menu, and lie in the APP autostart folder. These applications can be loaded when required, and also removed again afterwards.

Note: As of MagiC 4, desk accessories can be loaded also while the system is running (not just at boot-up). Furthermore accessories can be unloaded by clicking on the corresponding accessory entry in the first menu while the [Control] key is held down. One disadvantage is that at present accessories may not perform Pexec with mode 104.

See also:
About the AES   GEM   Startup-code for accessories   shel_write

8.2.2 The desktop window

Of the available windows, the desktop or background window plays a special role. It has the ID 0, occupies the whole screen area, is always open and also cannot be closed. The working area is the area below the menu bar. Only in this working area can other programs output to the screen or open their own windows.

Normally the working area of the desktop appears as a solid green area (in colour resolutions) or as a grey raster pattern (in monochrome operation). The screen-manager attends to the screen redraws all on its own; with a call of wind_set, other application programs can anchor any other object tree as a background. In that case too the screen-manager looks after any required redraws of sections of the image. Although this possibility is very alluring, there are several reasons that point against the use of the desktop window; the most important:

To sum up: If possible, the desktop background should not be used in your own programs.

See also: About the AES   wind_set   WF_NEWDESK

8.2.3 Data exchange via the GEM clipboard

To store files in the clipboard, one should proceed as follows:

The filename is always 'scrap.', the extension (suffix) depends on the selected format here; if possible one should always support one of the following standard formats:

Suffix Meaning
gem Vector graphics in metafile format
img Pixel images in XIMG format
txt ASCII text file, each line terminated with CR/LF

In addition one can support one or more of the following formats (the receiver then has the option of using the option with the greatest amount of information):

Suffix Meaning
asc ASCII text file, each paragraph terminated with CR/LF
csv ASCII file with comma-separated numbers
cvg Calamus vector graphic format
dif Export file of spreadsheets
eps Encapsulated PostScript
1wp Wordplus format
rtf Microsoft Rich Text Format
tex TeX

The receiving program should first check which of the available files contains the most information, and then use this file.

Important: Each of the files in the clipboard contains the same information on principle, just in different formats. The text processor Papyrus, for instance, imports 'scrap.rtf' only if its own format 'scrap.pap' could not be found.

It should be clear from the above explanation that only one data object (though in different formats) can be present in the clipboard at any time.

Note: A few old programs, such as First Word and First Word Plus, are promiscuous and the clipoards they create automatically are scattered all over the place - usually the directory they are launched from. Some other applications may then use this clipboard rather than the 'official' one on the boot drive!

See also: Clipboard functions   scrp_clear   Style guidelines

8.2.4 The object structure

Although the data structure of the object tree is not a tree in the sense of a binary tree, it nevertheless possesses within a pointer the logical chaining of a tree, with predecessors and successors (generally called 'parents' and 'children' respectively). The speci fication of parents and children is made via indices to an array.

The tree structure of the individual objects can be illustrated best with a simple example: A menu is composed at first of the menu bar. This in turn contains several title texts. The title texts therefore are contained directly in the menu bar, and are both children of the object 'menu bar', so they move on the same hierarchical level. The object menu bar refers with ob_head to the first menu title and with ob_tail to the last menu title. In the first menu title the pointer ob_next serves for addressing the next menu title. Thus the chaining shows the following structure:

      Menu bar:
   +---------+---------+--------+
   | ob_head | ob_tail | ...    |
   |    o    |    o    |        |
   +----|----+----|----+--------+
        |         +-------------------------+
        V                                   V
   +---------+---------+--------+       +---------+---------+--------+
   | ...     | ob_next | ...    |  ...  | ...     | ...     | ...    |
   |         |    o    |        |       |         |         |        |
   +---------+----|----+--------+       +---------+---------+--------+
   1st menu title |                          n-th menu title
                  +-----> 2nd menu title

The actions that may be performed with a given object is specified in ob_flags. The state of an object is held in the entry ob_state. The entry ob_type determines the object type.

For an exact definition some objects need an additional data structure such as TEDINFO or BITBLK. In that case a pointer to this additional structure will be stored in ob_spec.

Summarising again the total setup of the data structure for objects OBJECT:

         +-------------+
         |  ob_next    |   Index for the next object
         +-------------+
         |  ob_head    |   Index of the first child
         +-------------+
         |  ob_tail    |   Index of the last child
         +-------------+
         |  ob_type    |   Object type
         +-------------+
         |  ob_flags   |   Manipulation flags
         +-------------+
         |  ob_state   |   Object status
         +-------------+
         |  ob_spec    |   See under object type
         +-------------+
         |  ob_x       |   Relative X-coordiante to parent object
         +-------------+
         |  ob_y       |   Relative Y-coordinate to parent object
         +-------------+
         |  ob_width   |   Width of the object
         +-------------+
         |  ob_height  |   Height of the object
         +-------------+

See also:
AES object colours   Object types   Manipulation flags   Object status

8.2.4.1 AES object types

The following types of object are available for selection:

Type Meaning
G_BOX (20) Rectangular box with optional border; ob_spec contains sundry information about border width, colour and similar matters
G_TEXT (21) Formatted graphic text; ob_spec points to a TEDINFO structure
G_BOXTEXT (22) Rectangular box with formatted graphic text; ob_specpoints to a TEDINFO structure
G_IMAGE (23) Monochrome image;ob_specpoints to BITBLK structure
G_USERDEF (24) User-defined function for drawing a customized object; ob_spec points to a USERBLK structure. (Note: In some libraries this is called G_PROGDEF for a programmer-defined function)
G_IBOX (25) Transparent rectangle that can only be seen if the optional border does not have zero width; ob_spec contains futher information about the appearance
G_BUTTON (26) Push-button text with border for option selection; ob_spec points to a text string with the text that is to appear in the button

New as of MagiC Version 3.0:
If the object flag WHITEBAK is set, and bit 15 in object status = 0, then the button will contain an underscored character; for this, (high byte & 0xf) of ob_state gives the desired position of the underscore (with a suitable library one can make the underscored character when pressed together with the [Alternate] key select the button in the dialog of a running application)

On the other hand if bit 15 = 1 then we are dealing with a special button (radio-button or checkbox)

Further specialties: WHITEBAK = 1, bit 15 = 1 and in ob_state:
Highbyte = -2 Group frames
Highbyte = -1 Special button, no underscore
Highbyte != -1,-2 Special button, with underscore


(Here again (high byte & 0xf) of ob_spec is the underscore position). The presence of these features is best established via the function appl_getinfo (opcode 13).
G_BOXCHAR (27) Rectangle containing a character; in ob_spec both the appearance of the border and the character are defined
G_STRING (28) Character string; ob_spec points to the string

New as of MagiC Version 3.0:
If the object flag WHITEBAK is set, and the high-byte of ob_state != -1, then a character of the string will be underscored; the underscore position is determined by (high byte & 0xf) of ob_state

With WHITEBAK flag set and high byte ofob_state= -1 the complete string will be underscored. The presence of these features is best established via the function appl_getinfo (opcode 13).
G_FTEXT (29) Editable formatted graphic text; ob_spec points to a TEDINFO structure
G_FBOXTEXT (30) Rectangle with editable formatted graphic text; ob_spec points to a TEDINFO structure
G_ICON (31) Monochrome icon symbol with mask; ob_spec points to the ICONBLK structure
G_TITLE (32) Title of a drop-down menu; ob_spec points to the string.

As of MagiC 2 one can also underscore one of the characters. This is done as follows:

Set WHITEBAK in ob_state
(ob_state >> 8) & 0xf Position of the underscore
(ob_state >> 8) & 0xf0 is 0
G_CICON (33) Colour icon (available as of AES V3.3); ob_spec points to the CICONBLK structure
G_CLRICN (33) Colour icon; ob_spec is a pointer to an ICONBLK structure. Supported in the ViewMAX/3 beta and in FreeGEM.
G_SWBUTTON (34) Cycle button (i.e. a button which alters its text cyclically when clicked on); ob_spec points to a SWINFO structure. The presence of this object type should be inquired with appl_getinfo (opcode 13).
G_DTMFDB (34) For internal AES use only: desktop image. The ob_spec is a far pointer to a MFDB structure. Supported in the ViewMAX/3 beta and in FreeGEM.
G_POPUP (35) Popup menu; ob_spec points to a POPINFO structure. If the menu has more than 16 entries, then it can be scrolled. The presence of this object type should be inquired with appl_getinfo (opcode 13). Note: G_POPUP looks like G_BUTTON but the character string is not centred, so as to line up with the other character strings in the menu if possible.
G_WINTITLE (36) This object number is used internally by MagiC to depict window titles. The construction of this object type may change at any time and is therefore not documented.
G_EDIT (37) As of MagiC 5.20 an editable object implemented in a shared library is available; ob_spec points to the object. Warning: This type is not yet supported by the functions form_do, form_xdo, form_button, form_keybd, objc_edit, wdlg_evnt and wdlg_do at present, i.e. the corresponding events need to be passed on to the object (with edit_evnt).
G_SHORTCUT (38) This type is treated in a similar way to G_STRING, but any keyboard shortcut present is split off and output ranged right. The presence of this object type should be inquired for with appl_getinfo (opcode 13).

The introduction of proportional AES fonts required new strategy for the alignment of menu entries. So as to align keyboard shortcuts ranged right, objects of the type G_STRING inside a menu are therefore split into commands and shortcuts. This strategy however fails for menus that are managed by the program itself, e.g. within a window or a popup menu. This new object type had to be introduced in order to achieve usable alignment in that case too.
G_SLIST (39) XaAES extended object - scrolling list.

Note: For G_BOX, G_IBOX and G_BOXCHAR, the component ob_spec of the OBJECT structure does not point to another data structure, but contains further information for the appearance of the object. The following apply:

Bits Meaning
   
24..31 Character to be depicted (only for G_BOXCHAR)
16..23
 0 = Border width
 1..128 = Border lies 1..128 pixels at the inside of the object
-1..-127 = Border lies 1..127 pixel at the outside of the object
12..15 Border colour (0..15)
08..11 Text colour (0..15)
7 Text transparent (0) or opaque (1)
04..06
0 = Hollow
1 = Increasing intensity
2  
.  
.  
7 = Solid area
00..03 Inner colour (0..15)

The high byte is used by the AES only for submenus. If the highest bit of ob_type is 0x8000 and the bit SUBMENU in ob_flags is set, then the bits 8..14 specify which submenu is coupled with the menu entry. Hence each application can have a maximum of 128 submenus. MagiC only reads the low byte from ob_type, apart from the submenu handling. TOS reacts cleanly to unknown object types (such as the purely MagiC types G_SWBUTTON etc.), i.e. the objects are not drawn.

See also: Object structure in AES   AES object colours

8.2.4.2 AES object colours

The following table contains the predefined object colours. Of course particulars depend on the selected screen resolution, as well as any settings made by the user.

Number Colour Standard RGB values
WHITE (00) White 1000, 1000, 1000
BLACK (01) Black 0, 0, 0
RED (02) Red 1000, 0, 0
GREEN (03) Green 0, 1000, 0
BLUE (04) Blue 0, 0, 1000
CYAN (05) Cyan 0, 1000, 1000
YELLOW (06) Yellow 1000, 1000, 0
MAGENTA (07) Magenta 1000, 0, 1000
DWHITE (08) Light grey 752, 752, 752
DBLACK (09) Dark grey 501, 501, 501
DRED (10) Dark red 713, 0, 0
DGREEN (11) Dark green 0, 713, 0
DBLUE (12) Dark blue 0, 0, 713
DCYAN (13) Dark cyan 0, 713, 713
DYELLOW (14) Dark yellow 713, 713, 0
DMAGENTA (15) Dark magenta 713, 0, 713

Note: These colours also correspond mostly to the icon colours used under Windows and OS/2. With a suitable CPX module one can set the correct RGB values for the frst 16 colours.

See also: Object structure in AES   AES object types

8.2.4.3 AES object flags

The manipulation flags of an object determine its properties. The following options can be chosen:

Flag Meaning
NONE (0x0000) No properties.
SELECTABLE (0x0001) The object is selectable by clicking on it with the mouse.
DEFAULT (0x0002) If the user presses the [Return] or [Enter] key, this object will be selected automatically and the dialog exited; the object will have a thicker outline. This flag is permitted only once in each tree.
EXIT (0x0004) Clicking on such an object and releasing the mouse button while still over it will terminate the dialog (see also form_do).
EDITABLE (0x0008) This object may be edited by the user by means of the keyboard.
RBUTTON (0x0010) If several objects in an object tree have the property RBUTTON (radio button, similar to those on a push-button radio), then only one of these objects can be in a selected state at a time. These objects should all be children of a parent object with the object type G_IBOX. If another object of this group is selected, then the previously selected object will be deselected automatically.
LASTOB (0x0020) This flag tells the AES that this is the last object within an object tree.
TOUCHEXIT (0x0040) The dialog (see also form_do) will be exited as soon as the mouse pointer lies above this object and the left mouse button is pressed.
HIDETREE (0x0080) The object and its children will no longer be noticed by objc_draw and objc_find as soon as this flag is set. Furthermore this flag is also evaluated as of MagiC 5.20 by form_keybd, if objects for keyboard shortcuts are searched for. Input to hidden objects is still possible, however. To prevent this, the EDITABLE flag has to be cleared.
INDIRECT (0x0100) ob_spec now points to a further pointer that in turn points to the actual value of ob_spec (see also OBJECT). In this way the standard data structures such as TEDINFO etc. can be extended in a simple way.
FL3DIND (0x0200) Under MultiTOS this object creates a three-dimensional object (under MagiC as of Version 3.0 only from 16-colour resolutions onwards and when the 3D effect has not been switched off). In 3D operation this will be interpreted as an indicator. As a rule, such objects are buttons that display a status, e.g. radio-buttons.
ESCCANCEL (0x0200) Pressing the [Esc] key corresponds to the selection of the object with this flag. Therefore there may be only one default object in a dialog. Only effective in ViewMAX/2 and later.
FL3DBAK (0x0400) In 3D operation this object will be treated as an AES background object, and drawn as such. It is recommended to allocate the ROOT object with this flag in dialogs with 3D buttons. The same applies for editable fields and text objects, as only in this way will a consistent background colour be maintained.

See also (0x4000).
BITBUTTON (0x0400) This flag was introduced with ViewMAX beta, but not used there. Presumably a button with this flag contains a bitmap in place of a text. Only effective in ViewMAX/2 and later.
FL3DACT (0x0600) In 3D operation this object will be treated as an activator. As a rule such objects are buttons with which one can exit dialogs or trigger some action.
SUBMENU (0x0800) This is used in MultiTOS and from MagiC 5.10 on to mark submenus. menu_attach sets this bit in a menu entry to signify that a submenu is attached to it. The high byte of ob_typethen contains the submenu index (128..255) i.e. bit 15 of ob_type is always set simultabeously with SUBMENU.
SCROLLER (0x0800) Pressing the [PAGEUP] key corresponds to the selection of the first object with this flag in the dialog; pressing the [PAGEDOWN] key corresponds to the selection of the last object with this flag. Only effective in ViewMAX/2 and later.
FLAG3D (0x1000) An object with this flag will be drawn with a 3D border. From ViewMAX/2 on every button will be drawn automatically with a 3D border. The colour category (see USECOLOURCAT) will be used for this. Only effective in ViewMAX/2 and later.
USECOLOURCAT (0x2000) USECOLOURCAT (0x2000) The colour of the object is not a colour index of the VDI, but an entry in a table with colours for designated categories. This table has 16 entries. ViewMAX uses the following categories:
CC_NAME (8) Inactive title-bar
CC_SLIDER (8) Scroll bar background
CC_DESKTOP (10) The desktop
CC_BUTTON (11) Buttons and other 3D widgets
CC_INFO (12) Window information-line
CC_ALERT (13) Alert boxes (not used in ViewMAX or FreeGEM)
CC_SLCTDNAME (14) Active title-bar


Probably it is intended to let the categories 0 to 7 be defined by the application, while 8 to 15 are reserved for the system. The settings are stored in ViewMAX.INI (GEM.CFG in FreeGEM) and consist of one foreground, one background, a fill-style and a fill index in each case. Only effective in ViewMAX/2 and later.
FL3DBAK (0x4000) 3D background (sunken rather than raised). To check for this feature, use appl_init and check that bit 3 of xbuf.abilities is set.
SUBMENU (0x8000) Not implemented in any known PC AES.

See also: Object structure in AES   AES object types

8.2.4.4 AES object stati

The object status determines how an object will be displayed later on the screen. An object status can be of the following type:

Status Meaning
NORMAL (0x0000) Normal representation.
SELECTED (0x0001) Inverse representation, i.e. the object is selected (except for G_CICON, which will use its 'selected' image).
CROSSED (0x0002) If the object type is BOX, the object will be drawn with a white diagonal cross over it (usually this state can be seen only over a selected or coloured object). See also below.
CHECKED (0x0004) A checkmark tick will be displayed at the left edge of the object.
DISABLED (0x0008) The object will be displayed greyed out and is no longer selectable.
OUTLINED (0x0010) The object gets a border.
SHADOWED (0x0020) A shadow is drawn under the object.
WHITEBAK (0x0040) With PC-GEM this causes the icon mask not to be drawn with the icon, which can speed up output is some circumstances.
As of MagiC 3 this controls the underscoring of character strings. This feature can be ascertained with appl_getinfo (opcode 13).
DRAW3D (0x0080) An object is to be drawn with a 3D effect. This flag is of interest only for PC-GEM, and will be ignored by the Atari AES (and also in MagiC).
HIGHLIGHTED (0x0100) An object with this status will be surrounded by a dashed line that is drawn with MD_XOR. This status was introduced with ViewMAX beta.
UNHIGHLIGHTED (0x0200) An object with this status will be drawn with the surround explicitly set by the status HIGHLIGHTED removed. For this one has to proceed as follows: First the status HIGHLIGHTED must be cleared, then the status UNHIGHLIGHTED set and following this the object must be redrawn with the function objc_draw. A redraw of the object without the status UNHIGHLIGHTED would not remove the surround, as it lies outside the area that the object occupies. After the redraw the status UNHIGHLIGHTED should be cleared again. This status was introduced with ViewMAX beta.
UNDERLINE (0x0f00) This opcode is available in MagiC from Version 2.0 onwards, and sets the position and size of the underscore for objects of the type G_STRING, G_TITLE and G_BUTTON.
XSTATE (0xf000) This opcode is available in MagiC from Version 2.0 onwards, and serves for switching for the various button types (G_STRING, G_TITLE and G_BUTTON).

In GEM/5, CROSSED makes the object draw in 3D:

GEM/5 can be detected by calling vqt_name for font 1. If nothing is returned, GEM/5 is running.

Recent FreeGEM builds contain a system based on the GEM/5 one, but extended and backwards-compatible. The DRAW3D state is used instead of CROSSED:

To check for these abilities, use appl_init and check that bit 3 of xbuf.abilities is set.

See also: Object structure in AES   AES object types

8.2.5 The quarter-screen buffer

The quarter-screen buffer is required by the screen-manager to save the contents of the menu background when drop-down menus drop down. The 'QSB' (the usual abbreviation) is also used for the display of alert boxes. Normally its size should depend on the number of colour planes and the size of the system font, but not on the total size of the screen.

A good formula would be:
  500(characters) * space of one character * colour planes

In 'ST High' resolution this would give a value of exactly 8000 (i.e. a quarter of the screen memory). Unfortunately in many cases the AES is not so clever. The following table contains a summary of the algorithm used by some GEM versions:

GEM version Method for setting the QSB
1.0 and 1.2 Static, 8000 bytes
1.4 Dynamic, a quarter of the screen memory
3.0 Dynamic, half of the screen memory

Note: The GEM versions 1.0 and 1.2 (i.e. up to and including TOS Version 1.02) are not prepared by this for colour graphics cards - one of several reasons why even with the use of a special VDI driver under these GEM versions one can not make use of colour graphics cards.

See also: GEM

8.2.6 The rectangle-list of a window

To overcome the problem of windows that overlap each other, the AES holds for each window a so-called rectangle-list; when a window is partially obscured, GEM divides the visible portion of that window into the least possible number of non-overlapping rectangles, the details of which are then stored in the rectangle-list. Thus the elements of this list form a record of the currently completely visible working area of the corresponding window.

To redraw a window (or its contents) one first inquires with the function wind_get(WF_FIRSTXYWH) for the first rectangle of the abovementioned list. Then one checks whether this rectangle overlaps with the screen area to be redrawn; then and only then one can redraw this area with the use of vs_clip.

This method will be continued with all remaining elements of the rectangle-list, until the height and the width of a rectangle have the value zero.

See also: Clipping   WM_REDRAW   wind_get   wind_update

8.2.7 The screen-manager

The screen-manager is always active and supervises the position of the mouse pointer when this leaves the working area of the window of other applications. The areas in question are the frames of the windows, the drop-down menus and the menu bar.

When touching the menu area, the screen-manager automatically ensures that the section of the screen occupied by the menu is saved and later restored again (the quarter-screen buffer is used for this).

Manipulation of the window controllers also do not lead to permanent changes of the screen memory; the result of the interaction with the screen-manager are the so-called message events, which inform the relevant application about the user's actions.

Note: The ID of the screen-manager can, incidentally, be found easily by a call of appl_find("SCRENMGR").

See also: About the AES   GEM   Messages

8.2.8 Toolbar support

From AES version 4.1 onwards the operating system supports so-called toolbars. A toolbar is an OBJECT tree that is positioned below the information-line of a window (and above the working area) which makes it possible to display buttons, icons etc. in a window.

As already known from the window routines, the management of toolbars is shared betwen the AES and the application. Here the AES is responsible for the following actions:

The application, on the other hand, must look after the following:

For supporting toolbars in your own programs, you should respect the following points:

See also:
WF_TOOLBAR   WF_FTOOLBAR   WF_NTOOLBAR   WM_TOOLBAR   wind_get   wind_set

8.2.8.1 Redraw and updating of toolbars

For redraws of (parts of) the toolbar, one has to pay respect to the rectangle-list as usual. As the previous wind_get opcodes WF_FIRSTXYWH and WF_NEXTXYWH only respect the working area of a window, however, two new parameters (WF_FTOOLBAR and WF_NTOOLBAR) were introduced, with whose help the rectangle-list of a toolbar can be interrogated.

A redraw of (parts of) the toolbar may be necessary in the following situations:

Redraw is not necessary in the following cases, for instance:

See also: Rectangle-list of a window   Toolbar support

8.2.8.2 Toolbars and the window-manager

For handling toolbars an application can have recourse to the window- manager of the AES. In detail:

For tacking on a toolbar to a window, it is sufficient to call wind_set(handle, WF_TOOLBAR, ...) with the address of the toolbar object tree. If this call is executed while the window is open, then it is itself responsible for the correct calculation of the height of the toolbar.

To exchange a toolbar for another one, one can have recourse to a call of wind_set(handle, WF_TOOLBAR, ...) with the address of the new toolbar. If this call is executed while the window is open, then it is itself responsible for the correct calculation of the height of the (new) toolbar.

To remove a toolbar from a window, it is necessary to call wind_set(handle, WF_TOOLBAR, ...) with NULL parameters. If this call is executed while the window is open, then it is itself responsible for the correct calculation of the height of the toolbar.

In addition the following points have to be taken into consideration:

See also: AES   GEM   Toolbar support

8.2.8.3 Problems with wind_calc in toolbar windows

When applying the function wind_calc to windows that possess a toolbar there are several problems to be taken into account:

As this function is not passed a window ID (window handle), the desired sizes cannot be calculated correctly when a toolbar is present in the window. The reason for this is that, quite simply, the AES in this case has no information about the toolbar, and specially about its size.

Hence the values returned by wind_calc in such cases have to be further refined by the application. As the program can access the relevant OBJECT tree (and with this also the height of the toolbar), this should present no problems. In detail:

Note: Besides the height of the actual object, the height of the toolbar should include also the space requirement for special effects (3D, shadowing, etc.).

See also: WF_FTOOLBAR   WF_NTOOLBAR   WM_TOOLBAR   objc_sysvar

8.2.9 AES bindings

The AES is called via a single subprogram that is passed 6 parameters; these are addresses of various arrays that are used for input/output communications. To call an AES function, the following parameter block must be populated with the addresses of the arrays described below:

typedef struct
{
    int16_t *cb_pcontrol;  /* Pointer to control array */
    int16_t *cb_pglobal;   /* Pointer to global array  */
    int16_t *cb_pintin;    /* Pointer to int_in array  */
    int16_t *cb_pintout;   /* Pointer to int_out array */
    int16_t *cb_padrin;    /* Pointer to adr_in array  */
    int16_t *cb_padrout;   /* Pointer to adr_out array */
} AESPB;

The address of this parameter block (which lies on the stack) must be entered in register d1, and subsequently register d0.w must be filled with the magic value 0xc8 (200). With a TRAP #2 system call the AES can then be called directly. For the Pure-Assembler this could look like this, for instance:

                .EXPORT aes         ; Export function
                .CODE               ; Start of the code-segment

        aes:     MOVE.L 4(sp),d1    ; Address of the parameter blocks
                 MOVE.W #200,d0     ; Opcode of the AES
                 TRAP   #2          ; Call GEM
                 RTS                ; And exit

                .END                ; End of the module

There is no clear information available about which registers may be altered. In fact, however, the corresponding routines in ROM save all registers.

Now to the individual arrays. With each field, designated input or output functions can be performed. The following apply:

int16_t control[5] With this field information about the called function and its parameters can be determined. The following apply:
control[0] = Function number (opcode)
control[1] = Number of elements in int_in array the function is being sent
control[2] = Number of elements in int_out array the function is being sent
control[3] = Number of elements in addr_in array the function returns
control[4] = Number of elements in addr_out array the function returns

There is no clear information about which elements must be set before an AES call. It is required in each case for elements [0],[1] and [3]. It seems less sensible for the elements [2] and [4] - after all the AES functions know how many values they return in the output fields.
int16_t global[15] This field contains global data for the application and is used partly by appl_init and partly by other AES functions, and is filled automatically. The following apply:
global[0] Version number of the AES
global[1] Number of applications that can run concurrently; with a value of -1 there is no limit
global[2] Unique ID number of the application
global[3,4] Miscellaneous information that only has meanning for the application, and can be set and read by it
global[5,6] Pointer to a list of pointers to the object trees of the application (is set by rsrc_load)
global[7,8] Address of the memory reserved for the resource file. Only documented by Digital Research and not by Atari.
global[9] Length of the reserved memory. Only documented by Digital Research and not by Atari.
global[10] Number of colour planes. Only documented by Digital Research and not by Atari.
global[11,12] Reserved
global[13] Maximum height of a character, which is used by the AES for the vst_height call. This entry is only available as of AES Version 4.0, and also only documented by Atari.
As of PC-GEM Version 2.0 this value is interpreted as a bit-vector with the drives registered with the desktop (bit 15 = Drive A:).
global[14] Minimum height of a character, which is used by the AES for the vst_height call. This entry is only available as of AES Version 4.0, and also only documented by Atari.
As of PC-GEM Version 2.0 this value is interpreted as a bit-vector that specifies which of the drives listed in global[13] can be regarded as hard drives.
int16_t int_in[16] All 16-bit-sized input parameters are passed with this field.
int16_t int_out[10] All 16-bit-sized return values are supplied by the AES via this field.
int32_t addr_in[8] This field serves for the transmission of pointers (e.g. pointers to character strings) to the AES functions.
int32_t addr_out[2] All 32-bit-sized return values are supplied by the AES via this field.

Warning: If the operating system supports threads, then it is impera tive that a multithread-safe library is used. In particular one must ensure that each thread receives its own global field (see above).

See also: Sample binding   VDI bindings   TOS list

8.2.9.1 Sample binding for AES functions

The function 'crys_if' (crystal interface) looks after the proper filling of the control arrays, and performs the actual AES call. It is passed one WORD parameter in d0 containing the funtion's opcode minus 10 multiplied by 4 (for faster table indexing); this gives an index into a table in which the values for control[1], control[2] and control[3] are entered for each individual AES function.

AESPB c;

int16_t crys_if (int16_t opcode)
{
        int16_t i, *paesb;

        control[0] = opcode;
        paespb = &ctrl_cnts[ (opcode-10)*3 ];

        for (i = 1; i < 4; i++)
                control[i] = *paespb++;

        aes (c);
        return (int_out[0]);

} /* crys_if */

The table used for this could be built up as follows, for instance:

.GLOBAL ctrl_cnts
.DATA

ctrl_cnts: .dc.b     0,  1,  0       ; appl_init
           .dc.b     2,  1,  1       ; appl_read
           .dc.b     2,  1,  1       ; appl_write
            ...
            ...
            ...

.END

A fuller version is given in The Atari Compendium pp. 6.39-41. Note that the rsrc_gaddr call must be special cased in a library if you want to use the crys_if binding to call the AES.

See also: AES bindings   GEM


HomeAESAbout the AESApplication library