August 18, 2010
by
Helmut Karlowski et.al.
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:
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.
The keyword GEM points to xaloader.prg. FreeMiNT will now start XaAES automatically. Example:
GEM=<sysdir>\xaaes\xaloader.prg
In this case you may quit XaAES with Alt-Q from the taskmanager to return to the commandline.
Sometimes quitting XaAES also works here.
Xaloader runs <sysdir>/xaaes/xaaes.km by default.
You may specify any km-file on the commandline, e.g.:
xaloader.prg [optional directory/]some.km
On startup XaAES needs the following files:
There are 3 mandatory resource-files located in the xaaes-startup-directory:
- standard resource-file, n: resource-version, currently 009.
- special resource-file for widgets
- resource containing the extended AES object icons
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.
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.
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.
Note: If there are both present moose_w.adi is used.
If a file named xa_help.txt is found its content is displayed in the About-window.
This contains the configuration for XaAES. See below.
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.
Default values are false for bool, 0 for numbers or empty for strings unless otherwise mentioned.
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
Set the GEM clipboard to be in <directory>
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.
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.
See Resource-Files
use $HOME in shell_find
fake nAES cookie
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.
Swap left and right mouse buttons. Setting 'lrmb_swap = true' will make XaAES swap the left and right mouse buttons.
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.
Use the palette defined in the resource to remap icons.
Use the palette defined in the resource as screen-palette.
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
Standard GDOS fontid for windows & stuff
Size of the 'standard' AES font (for window titles, etc), high resolution
Size of the 'standard' AES font (for window titles, etc), low resolution
Size of the 'small' AES font.
Set number of lines of a popup above which it will be made scrollable
double click time (ms)
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.
See Video-Modes
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.
Time in milliseconds before popups open.
Time in milliseconds before popups close.
same as for mint.cnf
Selects wether the previous active application or the owner of the previous topped (or only) window should be set active upon client termination.
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.
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.
List of patterns that will be contained in the filter-menu of the fileselector. See also: XaAES-Pattern-Matching.
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:
cltalta_survivors = "_aes_shell_", "taskbar ", "toswin2 "
Applications that do not act on AP_TERM will also survive.
Applications found in this list will be killed immediately during shutdown. The same rule as for CTLALTA_SURVIVORS applies to the strings
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.
List of apps to display help.
See Iconifying
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.
Names the desktop-program
Runs a program at startup. <string> is full-path\program
These may also affect XaAES itself.
The syntax is:
<app_option>: app_options = <app-name>, <options-list> <options-list>: <options-list>, <option> <option>: <option-name> = <value>
For option-name see below. Value may be a number or true/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.
0: no shortcuts
1: shortcuts for alerts
2: shortcuts for dialogs
3: shortcuts for dialogs and alerts
The shortcuts that are defined in the clients' resource-file are always there.
By pressing certain letters together with Ctrl+Alt, you can access some more or less often used functions listed below.
A: Terminates all applications (A list of exceptions can be specified)
B: open System-window
E: open windows-submenu
F,L: open task-manager
I: (un-)iconify current top-window
K: launch a program
Help: open about
T,Home: Redraw screen
D: Open the screenshot dialog - see snapshot config-option
P: Restore palette in colour depth of 8-bits or less
Q: Quit XaAES (deactivated - set HOTKEYQUIT in xa_defs.c 1 to use this)
R: Attempt to recover a system that has locked up
V: Unhide all applications
W: Global window cycling
X. Hide all except the currently focused application
Y: Hide currently focused application
space: Open main menu bar
Shift-space: Open menu in current window if it has one, else open main menubar
TAB: Cycle open applications
Cursor-right: full current window
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:
Italic:
<i> <text> </i>
Bold:
<b> <text> </b>
Underlined:
<u> <text> </u>
If a <-bracket is preceeded by backslash, is gets printed and not interpreted.
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.
In addition to the features described in
the following has been added:
Alerts have a timestamp and no '|' inside
"Environment"-Entries are sorted by name
New list-entry "System"
Screen-layout (resolution, bit-depth, pixel-format)
display CPU-info from /kern/cpuinfo
info about memory-protection
Kernel-version from /kern/version
In addition to the features described in
the following has been added:
List is a tree, whereas clients are parent and their windows the children
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).
Also lists non-AES-apps (not toppable, of course)
Displays memory-statistics found in /kern/meminfo
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)
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.
Displays more process-information in a table:
Process-ID of a processes parent
The program-group of a process
Domain where 'M' is MiNT-domain, 'T' is TOS-domain.
where
Current process
Process is running
Process is waiting
Process is waiting for IO
Zombie
Terminated and resident
Stopped
Waiting in Fselect
For more details refer to programmer/mint.txt
Size. This is the total amount of memory the process uses.
Total count of 5ms-Ticks of CPU-usage of the process.
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.
The commandline minus process-name.
The display of the taskmanager is updated on every open, or, when it's open, by pressing Ctrl-Alt-F or Ctrl-Alt-L.
XaAES uses the following environment-variables:
See Global Commands.
Define application for running text-mode programs.
See USEHOME
Used in shel_find for locating applications.
Only changes from version 0.998 to 0.999 will be described here. For a documentaion of the fileselector currently
is recommended.
The changes are mainly:
PageUp/Down(Shift-CU/CD) pages the filelist.
The menu is opened by Ctrl-o.
If an entry is selected in the list-box, Cursor-Right focusses the edit-field, so the selection can be edited.
By pressing Ctrl-C the path and the marked file (if any) is copied to the Clipboard.
Sorting is case-sensitive, i.e. Z is placed before a (like ls does on many systems).
File-Pattern is case-sensitive except the filesystem is uppercase (like FAT) or the caller runs in TOS-domain. See also: XaAES-Pattern-Matching.
If the fileselector finds a match while typing that match is returned to the caller on OK (Return).
XaAES supports the following meta-characters for pattern-matching:
any character: '?'
any count of any character: '*'
character-class: '['<characters>']'
invert match: '!'
concatenate patterns: '|' between patterns
case-insensitivity of pattern: '|' first character
Matching *[], *!, *![], !<whole pattern> is possible. Patterns concatenated with | will result in any pattern to be tested for a match. This allows for example
launchpath=<somepath>\*.prg|*.app|*.tos|*.ttp|*.acc|!*.*
to filter for extensions typical for executable files.
If '|' is the first character the whole pattern-list is handled caseinsensitive.
By pressing Ctrl-C the selected list-entry is copied to the Clipboard.
All XaAES-windows are resizable.
Keyboardnavigation in all lists:
List is selected
Cursor-right: open tree
Cursor-left: collapse
Cursor up/down: move the cursor
List is not selected
Cursor-right: scroll right
Cursor-left: scroll left
Cursor up/down: scroll up/down
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:
Stop all AES-Clients.
Call ikbd_scan in the kernel directly not via addroottimeout in case the single-task-client disabled the timer-interrupt.
No main-menu of any other app is activated.
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
flags <app>
and remember the value displayed.
Then run
flags -f 0x1xxxx <app>.
where the 'x' are the previously displayed values.
If a program shall not be stopped do the same but with
flags -f 0x2xxxx <app>
on that program-file.
Daily builds: freemint.org
Release-version: sparemint
Author of this document and some enhancements to XaAES: Helmut Karlowski
MiNT-mailinglist: mintlist
If you find errors, bad english or want to contribute to this document feel free to contact me or even better join the mintlist.
Client-options
Commands for XaAES-clients
Comparison to TOS-AES
Config-Files
Contact
Ctrl-Alt-Shortcuts
Features for XaAES-internal windows
File-Listing and Matching
Files
Fileselector
Iconifying
Img-Files
Installation
Miscellaneous
Mouse-Driver
Mousewheel-Configuration
Resource-Files
Single-Task Mode
System-Window
XaAES Main-menu
XaAES-Pattern-Matching
