XaAES Userīs Manual

/*
 * XaAES - XaAES Ain't the AES (c) 1992 - 1998 C.Graham 
 *                                 1999 - 2003 H.Robbers
 *
 * A multitasking AES replacement for MiNT
 *
 * This file is part of XaAES.
 *
 * XaAES is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * XaAES is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with XaAES; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */


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

	Installing is pretty easy, just do the following:

	i) Stick these files all in one directory: lets say <path>
	   xaaes.prg    - The kernal
	   xa_setup.scl - Like GEM.CNF, but for xaaes, setup data only.
	   xa_exec.scl  - Executorial stuff, like running app's and desktop
	   
	   xaaesdbg.prg - The kernel compiled with debugging statements
	   xa_debug.scl - Like GEM.CNF, but for xaaesdbg.
	   
	   xaaes.rsc    - kernel GUI elements (menu, alert template, etc)
	   xaaeswdg.rsc - All the window gadgets
	   xa_mono.rsc		id for mono
	   monowidg.rsc         id for mono

      The last 2 have all color icons converted to standard mono icons;
      (No 3D widgets!)

      Default names are : xaaes.rsc & xaaeswdg.rsc

      You can specify others in the xa_setup.scl.
      If you dont care about colourfull widgets and have not that big a computer
      but only a colour monitor, you can specify the mono rsc's in the cnf
      and spare 170Kb compared to 256 colours, and much much more compared
      to higher colours.

	ii) Copy the mouse device driver 'moose.xdd' to one of:
		c:\multitos
		c:\mint

	iii) If you want a console shell (the xa_setup.scl file is set up to
	     give you one), you should edit the xa_setup.scl file so it runs
	     your fave shell (sh, mupfel, etc).

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

	      cd <path>
	      GEM=xaaes.prg   
	      
	      
		If XaAES fails to find its cnf and rsc this way,
		 it will look in the following paths:
		 	c:\gemsys
		 	c:\gemsys\xaaes
		 	c:\aes
		 	c:\aes\xaaes
		 	c:\mint
		 	c:\mint\xaaes
			c:\multitos
			c:\multitos\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-14	unused
		15    Additive mode bit for non standard resolutions. If set,
		      use the default screen resolution as preset by CentScreen.


	For example:
	
	'xaaes -fvideo 26'    will select 640*480*16colour VGA mode.
	'xaaes -fvideo x801a' will select 16 colour VGA mode in
	                      the resolution preset by centscreen.

	Note: 
	When you use a screenexpander like Screenblaster, you have to use
	the -fvideo switch as well. This will make the Screenblaster-Software
	to show up the resolution-selection-menu.


			 					    
	2) Using XaAES
	---------------

	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.



	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  and
	CTRL+ALT+ESC     : Open 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+A       : Shutdown by sending AC_CLOSE or AP_TERM to all
	                   clients.
	CTRL+ALT+M       : Recover the mouse.
	CTRL+ALT+Home and
	CTRL+ALT+T       : Recover screen and mouse.

	NOTE: CTRL+ALT+S only outputs anything if GENERATE_DIAGS was turned on
	at compile time.
	

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

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

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

	The other (more useful) option is in 'Quit all App'.
	This will open the taskmanager and send termination requests to all GEM
	applications.
	With "Quit XaAES" you will be returned to the command line or
	login prompt, if you ran XaAES from a command line or login shell.
	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 Skull
	  Kill the task that is selected in the task list immediately.

	o Trash
	  Send termination request to 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.


	Additionally there are some buttons. "Quit all App" and "Quit XaAES"
	will behave like explained before. "Reboot" tries to close all GEM-
	applications, then XaAES and then reboots the system. "Halt" behaves
	like "Reboot", but the system is halted after XaAES has been quitted.

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


	5) WINDOW SCROLLING, MOVING and SIZING
	---------------------------------------

	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).


	6) THE CONFIGURATION FILES
	---------------------------

	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)  variable-name :: letters, letters-and-digits
             quoted-or-literal-string :: variable-name, "any_character-not-",
	                        'any_character-not-',
				 any-character-not-space-or-comma
	     character-sequence :: quoted-or-literal-string,
	                           quoted-or-literal-string + character-sequence

	v)  Some of the commands are :

	    Commands only allowed in xa_setup.scl:

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

             resource <main resource filename>
             widgets <widgets resource filename>

	    Commands allowed in both xa_setup.scl and xa_exec.scl:
	    
	    string <variable-name> = <character-sequence>
            int <variable-name> = 
	    			digit-sequence-optionally-preceded-by-minus-sign
	            Define a variable.
		     export <name> <=> <character-sequence>
	            'setenv' is a synonym for 'export'

            export <variable-name>
            export <name> = <character-sequence>

	    NOTA BENE: environment variables must be declared BEFORE any run,
	               desk or shell

            xa_windows <nomove|nohide>
	            nomove implies nohide
	            Set these properties for the non modal dialogue windows
	            that XaAES creates on behalf of (pre multitasking)
		    applications. If your application has problems with moving
		    these dialogues, this feature might be solve it.

            windows <nohide>
	            Set this property if you dont like hiding at all.
	            Hider widgets will not be displayed.
	            Windows without the MOVE property cannot be hidden.

	    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).


	    Commands only allowed in xa_exec.scl:
	    
	         open <taskmanager>
	            Open the taskmanager window at bootup.
	         run  <character-sequence> <parameters....>
	            Launch a program.
	         desk  <character-sequence> <parameters....>
	         shell <character-sequence> <parameters....>
	            Launch the desktop.

	An example xa_setup.scl file (in fact, the one I use)
	can be found in the distribution.


	7) SHUT DOWN
	-------------

	"Quit all App" can be chosen from XaAES menu or by pressing ctrl+alt+A.
	
	The taskmanager will appear on the screen and show you which clients
	did not respond to the shutdown request.

	If only accessories remain, you can savely press the button
	'Halt' to finish the actual shutdown, or if you want to leave your
	computer alone, just switch the power off.
	
	Otherwise it might be necessary to close the remaining clients in their
	respective approppriate way. Just switch hence and forth, the
	taskmanager will stay available on the screen.


	8) Programs running 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...

