
                       GEM PROGRAMMING by Jomathan White

                                  ARTICLE III
     REFERENCE

     1) Creating Windows

     WORD wind_create(kind,x,y,w,h)
     WORD kind,x,y,w,h

     This function creates (but does not display) a GEM window.
     x,y,w and h are the maximum size the window can be set to.
     kind is a set of bit  flags  which define the 'widgets' (official term
     folks) that the window possesses,  as  follows  (these can be ANDed by
     standard name)

     Bit     Name            Function

     0       NAME    Window has a title bar, and a text title
     1       CLOSER  Window has a close box, and is therefore closeable
     2       FULLER  Window has a 'full' box, and can be maximised
     3       MOVER   Window can be moved if it has a title bar
     4       INFO    Window has a text info line
     5       SIZER   Window has  a sizing dragbox, and is sizable
     6       UPARROW Window has an up arrow
     7       DNARROW Window has a down arrow
     8       VSLIDE  Window has a vertical slidebar / scrollbar
     9       LFARROW Window has a 'move left' arrow
     10      RTARROW Window has a 'move right' arrow
     11      HSLIDE  Window has a horizontal slidebar / scrollbar

     Returns the window handle if successful,  or  -(a number) if no handle
     was available.

     TOS V1.0 and 1.01 had a limit  of  four windows. TOS 1.04 took this up
     to 7. Later versions are limited only by memory.

     Word wind_set(handle,mode,par1,par2,par3,par4)
     WORD handle,mode,par1,par2,par3,par4

     Sets various parameters for GEM windows.   Handle is the handle of the
     window you wish to alter. Par1 to  par4 depend upon the value of mode,
     as follows.. (note, for  brevity  I  have  not included parameters for
     versions of TOS not available to the general public)

     Mode            Function

     WF_NAME         Sets the text in the title bar of the window.
                     Par1 contains the high WORD of the pointer to the
                     string, and Par2 contains the low word.

     WF_INFO         Sets the text in the window info-line. Par1 and
                     Par2 contain the pointer to the string as  above.

     WF_CURRXYWH     Sets the actual size of the window. Par1 to par4
                     contain the x,y,w and h of the new setting, e.g
                     size including window widgets.

     WF_HSLIDE       Sets the position of the horizontal slider. Par1
                     contains the position between 1 and 1000. 1 is
                     leftmost

     WF_VSLIDE       Sets the position of the vertical slider. Par1
                     contains the position between 1 and 1000. 1 is at
                     the top.

     WF_HSLSIZE      Sets the width of the horizontal slider relative
                     to the whole width of the scrollbar. Par1 contains
                     the value.1000 is the full width.

     WF_VSLSIZE      As above, but for the vertical slide bar.


     WORD wind_get(handle, mode, par1, par2, par3, par4)
     WORD handle, mode
     WORD *par1, *par2, *par3, *par4

     NOTE: I am not going to give  the FULL definition of wind_get here, as
     it has a wide range of possible functions. I will list all that I have
     used, plus the other major ones. The more obscure ones can be found in
     any good GEM reference.

     Handle is the handle of the window  about which info is required. Par1
     to par4 are the variables which contain the information after the call
     is made. the information returned is defined by mode, as shown below..

     Mode            Function

     WF_ WORKXYWH    Returns the area of the window minus any windows
                     widgets, i.e. the blank part. Par1 - par4 contain
                     the x,y,w and h of this area.

     WF_CURRXYWH     Returns the actual size of the window, including
                     all window gadgets.

     WF_PREVXYWH     Returns the 'fulled' size of the window prior to
                     the last wind_set call.

     WF_FULLXYWH     Returns the values for the maximum possible size
                     of the window, as set by wind_create().

     WF_HSLIDE       Returns the current position of the horizontal
                     slidebar, in the usual 1-1000 range, in par1.

     WF_VSLIDE       As above, but for the vertical slidebar.

     WF_TOP          Par1 is filled with the handle of the currently
                     active window.

     WF_FIRSTXYWH    Par1 to par4 contain the x,y,w and h of the first
                     visible rectangle in the windows area. If w and h
                     both = 0, the window is completely covered.

     WF_NEXTXYWH     as above, but each time it is called it is for a
                     subsequent rectangle, When w and h both = 0,
                     the end of the list has been reached.

     WF_HSLSIZE      Returns the size of the horizontal slidebar in par1
                     (1-1000)

     WF_VSLSIZE      As above for the vertical slider.

     This function returns 0 if an error occurs.

     WORD wind_open(handle, x, y, w, h)
     WORD handle, x, y, w, h

     Displays the window specified by  handle  on  the screen, with a TOTAL
     size (i.e. with widgets) defined  by  x,y,w  and  h. This will usually
     also trigger a WM_REDRAW message of the working area of the window.

     Returns a 0 if an error occurs.

     WORD wind_calc (form, mode, x1, y1, w1, h1, x2, y2, w2, h2)
     WORD form. mode, x1, y1, w1, h1, x2
     WORD *x2, *y2, *w2, *h2

     This  function  converts  between   full  window  coordinates  (window
     including widgets) and working area coordinates (just the bit you want
     to draw on). You place the set of  data  you have in x1 to h1, and the
     other set is returned in x2   to  h2.  mode  is the set of widgets the
     window has (as  wind_create  above).  If  form  equals  WC_BORDER, the
     system presumes you are passing  whole  window coordinates, and passes
     back the  smaller  work  area  coords.  If  form  equals  WC_WORK, the
     opposite is presumed.

     VOID vs_clip(handle, flag, pxy)
     WORD handle, flag
     WORD *pxy

     Sets the global clipping rectangle  for VDI graphics functions. Handle
     is the workstation  handle.  Flag  =  0  for  clipping  off,  or 1 for
     clipping on. If on, *pxy should point to a GRECT defining the clipping
     rectangle. If flag =0, *pxy should be NULL.

     2) Handling Windows

     WORD evnt_mesag(msg)
     WORD *msg

     This function waits until a message  is  passed to your program by the
     system. Msg points to  this  message  structure  of  at least 16 bytes
     where the message should be placed.  (All  system messages will fit in
     16 bytes).

     msg[0] contains the message type (see below) - usually defined
     constants
     msg[1] contains the ap_id of the sending application
     msg[2] contains the size of the message over 16 bytes (you need
            to use appl_read to get the rest of the message)

     Further values of msg[] array parts are defined by the message type..

     Type            Function

     MN_SELECTED     A menu item has been selected. Msg[3] holds the
                     menu title object number, and msg[4] contains the
                     item object no.

     WM_REDRAW       A portion of the screen needs to be redrawn.
                     msg[4-7] contain the AES rectangle coordinates of
                     the corrupted area.

     WM_CLOSED       The user has clicked on the close box of the window
                     whose handle is in msg[3].

     WM_FULLED       The user has clicked on the full box for the
                     window whose handle is in msg[3]. If not fulled,
                     the window should be fulled. If it is already
                     fulled, it should be returned to its previous size.

     WM_ARROWED      The user has clicked on one of the window contents
                     movement areas. A row/column change is sent when
                     the arrows are clicked. A page message is sent when
                     the area around the slider bar is clicked. The
                     handle of the window is in msg[3], and the
                     contents of msg[4] define what has been clicked.

                             0       page up
                             1       page down
                             2       line up
                             3       line down
                             4       page left
                             5       page right
                             6       column left
                             7       column right

     WM_HSLID        The user has dragged the horizontal slider. the
                     window handle is in msg[3], and the new position
                     (1-1000) is in msg[4].

     WM_VSLID        The user has dragged the vertical slider. the
                     window handle is in msg[3], and the new position
                     (1-1000) is in msg[4].

     WM_SIZED        The user has re-sized the window. Msg[3] contains
                     the handle of the window. Msg[4-7]contain the new
                     size of the window.

     WM_MOVED        The user has dragged the window. Msg[3] contains
                     the window handle, and msg[4-7] contains the new
                     window size and location.

     NOTE: WM_SIZED and WM_MOVED can usually share the same code.

     There are actually  many  other  messages,  some  to  do  with new AES
     functions not in generally  available  versions  of  TOS,  or for MiNT
     processes, etc.. As I am not covering these areas, I have not included
     these messages. If you are  using  MiNT  /  MTOS  /  AES 4.0+, you can
     examine the extra messages in the Atari Compendium or the Modern Atari
     Systems Software book from Hisoft.

     Evnt_mesag always  returns  1,  according  to  Atari.  If  it  returns
     anything else for you, complain to them, not me.

     WORD evnt_timer(lotime,Hitime)
     WORD Lotime, Hitime

     This stops your program for a  specific number of milliseconds. Lotime
     and Hitime are the upper  and  lower  words (respectively) of a 32-bit
     integer that defines how  long  to  wait.  Note  that Atari have never
     guaranteed that this time is accurate, only that the wait time will be
     at  least that long (fat lot of good that is..). The main use for this
     function is with both variables  set  to  0,  to allow multitasking to
     continue by releasing the system.  Once  one  round  of other apps has
     been performed, control is  returned  to  your  program. This function
     also always returns 1.

     3) Redrawing Your Window

     WORD graf_mouse(mode, form)
     WORD mode
     VOIDP form

     This function controls the shape and function of the mouse pointer, as
     follows..

     Mode            Function

     ARROW           Change to default arrow
     TEXT_CSR        Change to I-bar
     BUSY_BEE        Change to bee
     POINT_HAND      Change to pointing hand
     FLAT_HAND       Change to open hand
     THIN_CROSS      Change to one pixel width (of lines) cross
     THICK_CROSS     Change to 3 pixel width (of lines) cross
     OUTLN_CROSS     Change to outline of THICK_CROSS
     USER_DEF        Change to user defined form as pointed to by form
                             (see below)
     M_OFF           Remove the mouse cursor from the screen
     M_ON            Put the mouse back on the screen

     FORM is a structure containing the  custom  mouse form, and is defined
     as follows.. (for other MODEs, FORM is null)

     typedef struct {
                     short mf_xhot;  /* x posn of hotspot in 16*16 grid */
                     short mf_yhot;  /* y posn of hotspot in 16*16 grid */
                     short mf_nplanes; /* no. of col planes (1 only ) */
                     short mf_fg;    /* foreground colour */
                     short mf_bg;    /*background colour */
                     short mf_mask[16]; /* 16 bytes mask data */
                     short mf_data[16];  /* 16 bytes form data */
                     }MFORM;

     WORD wind_update(flag)
     WORD flag

     Locks the screen while you redraw  a  window. No dialog boxes will pop
     up and no menu item can be activated. This way, you know that no other
     area will  be  corrupted  while  you  are  redrawing  the  screen. The
     function is defined by the value of flag,

     Flag            Function
     BEG_UPDATE      Notify AES you are beginning a redraw, and freezes
                     the screen
     END_UPDATE      Frees the screen
     BEG_MCTRL       prevents the mouse being accessed by processes
                     other than yours
     END_MCTRL       Gives the mouse back to the system


     5) Window Cleanups

     WORD wind_close(handle)
     WORD handle

     This function removes the window  associated  with the value of handle
     from the  screen.  Note  all  the  relevant  data  structures  are not
     cleared, and wind_set and wind_get  will  still work, though they will
     occasionally give odd results..

     WORD wind_delete(handle)
     WORD handle

     This function actually erases the  window  associated with handle from
     the system,  and  frees  the  value  of  handle  to  be  re-used  (not
     necessarily by your application).
