@database "eXtended AES Library 1.00"
@subject "Documentation/XAES"
@author "Ken Hollis/Bitgate Software"
@$VER: XAES_100.HYP 1.00
@options -s

@node Main "XAES Version 1.00"

@{B}XAES Version 1.00  by Ken Hollis of Bitgate Software@{0}

    1. Guidelines
	2. Library definitions

@endnode

@pnode XAES
XAES is a GUI programming  library based on XWindows (OSF/
MOTIF design) and is a C  programming type Object-Oriented
library.   XAES  is  an  acronym for  eXtended Application
Environment System.   This library has absolutely  nothing
to do with the  replacement of the OS,  AES,  VDI,  or any
other parts therein.  XAES is a completely compatible AES-
type GUI library.   All enhancements have  been completely
tested, and are 100% compatible with all machines.   It is
NOT compatible with MultiTOS.
@endnode

@pnode TRUE
TRUE is  an  integer  value equivalent  to (0==0)  or  the
integer  value 1,  depending  on  your compiler  type  and
version.
@endnode

@pnode FALSE
FALSE is  an integer  value equivalent  to (0==1)  or  the
integer  value 0,  depending  on  your compiler  type  and
version.
@endnode

@pnode FAIL
FAIL is an  integer value equivalent to -1.   This boolean
value usually signifies that  a routine did not work or it
is returning bad values.
@endnode

@pnode intrinsic
An intrinsic is  a library/OS  routine definition  that is
available for use by either the OS,  or the program at any
time during execution.  There are two types of intrinsics:
Global,  and Local.   Most of  the intrinsics (except  for
NKCC) in XAES are Local intrinsics,  meaning they are only
available to the  program that is using them at that time.
@endnode

@pnode NKCC
NKCC  is an  acronym  for Normalized  Keyboard  Conversion
Codes.   These are  a set of  assembly routines which  are
designed to  make the  return values  of the  TOS keyboard
easier to understand and use.   For more information, read
the documentation provided with this library.
@endnode

@pnode GEM
GEM is the  Graphic Environmental  Manager, of  which this
library uses and manipulates.
@endnode

@pnode VDI
VDI is the  Visual/Virtual Display Interface,  and is used
for displaying graphics.
@endnode

@pnode Motif
Motif  is a windowing  manager that runs  under X-Windows.
It  allows  a  3D  graphical  user  interface  with  Posix
programming compliance standards.
@endnode

@node Guidelines "XAES Programming Guidelines"

@{B}XAES Programming Guidelines@{0}

XAES is a self-contained GUI programming library.  XAES is not a replacement
in any way for AES, OS, GEM, or VDI.  The guidelines for creating routines
are as follows:

1.  In any GEM program, if your program uses a resource file, the resource
    file shoulded be loaded first (rsrc_load.)

2.  After which, the mouse should be changed to an arrow state (either by
    using WGrafMouse, or graf_mouse.)

3.  Resource objects should then be found, and saved in memory in your main
    program (using rsrc_gaddr.)

4.  Objects should then be fixed if they have any Extended Object types at
    this point and time, with fix_objects.

5.  WInit should be called.

6.  Attach any code to any objects you wish to attach code to (using
    WAttachCode.)

7.  menu_bar should then be called if you have a menu bar to display.

8.  Call WDoDial after all initialization has taken place.

9.  After the WDoDial routine, unfix_object should be called to remove any
    Extended Object type routines attached to objects.

10. WTerm should be called.

11. Any error codes should be returned at this point.

Follow these guidelines and you will create a perfect XAES program.

@endnode

@node Library definitions "Library definitions"
@{B}XAES 1.00 Library@{0}

XAES's intrinsic library is one of the most complex intrinsic libraries on
the Atari, yet it is among the easiest to use.  XAES's intrinsic libraries
were designed around the idea of X/Motif, and many ideas and simplicities
were taken from those programming environments.

XAES basically has two types of application intrinsics:

	- Initialization intrinsic
	- Termination intrinsic

The initialization intrinsic is the basis for initialization of your XAES
library program.  This intrinsic function simply opens the GEM desktop,
VDI workspace, and initializes NKCC.

The termination intrinsic simply deinitializes XAES, closes all windows that
remain on the screen, closes the desktop (if applicable), closes the VDI
workspace, and deinitializes NKCC.
@endnode

@node "Callbacks"
@{U}Method -- Callbacks@{0}

Callbacks are used mainly for handling the calling of routines in a
simplified manner.  XAES uses callbacks to call routines whenever an action
takes place (like the click of a button, or whatever.)

There are different types of callback routines.  Click on the one you wish
to get more information on:

    -- Main program callbacks
    -- Window routine callbacks
@endnode

@node "Main program callbacks"
@{U}Method -- Callbacks -> Main program@{0}

There are currently four callbacks that are used for main program processing.
WInit handles the calling of these callbacks depending on whether or not
you tell it to.  If you don't want XAES to handle the callbacks auto-
matically, you can control callbacks yourself.

@{U}The four callback indices:@{0}
XC_INITIALIZE  (1)  -- Initialization callback type
XC_DEINITALIZE (2)  -- Deinitialization callback type
XC_STARTUP     (3)  -- Startup callback type
XC_EXIT        (4)  -- Exit callback type

@{U}Setting callbacks:@{0}
To set callbacks, the routines are quite simple.  Each routine you want the
callback to point must have no calling parameters.  A sample callback
routine would be written as:

LOCAL void MyInitCallback(void)

As you can see, all callbacks for the main program must have no calls.  They
may contain calls to other functions within the callback, but the callback
itself cannot contain any parameters.

To place the callback into memory, the function to call is:

WSetCallback(type, rout);

where TYPE is the callback index type, and ROUT is a pointer to the routine.
Thus, if I wanted to make MyInitCallback the INITIALIZATION callback, I
would call the routine thusly:

WSetCallback(XC_INITIALIZE, MyInitCallback);

@{U}Calling your callback manually:@{0}
To call any main program callback, the method is as follows:

DoCallback(type);

where TYPE is the callback index type.

Macros have been set to make things easier for you.  The following macros
point to the following indices (this was taken straight from the header
file):

XCallInitializeCallback   - DoCallback(XC_INITIALIZE);
XCallDeinitializeCallback - DoCallback(XC_DEINITIALIZE);
XCallStartupCallback      - DoCallback(XC_STARTUP);
XCallExitCallback         - DoCallback(XC_EXIT);

These should be used instead, but of course, you can use the DoCallback
routine.  That's what it's there for.
@endnode