GEM pages
Home -> GEM -> AES

The Application Environment Services

In this document, I list assembly language and C interfaces to the Intel GEM AES. The C prototypes are similar to those provided by the GEM Developer's Kit, version 3.0. Most of the C interfaces are declared to return WORDs; these will nearly always be the value returned in int_out[0]. The symbol [!] indicates that a function behaves differently in different GEM versions.

This is still a work in progress. Some information is missing or requires additional explanation. The information has been obtained by examining GEM source and bindings rather than published documentation. I have not been able to disassemble GEM/4 enough to find the purposes of various functions; only to note their existence.

The AES deals with drawing windows on the screen, and with managing controls (text fields, buttons etc.).

The AES lives in the file GEM.EXE (in ViewMAX, VIEWMAX.OVL). It is accessed by using INT 0EFh with CX=00C8h and ES:BX=address of parameter block. It also checks for CX=00C9h, but in the single-tasking version this is a no-op.

The parameter block format is:

        DD        CONTROL     ;Address of control array
        DD        GLOBALS     ;Address of globals array
        DD        INT_IN      ;Address of integer input array
        DD        INT_OUT     ;Address of integer output array
        DD        ADDR_IN     ;Address of far pointer input array
        DD        ADDR_OUT    ;Address of far pointer output array

The control array is:

CONTROL: 
        DEFW      function    ;Input:  AES function, 10-134
        DEFW      #int_in     ;Input:  No. of integer parameters
        DEFW      #int_out    ;Input:  Max. no. of return words
        DEFW      #addr_in    ;Input:  No. of pointer parameters
        DEFW      #addr_out   ;Input:  Max no. of return pointers
                                       ;(ignored in single-tasking GEM)

The globals array is used to hold necessary GEM state relating to the current process. It is almost entirely managed by GEM and there are very few occasions when programs need to modify it.

Function 10 - Initialise AES

C Interface: Entered with:

[!] The extra parameter to an X_BUF_V2 is an extension in the FreeGEM AES. If addr_in[0] is set to 1 and an initialised X_BUF_V2 structure is passed in, then on return its arch member will be 0 for DRI GEM or ViewMAX, and 16 or 32 for FreeGEM.

Returns:

Function 11 - Read message pipe

C Interface: Entered with:

rwid is the application ID of the process that owns the message pipe (normally the calling process). This call will block until the required data have been returned.

See the message list for information on standard AES messages. All AES messages are 16 bytes long.

Function 12 - Write message pipe

C Interface: Entered with:

rwid is the application ID of the process to which the data should be sent. This call will block until the data have been sent.

See the message list for information on standard AES messages. All AES messages are 16 bytes long.

Function 13 - Find an application

C Interface: Entered with: Returns:

GEM's internal window manager process is called SCRENMGR.

Function 14 - Play back recorded events

C Interface: Entered with:

Function 15 - Record events to memory

C Interface: Entered with:

Each record in the buffer is 6 bytes; a 2-byte event type and a 4-byte event body:

Type                         Body
=======================================================================
0 = timer event              LONG millis; (Time in milliseconds)
1 = button event             WORD down (1=down 0=up); WORD click_count;
2 = mouse movement event     WORD x; WORD y;
3 = keyboard event           WORD char; WORD keystate;
=======================================================================

Function 16 - Set bitmaps of available drives

C Interface: Entered with:

[!] Not available in GEM 1.1 - added in GEM 1.2.

In GEM/4 and GEM/5, use function 18 to access drives beyond P:

Function 17 - Yield

C Interface: Entered with:

Allows other processes to run.

[!]Not present in GEM/1; it can be simulated by evnt_timer(0,0).

Function 18 - Extended available drive bitmaps

C Interface: Entered with: Returns:

(only if int_in[0] was 0)

[!] This function is only present in GEM/4 and GEM/5.

In addr_in, bit 31 corresponds to drive A:, bit 30 to drive B:, etc.

In addr_out, bit 15 corresponds to drive A: or Q:, 16 to B: or R:, etc.

Function 19 - Finish using AES

C Interface: Entered with:

Free all AES resources used by this program. On single-user versions, close all desk accessories.

Function 20 - Await keyboard event

C Interface: Entered with: Returns:

This call (like all evnt_* calls) will block the calling program until an event is received. If the low byte is 0, then the high byte holds a scancode; otherwise, the low byte holds an ASCII character.

Function 21 - Await mouse click

C Interface: Entered with: Returns:

The mask and state parameters work like this: the call will return when all the appropriate bits of the mouse state match all the appropriate bits of the state parameter. As "Professional GEM" puts it:

It is important to notice that all of the target states in btn_state must occur SIMULTANEOUSLY for the event to be triggered.

Note the limiting nature of this last statement. It prevents a program from waiting for EITHER the left or right button to be pressed. Instead, it must wait for BOTH to be pressed, which is a difficult operation at best.

The mouse button bits are:

The keyboard shift bits are:

Function 22 - Await mouse enter/leave rectangle

C Interface: Entered with: Returns:

The returned values have the same meanings as in evnt_button() above.

Function 23 - Await message

C Interface: Entered with:

Waits for a message to be received.

See the message list for information on standard AES messages. All AES messages are 16 bytes long.

In single-tasking GEM, this is the same operation as reading 16 bytes from the message pipe; see function appl_read()

Function 24 - Sleep

C Interface: Entered with:

Waits until at least the specified time. It may be more, depending on when other processes are blocked.

Function 25 - Monitor all events

C Interface: Entered with: Returns:

The flags word should be set to a bitwise OR of some of:

MU_KEYBD  0x0001  Key event
MU_BUTTON 0x0002  Mouse click event
MU_M1     0x0004  Mouse rectangle 1 enter/leave
MU_M2     0x0008  Mouse rectangle 2 enter/leave
MU_MESAG  0x0010  Message receive
MU_TIMER  0x0020  Timeout
MU_HELP   0x0100  Used in GEM/4 to check for a context-sensitive help request.
On return it will be the type of event that was received.

The parameters and results are as handled by the one-type evnt_*() calls listed above.

Some versions of the GEM Programmers Toolkit have an evnt_evnt() call that takes the evnt_multi parameters in a struct rather than as explicit parameters.

Function 26 - Set double-click time

C Interface: Entered with: Returns:

The double-click rate is 0 (slow) to 4 (fast). It is the length of time GEM waits after a mouse click to see if another mouse click is coming.

Function 30 - Create or remove menu bar

C Interface: Entered with:

Function 31 - Mark menu item as "checked"

C Interface: Entered with:

Function 32 - Mark menu item as enabled/disabled

C Interface: Entered with:

Function 33 - Mark menu item as selected/normal

C Interface: Entered with:

Function 34 - Set menu item text

C Interface: Entered with:

If the segment of the tree address is 0, the offset is the application ID for a desktop accessory. In this case, the text will be set for the accessory's menu item.

In GEM/3, this call actually sets the menu iten's object specification; so if you have bitmaps in your menus, this call could be used to point them at a new BITBLK structure. However, it would be unwise to rely on this implementation detail; better to call this only for menu items that are string objects.

Function 35 - Register a desk accessory

C Interface: Entered with: Returns:

Returns -1 if no spare menu options available.

Function 36 - Unregister a desk accessory

C Interface: Entered with:

Removes the appropriate desk accessory entry from the menu.

[!] Not present in GEM/1.

Function 37 - Set/get menu click options

C Interface: Entered with: Returns:

[!]Only present on GEM/3 and later. This call sets whether a click is needed to drop down menus, or whether the menus just appear when the mouse moves over the menu titles.

Note that this call is not present in the GEM/XM beta, even though it returns a version number of 0x300. It is implemented in recent FreeGEM/XM builds, which signify this by returning a version of 0x301.

Function 38 - Menu modal loop

C Interface:

None is provided, but it would be something like:

Entered with:

[!]This function is only present in GEM/4. It appears to be a modal loop controlling a popup menu (hence can be used for menu bars attached to windows).

Function 40 - Add an object to an object tree

C Interface: Entered with:

Adds the object as the parent's last child.

Function 41 - Delete an object from an object tree

C Interface: Entered with:

The object and all its children will be removed from the tree; unless it's the root object, in which case nothing happens.

Function 42 - Draw an object or object tree

C Interface: Entered with:

Function 43 - Find an object from its coordinates

C Interface: Entered with: Returns:

Function 44 - Find coordinates of an object

C Interface: Entered with: Returns:

Function 45 - Change an object's order in the tree

C Interface: Entered with:

The object and its siblings will be rearranged into the correct order.

Function 46 - Handle a keypress in a text field

C Interface: Entered with: Returns:

Event types are:

#define EDSTART 0   /* No-op in current PC versions */
#define EDINIT 1    /* Editing is starting; cursor position is set to 
                         * end of text */
#define EDCHAR 2    /* Character has been received, process it */
#define EDEND 3     /* Field is losing focus */

Function 47 - Change an object's state

C Interface: Entered with:

Function 50 - Modal entry form

C Interface: Entered with: Returns:

This will enter a modal loop, and not leave it until either:

The source of form_do() is normally provided with GEM developer kits, so that developers can construct versions with special behaviour.

Function 51 - Create or destroy dialog{ue} box

C Interface: Entered with:

The subfunctions are:

#define FMD_START 0 /* Save the screen area that will be overwritten. 
                           Must be called before the box is drawn */
#define FMD_GROW  1 /* Show "zooming box" for form opening */
#define FMD_SHRINK 2    /* Show "zooming box" for form closing */
#define FMD_FINISH 3    /* Restore the screen area that was overwritten. */
[!]The "grow" and "shrink" calls are not implemented in Digital Research's GEM; but GROWBOX.ACC can be used to provide the correct functionality.

Function 52 - Show alert message

C Interface: Entered with: Returns

The message box string is formed of three sections in square brackets: [n][line|line|...][button| button|...]

So, a typical message could be: "[1][The printer is not responding][ Retry | Cancel ]".

[!] ViewMAX/2 and later parse the "default button" parameter as two bytes; the low byte is the default button and the high byte is the cancel button (ESC is a shortcut for it). This style of parameter will crash earlier GEM versions.

Function 53 - Show system alert message

C Interface: Entered with: Returns:

Function 54 - Centre an object on the screen

C Interface: Entered with: Returns:

Function 55 - Handle keyboard event in a modal form

C Interface: Entered with: Returns:

[!] Not available in GEM 1.1 - added in GEM 1.2.

Function 56 - Handle click event in a modal form

C Interface: Entered with: Returns:

[!] Not available in GEM 1.1 - added in GEM 1.2.

Function 57 - GEM/4 Modal entry form

C Interface: Entered with: Returns:

If the context-sensitive help flag is set, pressing the [F1] key will trigger a 'help' mode. Clicking on an object when in 'help' mode then ends the modal loop, with an object number of -1 returned.

[!] This function is only available in GEM/4 and GEM/5.

Function 58 - GEM/4 alert

C Interface: Entered with: Returns

[!] This function is only available in GEM/4 and GEM/5.

If context-sensitive help was chosen, WM_REDRAW messages are sent out to some windows.

[!] The following functions (60-67) are mentioned in the GEM source under the condition "MULTIAPP". They are not included in any single-tasking PC GEM or documented in any known GEM programmer's toolkit; they are present in GEM/XM.

Function 60 - Create a process

C Interface: Entered with: Returns:

This function allocates a process ID, but does not launch the process; Having called it, you should use proc_run() to launch it before calling proc_create() again; GEM/XM doesn't support having more than one newly-launched process waiting around.

Function 61 - Run process

C Interface: Entered with: Returns:

The odd range of values passed to the load options is chosen for compatibility with the "isover" flag of shel_write(). See the GEM/XM Desktop source (pro_exec() in deskpro.c).

Function 62 - Delete processes

C Interface: Entered with:

Shuts down all Desk Accessories. GEM/XM completely ignores the parameter, but the Desktop uses -1.

Function 63 - Process information

C Interface: Entered with: Returns:

Function 64 - Allocate memory

C Interface: Entered with: Returns:

There's a commented-out version of this function in GEM/XM that takes two parameters (address and size) and only returns a success flag.

Function 65 - Free memory

C Interface: Entered with: Returns:

This function appears to be the counterpart of the commented-out proc_malloc() mentioned above. It probably shouldn't be called.

Function 66 - Switch to process

C Interface: Entered with: Returns:

Function 67 - Shrink process memory

C Interface: Entered with: Returns:

Reduces the memory allocated to this process to what it is using now, and creates the swap file used to page it out. Called by programs which were launched with all the memory in the system allocated to them, to give up unused memory.

The source of the GEM/XM Desktop calls this function proc_shrink().

Function 68 - Shrink process memory

C Interface: Entered with: Returns:

Behaves as proc_setblock() above, except that the creation of a swap file is optional.

Function 70 - Drag box for sizing

C Interface: Entered with: Returns:

Returns when the mouse button is released.

Function 71 - Drag box for drag/drop

C Interface: Entered with: Returns:

Returns when the mouse button is released.

Function 72 - Draw moving box

C Interface: Entered with:

This suffers from a slight problem on modern PCs; it draws too fast to see! This problem has been corrected in FreeGEM.

Function 73 - Draw expanding box

C Interface: Entered with:

This animates the "from" rectangle moving to the centre of the "to" rectangle, and then expanding to fill it.

[!] Many versions of Digital Research GEM do not implement this function, and some development kits include dummy bindings that don't call the AES. GROWBOX.ACC implements it on non-equipped GEMs.

Function 74 - Draw contracting box

C Interface: Entered with:

This performs the reverse animation of graf_growbox().

[!]Many versions of Digital Research GEM do not implement this function, and some development kits include dummy bindings for it. GROWBOX.ACC implements it on non-equipped GEMs.

Function 75 - See if a mouse moves off a control

C Interface: Entered with: Returns:

This will return when the mouse button is released.

Function 76 - Handle vertical/horizontal drag

C Interface: Entered with: Returns:

This will return when the mouse button is released.

Function 77 - Get GEM's VDI handle

C Interface: Entered with: Returns:

Function 78 - Set mouse pointer

C Interface: Entered with:

The cursor numbers are:

#define ARROW            0      /* Standard pointer */
#define TEXT_CRSR        1      /* I-beam */
#define HOURGLASS        2      /* Hourglass */
#define POINT_HAND       3      /* Pointing finger */
#define FLAT_HAND        4      /* Dragging hand */
#define THIN_CROSS       5      /* Thin crosshair */
#define THICK_CROSS      6      /* Thick crosshair */
#define OUTLN_CROSS      7      /* Outline crosshair */
#define USER_DEF       255      /* custom shape */
#define M_OFF          256      /* Hide mouse pointer */
#define M_ON           257      /* Show mouse pointer */

Function 79 - Read mouse/keyboard state

C Interface: Entered with: Returns:

Function 80 - Get scrap directory name

C Interface: Entered with: Returns:

[!] This function is not present in ViewMAX.

The file types returned by this function are:

Bit 0:  SCRAP.CSV
Bit 1:  SCRAP.TXT
Bit 2:  SCRAP.GEM
Bit 3:  SCRAP.IMG
Bit 4:  SCRAP.DCA
Bit 15: SCRAP.USR
The path returned will end with a "\".

Function 81 - Set scrap directory name

C Interface: Entered with: Returns:

[!] This function is not present in ViewMAX.

Function 82 - Empty scrap directory

C Interface: Entered with: Returns:

The files deleted are those mentioned earlier:

[!] This function is not present in GEM/1 or ViewMAX.

Function 90 - File selector

C Interface: Entered with: Returns:

[!] This function is not present in ViewMAX/3, and will crash ViewMAX/2.

Function 91 - File selector with title

C Interface: Entered with: Returns: [!] This is only present in FreeGEM. Note that if you are adding a binding for this function, the addr_in[] array may need to be redeclared for 3 entries instead of 2.

To check for this feature, use appl_init() and check that xbuf.arch is nonzero.

[!] This function is GEM/4 and GEM/5 also have a function 91, which behaves differently and is documented below. The FreeGEM function 91 is based on the Atari function of the same number and name.

Function 91 - GEM/4, GEM/5 - File selector

C Interface: Entered with: Returns: [!] This is only present in GEM/4 and GEM/5. It stands in the same relation to the normal file selector as function 57 does to function 50.

Function 100 - Create a window

C Interface: Entered with: Returns:

Single-tasking GEM allows 7 windows (8 including the desktop window). Styles are:

#define NAME    0x0001      /* Titlebar */
#define CLOSER  0x0002      /* Close button */
#define FULLER  0x0004      /* Maximise button */
#define MOVER   0x0008      /* Window can be moved */
#define INFO    0x0010      /* Info bar (below the title bar) */
#define SIZER   0x0020      /* Resize button (bottom right-hand corner) */
#define UPARROW 0x0040      /* "up" button for vertical scroll bar */
#define DNARROW 0x0080      /* "down" button for vertical scroll bar */
#define VSLIDE  0x0100      /* Vertical scroll bar */
#define LFARROW 0x0200      /* "left" button for horizontal scroll bar */
#define RTARROW 0x0400      /* "right" button for horizontal scroll bar */
#define HSLIDE  0x0800      /* Horizontal scroll bar */

[!] The following style is present in GEM/2 and later:

#define HOTCLOSE 0x1000     /* "Hot" close button */
The "hot" close button is used by the two-fixed-windows Desktop in GEM/2 and later. The difference between the "Hot" and normal close buttons is that you can move the mouse pointer out of the close button while holding it down, and WM_CLOSE messages will still be sent to the window.

[!] The following is not supported in PC GEM, but are in other GEMs:

#define SMALLER 0x4000      /* Iconify button */

Function 101 - Open a window

C Interface: Entered with:

Opens a window that has previously been created.

Function 102 - Close a window

C Interface: Entered with:

Closes a window, but does not free its handle. The window can be reopened if desired.

Function 103 - Delete a window

C Interface: Entered with:

Deletes the window, so its slot can be re-used.

Function 104 - Get window properties

C Interface: Entered with: Returns:

The window properties which can be read are:

Window areas (return a rectangle) 
#define WF_WXYWH     4  /* Work area. The area that can be drawn on. */
#define WF_CXYWH     5  /* Current window size/position */
#define WF_PXYWH     6  /* Previous window size/position */
#define WF_FXYWH     7  /* Full window size/position */
#define WF_FIRSTXYWH    11  /* First rectangle needing repainting */
#define WF_NEXTXYWH     12  /* Next rectangle needing repainting */

Sliders (return an integer) 
#define WF_HSLIDE    8  /* Position of horizontal slider, 0-1000 */
#define WF_VSLIDE    9  /* Position of vertical slider, 0-1000 */
#define WF_HSLSIZ       15  /* Size of horizontal thumb, 1-1000 */
#define WF_VSLSIZ       16  /* Size of vertical thumb, 1-1000 */

Others (return various)
#define WF_TOP      10  /* Handle of topmost window, 0 if none open */
#define WF_SCREEN   17  /* Address of AES graphics buffer. */
#define WF_TATTRB   18  /* Window attributes. */

The rectangles WF_CXYWH, WF_PXYWH, WF_FXYWH include window decorations.

WF_SCREEN returns four values: Buffer offset, buffer segment, buffer length (low), buffer length(high). The buffer is used to back up the screen behind menus; if you use it, you should disable menus with wind_update().

WF_TATTRB returns a bitmap in which two bits can be set:

#define WA_SUBWIN 0x01  /* The two windows on a GEM/3 desktop have this 
             * attribute set. If the active window has the 
             * WA_SUBWIN attribute, then other WA_SUBWIN windows
             * on the screen can also get events. */
#define WA_KEEPWIN 0x02 /* In multitasking GEM: the window should not be 
                         * closed when the application runs a DOS program */

[!] In some versions of the FreeGEM AES, it is possible to read the window decorations using this call. To check for this feature, use appl_init() and check that bit 2 of xbuf.abilities is set.

#define WF_OBFLAG  1001 /* Window tree: flag words */
#define WF_OBTYPE  1002 /* Window tree: type words */
#define WF_OBSPEC  1003 /* Window tree: spec dwords */

  wind_get(n, WF_OBFLAG, &a, &b, &c, &d) - a = object flags for decoration "n"
  wind_get(n, WF_OBTYPE, &a, &b, &c, &d) - a = object type of decoration "n"
  wind_get(n, WF_OBSPEC, &a, &b, &c, &d) - (b<<16)|a = spec of decoration "n"

  wind_set(n, WF_OBFLAG,  a,  b,  c,  d) - Set flags for decoration "n" to "a"
  wind_set(n, WF_OBSPEC,  a,  b,  c,  d) - Set spec of decoration "n" to (b<<16)|a


The "n" parameter is one of:

#define W_BOX            0  outline
#define W_TITLE          1  titlebar outline
#define W_CLOSER         2  close box
#define W_NAME           3  titlebar
#define W_FULLER         4  full-size box
#define W_INFO           5  info bar
#define W_DATA           6  work area outline
#define W_WORK           7  work area
#define W_SIZER          8  resize box
#define W_VBAR           9  vertical scroll bar outline
#define W_UPARROW       10  scroll up box
#define W_DNARROW       11  scroll down box
#define W_VSLIDE        12  vertical scroll bar
#define W_VELEV         13  scroll thumb
#define W_HBAR          14  horizontal scroll bar outline
#define W_LFARROW       15  scroll left box
#define W_RTARROW       16  scroll right box
#define W_HSLIDE        17  horizontal scroll bar
#define W_HELEV         18  horizontal scroll bar thumb

Function 105 - Set window properties

C Interface: Entered with:

The window properties which can be set are:

Sliders - take an integer parameter
#define WF_HSLIDE        8      /* Position of horizontal slider, 0-1000 */
#define WF_VSLIDE        9      /* Position of vertical slider, 0-1000 */
#define WF_HSLSIZ       15      /* Size of horizontal thumb, 1-1000 */
#define WF_VSLSIZ       16      /* Size of vertical thumb, 1-1000 */

Strings - these take two parameters, offset and segment
#define WF_NAME     2   /* Window title */
#define WF_INFO     3   /* Info line */

Window size - takes a rectangle as parameter
#define WF_CXYWH    5   /* Window size*/

Others
#define WF_TOP      10  /* Top (active) window */
#define WF_RESVD    13	/* GEM/1.1 window manager lockout */
#define WF_NEWDESK  14  /* Set object tree to draw on desktop*/
#define WF_TATTRB   18  /* Set window attributes */
#define WF_SIZTOP   19  /* Resize window and move to front */
#define WF_COTOP    20  /* To make two windows look like one */

WF_NEWDESK takes three parameters; the first two are the offset and segment of an object tree, and the third is the index of the object within it (normally 0). This tree will then be drawn instead of the standard desktop.

[!]WF_RESVD is only available in GEM/1.1. It takes one parameter, which is nonzero to lock the window manager and zero to unlock it. If the window manager is locked, windows will not be redrawn when they are moved or updated. Releasing the lock causes all windows to be updated.

[!]WF_COTOP is only available in ViewMAX/2 and later. It takes no extra parameters. It sets the window handle passed in int_in[1] as "co-top window" to the currently active window. You can pass a window handle of -1 for "none". When a window's co-top window is active, the window will also be drawn as active. This is for the tree view in ViewMAX, which uses two windows side by side; both must be drawn as active or inactive together.

[!] In some versions of the FreeGEM AES, it is possible to change the window decorations using this call; see wind_get() for details.

Function 106 - Find window from point

C Interface: Entered with: Returns:

Function 107 - Lock screen for drawing

C Interface: Entered with:

If the update flag is 1, then the AES is prevented from making changes to the screen (because the program is drawing on it). If the flag is 0, the AES is allowed to make changes. The update flag can also be 3 (take full control of mouse pointer - like a modal form does) or 2 (release mouse pointer).

Function 108 - Calculate window geometry

C Interface: Entered with: Returns:

Function 110 - Load resources

C Interface: Entered with: Returns:

Function 111 - Free resources

C Interface: Entered with: Returns:

Function 112 - Get resource address

C Interface: Entered with: Returns:

This is the only function in single-tasking GEM which uses addr_out. The resource types that can be passed are:

#define R_TREE       0  /* Object tree
#define R_OBJECT     1  /* Objects (as one big array) */
#define R_TEDINFO    2  /* Text field
#define R_ICONBLK    3  /* Icon
#define R_BITBLK     4  /* Bitmap
#define R_STRING     5  /* Free-form ASCII string */
#define R_IMAGEDATA      6  /* Free-form image data */
#define R_OBSPEC     7  /* Pointer to ob_spec member of object */
#define R_TEPTEXT    8  /* Pointer to te_ptext member of text field */
#define R_TEPTMPLT   9  /* Pointer to te_ptmplt member of text field */
#define R_TEPVALID  10  /* Pointer to te_pvalid member of text field */
#define R_IBPMASK   11  /* Pointer to ib_pmask member of icon */
#define R_IBPDATA   12  /* Pointer to ib_pdata member of icon */
#define R_IBPTEXT   13  /* Pointer to ib_ptext member of icon */
#define R_BIPDATA   14  /* Pointer to bi_pdata member of bitmap */
#define R_FRSTR     15  /* Pointer to free-form strings */
#define R_FRIMG     16  /* Pointer to free-form images */

The call types normally used are R_TREE, R_STRING and R_IMAGEDATA. It is rare that a program needs to access a TEDINFO, ICONBLK or BITBLK directly rather than via its containing object tree.

Function 113 - Set resource address

C Interface: Entered with: Returns:

This is called with one of the "pointer" resource types; R_OBSPEC to R_FRIMG. For example, it could set a new icon bitmap. In general programs manipulate resource pointers themselves rather than using this function.

Function 114 - Fix object positions

C Interface: Entered with:

This will convert an object's dimensions from the form used in the resource file (low byte is dimension in characters, high byte is offset in pixels) to screen coordinates. A height of 25 characters or a width of 80 is taken to mean as high/wide as possible.

Function 115 - Load resources (supports EMS)

C Interface: Entered with: Returns:
[!] This function is only present in GEM/4 and GEM/5. It behaves just like the normal version except that resources can be loaded into EMS memory. If resources are in EMS, then they should only be manipulated using GEM functions, not by trying to access them directly.

Function 116

[!] This function is used in GEM/4 and GEM/5 to manipulate resources in EMS, but exactly what it does is not known.

Function 120 - Read shell command

C Interface: Entered with:

If shel_write() has not been used, this will return the information with which the program was started.

Function 121 - Set next program to execute

C Interface: Entered with: Returns:

Function 122 - Get shell settings

C Interface: Entered with:

This function is intended for use only by the Desktop, to save its state while other programs are executing. Some versions of the GEM PTK do not supply bindings for this function.

The GEM/3 desktop checks if the first byte of this buffer is '#' on launch. If it is not '#', it displays its splash screen on load.

The GEM/3 AES initialises the buffer used by this function to all zeroes, so that the above splash screen check works. Earlier versions of the AES use the buffer to parse DESKTOP.INF, and the first call will return some or all of the contents of DESKTOP.INF.

Function 123 - Save shell settings

C Interface: Entered with:

This function is intended for use only by the Desktop, to save its state while other programs are executing. Some versions of the GEM PTK do not supply bindings for this function.

Function 124 - Find a program

C Interface: Entered with: Returns:

This will search the current directory and the search path.

Function 125 - Read environment

C Interface: Entered with: Returns:

Function 126 - Get the default application name

C Interface: Entered with: Returns:

[!] Not available in GEM 1.1 - added in GEM 1.2.

Function 127 - Set the default application name

C Interface: Entered with:

[!] Not available in GEM 1.1 - added in GEM 1.2.

Function 130 - Calculate intermediate rectangle

C Interface: Entered with: Returns:

Function 131 - Animate transition from one rectangle to another

C Interface: Entered with:

This function and the previous one are used internally in the implementation of graf_growbox() and graf_shrinkbox().

Function 132 - Set a colour category

C Interface: Entered with:

[!] This function is only present in ViewMAX/2 and later. To check for this feature in FreeGEM, use appl_init() and check that xbuf.arch is nonzero. Unfortunately there is no similar test for ViewMAX/2.

The colour categories used by ViewMAX are:

#define CC_NAME         8       /* Titlebar */
#define CC_SLIDER       9       /* Scrollbar background */
#define CC_DESKTOP      10      /* Desktop */
#define CC_BUTTON       11      /* Button and other 3D objects */
#define CC_INFO         12      /* Information bar (below titlebar) */
#define CC_ALERT        13      /* Alert box (ignored) */
#define CC_SLCTDNAME    14      /* Inactive titlebar */

[!] Later FreeGEM builds also allow:

#define CC_3DSHADOW 16      /* Foreground is 3D light colour */
                    /* Background is 3D dark colour */
#define CC_RADIO    17      /* Foreground and background of the */
                    /* radio button "dot" */
#define CC_CHECK    18      /* Colour of the checkbox tick */

To check for this feature, use appl_init() and check that bit 3 of xbuf.abilities is set.

Function 133 - Set desktop image

C Interface: Entered with:

[!] This call is only present in ViewMAX/3.

The "r1" member of the MFDB holds 1 to draw the image centred, 2 to draw it tiled.

Function 1010 - Get property (setting)

C Interface: Entered with: Returns:

"Options" should be 0 if the value is per user, 1 if it is global. Currently has no effect, because GEM does not support user profiles. It is recommended that global settings should be avoided.

[!] This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init() and check that bit 1 of xbuf.abilities is set.

Function 1011 - Put property (setting)

C Interface: Entered with: Returns:

prop_get() will remove any leading spaces from returned values; so if you are writing a string that may start with spaces, you should guard it with quotation marks when calling prop_put() and remove the quotation marks after the prop_get(). Carriage returns and linefeeds must not be written by prop_put().

"Options" should be 0 if the value is per user, 1 if it is global. Currently has no effect, because GEM does not support user profiles. It is recommended that global settings should be avoided.

[!] This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init() and check that bit 1 of xbuf.abilities is set.

Function 1012 - Delete property (setting)

C Interface: Entered with: Returns:

"Options" should be 0 if the value is per user, 1 if it is global. Currently has no effect, because GEM does not support user profiles. It is recommended that global settings should be avoided.

[!] This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init() and check that bit 1 of xbuf.abilities is set.

Function 1020 - Get extended AES information

C Interface: Entered with: Returns:

This call is equivalent to the Atari call, appl_getinfo(). Most of its sections only have meanings on the Atari.

The values returned for each section are:

0
Information about the normal AES font:
  1. font height
  2. font id
  3. font type (0=system, 1=font scale mechanism (FSM) )
1
information about the little AES font:
  1. font height
  2. font id
  3. font type (0=system, 1=FSM )
2
Colours:
  1. VDI device number
  2. number of suppurted OBJECT colors.
  3. Atari color icons are supported (1) or not (0)
  4. Atari enhanced RSCs (>64kB) are possible (1) or not (0)
3
Language:
  1. 0=English, 1=German, 2=French, 3=reserved, 4=Spanish, 5=Italian, 6=Swedish
4
general information 1:
  1. preemptive multitasking (1) or not (0)
  2. appl_find() converts MiNT/AES-IDs (1) or not (0)
  3. appl_search() available (1) or not (0)
  4. rsrc_rcfix() available (1) or not (0)
5
general information 2:
  1. objc_xfind() available (1) or not (0)
  2. reserved, always 0
  3. menu_click() available (1) or not (0)
  4. shel_r/wdef() available (1) or not (0)
6
general information 3:
  1. appl_read(-1,...) available (1) or not (0)
  2. shel_get(addr,-1) available (1) or not (0)
  3. menu_bar(tree,-1) available (1) or not (0)
  4. menu_bar(tree,100) available (1) or not (0)
7
general (MagiC) information:
    • Bit-0 = wdlg_xx() functions available (1)
    • Bit-1 = lbox_xx() functions available (1)
    • Bit-2 = fnts_xx() functions available (1)
    • Bit-3 = fslx_xx() functions available (1)
    • Bit-4 = pdlg_xx() functions available (1)
8
Mouse:
  1. graf_mouse(258-260, addr) available (1) or not (0)
  2. The AES remember the mouse form of each application (1) or not (0)
9
Menus:
  1. MultiTOS compatible submenus available (1) or not (0)
  2. MultiTOS compatible popups available (1) or not (0)
  3. MultiTOS compatible scrollmenus available (1) or not (0)
  4. enhanced MN_SELECTED message available (1) or not (0)
10
shel_write():
  1. available modes:
    • Bit 0..7: highest possible value for doex & 0x00ff
    • Bit 8..15: Bits of doex & 0xff00, that are treated like MultiTOS does.
    • 1: shel_write(0,...) undoes previous shel_write calls (-> the desktop will be started after the actual program)
    • 0: launching programm (MultiTOS like)
    • 1: shel_write(1,...) starts programs after the actual one
    • 0: starts Programs immediately (MultiTOS like)
  4. ARGV via iscr supported (1) or not (0)
11
Windows:
  1. bits that are set represent supported functions:
    • Bit 0: WF_TOP returns the second uppermost window
    • 1: wind_get (WF_NEWDESK)
    • 2: wind_g/set (WF_COLOR)
    • 3: wind_g/set (WF_DCOLOR)
    • 4: wind_get (WF_OWNER)
    • 5: wind_g/set (WF_BEVENT)
    • 6: WF_BOTTOM
    • 7: WF_ICONIFY
    • 8: WF_UNICONIFY
    • 9..15: reserved, always 0
  2. reserved, 0
  3. available window buttons:
    • Bit 0: Iconifier
    • 1: Backdrop-Button (MagiC)
    • 2: Shift-Click for Backdrop
    • 3: "Hot" Closebox (GEM/3 and MagiC)
    • 4..15: reserved, 0
  4. wind_update(256..257) 'check and set' available (1) or not (0)
12
Messages
  1. Bits which are set represent supported messages:
    • 0: WM_NEWTOP
    • 1: WM_UNTOPPED
    • 2: WM_ONTOP
    • 3: AP_TERM
    • 4: MultiTOS like resolution change
    • 5: CH_EXIT
    • 6: WM_BOTTOM
    • 7: WM_ICONIFY
    • 8: WM_UNICONIFY
    • 9: WM_ALLICONIFY
  2. reserved, 0
  3. WM_ICONIFY delivers coordinates (1) or not (0)
13
OBJECTs
  1. Atari-style 3D objects via ob_flags available (1) or not (0)
  2. objc_sysvar() available (1) or not (0)
  3. Speedo- and GDOS-Fonts allowed in the TEDINFO structure (1) or not (0)
    • Bit 0: G_SWBUTTON available
    • 1: G_POPUP available
    • 2: WHITEBAK is used for underlining (MagiC like)
    • 3: G_SHORTCUT available
14
Formulars ( MagiC form_xdo() and form_xdial() )
  1. MagiC like Flydials supported (1) or not (0)
  2. MagiC like key tables supported (1) or not (0)
  3. last cursor position will be returned (1) or not (0)
  4. reserved, 0

[!] This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init() and check that bit 0 of xbuf.abilities is set.

This function corresponds to the Atari function number 130, appl_getinfo().

Function 1030 - Get shell name

C Interface: Entered with: Returns:

[!] This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init() and check that bit 4 of xbuf.abilities is set.

Function 1031 - Set shell name

C Interface: Entered with: Returns:

[!] This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init() and check that bit 4 of xbuf.abilities is set.

Return to archive listing

HTML documentation by John Elliott, Thomas H.