Skip to content

XaAES

Jump to bottom Edit New page
Xavier edited this page May 12, 2023 · 11 revisions

Preface

Parts of this document have been copied from the sample xaaes.cnf, the old user guide, and the xaaes sources. As not everything is clear, some items have been marked with ?. Currently there are some things missing in this documentation but those that are new to the user since version 0.998 should be mostly there.

You may find additional information here:

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.

XaAES can be started by running the XaAES loader from any of the following locations:

  • From mint.cnf - The keyword GEM points to xaloader.prg. FreeMiNT will now start XaAES automatically. Example: GEM = \xaaes\xaloader.prg
  • By init - As it is configured in an EasyMiNT installation. This allows more distro specific tasks to be completed before hand.
  • From the command line - In this case you may quit XaAES with + from the taskmanager to return to the commandline.
  • By the TOS desktop - Sometimes quitting XaAES also works here.

XALOADER.PRG will then load and runs the appropriate kernel module, /xaaes/xaaes.km by default.

defaults to "/mint/" or, if this directory doesn't exist, "/mint". is the version of the kernel where dots are replaced by minus, e.g. 1.17.0 gives 1-17-0. Any version compiled from cvs, including the daily builds replaces the last point value with cur, e.g. 1-18-cur .

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

xaloader.prg [optional directory/]xaaes.km

Files

On startup, XaAES uses various files, some of which can be changed at load time.

Resource Files

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

  • xaaes.rsc - standard resource file. is the resource version, currently 014.
  • xamno.rsc - mono resource file. is the resource version, currently 014.
  • xaaeswdg.rsc - special resource file for widgets
  • xa_xtobj.rsc - resource containing the extended AES object icons

The system-resource-file has a version-number (currently 0.1.6). The file name defined in xaaes.cnf is used to load this reosurce file, if not present xaaes.rsc is used.

There is also a resource file for monochrome display (xa_mono.rsc) that reportedly saves memory. Some assistance in updating these resources would be useful.

You can choose other resource files for the first two in xaaes.cnf. For example to get different widgets, there are some in the widgets folder.

There are also checkbox and tickbox widget alternatives to the xa_xtobj.rsc in the directory xobj in the XaAES folder.

For more information on widget and extended widget object file, see Widgets and Buttons in the section on Theming and Extended Textures.

IMG Files

XaAES also reads IMG files from a folder called img in the current XaAES folder. This is needed if you want the textured look. If not present, you get the default rendering. This does not affect the use of the gradient setting in xaaes.cnf

For more information on texture files, see Theming and Extended Textures.

Mouse Drivers

  • 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 on the mouse.

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

For more information on configurations, see Mouse Configuration

Help File

If the help file xa_help.txt is found its content is displayed in the About window, accessible from XaAES menus. The default help file is English, there also are help files for: CS, DE, ES, FR, HU, RU.

Config Files

  • xaaes.cnf

This contains the configuration for XaAES. See below (next topic).

xaaes.cnf

The XaAES configuration file is in the same format as the MiNT configuration file (mint.cnf). It lets you set several runtime options for XaAES, global or environment variables, application specific settings for clients and programs to be run automatically at start up.

Commands are not case sensitive unless stated otherwise. bool values can be true or false, yes or no.

Lines starting with # (hash) are considered remarks, and are ignored. If a command is not understood, it will get ignored.

Global Commands

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

General

  • INCLUDE - Include another config file at this place. E.g. include c:\mint\startapps.cnf
  • SETENV - Set an environment variable, or override one previously set. May be used multiple times. Same format as for mint.cnf. This is also used in combination with shell to correctly run most dektops. E.g. setenv TOSRUN c:\toswin\tw-call.app - See Setting a Desktop
  • RESOURCE (default xaaes.rsc) - main resource filename. E.g. resource = xa_mono.rsc - See Resource Files
  • VIDEO (default 1) - See Video Modes
  • USEHOME (default true) - use the contents of the $HOME environment variable in shell_find function. E.g. usehome = false
  • CANCEL - List of words that XaAES interprets as Cancel. A button containing a word from this list in a dialog or alert will be selected if Undo is pressed. E.g. cancel = cancel,abbruch,annuler,avbryt,anuluj,afbryd,undo
  • FILTERS - List of patterns that will be contained in the filter-menu of the fileselector.

Mouse

See Mouse Configuration for more details on setting specific options.

  • LRMB_SWAP (default false) - Swap left and right mouse buttons. If you are left handed, setting will make using XaAES and user desktop more natural. E.g. lrmb_swap = true
  • DC_TIME <number/ms> (default 50) - double click time in milliseconds. E.g. dc_time = 35
  • 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 the mouse driver (moose.adi). E.g. mp_timegap = 5
  • VERTICAL_WHEEL_ID (default 0) - Set which mouse wheel to use for veritcal scrolling. E.g. vertical_wheel_amount = 1
  • HORIZONTAL_WHEEL_ID (default 1) - Set which mouse wheel to use for horizontal scrolling. E.g. horizontal_wheel_id = 0
  • VERTICAL_WHEEL_AMOUNT (default 1) - The number of text lines to scroll up or down. E.g. vertical_wheel_amount = 3
  • HORIZONTAL_WHEEL_AMOUNT (default 1) - The number of text characters to scroll left or right. E.g. horizontal_wheel_amount = 5
  • EIFFEL_SUPPORT (default false) - if set F-keys > 10 cause eiffel mouse wheel events. E.g. eiffel_support = true

Look

  • RESOURCE (default xaaes.rsc) - dialog resource filename E.g. resource = xamno.rsc
  • WIDGETS (default xaaeswdg.rsc) - window widgets resource filename E.g. widgets = widgets/magicwdg.rsc
  • XTOBJS (default xa_xtobj.rsc) - extra widgets (checkbox & tickbox) resource filename E.g. xtobjs = xobj/nine-ozk.rsc
  • REMAP_CICONS (default false) - Use the palette defined in the resource to remap colour icons. E.g. remap_cicons = true
  • SET_RSC_PALETTE (default false) - Use the palette defined in the resource as the screen palette. E.g. set_rsc_pallete = true
  • WIDGET_AUTO_HIGHLIGHT (default false) - When true, standard window widget are automatically highlighted when the 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. E.g. widget_auto_highlight = true
  • GRADIENTS (default 0) - setting gradients to default/1, or the name of a file in the gradients folder (XAAES/PAL/*.GRD) allows the use of colour gradients in the window widgets and AES object renderer in hicolour or truecolour video modes. This replaces the use of texture images. E.g. gradients = n_yellow
  • IMGS (default img) - use a different directory to load image textures from. Setting gradients to a non-zero value will stop the loading of textures. If the folder is empty, no textures will be loaded, resulting in a traditional GEM look. E.g. imgs = themes/ecogreen
  • PALETTE (default internal) - load a specific palette from XAAES/PAL/*.PAL, resulting in a traditional GEM look. E.g. palette = gem
  • BACK_COL (default 13) - change the default background color. Color numbers are standard color palette order. E.g. back_col = 13
  • MENUBAR (default 2) - hideable menubar, where 0 is off, 1 is on, and 2 is always on (default). E.g. menubar = 0
  • MENU_LAYOUT (default 0) - menubar style, where 1 is short and 0 is long, the traditional GEM look. E.g. menu_layout = 1
  • MENU_ONTOP (default 1) - menubar may be overwritten (0) or not (1). E.g. menu_ontop = 0

Feel

  • 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. E.g. menu = pull
  • MENUPOP_PIDS (default false) - Setting this to true makes XaAES list its clients in the client list menu popup 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' or 'false' process ID's are not listed, only the client's nice name if available, else its process name (proc_name). E.g. menupop_pids = true
  • 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 grey colour until the client re-enters evnt_multi(). For slow machines, this timeout must be higher (longer) than on faster machines. E.g. redraw_timeout = 1500
  • POPUP_TIMEOUT <number/ms> (default 10) - Time in milliseconds before popups open. E.g. popup_timeout = 100
  • POPOUT_TIMEOUT <number/ms> (default 1000) - Time in milliseconds before popups close. E.g. popuot_timeout = 800
  • POPSCROLL (default 0) Set number of lines of a popup above which it will be made scrollable. E.g. popscroll = 5
  • NEXT_ACTIVE <'client' or 'window'> (default window) - Selects whether the previous active application or the owner of the previous topped (or only) window should be set active upon client termination. E.g. next_active = client
  • 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 in front, making it active. This is the normal behaviour done by other AES's we thinks. - DONT USE THIS SETTING
  • ALERT_WINDOWS (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. E.g. alert_windows = 0x0000 - THIS IMPLEMENTATION IS NOT DEFINATE AND ONLY PARTIAL
  • NAES_COOKIE (default false) - fake nAES cookie. Some applications need to think they are running under N.AES.

Iconify

There are some complex details regarding the use of the iconify setting in XaAES. For more detailed information see the section on Iconifying.

  • ICNFY_ORIENT (default 3) - Screen start position and direction. E.g. icnfy_orient = 0x103
  • ICNFY_WIDTH (default 72) - Width in pixels before next icon is placed next to each other. E.g. icnfy_width = 80
  • ICNFY_HEIGHT (default 72) - Height in pixels of new row for iconified icons. E.g. icnfy_height = 64
  • ICNFY_LEFT (default 0) - Number of pixels from left edge of screen. E.g. icnfy_left = 100
  • ICNFY_RIGHT (default 0) - Number of pixels from left edge of screen. E.g. icnfy_right = 2
  • ICNFY_TOP (default 0) - Number of pixels from left edge of screen. E.g. icnfy_left = 20
  • ICNFY_BOTTOM (default 0) - Number of pixels from left edge of screen. E.g. icnfy_left = 32
  • ICNFY_REORDER_TO (default is 0) - Setting this to a non zero value will make XaAES rearrange the currently iconified windows when an iconified window is uniconified or hidden. This will also, later on, reorder iconified windows when an application that quits had iconified windows. E.g. icnfy_reorder_to = 100

Font-settings

  • FONT_ID (default 1) - Standard GDOS fontid for windows & stuff
  • STANDARD_POINT (default 10) - Size of the 'standard' AES font (for window titles, etc) in high resolution
  • MEDIUM_POINT (default 9) - Size of the 'standard' AES font (for window titles, etc) in low resolution
  • SMALL_POINT (default 8) - Size of the 'small' AES font.
  • INFOLINE_POINT (default -1, same as STANDARD_POINT) - Define font-size for window infoline in points.
  • XAW_POINT (default 10) - Define font-size for XaAES windows in points.

Applications

  • APP_OPTIONS - See Client-options
  • CTLALTA_SURVIVORS - 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 " (5 spaces). Each app-name is separated with comma. This will allow you to specify which applications XaAES does not attempt to terminate when user presses
      • 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 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 + + + . Applications that do not act on AP_TERM will also survive. The following will keep the desktop, taskbar and toswin2 running after a + + action:
cltalta_survivors = "_aes_shell_", "taskbar ", "toswin2 "
  • KILL_WO_QUESTION - Applications found in this list will be killed immediately during shutdown. The same rule as for CTLALTA_SURVIVORS applies to the strings. E.g. kill_wo_question = "procalc ","mintsett", "st-guide", "xcontrol"

Paths

  • LAUNCHPATH (default is XaAES directory) - Define the initial directory that is opened by the XaAES launcher to start programs. A pattern to select typical executable files may be appended. Eg: launchpath = u:\usr\gem\|*.prg|*.app|!*.*|*.acc - See XaAES Pattern Matching
  • CLIPBOARD (default c:\clipbrd) - Set the GEM clipboard directory. Eg clipboard = c:\home\clipbord
  • ACCPATH (default c:\) - Set the location that XaAES will try to load accessories from. When ACCPATH is present in the Environment this precedes the config variable. E.g. accpath = c:\acc

Programs

  • SNAPSHOT - Define a snapshot program or screen grabber. 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 here is called, if present. E.g. snapshot = c:\apps\snapshot.prg
  • HELPSERVER - Help file formats and where to find the program you want to handle them. This variable may be defined more than once to allow for different file types. E.g. helpserver = HYP,ST-GUIDE,c:\st-guide.acc
  • SHELL - Path and filename of the program you wish to use as your desktop. E.g. shell = c:\teradesk\teradesk.prg
  • RUN - Runs a program at startup. Must be path and filename. Can be used more than once. E.g. run c:\taskbar\taskbar.prg

Setting a Desktop

In order for a desktop to function correctly, certain environment variables usually need to be set up first. The following are examples known to function with that desktop, when the appropriate files are in the described locations. The program set in shell will be run after all other programs set with run have been executed.

Note: the use of replacement file selectors is not recommended.

The length on the string used to set AVSERVER and FONTSELECT is 8 characters in total, padded with spaces. This information is usually available in the documentation that comes with your chosen desktop.

  • Thing
setenv AVSERVER   "THING   "
setenv THINGDIR   u:\c\thing
shell = c:\thing\thing.app

optional: 

setenv FONTSELECT "THING   "

Note: when using thing, if THINGDIR is not set, $HOME will be used instead.

  • Jinnee
setenv AVSERVER   "JINNEE  "
setenv FONTSELECT "JINNEE  "
shell = c:\jinnee\jinnee.app
  • Teradesk
setenv AVSERVER   "DESKTOP "
shell = c:\teradesk\desktop.prg

optional: 

setenv FONTSELECT "DESKTOP "
setenv OLGAMANAGER c:\olga.app

You can start Teradesk or Thing from the XaAES launcher as well. It is possible to set console as the shell, but it these not AV servers, there is however a standalone AVSERVER available (oldish).

Client Options

XaAES allows for any application to be tweaked in how it acts, looks or feels. XaAES itself can be be modified by using the application name aessys.

The syntax is: 

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

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

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

The app-name above is the filename part of the program file. 'default' affects all applications. A 'default' configuration has to be specified first. With appname being 'aessys', you can specify the configuration for the aessys's windows, like taskmanager, etc.

  • windowner (default false) - Will make XaAES show the name of the application owning the window in the window's title.
  • nohide (default false) - Windows will not have the HIDE widget, and thus cannot be hidden.
  • xa_nohide (default true) - Windows containing form_do() sessions will not have the HIDE widget and thus not be hidable. Autosort is one application that cannot have its form_do() session hidden (or moved).
  • xa_nomove (default true) - Windows containing a form_do() session will not be moveable. These are usually dialog or Alert boxes. The XaAES file selector is affected by this setting, when the application is aessys. Autosort is one such application that requires a setting of true.
  • standard_font_point (default 10) - Set standard font-size, in points. This is set on every main menu switch.
  • noleft (default false) - Windows can not be moved off screen to the left.
  • nolive (default false) - Disables live window move, resize, etc.
  • thinwork (default false) - The "inner" 3d-effect is disabled. This 3d-effect 'frames' the work-area of windows in a 3d-ish frame.
  • winframe_size (default 1) - Set the size of window frame. A value of -1 sets "overscan windows", which contains no frame or shadowing. It is not recommended to set a value of -1 yet!. A value of 0 will make windows without any borders. Positive values make window-frames larger. Be aware that no window fram border usually means no window resizing by grabbing the brorder (because there isn't on to grab).
  • naesff (default false) - N.AES Full Fix. When set to true, XaAES will send full WM_REDRAW message when all four window coordinates change, which happens when windows are FULLed (maximized). This will fix redraw problems with apps like Jinnee.
  • wheel_reverse (default false) - If set to true then the mouse wheel directions are inverted or reversed.
  • inhibit_hide (default false) - Setting this will prevent the app from being hidden by XaAES, which is very handy for applications like Taskbar, zTask, or FreeGEM. It can be considered the same an "always on top" setting found on other OS's.
  • spaceXinsert (default false) - This exchanges the space bar/insert key behaviour in dialogs and lists. If false, insert (INS) will select a button in a dialog, space will select a list. This option is case sensitive, so for example SPACEXINSERT will not be recognized.
  • clwtna - (Close Last Window Tops Next App) Allows you to choose what to do when the last window of a client or application that is on top has been closed. This argument takes a value of 0, 1 or 2, which have the following meaning;
    • 0 - This keep the client whose last window is closed from being untopped. This prevents XaAES from topping another application when the last window it owns is closed.
    • 1 - This will top the owner of the window below the closed window. That is, the owner of the window previously ontop will be topped. This is the normal behaviour found on other AESs.
    • 2 - This will top the previously topped client, regardless of windows. Even when the previously active client dont have any windows, it will get topped.
  • icn_pal_name - (Set mapping-palette for icons) Icon- colours for the app will be mapped according to the specified palette. The global command palette has to be set. To remap widgets set icn_pal_name for aessys. This only has an effect if icn_pal_name and pal differ. The palette specified by icn_pal_name has to be in the pal-dir. Currently only 8bit-icons are supported. The palette given in the rsc-file precedes the palette set by icn_pal. remap_cicons must be true.
  • alt_shortcuts (default 3) - 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.
    • 0 - no shortcuts
    • 1 - shortcuts for alerts
    • 2 - shortcuts for dialogs
    • 3 - shortcuts for dialogs and alerts.
  • rsc_lang (default 0) - If set XaAES creates or uses a translation file (.rsl) for this application.
    • 0 - no translation
    • 1 - read an existing translation file (or create, if not present)
    • 2 - always create a translation file (overwrite existing one)
  • ignore_rsc_size (default false) - If true difference between resource-filesize and size given in rsc-header is no error.

Client Examples

Some working examples of applications. Some that function better, others are more for visual effect. Note the use the application named aessys. This is the AES itself, and any settings here will be used by default.

app_options = default, thinwork = true, winframe_size = -1, xa_nomove = false,  clwtna = 0
app_options = aessys, thinwork = true, winframe_size = 0, xa_nomove = false
app_options = autos401 ,xa_nomove = true
app_options = ataricq, thinwork = true, winframe_size = 0
app_options = jinnee, naesff = true

Ctrl-Alt-Shortcuts

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

      • : Terminates all applications (a list of exceptions can be specified)
      • : open System window
      • : open window sub menu
      • : Open the screenshot dialog - see snapshot config option
      • , + + :: open or refresh task-manager
      • : Halt system (and execute SDMASTER if set)
      • : open about
      • : (un-)iconify current top-window
      • : launch a program
      • ,: Redraw screen
      • : Restore palette in colour depth of 8-bits or less
      • , + + : Quit XaAES (and execute SDMASTER if set)
      • : Attempt to recover a system that has locked up
      • : Unhide all applications
      • : Global window cycling
      • : Hide all except the currently focused application
      • : Hide currently focused application
      • : Open main menu bar
        • : Open menu in current window if it has one, else open main menubar
      • : Cycle open applications
      • : full current window

XaAES Main-Menu

About
XaAES
The XaAES Aboutbox

Instead of listing lots of contributors to XaAES and part of the GPL as in previous versions, the main web address for MiNT and the GPL copyright are now 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 less-than-sign (<) is preceeded by backslash (escaped, eg. \< ), is gets printed and not interpreted.

Launch Program

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.

Launch Desk

This option is used to restart the chosen desktop as defined in the XaAES configuration file variable SHELL. eg shell = c:\teradesk\desktop.prg

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
  • 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 /doc/programmer/mint.txt)
    • SZ - Size. This is the total amount of memory the process uses.
    • CPU - CPU Time. Total count in 5ms Ticks of CPU usage by 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 arguments, minus the process name.

The taskmanager is only updated when opened. It can be refreshed by pressing + + or + + .

System-Window

In addition to the features described in Unofficial XaAES documentation, 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 information from /kern/cpuinfo
    • Information about memory-protection
    • Kernel version from /kern/version

Quit All Apps

Closes all applications running under XaAES, which include those started from the desktop shell.

Quit XaAES

This option quits XaAES.

Fileselector

Only changes from version 0.998 are described below. For extensive documentation of the fileselector see the Unofficial XaAES documentation online.

Keyboard

  • , ( + , ) pages the filelist.

  • The menu is opened by + .

  • If an entry is selected in the list-box, focusses the edit-field, so the selection can be edited.

  • By pressing + the path and the marked file (if any) is copied to the Clipboard.

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

XaAES Pattern Matching

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

  • any character: '?'
  • any count of any character: '*'
  • character-class: '['']'
  • invert match: '!'
  • concatenate patterns: '|' between patterns
  • case-insensitivity of pattern: '|' first character

Matching *[], *!, *![], ! 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 case-insensitive.

Environment

XaAES uses the following environment variables when available, but they do not need to be present in xaaes.cnf:

  • ACCPATH - Set accessories path Paths
  • TOSRUN - Define application for running text mode (console) programs.
  • HOME - Set the home path, often set in mint.cnf. See Paths
  • PATH - Default search paths. Usually already set by mint.cnf or the system (console startup script). Used in shel_find for locating applications.
  • SDMASTER - Shutdown master. If set to an existing program, it is executed when leaving XaAES by a hotkey. See Ctrl-Alt-Shortcuts

Environment variables are also used when setting a desktop to be used with XaAES, see Setting a Desktop under xaaes.cnf.

  • SDL_VIDEODRIVER - Help control video rendering on ARAnyM when using fVDI. E.g. setenv SDL_VIDEODRIVER gem

Any environment variables set in mint.cnf can be over-ridden by setting the same variable in xaaes.cnf. You can also define any environment variables the could be used in a console program, or by any other application. E.g. setenv GEMJINGPATH u:\c\gemjing\gemjing.prg

Mouse Configuration

In the XaAES configuration file ('' xaaes.cnf ''), there are various configuration settings available for the mouse and the mousewheel.

Swapping Mouse Buttons

To swap the mouse buttons, because you are lefthanded, us the following setting:

  • LRMB_SWAP (default false) - E.g. lrmb_swap = true

Mouse Timings

The following setting can be useful in ensuring a more comfortable user experience:

  • DC_TIME <number/ms> (default 50) - double click time in milliseconds. E.g. dc_time = 35
  • 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 the mouse driver (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 (as in Thing's directory window), and the "extra click" fires some unwanted action. E.g. mp_timegap = 5

Using the Mousewheel

In order to use the mousewheel, moose_w.adi must be loaded. If your mousewheel is not working, check that the file is present in the XaAES folder, and named as described. If it is present and named correctly, it will be the first mouse driver that XaAES looks for. Otherwise it will look for and then load moose.adi. If both are present, the moose_w.adi is loaded.

There are currently four settings available that are used to set wheel configuration:

  • VERTICAL_WHEEL_ID (default 0) - Set which mouse wheel to use for veritcal scrolling. E.g. vertical_wheel_amount = 1
  • HORIZONTAL_WHEEL_ID (default 1) - Set which mouse wheel to use for horizontal scrolling. E.g. horizontal_wheel_id = 0
  • VERTICAL_WHEEL_AMOUNT (default 1) - The number of text lines to scroll up or down. E.g. vertical_wheel_amount = 3
  • HORIZONTAL_WHEEL_AMOUNT (default 1) - The number of text characters to scroll left or right. E.g. horizontal_wheel_amount = 5

With vertical_wheel_id you can choose which wheel you want to use as the vertical wheel. Likewise with horizontal_wheel_id, you set the ID of the wheel you want to define as the horizontal wheel. Do NOT set the same value for both vertical and horizontal wheel ID's.

With vertical_wheel_amount you can set the amount of lines to scroll per turn of the vertical wheel. Likewise, you can set the amount of columns to to scroll per turn of the horizontal wheel using horizontal_wheel_amount. The value for these configuration variables must be a number between 1 and 20. Per now, this actually sets the number of WM_ARROWED messages send to the application per turn of the wheel.

For those with mouse connected through an Eiffel interface, support for the mousewheel is enabled with:

  • EIFFEL_SUPPORT (default false) - if set F-keys > 10 cause eiffel mouse wheel events. E.g. eiffel_support = true

Iconifying

  • ICNFY_REORDER_TO (default is 0) - Setting this to a non zero value will make XaAES rearragne the currently iconified windows when an iconified window is uniconified or hidden. This will also, later on, reorder iconified windows when an application that quits had iconified windows. E.g. icnfy_reorder_to = 100

Orientation and Direction

  • ICNFY_ORIENT (default 3) - Screen start position and direction.his controls how XaAES arranges iconified windows. Currently the following orientations are available:
    • 0 - Iconified windows are stacked top -> bottom starting at the top/left of the screen. When one column is full, the next column is being used.
    • 1 - Iconified windows are stacked top -> bottom starting at the top/right of the screen. When a column is full, windows are stacked in the column to the left of the filled one.
    • 2 - Iconified windows are placed in rows going left -> right starting at the top/left of the screen. When a row is full, the row below the current one is used.
    • 3 - Iconified windows are placed in rows going left -> right starting at the bottom/left of the screen. When a row is full, the row above the current one is used.
    • If your bit 8 in icnfy_orient value is set, then the starting position will be reversed. This means that for orientation 0, the windows will be stacked bottom -> top starting at the bottom-most position instead. Using a hexadecimal value is easy for better readability.

Examples:

  • icnfy_orient = 0x003 - Start at left/bottom of the screen and go towards the right/bottom.
  • icnfy_orient = 0x103 - Start at right/bottom corner and go towards windows towards the left/bottm corner.

Iconify Icon Size

  • ICNFY_WIDTH (default 72) - Width in pixels before next icon is placed next to each other. E.g. icnfy_width = 80
  • ICNFY_HEIGHT (default 72) - Height in pixels of new row for iconified icons. E.g. icnfy_height = 64

Edge of Screen

  • ICNFY_LEFT (default 0) - Number of pixels from left edge of screen. E.g. icnfy_left = 100
  • ICNFY_RIGHT (default 0) - Number of pixels from right edge of screen. E.g. icnfy_right = 2
  • ICNFY_TOP (default 0) - Number of pixels from top of screen. E.g. icnfy_top = 20
  • ICNFY_BOTTOM (default 0) - Number of pixels from bottom of screen. E.g. icnfy_bottom = 32

These variables dictate how far from left, right, top and bottom edges of the screen the iconified windows should be placed. This means that if icnfy_left is set to 4, iconified windows are always placed minimum 4 pixels off the left edge of the screen. If you want to protect the area of the taskbar, for example, you can use icnfy_bottom = 20, as that makes sure iconified windows never get closer to the bottom of the screen than 20 pixels.

Theming and Extended Textures

XaAES allows for textures to be used in various parts of the GEM interface. Individual IMG files may be changed according to your preference, or a complete theme can be used. Some of the files and themes mentioned here may be available on the Unofficial XaAES website.

No IMG files or file names are absolutely required, as there are no problems caused if any are missing. There is a specific layer order in which the textures are used allowing certain textures to be automatically used when others are missing.

XaAES has a specific naming convention for the different parts that are textured, a system which was extended to allow individual parts of scroll bars and unfocused windows to be textured as well. There are now skinning and texture conversion tutorials available on the internet.

Textures from Previous Versions

The texture images and naming conventions from previous versions are still valid, for those who have created there own, or have a desired look they wish to continue using with newer versions of XaAES. Sharing themes, textures or screenshots will help to make more themes available in the future.

Textures in Newer Versions

Some themes are now available that make better graphical use of GEM's interface when rendered by XaAES. Previous themes can now be enhanced with specific textures for individual parts of the window scroll bars, separate from those used in the new Scrolling List Box object in XaAES, which is used in the file selector.

The extended textures also allow for different focused and unfocused themes. A completely different look can be seen for the current window and any window you are not currently using, allowing for subtle colour differences with shading, high contrast with completely different colours, or even different patterns, the choice is now yours.

Using Basic Textures

The following file names and what they affect are listed in the layered order that XaAES uses to build various parts of GEM's interface. Any texture named this way will also work with any version 0.998 of XaAES that comes with version 1.16.3 of FreeMiNT or older. All images are tiled left to right, top to bottom.

  • EXTERIOR.IMG - affects the window box, within which all other parts are drawn on top, including the background before any window buttons or widgets are drawn. It is rendered from the top left position of most square objects, except for many text input types and the content area of a scrolling list box.
  • INFO.IMG - window info or status bar background. The minumum height containing small font size text in this area is (? what ?) pixels.
  • WTITLE.IMG - window title bar, not including the button or widget areas, also used for popup or alert box title bars. The minimum height containing standard font size text is 21 pixels. This is also used as the basis for the scrolling list box background. Excludes title bar button or widget areas.
  • SLWTITLE.IMG - title bar background for scrolling list boxes, not including the button or widget areas. The minimum height containing standard font size text is 21 pixels.
  • POPBKG.IMG - main menu and window menu background, as well as some popup menu backgrounds. Remember that some menus are wider that others, like the history menu in Highwire.
  • DBOX.IMG - dialog(?) box background. This is used for the as the basis for DTEXT rendered areas, and most DBUTTON areas, but not all.
  • DTEXT.IMG - text boxes not used for input purposes or disabled input types. Often on multiple layers, only certain texture styles are suitable in achieving the desired visual effect or seamless appearance when the texture is draw in a new area. Not all text area types are affected, those being rendered in a plain colour.
  • DBUTTON.IMG - button backgrounds. These areas are not always of a certain height, so a nice vertical flow of the texture is often desired.
  • SLIDE.IMG - the area in which a scroll bar moves. This is also the basis before SLIDER.IMG is rendered. It is the basis for both horizontal and vertical scroll bar area, including where scroll buttons or widgets are to be drawn.
  • SLIDER.IMG - the scroll bar itself. These areas are approximately 20 pixels across, including both border outlines.

Using Extended Textures

The following file names and what they affect are listed in the layered order that XaAES uses to build various parts of the scroll bars, and unfocused windows and there objects. These will have no affect on XaAES texturing before version 1.17.0 of FreeMiNT. All images are tiled left to right, top to bottom.

  • UXTERIOR.IMG - overlays EXTERIOR.IMG for all unfocused windows when present, becoming the basis form most object drawn on the unfocused window.
  • INFOU.IMG - for unfocused menus. Does not seem to have much effect.
  • WTITLEU.IMG - background for unfocused window title bars and unfocused popup or alert box title bars. The basis for unfocused scrolling list box title bars. Excludes title bar button or widget areas.
  • ULWTITLE.IMG - background for unfocused scroll list box title bars. Does not seem to have much effect.
  • SLIDE.IMG - becomes horizontal scroll bar area for both scroll list boxes and focused windows, when VSLIDE.IMG is present.
  • SLIDEU.IMG - replaces SLIDE.IMG as the basis for all scroll bar areas in unfocused windows. Does not affect scroll bar areas of scroll list boxes in unfocused windows. It is the horizontal scroll bar area when VSLIDEU.IMG is present.
  • VSLIDEU.IMG - replaces SLIDEU.IMG in the vertical scroll bar area of unfocused windows.
  • VSLIDE.IMG - replaces SLIDE.IMG in the vertical scroll bar area of both scroll list boxes and focused windows.
  • SLIDE.IMG - becomes te horizontal scroll bar for both scroll list boxes and focused windows, when VSLIDER.IMG is present.
  • SLIDERU.IMG - replaces SLIDER.IMG as the scroll bar in unfocused windows. Does not affect scroll bar areas of scroll list boxes in unfocused windows. It is the horizontal scroll bar when VSLIDERU.IMG is present.
  • VSLIDERU.IMG - replaces SLIDERU.IMG as the vertical scroll bar for unfocused windows.
  • VSLIDER.IMG - replaces SLIDER.IMG as the vertical scroll bar for both scroll list boxes and focused windows.

Texture File Formats

XaAES's texturing works in either 8 bit colour mode with 256 colours in a palette, or any hicolour colour mode with 32767 (15 bit) colours or more, most often with 65534 (16 bit) colours or 24 bit (16.4 million) colour modes. This is reflected in the names of the folder found in XaAES's image directory, XAAES/IMG/8B/ and XAAES/IMG/HC/ respectively.

Although the images used in the 8B folder can be 256 colour (8 bit) XIMG images, experiments have found that that standard 16 colour images give far better results, as there is a colour mapping algorithm that map the image into the 256 colour palette, with can cause hideous results, even when the image uses the correct palette.

Again with XaAES's hicolour mode rendering, although some of the original texture images in the HC folder are 24 bit XIMG images, better results are often gained by using 256 colour XIMG images saved with the correct colour palette. Note that the 24 bit XIMG format was never formally defined, but rather came from the rules of logic which outlined the 2, 4 , and 8 bit formats that cam before it. This has affected the reliability of the format, in that not all 24 bit XIMG format images are compatible with XaAES.

XaAES can now look for images in folders other than the default IMG folder in its own directory (see: Feel).

Colour Palette Troubleshooting

There are two different colour palettes widely in use for Atari ST based GEM desktops. The first one is the standard 256 colour palette that comes built into the Atari Falcon and Atari TT, with the first sixteen colours mapping to those found on the Atari ST/e. This is sometimes referred to as a hardware palette, and is often considered to be very dark as the colours were chosen by purely mathematical divisions.

The second palette was initial designed for NVDI usage, with softer and more pastel colouring, which became common on MagiC systems, two versions of which was supplied with Jinnee desktop replacement. It can be found by the names of NVDI.PAL, and ALTERNAT.PAL. fVDI has the ability to load a palette file at boot time, if your system uses that VDI replacement. XaAES now comes with the palette file XAAES/PAL/GEM.PAL (see: Feel).

Colour palettes can be edited and created on most systems using XCONTROL's colour palette tool. With graphical desktop set up to use a hicolour mode, a 256 colour palette is also available, as a colour palette is still often reference from a time when not even 256 colours where available.

The textures used and what they look like when using XaAES are directly related to both the colour palette used by the desktop (through the VDI) and the original colour palette used when the image was saved. You will know the two are not is sync when you see colour desktop icons and XaAES textures displayed in often strange psychedelic colour combinations.

Generally speaking from experience, you should match the colour palette of your desktop to the icons you are using or want to use with your desktop replacement. Some of the better icon sets use the NVDI palette. Only then match the texture images or theme pack to that same colour palette, as it will save a lot of headaches that way. Sometimes modifying the desktop colour palette without modifying the images can give pleasant results.

The above mentioned colour palettes are available for GIMP, and as GIF images.

Widgets and Buttons

Widget files are a standard format, with a specific unnamed tree structure. Window widget and scroll bar buttons are contained in one RSC resource file. The select mode of the icons can be used to do a mouse over style button change. Each icon resource set should contain mono, 16 and 256 colour icons. If no selected icon is present, the unselected one will be used instead. These files can be any name in any location, as long as they are correctly entered into XAAES.CNF.

XaAES can also use a checkbox and radio button RSC resource. Again these widget files are a standard format, with a specific unnamed tree structure. Each widget type consists of four images unselected, selected, disabled and focused. By default XaAES will read this from the location XAAES/XA_XTOBJ.RSC (see: Feel).

When creating themes, sometimes it is better to add a background to the images and icons. However, if you are doing a widget set for any theme, especially one where the background or colour is likely to change, a transparent background is more suitable. There are quite a few window button resources that come with XaAES, but only one or two checkbox and tickbox widget sets.

Creating Texture Files

If you are using Windows or Linux to design and create the textures you wish to use with XaAES, you can find the standard 16 colour, 256 colour, and NVDI 256 colour palettes available for GIMP, which makes life easier.

Textures can not be larger than 720 x 720 square. The longest title bar texture is 1600 x 21 in size. Scroll bar textures are 20 pixels across, possible maximum size of 1800 x 20 (and 20 x 1800, both untested). It is believed that XaAES can not read more than 518400 pixels per image.

Various file formats are available, but the best suited to conversion between OS platforms are GIF, TGA and TIFF. Here are are some rules to follow regardung use of those formats:

  • GIF - 256 colours or less. There are two formats, GIF87a or GIF89a). Not all Atari ST tools support both.
  • TGA - 256 colours to 32 bit (16.4 million + alpha channel) colour. These usually come in one flavor.
  • TIFF - 24 bit (16.4 million) colour or less. When saving these files you are given compression options, always use the least or no compression as a lot of Atari ST tools do not support higher compression.

There are a few free tools to help converting images back and forth between image formats, here are a couple to get you started:

  • zView - by Zorro is free and a great image view that contains an image conversion tool. ( http://the.zorro.free.fr/zview.html )
  • GEMView - by Dieter Fiebelkorn. Can now be used for free by registering with the author by email. ( http://www.fiebelkorn.net/GEMVIEW.HTML )
  • GrafTool - by Joergen von Bargen is another tool from way back in 1997. This one is unfinished and is very definitely still in the beta stage, and is in German only. Although it is a somewhat quirky tool, it can successfully be used, has a batch mode, and can handle palette files as well. (check an ftp archive for GT970106.LZH).

If you have a good setup on your Atari ST, TT or Falcon, and paint program that can save 256 colour and 24 bit (16.4 million) colour XIMG image files should be able to do the job. However XaAES 24 bit XIMG format is not as common as it should be.

Video Modes

Note: Use of the video setting is not meant for normal use with ARAnyM, or systems with PCI based video cards. In ARAnyM the desktop resolution is set from its front end, and through the use of fVDI and its fdvi.sys configuration file.

  • VIDEO (default 1) - This selects the video mode that XaAES will boot into.

If not set, will be set to 1, which means is "use current or default video mode". If you don't have a Falcon, can be:

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

All other values are ignored!

If you have a Falcon, is the same argument as to the VsetMode() OS call:

  • BIT: Name - Meaning
  • 0-2: BPS - Number of bitplanes:
    • '''000 ''': 2colour
    • 001: 4colour
    • 010: 16 colour
    • 011: 256 colour
    • 100: 16 bits/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.

Note: When you use a screen expander like Screenblaster, you have to use the video option as well. This will make the Screenblaster software to show up the resolution selection menu.

Examples:

  • video = 0x801b - use current rez, 256 colours.
  • video = 0x801c - use current rez, 16 bit/truecolour.
  • video = 4 - select 640*400*2 colour (ST High)(mono).
  • video = 0x801a - will select 16 colour VGA mode in the resolution preset by CentScreen.
  • video = 0x801b - will select 256 colour VGA mode in the resolution preset by CentScreen.
  • video = 24 - will select 640*480*16 colour VGA mode.
  • video = 26 - will select 640*480*16 bit/truecolourcolour VGA mode.
  • video = 27 - will select 640*480*256 colour VGA mode.
  • video = 0x0018 - will select 640*480*16 colour VGA mode.

Miscellaneous

Features for XaAES Internal Windows

  • By pressing + the selected list-entry is copied to the Clipboard.
  • All XaAES-windows are resizable.
  • Keyboard navigation in all lists:

    • List is selected

      open tree

      • collapse

      • / : move the cursor

    • List is not selected

      scroll right

      • scroll left

      • / : scroll up/down

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 the following in a console: 

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.

When you want all clients to be stopped regardless of the above, set: 

flags -f 0x3xxxx <app>

on the single task app.

The flags utility is part of the mintbin package, available in the SpareMiNT RPM.

Comparison to TOS-AES

XaAES implements most parts of a standard TOS 4.1 AES, and a couple of its own.

Additional Events

XaAES defines some special events which can be handled by Programs.

Event Name evnt_multi() mask Description
MU_WHEEL 0x0040 Mouse Wheel events
MU_MX 0x0080 Mouse movement events
MU_NORM_KEYBD 0x0100 Normalized keyboard events

download

Find the latest version on the FreeMiNT downloads page, or a daily cvs build available from freemint.github.io.

[Home] [Project] [Download] [Get in touch] [Acknowledgements]

Clone this wiki locally