                 GEM Programming                        Article II

                           QUICK REFERENCE GUIDE

A lot of these functions  are  information  functions and therefore refer to
parts of the system or other functions  that haven't been discussed yet. So,
if something seems unclear, hold on  a  while, and hopefully a later article
will make it clear.

1) Initialising the AES

WORD appl_init(void)
Notifies the AES that you wish to start a GEM application.
Returns the application's global identifier.

Also initialises the applications global array. This array is handled
differently by different compilers, but it's contents are listed as
follows.

[0]     AES version number.
[1]     No. of processes which the AES  can run at once. Single tasking
        OS's return 1, Multi tasking OS's return -1.
[2]     Application Identifiers (as returned by appl_init).
[3-4]   LONG which the application can use.
[5-6]   Pointer to the beginning of are for loading resources into
        with rsrc_load.
[7-12]  Reserved.
[13]    Maximum character size available via VST_HEIGHT. Only with AES
        version 0x0400.
[14]    Minimum character size available via VST_HEIGHT. Only with AES
        version 0x0400.

WORD appl_write(ap_id,length,message)
WORD ap_id      The global id of the application to send the message to
WORD length     The number of bytes to be written to the message pipe
VOID *message   The actual message data

        Sends the buffered data as a message to the target application.
        Returns 0 if the message was sent successfully.

Since all AES messages are 16 bytes long, it is a good idea to use the
same length, This greatly simplifies the target applications event
processing.

As of TOS 1.04, DA's may send MN_SELECTED messages to the desktop to
access desktop functions.

As of TOS 4.00, you can use shel_write(7,...) to send a message to
ALL currently running processes.

WORD appl_read(ap_id,length,message)
WORD ap_id      The global id of the current application
WORD length     The number of bytes to be read from the message pipe
VOID *message   The place in memory where the message is to be stored.

        This routine waits until a message is in the pipe of the correct
length, then places it  in the relevant area of ram. Note that it is
possible to use evnt_mesag or evnt_multi to check for messages which do
not halt the application As of AES V 4.0, using an ap_id of -1 causes the
function to reurn immediately if no message is available.

        Again, it is advised to use messages of the same length as the
standard AES messages (16 bytes).

WORD appl_find(filename)
CHAR *Filename  Standard C string of the target applications filename,
                without extension. It is therefore 9 bytes long.

        This routine checks if an application with a particular filename
(of it's executable file) is currently running. If so, It returns that
applications global is. If not, it returns -1.

        This function has been extended in AES 4.0 and above. If the
upper word of Filename is 0xFFFF, the lower word is presumed to be a MiNT
id, and the function returns the AES id. If the upper word of Filename is
0xFFFE,  the reverse is presumed. If the upper word is 0x0000, the current
processes ap_id is returned.

WORD appl_search(mode, filename, type, ap_id)
WORD mode               0 = return the filename of the first process
                        1= return the filename of a subsequent process

Char *Filename  As above

WORD *type              1 = search system processes
                        2 = search applications
                        4 = search accessories
WORD *ap_id     returns the global id of the next process to match the
                search criteria.

NOTE:   This call is only available if the current system runs AES 4.0
or above.

        returns 0 if no app that fits can be found, or 1 if it has found
a matching process.


WORD appl_getinfo(ap_gtype,ap_gout1,ap_gout2,ap_gout3,ap_gout4)
WORD ap_gtype   A word flag that defines the information returned
WORD *ap_gout1
     *ap_gout2
     *ap_gout3  All contain information returned, depending upon the value
     *ap_gout4  of ap_gytpe.

NOTE: This function is only available in AES 3.40 or later, and ap_gtype
      >4 is only supported in AES v4.1 or over.

        Depending upon the value of ap_gtype, ap_gout1 to ap_gout4 are
filled with values as the following. If a variable is not mentioned, it
is not used.

If ap_gytpe=0, the information returned is about the standard AES font as
                follows
                ap_gout1=pointsize
                ap_gout2= Font id
                ap_gout3= 0 for bitmap font, 1 for vector font

if ap_gtype=1, the information is about the AES small font, as above

if ap_gtype=2, the information is about the video display.
                ap_gout1=resolution number, as returned by Getrez.
                ap_gout2=The number of colours the AES object library
                        supports
                ap_gout3=1 if colour icons are supported, or 0 if they
                        are not
                ap_gout4=1 if 'new' resource files are supported, or 0 if
                        only standard ones are.

if ap_gtype=3, the info is about the language the AES is using.
                ap_gout1=       0 for English
                                1 for German
                                2 for French
                                3 is reserved (why??)
                                4 for Spanish
                                5 for Italian
                                6 for Swedish (was not implemented)

if ap_gtype=4,  the info is classed as Environment info..
                ap_gout1=0 for cooperative multitasking, 1 for pre-emptive.
                ap_gout2=1 if appl_find can convert between MiNT and AES
                                process identifiers, or 0 if it can't.
                ap_gout3=1 if appl_search is available, and 0 if it not.
                ap_gout4=1 if rsrc_rdfix is available, or 0 if it isn't.

if ap_gtype=5, the info is further general system info.
                ap_gout1=1 if objc_xfind is available, and 0 if it isn't.
                ap_gout2 is reserved..
                ap_gout3=1 if menu_click is available
                ap_gout4=1 if shel_rdef and shel_wdef are available

if ap_gtype=6, the info is the final batch of general system info.
                ap_gout1=1 if you can use -1 as an ap_id for appl_read
                ap_gout2=1 if you can use -1 as a length parameter for
                                shel_get
                ap_gout3=1 if you can use -1 as a mode parameter for
                                menu_bar
                ap_gout4=1 if you can use MENU_INSTL as a mode for
                                menu_bar

if ap_gtype=7, the information is currently 'reserved' (very useful that
                is then...)

If ap_gtype=8, the information is to do with mouse support.
                ap_gout1= if you can use 258-260 as a mode parameter for
                                graf_mouse
                ap_gout2=1-AES controls the mouse form, 0- the application
                                controls the mouse form

If ap_gtype=9, the information is about menu support.
                ap_gout1=1 if MULTITOS submenus are available or 0 if
                                submenus aren't supported.
                ap_gout2=1 if MULTITOS popupmenus are available
                ap_gout3=1 if MULTITOS scrollable menus are supported
                ap_gout4=1 if the message MN_SELECTED contains object tree
                                information in msg[5-7]

if ap_gtype=10, the information is about shel_write..
                ap_gout1= when &'d with 0x00FF, indicates the highest
                                value for the mode parameter.
                          when &'d with 0xFF00, indicates which extended
                                shel_write mode bits are supported
                ap_gout2=0 - shel_write with a 0 mode parameter launches
                                an application
                         1 - shel_write with a 0 mode parameter cancels
                                the previous shel_write.

                ap_gout3=0- shel_write takes effect when the current app
                                quits
                         1- shel_write takes effect immediately

                ap_gout4=1 - ARGV parameter passing is available
                         0 - It isn't.

if ap_gtype=11, the information pertains to the windowing system
                ap_gout1= a bitmap for extended option for wind_get and
                                wind_set
                        0       WF_TOP returns window below the top
also
                        1       WIND_GET(WF_NEWDESK..) is available
                        2       WF_COLOR can be set /queried
                        3       WF_DCOLOR  "    "       "
                        4       WF_OWNER        "       "
                        5       WF_BEVENT       "       "
                        6       WF_BOTTOM       "       "
                        7       WF_ICONIFY      "       "
                        8       WF_UNICONIFY    "       "
                        9-15    UNUSED

                ap_gout2 = unused

                ap_gout3 = a bitmap of extended window gadgets that are
                                available
                        0       Iconifier gadget can be used
                        1       Bottomer gadget can be used
                        2       SHIFT-CLICK sends window to bottom
                        3       "hot" close box supported
                        4-15    unused

        (NOTE: as far as I am aware NONE of these gadgets are available in
any TOS version available to the general user. However, many are available
in current developer versions of TOS 5 / MTOS).

If ap_gtype=12, extra message support info is returned..
                ap_gout1= A bitmap of extra messages which are available.
                        0       WM_NEWTOP
                        1       WM_UNTOPPED is sent
                        2       WM_ONTOP is sent
                        3       AP_TERM may be received
                        4       Shutdown and resolution change messages
                                        are used.
                        5       CH_EXIT is sent
                        6       WM_BOTTOM may be sent
                        7       WM_ICONIFY is sent
                        8       WM_UNICONIFY is sent
                        9       WM_ALLICONIFY may be received.
                        10-15 unused

                ap_gout2=is a further bitmap, reserved for future use

                ap_gout3=is a bitmap defining a certain message behaviour.
                         If bit 0 is set, then wm_iconify gives a message
                         to where to iconify to. The rest of the word is
                        currently unused.

if ap_gtype=13 extended object support flags are returned
                ap_gout1= 1 if 3d AES objects are supported
                ap_gout2=       0- objc_sysvar is not available
                                1-MultiTOS objc_sysvar is available
                                2- Other form of objc_sysvar is available.

                ap_gout3=       1 if GDOS fonts may be used in objects
                                0 only the system font may be used

if ap_gtype=14 data is supplied on enhancements to form_do.
                ap_gout1 =1 if 'flying' dialogs are supported

                ap_gout2 = 1 if Mag!x keyboard tables are available

                ap_gout3 = 1 if the last cursor position is returned by
                                form_do


WORD graf_handle(wcell, hcell, wbox, hbox)
WORD *wcell,*hcell,*wbox,*hbox
        returns the VDI handle for the current physical workstation (the
screen...) and
        wcell, hcell - width and height of the system character set
        wbox, hbox - minimum  width  and  height  of  the dialog box BOXCHAR
object


WORD appl_exit(void)
        The last AES/VDI call a GEM app should make. Returns a 0 if an
error takes place while exiting, although no-one actually knows what you
are supposed to DO if it does that..


2) Initialising the VDI
WORD v_opnvwk(work_in, handle, work_out)
WORD *work_in, *handle, *work_out

Handle should pass to the function the VDI physical workstation handle
returned by graf_handle. Upon return it contains the VDI workstation
handle (which is used for any drawing functions) or 0 if no virtual
workstation is available.
work_in is an array of 11 items defined as follows
        0       Device ID number. Getres+2 for screens, as defined in
                                assign.sys for others.
        1       Default line type
        2       "       line color
        3       "       marker type
        4       "       marker color
        5       "       font
        6       "       text colour
        7       "       fill interior
        8       "       fill style
        9       "       fillcolour
        10      0 - use NDC coordinates
                1- use raster coordinates
                NDC coordinates only function if GDOS is available

work_out is an array of 57 WORDS. Not all of these are really relevant, so
to conserve space I shall only list the most useful. Some are defined in
AES.H, and those names are listed

        0       (width of device in pixels) - 1         (xres)
        1       (height of device in pixels)-1          (yres)
        5       No. of character heights (0=vector text)(cheights)
        13      No. of colours available                (colors)
        35      color capable(0=no)                     (cancolor)
        36      text rotation (0=no)                    (cantextrot)
        39      no of palette entries   0 = >32667
                                        2= monochrome   (palette)
                                        else =no. colors

If you wish to know more of these, consult the compendium, or any other
good GEM reference source.

WORD v_opwk work_in, handle, work_out)
WORD *work_in, *handle, *work_out
                This function is identical to v_opnvwk with a couple of
exceptions. Firstly, on calling handle need not have any specific value
(the handle of the workstation to open is in work_in[0] ). On return it
will contain the workstation handle or 0 if the call fails. Note that
Atari programming guidelines recommend only opening a physical device
when you are ready to use it, as other apps may change the status of the
device while you have it open otherwise.

WORD vq_extnd(handle, mode,work_out)
WORD handle, mode
word *work_out
        handle is as for v_opnvwk.
        If mode = 0, work_out is filled with the same info as for
                v_opnwvk. However, if mode = 1, further information is
                returned. Again, listing all 57 items is, frankly, more
                than my tired fingers could stand. However, here are the
                most useful items again..
        5       0= lookup table not used (therefore truecolour) (lut)
        8               0= no character rotation available
                        1= 90o rotations available              (textrot)
                        2 = any angle of rotation available


VOID v_clsvwk(handle)
WORD handle
        Closes the workstation. Handle contains the VDI workstation handle
to close.


3) Loading a Resource File

WORD rsrc_load(Filename)
CHAR *Filename
        Filename is a null-terminated string specifying the resource file
to load. returns 0 if unsuccessful.


WORD rsrc_free(void)
        returns 0 if the resource cannot be cleared. Quite what you do
then is anyone's guess...

