
   This text is NOT, that is _NOT_, official yet, as it is more a collection 
 of notes for myself to remember right now. Consider everything in this 
 textfile unusable/unimplemented unless clearly noted otherwise!

  Intention is that this file will contain documentation on new calls/things 
 added to XaAES. This file will also contain known differences between XaAES 
 and other AES's.

===============================================================================
                            -= The N.AES cookie =-

 Because some programs insists on appl_control(), for example, instead of
checking with appl_getinfo(), XaAES now has an option to install a fake
'nAES' cookie. You enable this option by setting;

naes_cookie = yes

 in your xaaes.cnf.

 This fake cookie contains the following;

static N_AESINFO naes_cookie =
{
 0x0300,             /* version 0.3.0 */
 (25<<9)|(1<<5)|1,   /* 1 jan, 2005   */
 (1<<11)|(2<<5)|3,   /* 01:02:03      */
 0x8000,             /* Bit 15 set indicates that this really is XaAES */
 0L,
 0L,
};

 This structures element will never change under XaAES. Since N.AES does not
to be in development anymore, it is unlikely it will ever hit version 0.3.0.
Furthermore, if date and time is Jan 1st, 2005/01:02:03 together with bit
15 set in flags, one can safely assume this is the XaAES fake N.AES cookie.

 It is extremely strongly recommended that one does NOT check cookies at
all when determining function availability of any AES. The info above is more
of interest to authors of sysinfo software, etc., and must not be used for
anything else.

===============================================================================
                            -= Detecting XaAES =-

 appl_getinfo() is the correct call to use if the application wants to know
 which AES it runs under.

 Normal binding;

 INPUT:
  control[0]    130                              Opcode
  control[1]      1                              Elements in intin
  control[2]      5 (or 1 - extended appl_info)  Elements in intout
  control[3]      0 (or n - extended appl_info)  Elements in addrin
  control[4]      0                              Elements in addrout

  intin[0]        Mode

 OUTPUT:
  intout[0]       Return value - 0 = failure, 1 = success
  intout[1]       ap_gout1
  intout[2]       ap_gout2
  intout[3]       ap_gout3
  intout[4]       ap_gout4

 With extended appl_info, control[N_ADDRIN] and control[N_INTOUT] is consulted
 to determine what information should be returned based on 'Mode'. The meaning
 of the different extended parameters are documented for each extended 'Mode'.

 If control[N_INTOUT] have a value of 1, the normal ap_gout[1-4] elements are
 not used.

 If control[N_ADDRIN] have a value other than 0, then pointers are passed in
 addrin[0 .. N_ADDRIN], whose value depends on the 'Mode' being used.


 AES_WINDOW (11) - XaAES adds the following;

 'ap_gout1'     Bit  9 wind_get/set(WF_WHEEL)
                Bit 10 wind_get(WF_FIRSTAREAXYWH)
                Bit 11 wind_get/set(WF_OPTS)
                Bit 12 wind_get/set(WF_MENU) 

 AES_MESSAGES (12) - XaAES addes the following;

 'ap_gout1'     Bit 10 WM_REPOSED supported.

---------------------- Extended appl_info() modes --------------------------

 AES_VERSION (96)

 This is a new extended mode which will return detailed version information
 about the AES. When control[N_INTOUT] == 5, the following is filled into
 ap_gout[1-4];

  ap_gout1 = Major version number (decimal)
  ap_gout2 = Minor version number (decimal)
  ap_gout3 = Development Status (Beta, alpha, etc.)
  ap_gout4 = Target platform (m68k, etc.)
 'ap_gout1' &     Together, these two contain the decimal representation of
 'ap_gout2'       the AES's version number. For XaAES v0.992, 'ap_out1'
                  contains 0 (0x0000) and 'ap_out2' contains 992 (0x3e0).
 'ap_gout3'       This is a 16-bit integer where bits 0-7 (the low byte) is
                  a value indicating the development status of the AES,
                  see below (AES_DEVSTATUS_xxx) for meaning of different
                  values. Bits 8-15 are flags, see below (AES_FDEVSTATUS_xxx)
                  for current definitions.
 'ap_gout4'       This is a value indicating which platform the AES was built
                  for. See below (AES_ARCH_xxx) for meaning of different
                  values.

 When control[N_ADDRIN] == 4, the meaning of the pointers and what is filled
 is defined as follows;

  addrin[0]     'aes_id' pointer
  addrin[1]     'long_name' pointer
  addrin[2]     'info_string' pointer
  addrin[3]	reserved, set to NULL.
 
 'aes_id'       This is a character string with a fixed lenght of 8 bytes,
                into which the AES will write its unique AES ID.
                the AES ID is a right-aligned, space padded string, and can
                be considered to be the current AES's short name.
                For XaAES this string is filled with "   XaAES".

 'long_name'    This is a character buffer that the application must ensure
                can take up to 256 (255 + 0 termination) characters. The AES
                fills its long name description into this buffer. Lines in
                here are delimitted using CR (ascii 13). For XaAES, this
                buffer contains the following after the call;

                "XaAES Ain't the AES, a free MultiTasking AES for FreeMiNT"

 'info_string'  This is a character buffer that the application must ensure
                can take up to 256 (255 + 0 termination) characters. The AES
                fills this buffer with the following information where each
                element is delimitted by the "|" (ascii 0x7c) character.
                The string is constructed as follows;

                "asci version|development status|architecture target|
                 build date & time|compiler used",0

                Example string returned might be;
                "0.992|Alpha|m68k|Dec 17 2004 22:58:52|gcc 2.95.3",0
 
 Here are new appl_info() constants to add to your header file;

/*
 * AES_VERSION mode for appl_init()
 */
#define AES_VERSION  96

/*
 * Target architecture definitions, returned by
 * appl_getinfo(AES_VERSION) in ap_gout4.
 */
#define AES_ARCH_M68K 0

/*
 * Development status - values low byte returned
 * by appl_getinfo(AES_VERSION) in low byte of ap_gout3 
 */
#define AES_DEVSTATUS_ALPHA   0
#define AES_DEVSTATUS_BETA    1
#define AES_DEVSTATUS_RELEASE 2
/*
 * Development status flags - bits 8-15 of ap_gout3
 * returned by appl_getinfo(AES_VERSION)
 */
#define AES_FDEVSTATUS STABLE 0x100

===============================================================================
                       -= New window kind definitions =-

 XaAES now makes use of bit 15 in the 'kind' parameter of wind_create(). Setting
this bit will make XaAES allow for window border sizing without the SIZER gadget
being used.

#define BORDER  0x8000

 I hope this bit is not used for other purposes. This also means there is no
more free bits, and so future extensions will have to require an extended
wind_create() call. As of now, if control[1] has a value of 6 or more, XaAES
will pick up another 16-bits (short) of 'kind' bits from intin[5]. However,
no definitions are made yet.

===============================================================================

                            -= Shading windows =-

   XaAES now supports shading like N.AES and MagiC supports it, except from
 one important point; ALL window status'es remains across
 close_wind()/open_wind() calls, INCLUDING shaded. That means one should
 not rely on the fact that SHADED status will be cleared when one closes
 the window, like other AES's do. Instead, if you want to control SHADE
 status of a window, use the documented;

     wind_set(wh, WF_SHADE, mode, p2, p3, p4)

     'mode' selects wether to SHADE (mode = -1) or UNSHADE (mode = 0) the
     window in question. p2, p3 and p4 are usused at the moment and
     must be set to 0.

===============================================================================
=                            wind_set() extensions                            =
-------------------------------------------------------------------------------

 short wind_set(short handle, short mode,
                short p1, short p2, short p3, short p4);
 {
 	intin[0] = handle;
 	intin[1] = mode;
 	intin[2] = p1;
 	intin[3] = p1;
 	intin[4] = p1;
 	intin[5] = p1;
 }

 GEM arrays as follows:

	Address     Element    meaning 
        ------------------------------------------------------
        control    control[0]   105        # Opcode
        control+2  control[1]   6          # Entries in intin
        control+4  control[2]   1 (or 5)   # Entries in intout (XaAES only)
        control+6  control[3]   0          # Entries in addrin 
        control+8  control[4]   0          # entries in addrout 
        intin      intin[0]    handle
        intin+2    intin[1]    mode
        intin+4    intin[2]    p1
        intin+6    intin[3]    p2
        intin+8    intin[4]    p3
        intin+10   intin[5]    p4
        intout     intout[0]   Return value (1 = OK, 0 = error)

      XaAES uses the following extra output elements if control[2]
      indicates the application wants it:

        intout+2   intout[1]
        intout+4   intout[2]
        intout+6   intout[3]
        intout+8   intout[4]

 XaAES wind_set() extensions;
...............................................................................
 wind_set(handle, WF_CURRXYWH, x, y, w, h);

   Compatible with all other AES's, except from the following points;

   1. If x, y, w and h all have a value of -1, XaAES ignores the call,
      but fills in any return values when needed (see below).
   2. x and y values of -1 are 'legal', i.e, one cannot use -1 to use
      any old x value. Ofcourse, x and y coordinates are checked to be
      inside the rootwindow (not X when noleft = false).
   3. When h have a value of 0, the window is infact shaded. This is a thing
      N.AES does with MiNTSetter, altho I'm not sure this is correct.
      The application is sent a WM_SHADED. On the next
      wind_set(handle, WF_CURRXYWH,...) where the h coordinate is not equal
      to the window's shaded height, the window is unshaded. While the
      window is shaded via this method, shift-clicks on the window title to 
      shade a window is ignored.

   Placing a value of 5 in control[2]:
   1. XaAES returns the CURRXYWH of the new position the window was moved to,
      removing the need for a wind_get(handle, WF_CURRXYWH,...) call.

  Note: wind_set(handle, WF_CURRXYWH, -1, -1, -1, -1); will return exactly
        the same as wind_get(handle, WF_CURRXYWH);
...............................................................................
 wind_set(handle, WF_PREVXYWH, x, y, w, h);

   If either x, y, w or h have a value of -1, that coordinate is not changed.
   If ALL coordinates have a value of -1, the window is actually moved to the
   current PREVXYWH coordinates, making the current window position the new
   PREVXYWH position.

   Placing a value of 5 (or more) in control[2]:
     1. XaAES returns the resulting PREVXYWH, which the window will be moved to
        on the next use of the FULLED gadget or...
     2. When all coordinates passed have a value of -1, XaAES return the
        CURRXYWH of the new position the window was moved to, removing the
        need for a wind_get(handle, WF_CURRXYWH,...) call.
 
-------------------------------------------------------------------------------
 wind_set(handle, WF_FULLXYWH, x, y, w, h);

   If either x, y, w or h have a value of -1, that coordinate is not changed.
   If ALL coordinates have a value of -1, the window is actually moved to the
   current FULLXYWH coordinates, making the current window position the new
   PREVXYWH position.

   Placing a value of 5 (or more) in control[2]:
     1. XaAES returns the resulting FULLXYWH, which the window will be moved to
        on the next use of the FULLED gadget or...
     2. When all coordinates passed have a value of -1, XaAES return the
        CURRXYWH of the new position the window was moved to, removing the
        need for a wind_get(handle, WF_CURRXYWH,...) call.
 
-------------------------------------------------------------------------------
 wind_set(handle, WF_OPTS, mode, wopt0, wopt1, wopt2);

 'handle'     is window handle or -1. If handle is a legal window handle,
              the options will only apply to that window. If 'handle' is
              -1, the settings will apply to all windows the application
              creates AFTER this call.

 'mode'       is 0 to clear the selected bits or 1 to set the selected bits.

 'wopt0'      Currently available options are as follows;

           #define WO0_WHEEL           0x0001
              Setting this bit will enable extended mouse wheel support, and
              go into WHL_AROWWHEEL mode causing XaAES to send extended
              WM_ARROWED messages to the application when the mouse wheel turns.
              Read section "XaAES and wheel mouse handling." for details.

           #define WO0_FULLREDRAW      0x0002
              Setting this bit will make XaAES send WM_REDRAW messages to cover
              the whole work-area of the window when it is FULLED. Default
              behaviour is to only send WM_REDRAW messages for the areas that
              need it, blitting the already visible parts. This can also be
              configured via xaaes.cnf, see the app_options argument 'naesff'.

           #define WO0_NOBLITW         0x0004
              Setting this bit will make XaAES send WM_REDRAW messages to cover
              the whole work-area of the window when its WIDTH changes. This is
              handy for apps like HighWire, Textprocessors ,etc, that need to
              reformat when window width changes. Default behaviour is to send
              WM_REDRAW messages for the areas that need it.

           #define WO0_NOBLITH         0x0008
              Setting this bit will make XaAES send WM_REDRAW messages to cover
              the whole work-area of the window when its HEIGHT changes.
              Default behaviour is to send WM_REDRAW messages for the areas
              that need it.

           #define WO0_SENDREPOS       0x0010
              Setting this bit will make XaAES send a WM_REPOSED(38) message
              when a windows X/WIDTH and/or Y/HEIGHT coordinate pair changes.
              Such changes happes when the user resizes the window using
              upper/left borders. Default behaviour is to first send a WM_MOVED
              followed by a WM_SIZED message under these conditions, because
              older apps dont evaluate the WIDTH/HEIGHT in WM_MOVED messages.
              So, dudes, set this bit and use WM_REPOSED! :)

 'wopt1'      Currently undefined and must be cleared.
 'wopt2'      Currently undefined and must be cleared.

 usage:
      wind_set(handle, 1, wopt0, wopt1, wopt2); to set selected bits
      wind_set(handle, 0, wopt0, wopt1, wopt2); to clear selected bits

-------------------------------------------------------------------------------
===============================================================================
                       XaAES and wheel mouse handling.

  This has changed a little compared to the original documentation and
 implementation. When the wheel is on a window whose owner dont know about
 mouse wheels at all, normal WM_ARROWED messages are sent, regardless wether
 the window has ARROW gadgets or not.
  There is no extra info added to these messages in this case, as it were in
 the original implementation.

  Currently mouse wheel events are sent to the owner of the window underneath
 the mouse pointer in all cases except when owner of mouse_lock() is waiting
 for MU_WHEEL.

  For programmers who want to take advantage of mouse wheels in a better way,
 here's an overview;

  wind_set(handle, WF_WHEEL, mode, wheel_mode, 0, 0);

  handle      Window handle, or -1 if one wants settings to apply to all windows
              created hereafter by the application.
  
  mode        0 = Turn extended wheel awareness off, 1 = Turn on.
  
  wheel_mode
           WHL_REALWHEEL ( 0 )
              When wheel_mode is set to 0 (XWHL_REALWHEEL), XaAES will send
              real wheel messages, constructed as follows;

              msg[0] = WM_WHEEL ( 345 )
              msg[1] = ID of sender
              msg[2] = ...
              msg[3] = window handle
              msg[4] = Mouse X
              msg[5] = Mouse Y
              msg[6] = keyboard shift status
              msg[7] = Wheel info
  
              'wheel info' consists of the following data;
              bits 0-7    - Wheel amount
              bits 8-11   - orient
              bits 12-15  - Wheel ID
 
              'orient' is a bitmask where bit 0 indicates direction, and
              bit 1 indicates orientation;

               bit 0  -  0 = up or left
                         1 = down or right
               bit 1  -  0 = vertical (bit 0 indicates UP/DOWN)
                         1 = horizontal (bit 0 indicates LEFT/RIGHT)

              'wheel ID' contains the wheel number. 0 is wheel #1, etc..
              'wheel amount' holds the number of wheel-turns.
      
           WHL_AROWWHEEL ( 1 ) This is the default wheel_mode set if the
              value passed is outside the available range. When this mode is
              selected, extended WM_ARROWED messages are sent upon each wheel
              turn. With this mode, only one WM_ARROWED message is send if
              configured to scroll more than one line per wheel turn. This
              means the application must check, and scroll the appropriate
              number of lines indicated by bits 8-15 in msg[4];
              
              msg[0] = WM_ARROWED
              ...
              msg[4] = Extended, see below.
              msg[5] = Mouse X
              msg[6] = Mouse Y
              msg[7] = keyboard shift status

              There is extended info in msg[4] with this mode, layed out as
              follows;
                       bits 0-2 -  WA_xxx (same as in the original WM_ARROWED
                                   messages, a value between 0 and 7)
                                   bits 3-7 -  unused.
                       bits 8-15 - Number of lines to scroll (unsigned byte)
     
                     This makes it possible for wheel aware applications to
                     scroll the required amount instantly, wihtout receiveing
                     more than this one extended WM_ARROWED.

           WHL_SLDRWHEEL ( 2 )
              When wheel_mode is set to 2 (XHWL_SLDRWHEEL), XaAES converts
              wheel turns into slider movements. XaAES sends standard
              WM_VSLID/WM_HSLID messages reflecting the wheel turns.
              For this to work, WF_VSLIDE/WF_HSLIDE wind_get/set() modes have
              been extended. When the application gets the WM_xSLIDE message,
              it must pass back the position from the message unmodified
              together with your modified position;

              wind_set(handle, WF_[V,H]SLIDE, postion, unmodified, 0, 0);

              Even if the application snaps slider movements and finds that
              the slider does not move, it has to pass back the unmodified
              slider position via wind_set(). In cases where the original
              slider position match the prevsiously set position, XaAES does
              not set or redraw the slider. But it needs to collect the 'real'
              position of the slider for wheel -> slider calculations to work.

      
-------------------------------------------------------------------------------
===============================================================================
                  New event/poll functions - One entry point!


 xevnt_multi(short mode,
             struct xevnt_mask *in_events,
             struct xevnt_mask *out_events,
             struct xevents *inevents,
             struct xevents *outevents);

 GEM arrays as follows:

	Address     Element    meaning 
        ------------------------------------------------------
        control    control[0]   Yes.. what? # Opcode
        control+2  control[1]   1           # Entries in intin
        control+4  control[2]   4           # Entries in intout (XaAES only)
        control+6  control[3]   4           # Entries in addrin 
        control+8  control[4]   0           # entries in addrout 

        intin      intin[0]    mode (0 = block, 1 = setup for poll, 2 = read)
        addrin     addrin[0]   Address of struct xevent_mask, conaining a
                               bit mask denoting events to use.
        addrin     addrin[1]   Address of struct xevnt_mask into which XaAES
                               writes events that occured.
        addrin+4   addrin[2]   Address of a struct xevents containing event
                               criterias.
        addrin+8   addrin[3]   Address of a struct xevents that XaAES will
                               modify according to events happening when in
                               block-mode.

        intout     intout[0]   Return value (1 = OK, 0 = error)
        intout+2   intout[1]   Mouse X coordinate
        intout+4   intout[2]   Mouse Y coordinate
        intout+6   intout[3]   Keyboard shift status


 xevnt_poll(struct xevent_mask *events);

 GEM arrays as follows:

	Address     Element    meaning 
        ------------------------------------------------------
        control    control[0]   Yes.. what? # Opcode
        control+2  control[1]   0           # Entries in intin
        control+4  control[2]   4           # Entries in intout (XaAES only)
        control+6  control[3]   1           # Entries in addrin 
        control+8  control[4]   0           # entries in addrout 

        addrin     addrin[0]   Address of struct xevent_mask, conaining a
                               bit mask denoting events to use.

        intout     intout[0]   Return value (1 = OK, 0 = error)
        intout+2   intout[1]   Mouse X coordinate
        intout+4   intout[2]   Mouse Y coordinate
        intout+6   intout[3]   Keyboard shift status

struct xevent_mask
{
  unsigned long events3;
  unsigned long events2;
  unsigned long events1;
  unsigned long events0;
};

struct xevnts
{
  struct evnt_mu_keyboard  *e_kbd;
  struct evnt_mu_button    *e_but;
  struct evnt_mu_m1        *e_mu1;
  struct evnt_mu_m1        *e_mu2;
  struct evnt_mu_mx        *e_mx;
  struct evnt_mu_mesag     *e_mesag;
  struct evnt_mu_timer     *e_timer;
  struct evnt_mu_fselect   *e_fselect;
  struct envt_mu_pmsg      *e_pmsg;
  long reserved[64-8];
};

struct evnt_mu_keyboard
{
  unsigned short scan;
  unsigned short ascii;
  unsigned short aes;
  unsigned short norm;
  unsigned short kstate;
};

struct evnt_mu_button
{
  short clicks;
  short mask;
  short state;
  short kstate;
  short x, y;
};

struct evnt_mu_mr
{
  short x, y, w, h;
  short flag;
};

struct evnt_mu_mx
{
  short reserved;
};

struct evnt_mu_mesag
{
  short type;
  short id_sender;
  short len;
  short data[16-3];
};

struct evnt_mu_timer
{
  long delta;
};

struct evnt_mu_pmsg
{
  long userlong1;
  long userlong2;
  short pid;
  short reserved[16-5];
};

struct evnt_mu_fselect
{
  long timeout;
  unsigned long rfds;
  unsigned long wfds;
  short reserved[16-6];
};
