AES

About the AES

Application 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:

• Accessories
• Bindings of the AES
• The desktop window
• Data exchange via the GEM clipboard
• Messages
• AES object structure
• Quarter-screen buffer
• Rectangle-list of a window
• Screen-manager
• Toolbar support

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

• Startup-code for accessories
• Accessories in MagiC

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:

• If the register a0 has the value zero at program startup, then we are dealing with a normal program launch.
   

• Otherwise we are dealing with a desk accessory, and register a0 contains a pointer to the (incompletely) filled BASEPAGE. The TPA has already been shrunk appropriately (to the sum of basepage size and the length of the three program segments), but a stack still has to be created.
   

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:

• Even under a multitasking-capable GEM (MagiC or MultiTOS), there can be only one screen background. This should be reserved for the program that can make the most use of it - as a rule this is the desktop or a desktop replacement such as the Gemini shell, Thing or Jinnee for instance.
   

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:

• Delete all clipboard files that match the mask 'scrap.*' and 'SCRAP.*'. Note: The mask 'SCRAP.*' must be allowed for because old programs knew nothing of alternative and case-sensitive file-systems.
• Save the data to be stored in one or several formats.
• Send the message SC_CHANGED to all applications in the system and SH_WDRAW to the system shell.

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:

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):

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:

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:

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.

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:

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:

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

• If an object is both CROSSED and SELECTABLE, then it is drawn as a checkbox.
• If it is CROSSED, SELECTABLE and an RBUTTON, it is drawn as a radio button.
• If it is a button or a box and it is CROSSED, then it is drawn as a raised 3D shape, similar to Motif.
• If a button is CROSSED and DEFAULT, a "Return key" symbol appears on it (rather like NEXTSTEP).
• Boxes and text fields that are CROSSED and CHECKED appear sunken.

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:

• If an object is both DRAW3D and SELECTABLE, then it is drawn as a checkbox.
• If it is DRAW3D, SELECTABLE and an RBUTTON, it is drawn as a radio button.
• If a button is DRAW3D and DEFAULT, a "Return key" symbol will be on it.
• If an object with a 3D border has the WHITEBAK state, then the 3D border will not have a black edge.
• If a radio button or checkbox has the WHITEBAK state, then it will be drawn with a white background rather than in the colour used by 3D objects.

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:

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 above mentioned 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:

• Adaptation of the X- and Y-coordinates of the toolbar when the window is moved or its size is changed.
• Ensuring that the window is configured to the size required by the window components and the toolbar.
• Adjustment of the toolbar's width to the width of the window.
• Redraw of the toolbar on receipt of a WM_REDRAW message.
• Sending of AES messages when the user activates an object of the toolbar.

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

• Construction of an OBJECT tree for the toolbar (in particulat one has to ensure that all selectable elements of the toolbox have the status TOUCHEXIT).
• Adjustment of the width of a toolbar object if this depends on the width of the window (may be required when changing the size of the window).
• Handling of USERDEF objects.
• Redrawing all objects whose appearance is to be changed. In this case it is imperative that the rectangle-list of the toolbar is inquired for and/or taken into account.
• Problems that arise in connection with the screen resolution have to be solved. Thus, for instance, the height of an icon in the ST Medium resolution can differ from the height of the icon in the TT030 Medium resolution.

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

• Communication with the AES window-manager
• Problems with wind_calc
• Redraw and updating of toolbars
• Toolbar support under XaAES

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:

• The toolbar contains user-defined objects (USERDEF's).
• The status of an object in the toolbar was altered. The area to be redrawn here consists of the size of the object plus the space required for special effects (3D, shadowing, outlining etc.).

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

• The relevant window is iconified. The application does not have to take on any management of the toolbar; this is only required at the restoration of the iconification, the so-called uniconify.
• The toolbar present in the window is to be replaced by another one. In this case a call of wind_set with the opcode WF_TOOLBAR and the address of the new OBJECT tree will suffice.
• The toolbar present in the window is to be removed. In this case a call of wind_set with the opcode WF_TOOLBAR and NULL parameters will suffice.

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:

• If a window is closed with wind_close, then any toolbar present will not be removed. At a later reopening the toolbar will be in place once more.
• If a window is removed with wind_delete, then its link to a toolbar will be dissolved.
• To be able to recognize mouse-clicks on toolbar objects, these have to possess the status TOUCHEXIT. When such an object is clicked on, the AES creates a WM_TOOLBAR message which is sent to the relevant application.

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:

• When ascertaining the border areas of the window, the height of the toolbar must be added to the height returned by the function.
• When ascertaining the working area of the window, the height of the toolbar must be added to the Y-value (couty) returned by the function.

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:

Warning: If the operating system supports threads, then it is imperative 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

AES

About the AES

Application library