XaAES User Manual
(W)Craig Graham (c_graham@patrol.i-way.co.uk)

Most of this text is left unchanged from what Craig wrote earlier, but
a few things need to be pointed out:
- XaAES can be started from inside GEM as any normal program. In fact,
  that's the only way I've got it to run lately, but that may depend
  on my hardware and/or software setup. If you run it that way, only
  the current screen mode can be used.
- There are some new possibilities with the XAAES.CNF file. For example,
  debug output can be turned off and direct calls can be turned on.
  See that file for more information.
Johan Klockars   (rand@cd.chalmers.se)
980714

I never tried to start XaAES from inside GEM


|	New in v0.8 is marked |

|	The built in fileselector is greatly improved.
|	Especially TOS 8+3 names are displayed in upper case
		(like most desktops do).
|	Size adapted to screen size.
|	Full scrollable list box.
|	Very much like Selectric. But without all the desktoplike features.
|	Hey! its multitasking, you can reach the existing desktop!

Henk Robbers	(h.robbers@cable.a2000.nl)
000904

	1) INSTALLATION
	-------------------

	Installing is pretty easy, just do the following:

|	i) Stick these files all in one directroy: lets say <path>
	   xaaes.tos    - The kernal
|	   xaaesdbg.tos - The kernel compiled with debugging statements
	   xaaes.cnf    - Like GEM.CNF, but for xaaes.
|	   xaaes.rsc    - various kernal GUI elements (menu, alert template, etc)
|	   xaaeswdg.rsc - All the window gadgets
|
|	ii) Copy the mouse device driver 'vmoose.xdd' to one of:
		c:\multitos
		c:\mint
		c:\
		Your auto folder

	iii) If you want a console shell (the xaaes.cnf file is set up to give you
		one), you should edit the xaaes.cnf file so it runs your fave shell
		(I use sh, but mupfel, etc will work as well).

	iv) Add these lines to your MiNT.CNF file:

|	      cd <path>
|	      GEM=xaaes.tos   ... cq  xaaesdbg.tos
|
|		If XaAES fails to find its cnf and rsc this way,
|		 it will look in the following paths:
|		 	c:\mint
|		 	c:\mint\xaaes
|			c:\multitos
|			c:\multitos\xaaes
|		 	c:\gemsys
|		 	c:\gemsys\xaaes
|		 	c:\
|			c:\xaaes

	     Alternatively, if you are a bit more of a techie, XaAES will run
	     happily from a command line (and let you exit back to it) or as a
	     login shell.

	Ok, thats it.

	1.1) COMMAND LINE ARGUMENTS


|	mode or
|	modecode can be a octal number like o7
|	                a hex number   like x26
|	                a bit pattern  like b11010
|	                a decimal number as usual

	XaAES has the following command line arguments:

	1.1.1) Standard Atari Video Mode Select

	         -video <mode>

	Selects the video mode that XaAES will boot into where <mode> is:

	      2 = 320*200, 16 colour (ST-Low)
	      3 = 640*200, 4 colour (ST-Medium)
	      4 = 640*400, 2 colour (ST-High)
	      6 = 640*480, 16 colour (TT Medium)
	      8 = 1280*960, 2 colour (TT High)
	      9 = 320*480, 256 colour (TT Low)

	These numbers are simply the VDI physical workstation id's that
	are assigned to each video mode. If you have a strange video card,
	use whatever workstation ID your card's driver is assigned to.

	You should use this if you have an ST/TT - it will work on a falcon
	but you will get better performance by using the -fvideo switch 
	instead.

	1.1.2) Falcon Video Mode Select

		-fvideo <modecode>

	Select a falcon video mode, where <modecode> is a video modecode
	as used by the VsetMode() OS call. The format of this is:

		BIT	Name	Meaning
		0-2	BPS	Number of bitplanes:
					000=2colour
					001=4colour
					010=16colour
					011=256colour
					100=16bits/pixel (True colour)
		3	COL	Number of columns
					0=40
					1=80
		4	VGA	Monitor select
					0=TV mode
					1=VGA mode
		5	TVSEL	TV standard select
					0=NTSC
					1=PAL
		6	OVERSCN	Overscan flag (not valid for VGA)
					0=don't overscan
					1=overscan
		7	STMODES	ST Compatibility mode
					0=Standard VGA video modes
					1=ST Compatible Video modes
		8	VERTFLAG Vertical mode
					VGA:
						0=standard
						1=line doubling (half res)
					TV:
						0=standard
						1=Interlace (double res!!!)
		9-15	unused

	For example, 'xaaes -fvideo 26' will select 640*480*16colour VGA mode.

	This should work with video expanders (it works fine with 
	FalconScreen) and with NVDI (I've tried it with NVDI4).
			 					    
	2) Using XaAES
	-----------------

	2.1) Menus

	Generally XaAES is like GEM, but with a few exceptions. Most notably,
|	menu's can be Mac-style pull down, or GEM style drop down.
|	Mac style: you've got to click on a menu title to see the menu.
|	GEM style: just point at it.

|	This is governed by the 'menu' config statement.

	2.2) Typing			

|	XaAES can be point-to-type - so keyboard input goes to the window under the
	mouse and NOT to the top window. This depends on compile time flags - check
	the boot message to see if this feature is active.
|   Is completely disabled in v0.8

	3) XaAES Keyboard Combo's
	----------------------------

	There are a couple of keyboard combo's that XaAES uses for itself. These are:

	CTRL+ALT+TAB     : swaps menu bars, not top windows.
	CTRL+ALT+L       : Activate the 'Task Manager' window.
	CTRL+ALT+S       : Output a status dump to the debug file
	CTRL+ALT+K       : Clean up - search for dead clients that didn't call
	                   appl_exit
	CTRL+ALT+R       : Attempt to recover control of a hung system - use as a last
	                   resort, as this will kill the clients that are blocking
	                   the system.
	CTRL+ALT+D       : Toggle debug output (if enabled at compile time)
	CTRL+ALT+C       : Shutdown immediately, killing all clients.
|	CTRL+ALT+M       : Recover the mouse.
|	CTRL+ALT+Home    : Recover screen and mouse.

	NOTE: CTRL+ALT+S only outputs anything if GENERATE_DIAGS was turned on at
	compile time - in the binary distributions released by me (Craig) they will
	have no effect as all diagnostics are turned off.

	4) SYSTEM MENU
	---------------

	The XaAES system menu (CTRL+ALT+TAB until you get it) currently contains two
	useful options.

	One is the 'About XaAES...' option which (surprisingly) brings up a nice
	little descriptive box.

	The other (more useful) option is in 'Shutdown'. This will kill all GEM
	programs and exit XaAES gracefully. Unlike MultiTOS, if you ran XaAES from a
	command line or as a login shell, you will be returned to the command line or
	login prompt. You can then re-start XaAES, or do whatever - XaAES can be
	exitted and restarted as many times as you like without rebooting the machine.

	XaAES catches CTRL+ALT+C and CTRL+ALT+\  (SIGINT & SIGQUIT respectively) and
	executes the shutdown procedure in response to them, so you should be able to
	get back to your command line in most situations.

	4.1) TASK MANAGER
	------------------
	The 'Process' menu of the XaAES System menu also contains the
	'Task Manager' option. This opens a window with a scrolling list
	of current AES client applications. This is not a list of all
	MiNT processes, it's only a list of GEM programs.

	The Task Manager allows you to suspend, resume, kill and launch
	GEM programs.

	The icons next to each list entry represent the app status
	(Application awake, Accesory awake, Sleeping/suspended, messages
	pending, owns lock, etc).

	There is a set of icon buttons at the top of the window
	(from left to right):

	o Launch
	  Launch a new GEM program. A file selector will prompt you for
	  the filename.

	o Trash
	  Kill the task that is selected in the task list.

	o Sleep
	  Put the selected task to sleep. This will hide all it's windows
	  and send SIGSTOP to the process to suspend it.

	o Wake
	  Wake up the selected task. This is the opposite of Sleep, and
	  will restore all the app's windows (on top, in the order the app
	  had them) and send SIGCONT to let the process continue.

	As previously mentioned, CTRL+ALT+L will also open the Task Manager.  

	6) WINDOW SCROLLING
	--------------------

	Scroll bars are extended from the usual GEM style to be similar to WinX's
	behaviour. Clicking and dragging the scroll bar with the right hand button
	will work the same as normal GEM. Clicking and dragging with the left hand
	button will do REALTIME/LIVE scrolling, where the window will update as you
	move the mouse (not just when you release it as in the standard GEM behaviour).
	This is nice for programs that have fast window updates, but is annoying for
	old/slow programs (which is why it's on a seperate button).

	7) THE xaaes.cnf FILE
	-----------------------

	This is a bit like MultiTOS's GEM.CNF file. It's main purpose is to let you
	auto-launch programs as XaAES starts up. Generally the syntax of this is
	supposed to be the same as Atari's GEM.CNF file

	It's a simple text file with the following format:

	i)   '#' is a comment line.
	ii)  Commands are not case sensitive (although paths may be, depending on
	     your filesystem).
	iii) If a command isn't understood, it gets ignored...
|	iv)  Some of the commands are :

|		     string <name> <=> <character sequence>
|	            Define a environment variable.
|	            NOTA BENE: variables must be decared BEFORE any run, desk or shell

|	            'export' and 'seten'v are synonyms for 'string'

	         debug <file/device>
	            Set debugging output to <file/device> (default is .\debug.list)

	         clipboard <directory>
	            Set the GEM clipboard to be in <directory> (default is c:\clipbrd).

	         accpath <directory>
	            Set the location that XaAES will try to load accessories 
	            from (default is c:\).

	         run  <program> <parameters....>
	            Launch a program.
|	         desk  <program> <parameters....>
|	         shell <program> <parameters....>
|	            Launch the desktop.

	An example xaaes.cnf file (in fact, the one I use)
|	can be found in the distrubution.

	8) Programs That Run As APP/ACC.
	---------------------------------

	Several programs that run as either APP or ACC will fail to
	run correctly (or at all) under XaAES. For some reason (don't
	ask why) many of these (for example ST-Guide) will fail if run
	as:
		c:\stguide.app
	but will work fine if run as
		u:\c\stguide.app
	Now, these should be the same path with the same behaviour, but
	there appears to be a subtle differance in the way Pexec() works
	if you launch a u: relative path. So, instead of clicking on st-guide
	in a c: window from Thing, use the u:\c\ window instead...

	x) Caveats
	--------------

|	Craig:
	I've compiled  out most of the diagnostics, but if you get funny messages on
	the screen, add the line 'debug \dev\null' to the xaaes.cnf file.

	Loads of stuff is missing at the moment, don't hassle me - fix it and get
	back to me.

|	Henk:
	I would say only a few things are missing at this moment.
	A binary distribution contains 2 binaries:
		xaaes.tos		debugging compiled out. The fast one.
		xaaesdbg.tos    All debugging available. So will be slow!

