########################################
# @(#) XaAES-userguide
# @(#) Helmut Karlowski, 07.08.2010
########################################
!language english

!ifdest [asc]
	!define weblink (!2)
!else
	!define weblink <a href="(!2)">(!1)</a>
!endif
!ifdest [asc]
	!define maillink (!2)
!else
	!define maillink <a href="mailto:(!2)">(!1)</a>
!endif

#special preamble for dvipdfm, dvips
!no_preamble [tex]

#!use_label_inside_index [html]
#!use_udo_index           [all]

!use_nodes_inside_index  [all]
!use_label_inside_index  [all]
!use_alias_inside_index  [all]

!no_headlines [html]
!html_merge_nodes
!html_merge_subnodes
!html_merge_subsubnodes

#
!tex_tetex
!tex_2e

#graphic-input for different formats
#!include graphicmac.u

#####################################################
#######START###################
############

!docinfo [title]   XaAES User Manual
!docinfo [program] XaAES: A multitasking AES replacement for MiNT
!docinfo [date]    (!today)
!docinfo [author]  Helmut Karlowski et.al.

#!use_auto_subtocs    [info,html,stg,tvh,win,aqv]
#!use_auto_subsubtocs [info,html,stg,tvh,win,aqv]
!no_effects          [asc]
!use_justification   [asc]

########################################

!begin_document
!maketitle
!tableofcontents

!node Preface

Parts of this document have been copied from the sample xaaes.cnf, the
old usrguide, and the xaaes-sources.

As not everything is clear, some items have been marked with ?.

Currently there is a lot stuff missing in this documentation but things that are
new to the user since version 0.998 should be mostly there.

You may find additional information here:

!begin_itemize
!item (!weblink [the spamint-wiki] [http://wiki.sparemint.org/index.php/XaAES])
!item (!weblink [Unofficial XaAES] [http://xaaes.atariforge.net/docs.php])
!end_itemize

!node Installation

XaAES is normally included in the standard FreeMiNT distribution. It's
files are located in the subdirectory xaaes in the FreeMiNT system
folder. To start XaAES you need to run the program xaloader.prg which
you can find in the XaAES folder. There are three common ways of
starting XaAES.

<sysdir> defaults to "<bootdrive>/mint/<VERSION>" or, if this
directory doesn't exist, "<bootdrive>/mint". <VERSION> is the version
of the kernel where dots are replaced by minus, e.g. 1.17.0 gives 1-17-0.

!begin_description

!item [From mint.cnf] The keyword GEM points to xaloader.prg. FreeMiNT will now
	start XaAES automatically. Example:

		GEM=<sysdir>\xaaes\xaloader.prg

!item [By init]

!item [From the command line] In this case you may quit XaAES with Alt-Q
	from the taskmanager to return to the commandline.

!item [By the TOS desktop] Sometimes quitting XaAES also works here.

!end_description

Xaloader runs <sysdir>/xaaes/xaaes.km by default.

You may specify any km-file on the commandline, e.g.:

!begin_sourcecode
xaloader.prg [optional directory/]some.km
!end_sourcecode

!subnode Files


On startup XaAES needs the following files:

!subsubnode Resource-Files

There are 3 mandatory resource-files located in the
xaaes-startup-directory:

!begin_description
!item [xaaes[n!]].rsc	-	standard resource-file, n: resource-version, currently 009.
!item [xaaeswdg.rsc] 	-	special resource-file for widgets
!item [xa_xtobj.rsc]	-	resource containing the extended AES object icons
!end_description

You can choose other resource-files for the first two in xaaes.cnf to get
different widgets for example (some are in the 'widgets'-folder).

The system-resource-file has a version-number (currently 0.0.9), which
gives xaaes009.rsc. If this file is not found the name defined in
xaaes.cnf is used if present. If not, xaaes.rsc is used.

There is also a resource-file for monochrome display (xa_mono.rsc), that
reportedly saves memory, but it has not yet been updated for the latest
XaAES-version.

There are alternatives to xa_xtobj.rsc in the directory xobj.

!subsubnode Img-Files
XaAES also reads img-files from a folder called img. This is needed if you
want a textured look. If not present, you get the default rendering.

!subsubnode Mouse-Driver

!begin_description
!item [moose.adi]
!item [moose_w.adi]
!end_description

For mouse-control one of moose.adi or moose_w.adi is needed in the
xaaes-folder. The _w-version is needed for  mouse-wheel-support, but also
works if there is no wheel-mouse.

!begin_quote
Note: If there are both present moose_w.adi is used.
!end_quote

!subsubnode Help-File
If a file named xa_help.txt is found its content is displayed in the About-window.

!subsubnode Config-Files

!begin_description
!item [xaaes.cnf]
!end_description

This contains the configuration for XaAES. See below.

!label xaaes.cnf
!node xaaes.cnf

This lets you set several runtime-options for XaAES and its clients and
start programs at start-up. It uses mostly the same syntax as is used in mint.cnf.

Commands are not case sensitive unless otherwise mentioned.

If a command isn't understood, it gets ignored.


!subnode Global Commands

Default values are false for bool, 0 for numbers or empty for strings unless otherwise mentioned.

!begin_description

!label LAUNCHPATH

!item [LAUNCHPATH	<character-sequence>]

Define the initial directory that is opened by the
XaAES-launcher to start programs. A pattern to select
typical executable files may be appended.

		Example:
		launchpath  = u:\usr\gem\|*.prg|*.app|!*.*|*.acc

		See also: XaAES-Pattern-Matching

!item [CLIPBOARD	<character-sequence>	(default c:\clipbrd)]
	Set the GEM clipboard to be in <directory>

!label snapshot
!item [SNAPSHOT	<character-sequence>	define snapshot-program]
	The external snapshot is called with the arguments: '0 T 1 [x y w h]'	where

T=0: full screen, T=2: top window

	If x, y, w, h are provided, this rectangle should be snapped.
	If XaAESSnap is not loaded, the external program that is
	defined in xaaes.cnf for snapshots is called, if present.


!item [ACCPATH 	<character-sequence>]
        Set the location that XaAES will try to load accessories
        from (default is c:\). When ACCPATH is present in the
Environment this precedes the config-variable.

!item [RESOURCE 	<character-sequence>	main resource filename (default xaaes009.rsc)]
	See Resource-Files

!item [WIDGETS 	<character-sequence>	widgets resource filename (default xaaeswdg.rsc)]

!label USEHOME
!item [USEHOME		<bool>]		use $HOME in shell_find

!item [NAES_COOKIE	<bool>]         	fake nAES cookie


!item [MENUPOP_PIDS	<bool>]
	Setting menupop_pids = true makes XaAES list its clients in the client-list-
	menupopup using the following format;

	 "  PPID(RPPID) -> PID Client nice name"

	 where 'PPID' is the physical parent-pid of the Client (which is the AESSYS).
	'RPPID' is the Process ID of the process that called shel_write() to start
	it, it is the "Real Parent PID". 'PID' is the Process ID of the client.
	 If set to 'no' (the default), only the client's nice name (when available,
	else its 'proc_name') is listed.



!item [LRMB_SWAP	<bool>]
	Swap left and right mouse buttons. Setting 'lrmb_swap = true' will make
	XaAES swap the left and right mouse buttons.

!item [WIDGET_AUTO_HIGHLIGHT	<bool>]
	When widget_auto_highlight is set true, standard window widget are
	automatically highlighted when mouse hovers over them. This is still
	very experimental, and widgets are not actually highlighted, they
	are just animated - that is redrawn in SELECTED status.

!item [REMAP_CICONS	<bool>]
	Use the palette defined in the resource to remap icons.

!item [SET_RSC_PALETTE <bool>]
	Use the palette defined in the resource as screen-palette.

!item [ALERT_WINDOWS		<bitmask>		default 0xffff]
	alert_window is a bitmask indicating which alerts coming via the
	alert pipe will be shown in a window. The idea is that this mask
	is used to tell the AES which alerts you want like this;
	 bit 0 set -> show alerts with no icon
	 bit 1 set -> show alerts with INFO icon
	 bit 2 set -> show alerts with QUESTION icon
	 bit 3 set -> show alerts with STOP icon
	 etc., etc.

	Because there is no consideration as to which icon is used
	(for example, kernel's PROCESS KILLED alerts have icon #1, the same
	as used for other warnings/informative ALERTS), the implemention
	is not complete. So for now use this to either turn off or on alerts
	altogether. To turn on alert windows, use a mask where all bits are set,
	y0xffff, and to turn off clear all bits, 0x0000

	THE IMPLEMENTATION IS NOT DEFINATE AND ONLY PARTIAL AS OF NOW


!item [FONT_ID		<number>	(default 1)] Standard GDOS fontid for windows & stuff

!item [STANDARD_POINT	<number>	(default 10)]
			Size of the 'standard' AES font (for window titles, etc), high resolution

!item [MEDIUM_POINT	<number>	(default 9)]
			Size of the 'standard' AES font (for window titles, etc), low resolution

!item [SMALL_POINT	<number>	(default 8)]	Size of the 'small' AES font.


!item [POPSCROLL	<number>	 (default 0)]
			Set number of lines of a popup above which it will be made scrollable

!item [DC_TIME		<number/ms>	(default 50)]	double click time (ms)


!item [MP_TIMEGAP	<number/ms>	(default 3)]
		Mouse packet time-gap. This is the time (in 200hz timer ticks) that
		must pass after a button-release event before a new button-press
		event is accepted by moose.adi. Because of unstable mouse-buttons,
		a button-press may follow immediately after a button-release, creating
		an "extra" mouse-click. This is especially annoying when releasing
		the right-button after a drag-session (Thing's directory-window, for
		example), and the "extra-click" fires some unwanted action.

!item [VIDEO		<number>	(default 1)]	See Video-Modes

!item [REDRAW_TIMEOUT	<number/ms>	(default 500)]
		This is the time in ms XaAES will wait for clients to
		service WM_REDRAW messages between actions that generate redraws,
		like moving/closing/opening/etc. windows. If a client is busy and this
		'timeout' happens, it is marked as lagging and XaAES will service the
		redraws for it. When this happens, XaAES just draws the areas not
		serviced with dark gray color until the client re-enters evnt_multi().
		For slow machines, this timeout must be higher (longer) than on faster
		machines.

!item [POPUP_TIMEOUT	<number/ms>	  (default = 10)] Time in milliseconds before popups open.

!item [POPOUT_TIMEOUT	<number/ms>	  (default 1000)] Time in milliseconds before popups close.

!item [SETENV]		same as for mint.cnf

!item [NEXT_ACTIVE	 <'client' or 'window'>	(default 'window')]
		Selects wether the previous active application or
		the owner of the previous topped (or only) window
		should be set active upon client termination.

!item [CLOSE_LASTWIND	<'client' or 'window'>	(default 'window')]
		DEPRECIATED - OBSOLETE
		close_lastwind = 'client' or 'window' (default is 'window')

		Selects what to do when the last window of a client is closed.

		Setting to 'client' will keep the application whose
		last window is closed as the top application. This prevents
		XaAES from putting infront another application when the last
		window of the application currently infront is closed.

		Setting to 'window' will make XaAES put the application
		who owns the foremost window infront, making it active.
		This is the normal behaviour done by other AES's we thinks.


!item [APP_OPTIONS	<string>]
	See Commands for XaAES-clients.

!item [CANCEL		<comma-separated string-list>]
		List of words that XaAES interpretes as Cancel. A button containing a word
		from this list in a dialog or alert will be selected if Undo is pressed.

!item [FILTERS		<comma-separated string-list>]
		List of patterns that will be contained in the filter-menu of the fileselector.
		See also: XaAES-Pattern-Matching.

!item [CTLALTA_SURVIVORS		<comma-separated string-list>]
		The strings are the filename part of the program file, padded with
		spaces to fit 8 characters. This is NOT the 'nice' name. So, if your
		Toswin2 binary is named "tw2.app", you use "tw2     ". Each app-name
		is separated with comma.
		This will allow you to specify which applications XaAES does not
		attempt to terminate when user presses CTRL-ALT-A to quit all
		applications. Normally, this keycombo quits all running applications
		leaving only XaAES. However, most of the time, keeping certain
		applications running is preferred, such as the desktop, the taskbar,
		av-server application, etc, etc.
		One special name is '_aes_shell_', which will prevent XaAES from
		terminating the desktop loaded via "shell = " configuration variable.
		One can still use the name of the desktop program if it is konwn, but
		an easier way is to use '_aes_shell_', as that will work without
		further configuration modifications when one changes desktop from, say,
		Thing to Jinnee.
		If you want to bypass this setting, and quit ALL applications, leaving
		only XaAES, you can press ctrl-alt-shift-a.

		The following will keep the desktop, taskbar and toswin2 running after
		a ctrl-alt-a action:

!begin_sourcecode
		cltalta_survivors = "_aes_shell_", "taskbar ", "toswin2 "
!end_sourcecode

		Applications that do not act on AP_TERM will also survive.

!item [KILL_WO_QUESTION	<comma-separated string-list>]
		Applications found in this list will be	killed immediately during shutdown.
		The same rule as for CTLALTA_SURVIVORS applies to the strings

!item [?MENU		<'pull', 'push', 'leave', or 'nolocking'>               (default 'leave')]
		Determines whether a menu opens by hovering or clicking. If set to push
		menus have to be clicked to open. pull is the same as
		leave, nolocking has no effect.


!item [?HELPSERVER	<comma-separated string-list>]
		List of apps to display help.


!item [VERTICAL_WHEEL_ID]	See Mousewheel-Configuration.

!item [HORIZONTAL_WHEEL_ID]	See Mousewheel-Configuration.

!item [VERTICAL_WHEEL_AMOUNT]	See Mousewheel-Configuration.

!item [HORIZONTAL_WHEEL_AMOUNT]	See Mousewheel-Configuration.


!item [ICNFY_...]
	See Iconifying


!item [GRADIENTS	<number>	(default 0)]
	setting gradients to a nonzero value turns on use of
	color gradients in the window widget and aes object
	renderer in hc/tc color modes.
	This is only a temporary configuration that will be gone
	later on. Only turn this on if you have a fast machine.

!item [SHELL	<string>]	Names the desktop-program

!item [RUN	<string>]	Runs a program at startup. <string> is full-path\program

!end_description

!subnode Commands for XaAES-clients

These may also affect XaAES itself.

The syntax is:

!begin_sourcecode
<app_option>: app_options = <app-name>, <options-list>

<options-list>: <options-list>, <option>

<option>: <option-name> = <value>
!end_sourcecode

For option-name see below. Value may be a number or true/false.


!subsubnode Client-options

!begin_description

!item [windowner]
!item [nohide]
!item [xa_nohide]
!item [xa_nomove]
!item [xa_objced]
!item [xa_none]
!item [noleft]
!item [thinwork]
!item [nolive]
!item [wheel_reverse]
!item [naesff]
!item [naes12]
!item [naes]
!item [winframe_size]
!item [inhibit_hide]
!item [spaceXinsert 	<bool>	(default false)]	exchanges space/insert-behaviour in dialogs and lists.
If false, Insert will select a button in a dialog, space will select a
list. This option is casesensitive, so for example SPACEXINSERT will not
be recognized.

!item [clwtna]

!item [alt_shortcuts	<number>	(default 3)]

!begin_itemize
!item  0: no shortcuts
!item  1: shortcuts for alerts
!item  2: shortcuts for dialogs
!item  3: shortcuts for dialogs and alerts
!end_itemize
Controls how XaAES handles Alt-shortcuts. Since version 0.999 every standard
GEM-application gets Alt-shortcuts for dialogs that use form_do, even
when there are no shortcuts defined with WHITEBAK in the resource-file.

The shortcuts that are defined in the clients' resource-file are always there.

!end_description

!node Ctrl-Alt-Shortcuts

By pressing certain letters together with Ctrl+Alt, you can access some
more or less often used functions listed below.

!begin_itemize
!item A:				 Terminates all applications (A list of exceptions can be specified)
!item B:					open System-window
!item E:					open windows-submenu
!item F,L:			open task-manager
!item I:					(un-)iconify current top-window
!item K:					launch a program
!item Help:					open about
!item T,Home:				Redraw screen
!item D: 						Open the screenshot dialog - see snapshot config-option
!item P: 						Restore palette in colour depth of 8-bits or less
!item Q: 						Quit XaAES	(deactivated - set HOTKEYQUIT in xa_defs.c 1 to use this)
!item R: 						Attempt to recover a system that has locked up
!item V: 						Unhide all applications
!item W: 						Global window cycling
!item X. 						Hide all except the currently focused application
!item Y: 						Hide currently focused application
!item space: 				Open main menu bar
!item Shift-space: 	Open menu in current window if it has one, else open main menubar
!item TAB: 					Cycle open applications
!item Cursor-right:	full current window
!end_itemize

!node XaAES Main-menu

!subnode About

Instead of listing lots of contributors to XaAES and part of the GPL
in previous versions, the main web-address for MiNT, and the
GPL-copyright are mentioned.

Additionally the file 'xa_help.txt' is displayed if present.

This file may contain some special tags:

!begin_itemize
!item Italic:
!begin_sourcecode
	<i> <text> </i>
!end_sourcecode

!item Bold:
!begin_sourcecode
	<b> <text> </b>
!end_sourcecode

!item Underlined:
!begin_sourcecode
	<u> <text> </u>
!end_sourcecode
!end_itemize

If a <-bracket is preceeded by backslash, is gets printed and not interpreted.

!subnode The Launcher

There is no desktop needed to launch programs as XaAES is able to start
them itself using the Launcher. It opens the fileselector in LAUNCHPATH.
You may also select any other directory from where to start a program.

If a client is launched from launchpath, and the entry is a symlink,
home_path for that client is set to the directory of the link-target. It
behaves then as if started from that directory, and finds its resource-
and other files.

!subnode System-Window

In addition to the features described in

(!weblink [Unofficial XaAES] [http://xaaes.atariforge.net/docs.php?chapter=6.htm#6.2.2])

the following has been added:

!begin_itemize
!item Alerts have a timestamp and no '|' inside
!item "Environment"-Entries are sorted by name
!item New list-entry "System"
!begin_itemize
!item Screen-layout (resolution, bit-depth, pixel-format)
!item display CPU-info from /kern/cpuinfo
!item info about memory-protection
!item Kernel-version from /kern/version
!end_itemize
!end_itemize

!subnode Taskmanager

In addition to the features described in

(!weblink [Unofficial XaAES] [http://xaaes.atariforge.net/docs.php?chapter=6.htm#6.4])

the following has been added:

!begin_description

!item [List] List is a tree, whereas clients are parent and their windows the children

!item [Select window or client] If exited with Ok, and a client is selected, this client is topped.
If a window  is selected, this window is topped. Unselect with
Space (or Insert).

!item [Pocesses] Also lists non-AES-apps (not toppable, of course)

!item [Memory] Displays memory-statistics found in /kern/meminfo

!item [Stop/Continue] Similar to killing a process by clicking on the skull it may be
stopped by clicking on the bed (the left one). Continue a stopped
process by clicking on the right bed (the one with the alarm)

!item [Load] Display actual load and load-average (see
/doc/programmer/newcall.html/suptime.html). By selecting the "toggle
load"-button this can be switched off and on.

!item [Process-Information] Displays more process-information in a table:
!begin_description
!item [ppid] Process-ID of a processes parent
!item [pgrp] The program-group of a process
!item [DOM] Domain where 'M' is MiNT-domain, 'T' is TOS-domain.
!item [STATE] where
!begin_description
!item [Cur]: Current process
!item [Run]: Process is running
!item [Wait]:  Process is waiting
!item [IO]:   Process is waiting for IO
!item [Zomb]: Zombie
!item [TSR]: Terminated and resident
!item [STOP]: Stopped
!item [Slct]: Waiting in Fselect
!end_description

For more details refer to programmer/mint.txt

!end_description

!item [SZ] Size. This is the total amount of memory the process uses.
!item [CPU] Total count of 5ms-Ticks of CPU-usage of the process.
!item [%] Percentage of the above. Note that this will not sum up to 100
most of the time because terminated processes do not appear in the list.
!item [args] The commandline minus process-name.
!end_description

The display of the taskmanager is updated on every open, or, when it's
open, by pressing Ctrl-Alt-F or Ctrl-Alt-L.

!node Environment

XaAES uses the following environment-variables:

!begin_description

!item [ACCPATH]	See Global Commands.

!item [TOSRUN] Define application for running text-mode programs.

!item [HOME] See USEHOME

!item [PATH] Used in shel_find for locating applications.

!end_description

!node Fileselector

Only changes from version 0.998 to 0.999 will be described here. For a
documentaion of the fileselector currently

(!weblink [Unofficial XaAES] [http://xaaes.atariforge.net/docs.php?chapter=6.htm#6.3])

is recommended.

The changes are mainly:

!subnode Keyboard
!begin_itemize

!item PageUp/Down(Shift-CU/CD) pages the filelist.
!item The menu is opened by Ctrl-o.
!item If an entry is selected in the list-box, Cursor-Right focusses the edit-field,
			so the selection can be edited.
!item By pressing Ctrl-C the path and the marked file (if any) is copied to
the Clipboard.
!end_itemize

!subnode File-Listing and Matching

!begin_itemize

!item Sorting is case-sensitive, i.e. Z is placed before a (like ls does
on many systems).

!item File-Pattern is case-sensitive except the filesystem is uppercase
(like FAT) or the caller runs in TOS-domain. See also: XaAES-Pattern-Matching.

!item If the fileselector finds a match while typing that match is returned
to the caller on OK (Return).

!end_itemize



!node XaAES-Pattern-Matching

XaAES supports the following meta-characters for pattern-matching:

!begin_itemize
!item any character: '?'
!item any count of any character: '*'
!item character-class: '['<characters>']'
!item invert match: '!'
!item concatenate patterns: '|' between patterns
!item case-insensitivity of pattern: '|' first character
!end_itemize

Matching *[], *!, *![], !<whole pattern>
is possible. Patterns concatenated with | will result in any pattern to be
tested for a match. This allows for example

!begin_sourcecode
launchpath=<somepath>\*.prg|*.app|*.tos|*.ttp|*.acc|!*.*
!end_sourcecode
to filter for extensions typical for executable files.

If '|' is the first character the whole pattern-list is handled
caseinsensitive.

!node Video-Modes

!node Iconifying

!node Miscellaneous

!subnode Features for XaAES-internal windows
!begin_itemize
 !item By pressing Ctrl-C the selected list-entry is copied to the
Clipboard.
 !item All XaAES-windows are resizable.
 !item	 Keyboardnavigation in all lists:
 !begin_itemize
  !item List is selected
  !begin_itemize
   !item Cursor-right: open tree
   !item Cursor-left: collapse
   !item Cursor up/down: move the cursor
  !end_itemize
  !item List is not selected
  !begin_itemize
   !item Cursor-right: scroll right
   !item Cursor-left: scroll left
	 !item Cursor up/down: scroll up/down
  !end_itemize
 !end_itemize
!end_itemize

!subnode Single-Task Mode

This has been introduced to be able to run some old but valuable
software that did not work with MiNT since version 1.16 (and maybe
earlier), especially the pure-debugger.

This implies:

!begin_itemize
!item Stop all AES-Clients.

!item Call ikbd_scan in the kernel directly not via addroottimeout in case
the single-task-client disabled the timer-interrupt.
!item No main-menu of any other app is activated.
!end_itemize

To control this currently there has to be the bit 16 (0x10000) set in
p_flags of the relevant binary.

Any client that has bit 17 (0x20000) set, is not stopped except when the
single-task-app has this bit also set, i.e. when it has 0x3xxxx.
This may be important because the single-task-client possibly does tty-IO,
and needs the toswin (or another) console.


To setup an application for this run

!begin_sourcecode
flags  <app>
!end_sourcecode

and remember the value displayed.

Then run

!begin_sourcecode
flags -f 0x1xxxx <app>.
!end_sourcecode

where the 'x' are the previously displayed values.

If a program shall not be stopped do the same but with

!begin_sourcecode
flags -f 0x2xxxx <app>
!end_sourcecode

on that program-file.

!subnode Mousewheel-Configuration

!subnode Comparison to TOS-AES

!node download

!begin_itemize
!item Daily builds: (!weblink [freemint.org] [http://www.freemint.org/builds])
!item Release-version: (!weblink [sparemint] [http://sparemint.org/sparemint/download.html])
!end_itemize

!node Contact

!begin_itemize
!item Author of this document and some enhancements to XaAES: (!maillink [Helmut Karlowski] [helmut.karlowski[at!]ish.de])
!item MiNT-mailinglist: (!weblink [mintlist] [http://sparemint.org/mailinglist/])
!end_itemize

If you find errors, bad english or want to contribute to this
document feel free to contact me or even better join the mintlist.

!end_document

