## XaAES User Manual

# XaAES: A multitasking AES replacement for MiNT

August 18, 2010
by
Helmut Karlowski et.al.

# Contents

- 1 Preface
- 2 Installation
  - 2.1 Files
    - 2.1.1 Resource-Files
    - 2.1.2 Img-Files
    - 2.1.3 Mouse-Driver
    - 2.1.4 Help-File
    - 2.1.5 Config-Files
- 3 xaaes.cnf
  - 3.1 Global Commands
  - 3.2 Commands for XaAES-clients
    - 3.2.1 Client-options
- 4 Ctrl-Alt-Shortcuts
- 5 XaAES Main-menu
  - 5.1 About
  - 5.2 The Launcher
  - 5.3 System-Window
  - 5.4 Taskmanager
- 6 Environment
- 7 Fileselector
  - 7.1 Keyboard
  - 7.2 File-Listing and Matching
- 8 XaAES-Pattern-Matching
- 9 Video-Modes
- 10 Iconifying
- 11 Miscellaneous
  - 11.1 Features for XaAES-internal windows
  - 11.2 Single-Task Mode
  - 11.3 Mousewheel-Configuration
  - 11.4 Comparison to TOS-AES
- 12 download
- 13 Contact

# 1 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:

- the spamint-wiki

- Unofficial XaAES

# 2 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.

From mint.cnf

  The keyword GEM points to xaloader.prg. FreeMiNT will now start XaAES automatically. Example:

  GEM=<sysdir>\xaaes\xaloader.prg

By init

From the command line

  In this case you may quit XaAES with Alt-Q from the taskmanager to return to the commandline.

By the TOS desktop

  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

## 2.1 Files

On startup XaAES needs the following files:

### 2.1.1 Resource-Files

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

xaaes[n].rsc

  - standard resource-file, n: resource-version, currently 009.

xaaeswdg.rsc

  - special resource-file for widgets

xa_xtobj.rsc

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

### 2.1.2 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.

### 2.1.3 Mouse-Driver

moose.adi

moose_w.adi

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.

### 2.1.4 Help-File

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

### 2.1.5 Config-Files

xaaes.cnf

This contains the configuration for XaAES. See below.

# 3 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.

## 3.1 Global Commands

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

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

CLIPBOARD <character-sequence> (default c:\clipbrd)

  Set the GEM clipboard to be in <directory>

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.

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.

RESOURCE <character-sequence> main resource filename (default xaaes009.rsc)

  See Resource-Files

WIDGETS <character-sequence> widgets resource filename (default xaaeswdg.rsc)

USEHOME <bool>

  use $HOME in shell_find

NAES_COOKIE <bool>

  fake nAES cookie

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.

LRMB_SWAP <bool>

  Swap left and right mouse buttons. Setting 'lrmb_swap = true' will make XaAES swap the left and right mouse buttons.

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.

REMAP_CICONS <bool>

  Use the palette defined in the resource to remap icons.

SET_RSC_PALETTE <bool>

  Use the palette defined in the resource as screen-palette.

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

FONT_ID <number> (default 1)

  Standard GDOS fontid for windows & stuff

STANDARD_POINT <number> (default 10)

  Size of the 'standard' AES font (for window titles, etc), high resolution

MEDIUM_POINT <number> (default 9)

  Size of the 'standard' AES font (for window titles, etc), low resolution

SMALL_POINT <number> (default 8)

  Size of the 'small' AES font.

POPSCROLL <number> (default 0)

  Set number of lines of a popup above which it will be made scrollable

DC_TIME <number/ms> (default 50)

  double click time (ms)

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.

VIDEO <number> (default 1)

  See Video-Modes

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.

POPUP_TIMEOUT <number/ms> (default = 10)

  Time in milliseconds before popups open.

POPOUT_TIMEOUT <number/ms> (default 1000)

  Time in milliseconds before popups close.

SETENV

  same as for mint.cnf

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.

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.

APP_OPTIONS <string>

  See Commands for XaAES-clients.

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.

FILTERS <comma-separated string-list>

  List of patterns that will be contained in the filter-menu of the fileselector. See also: XaAES-Pattern-Matching.

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:

  >                     cltalta_survivors = "_aes_shell_", "taskbar ", "toswin2 "

  Applications that do not act on AP_TERM will also survive.

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

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

?HELPSERVER <comma-separated string-list>

  List of apps to display help.

VERTICAL_WHEEL_ID

  See Mousewheel-Configuration.

HORIZONTAL_WHEEL_ID

  See Mousewheel-Configuration.

VERTICAL_WHEEL_AMOUNT

  See Mousewheel-Configuration.

HORIZONTAL_WHEEL_AMOUNT

  See Mousewheel-Configuration.

ICNFY_...

  See Iconifying

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.

SHELL <string>

  Names the desktop-program

RUN <string>

  Runs a program at startup. <string> is full-path\program

## 3.2 Commands for XaAES-clients

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.

### 3.2.1 Client-options

windowner

nohide

xa_nohide

xa_nomove

xa_objced

xa_none

noleft

thinwork

nolive

wheel_reverse

naesff

naes12

naes

winframe_size

inhibit_hide

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.

clwtna

alt_shortcuts <number> (default 3)

  - 0: no shortcuts

  - 1: shortcuts for alerts

  - 2: shortcuts for dialogs

  - 3: shortcuts for dialogs and alerts

  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.

# 4 Ctrl-Alt-Shortcuts

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

# 5 XaAES Main-menu

## 5.1 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:

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

## 5.2 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.

## 5.3 System-Window

In addition to the features described in

Unofficial XaAES

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

## 5.4 Taskmanager

In addition to the features described in

Unofficial XaAES

the following has been added:

List

  List is a tree, whereas clients are parent and their windows the children

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

Pocesses

  Also lists non-AES-apps (not toppable, of course)

Memory

  Displays memory-statistics found in /kern/meminfo

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)

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.

Process-Information

  Displays more process-information in a table:

  ppid

    Process-ID of a processes parent

  pgrp

    The program-group of a process

  DOM

    Domain where 'M' is MiNT-domain, 'T' is TOS-domain.

  STATE

    where

    Cur:

      Current process

    Run:

      Process is running

    Wait:

      Process is waiting

    IO:

      Process is waiting for IO

    Zomb:

      Zombie

    TSR:

      Terminated and resident

    STOP:

      Stopped

    Slct:

      Waiting in Fselect

    For more details refer to programmer/mint.txt

SZ

  Size. This is the total amount of memory the process uses.

CPU

  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.

args

  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.

# 6 Environment

XaAES uses the following environment-variables:

ACCPATH

  See Global Commands.

TOSRUN

  Define application for running text-mode programs.

HOME

  See USEHOME

PATH

  Used in shel_find for locating applications.

# 7 Fileselector

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

Unofficial XaAES

is recommended.

The changes are mainly:

## 7.1 Keyboard

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

## 7.2 File-Listing and Matching

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

# 8 XaAES-Pattern-Matching

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.

# 9 Video-Modes

# 10 Iconifying

# 11 Miscellaneous

## 11.1 Features for XaAES-internal windows

- 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

## 11.2 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:

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

## 11.3 Mousewheel-Configuration

## 11.4 Comparison to TOS-AES

# 12 download

- Daily builds: freemint.org

- Release-version: sparemint

# 13 Contact

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

# Index

A | C | D | E | F | G | H | I | K | L | M | O | P | S | T | U | V | X | Y

About

Client-options
Commands for XaAES-clients
Comparison to TOS-AES
Config-Files
Contact
Ctrl-Alt-Shortcuts

download

Environment

Features for XaAES-internal windows
File-Listing and Matching
Files
Fileselector

Global Commands

Help-File

Iconifying
Img-Files
Installation

Keyboard

LAUNCHPATH

Miscellaneous
Mouse-Driver
Mousewheel-Configuration

Resource-Files
Single-Task Mode
System-Window

Preface

snapshot

Taskmanager
The Launcher

USEHOME

Video-Modes

XaAES Main-menu
XaAES-Pattern-Matching

xaaes.cnf
xaaes.cnf

A | C | D | E | F | G | H | I | K | L | M | O | P | S | T | U | V | X | Y