A brief user's guide to the newer features of EmuDesk, the EmuTOS desktop
=========================================================================

The current version of EmuDesk implements all of the features of the
Atari TOS 2/3/4 desktop, including:

1) menu items
    . search
    . bottom to top
    . select all items
    . set file mask
    . size to fit
    . install icon
    . install application
    . install devices
    . remove desktop icon
    . desktop configuration
    . read .inf file
    . blitter
    . cache
Due to space limitations, the implementation of the above is somewhat
restricted in the 192K ROMs (see the detailed descriptions below).  If
you make any changes to the desktop using the above features, you must
save the desktop to preserve the changes.

2) other features
    . user-assignable icons
    . user-assignable mouse cursors
    . open disk window via keyboard shortcut
    . desktop shortcuts
    . desktop printer support
Due to space limitations, desktop shortcuts & desktop printer support
are not available in the 192K ROMs.


Search
======
192K ROMs:
This is not available.

Other ROMs:
This prompts for a search string, then searches for matching files and
folders.  The search string entered is not the usual TOS wildcard
specification: any characters you enter must be matched, but missing
characters are ignored, i.e. are treated as though they were wildcards.
For example, searching for "A.T" will match "A.T", "ABC.TTP", etc.

If there are no icons currently selected, Search just selects all
matching files and folders in the topmost window, and the search ends.

Otherwise, the folders corresponding to the selected icons are searched
recursively, in sequence.  If a folder contains a matching name, the
folder is displayed in a window, with the matched files selected, and
the user is prompted to continue to search or cancel.

If cancel is selected, the search ends, with the window showing the
most-recently-matched files; otherwise, the search continues.  When
all folders have been searched, an alert is displayed: either "No more
files" if at least one file was found, or "xxx not found" if no matching
files were found.


Bottom to top
=============
192K ROMs:
This is not available.

Other ROMs:
This is used to cycle through open windows: each time it is selected,
the window that is currently bottom of the window stack is topped.
Thus it is only selectable if two or more windows are open.


Select all items
================
192K ROMs:
This is not available.

Other ROMs:
This selects all items in the topmost window.


Set file mask
=============
192K ROMs:
This is not available.

Other ROMs:
This is used to change the file mask of the currently-topped window, to
control which files are displayed within the window.  Note that folders
are always displayed; the mask affects the display of files only.  The
default file mask when a window is opened is "*.*"


Size to fit
===========
192K ROMs:
This is not available.

Other ROMs:
This is used to change the way that desktop windows are displayed.  If
'Size to fit' is enabled, the width of a window controls the number of
columns of files that are displayed, and the horizontal scroll bar and
arrows are unused.  If 'Size to fit' is disabled, a desktop window is
treated as a view onto a virtual window that is the width of the desktop,
and both vertical and horizontal scrolling are possible.


Install icon
============
192K ROMs:
This may be used to associate a specific icon with a desktop item (disk
or trash).  You may select an existing desktop item and click on "Install
icon...", or you may click on "Install icon..." with no item selected.
If you click on a window icon (file or folder), it will be ignored.

Other ROMs:
This may be used to associate a specific icon with a desktop item (disk
or trash), or a window item (file or folder).  You may select an existing
icon and click on "Install icon...", or you may click on "Install icon..."
with no item selected.  In the latter case, you'll get a dialog requesting
you to select the type of icon (desktop or window).

. Installing a desktop icon
  You may select the type (drive or trash), the label (displayed beneath
  it on the desktop), and the icon shape (use the up & down arrows to
  scroll through the available shapes).  In addition, for drives you can
  select the drive letter.

. Installing a window icon
  If you pre-selected an icon, you may only change the shape of the icon
  for that specific file or folder.  If you did not pre-select an item,
  you can select the files that the icon will apply to (standard TOS
  wildcards may be used), the type of item (file or folder), and the icon
  shape.  In either case, to change the icon shape, use the up & down
  arrows to scroll through the available shapes.


Install application
===================
The basic purpose of "Install application..." is to link an application
to data files with a specified extension.  After you have done this, when
you use the desktop to open a file with the specified extension, the
corresponding application is launched.  For example, you could associate
all .TXT files with a text editor; then, double-clicking on a .TXT file
would automatically launch the editor.

In addition, you can assign a function key to an application; pressing
the function key at the desktop will then launch the application.  Note
that a list of all currently-assigned function keys is available via the
"Desktop configuration..." menu item (see "Desktop configuration" below).

Finally, you can set "autoboot" for one application (only): this will
launch that application during system initialisation, immediately before
the desktop itself runs.

| EmuTOS-only feature:
| If you specify an extension of * or ???, the application will be treated
| as the "default viewer".  This is only called when trying to open a file
| whose extension is not handled by any other application.  Only one default
| viewer can be active at any time: specifying a new default viewer will
| silently remove any existing one.

To use "Install application...", highlight one or more applications and
click on "Install application...".  In the dialog box, the application
name of the first application selected will be prefilled.  The following
fields and buttons specify in detail how the application is run:

. Arguments
  If you need to pass information (in addition to the name of the data
  file) to the application when it starts, you may specify it here.  This
  is typically only relevant to utility programs, and the information
  needed will be in the application documentation.  In most cases, you
  should leave this blank.

. Document type
  This specifies the extension to associate with this application, for
  example TXT or RSC, and is required.  Wildcards are allowed.

. Install as F__
  This specifies the function key that will launch the application;
  values from 1 to 20 are allowed (11-20 are shift-F1 through shift-F10).
  Leaving this blank is valid, and means that no function key will launch
  the application.

. Boot status
  Select "Auto" to autoboot this application (see above).  Since only one
  autoboot application is allowed, if you set "Auto" for an application,
  EmuTOS will automatically disable "Auto" for any existing autoboot
  application.

. Application type
  Selecting TOS or TTP will launch the program in character mode; GEM or
  GTP will launch the application in graphics mode.  The appropriate
  value will be prefilled according to the type of application selected,
  and should not normally be changed.

. Default dir
  This specifies the default directory when the application is launched:
  either the directory of the application itself, or the top window (i.e.
  the directory of the data file).  The one to choose depends on the
  specific application.  If the application has supporting files (such as
  resource or help files), it typically will look for them in the default
  directory.  For such an application, you will need to specify a default
  directory of "Application".  Otherwise, specify "Window".

. Parameter
  When a program is launched due to it being an installed application,
  the desktop provides the application with the name of the data file
  that caused the launch: this is known as a parameter.  In most cases,
  the application expects that the full path of the data file will be
  provided.  Some (usually older) programs may expect the filename only.
  Unless the application's documentation indicates otherwise, you should
  normally try "Full path" first; if that does not work, you can try
  "File name", although that may require you to modify the "Default dir"
  specified above.

At the bottom of the dialog box are the following exit buttons:

. Install
  Installs the application.  You must save the desktop afterwards if you
  want the change to be saved across boots.

. Remove
  Removes an existing installed application.  You must save the desktop
  afterwards if you want the change to be saved across boots.

. Skip
  Skips installing/removing the current application, and moves on to the
  next one you specified.  If you only specified one application, this
  is the same as Cancel.

. Cancel
  Skip installing/removing all remaining applications.


Install devices
===============
This automatically installs icons for all devices that are currently
known to GEMDOS (have an entry in _drvbits) and that do not currently
have an icon.  It also removes any icons for devices that are not known
to GEMDOS.  For device A: or B:, a floppy icon is used; otherwise a hard
disk icon is used.  You must save the desktop if you want the new setup
to be preserved.


Remove desktop icon
===================
This is used to remove a desktop icon.  Highlight the icon you wish to
remove, and click on "Remove desktop icon".


Desktop configuration
=====================
192K ROMs:
This is not available.  However, note that menu item shortcuts that are
present in EMUDESK.INF *will* be loaded.  So even with the 192K ROMs,
you can set up your own preferred menu item shortcuts by inserting them
in EMUDESK.INF.  If you are knowledgeable and careful, you could edit
EMUDESK.INF directly.  But an easier way is to launch a PRG version of
the 256K or 512K ROMs, set up the shortcuts there, and save the desktop.

Other ROMs:
This is equivalent to the corresponding Atari TOS menu item.  You may do
the following:
. specify the default directory and input parameter for all applications
  that are not installed applications.  See "Install application" above,
  under 'Default dir' and 'Parameter', for further information.  Note
  that, if you do not have a saved desktop (EMUDESK.INF), the initial
  defaults for these two buttons are the opposite of those in Atari TOS;
  we believe the EmuTOS defaults are better choices for most software.
. display the function keys (and corresponding programs) that have been
  assigned via the "Install application..." menu item.  To display, use
  the arrows: up/down arrows select the previous/next assigned function
  key (in key number sequence), and left/right arrows scroll along the
  full pathname of the program.
. update shortcuts for menu items.  To update, use the up/down arrows to
  select the desired shortcut, then enter a new letter in the 'Key:'
  field.  You may also blank out the field to remove an existing shortcut.
  To remove all existing shortcuts, select 'Clear all'.  Note that the
  shortcuts are entered as capital letters, but are accessed from the
  desktop via the corresponding control key.  Also, note that the list
  of shortcuts is not updated until you click on 'OK'; if you make a
  mistake, just click on 'Cancel'.
This dialog also displays the current free memory (more accurately, the
size of the largest free memory area) in KB (1KB = 1024 bytes).  For
systems with alternate RAM, two numbers are displayed: the first is for
ST RAM, the second is for alternate RAM.


Read .INF file
==============
192K ROMs:
This is not available.

Other ROMs:
This item allows you to read in an EmuDesk .INF file 'on the fly'.
After the file has been read in, the desktop is restarted immediately,
a very fast process.  After the restart, the desktop layout and
preferences will be set up according to the contents of the new .INF
file, except that the video resolution specified is ignored (this is
the same behaviour as Atari TOS).


Blitter
=======
This item allows you to enable or disable the use of the blitter by the
desktop.  The item is greyed-out if the system does not have a blitter.


Cache
=====
192K ROMs:
This is not available.

This item allows you to enable or disable the CPU hardware cache.  The
item is greyed-out if the CPU does not have a cache.


User-assignable icons
=====================
When EmuDesk starts, it looks for a file called EMUICON.RSC in the root
of the boot drive.  This file should be a standard Atari resource file,
with at least eight icons.  All icons in the file must be 32x32-pixel
monochrome icons.  If the file is found, these icons are used for the
desktop and window displays; if not found, a standard set of eight
builtin icons is used instead.  The builtin icons (or the first eight
of the loaded icons, if EMUICON.RSC is in use) have the following usage:
    0   hard drive
    1   floppy drive
    2   folder
    3   trash
    4   printer
    5   removable disk
    6   generic application icon
    7   generic document icon
Icons 8 and above can be used as you wish.

Note that, for historical reasons, these assignments are different from
those used by Atari TOS, so if you have an equivalent RSC file that works
with Atari TOS, you will need to move the icons around to get the same
desktop display.

A default EMUICON.RSC file is shipped with the release; the first 8 icons
are the same as the builtin ones.  Also shipped is the corresponding
EMUICON.DEF file so that you can modify the resource with a standard
resource editor.  The EMUICON.DEF file is not used during startup, so
does not need to be on the boot disk.

In the EXTRAS folder, you will find other examples of EMUICON.RSC file
(with their corresponding EMUICON.DEF files).  To use one, just copy it
to the root of your boot disk, and rename it to EMUICON.RSC.

You should be aware that each additional icon beyond the basic set
consumes about 300 bytes of RAM, so if you are short of memory, avoid
putting too many icons in EMUICON.RSC.


| EmuTOS-only feature:
| User-assignable mouse cursors
| =============================
| When the AES starts up, it looks for an optional file called EMUCURS.RSC
| in the root directory of the boot drive.  This file should be a standard
| Atari resource file, containing 8 ICONBLKs; each ICONBLK is a container
| for a mouse cursor.  If the file is found, these cursors are used instead
| of the builtin cursors.  The usage is as described for the AES graf_mouse()
| call:
|     0   arrow
|     1   text cursor / i-beam
|     2   busy bee / hourglass
|     3   pointing hand
|     4   flat hand
|     5   thin cross
|     6   thick cross
|     7   outline cross
|
| A sample EMUCURS.RSC file is shipped with the release in the EXTRAS folder;
| the mouse cursors in it are the same as the builtin ones.  Also shipped
| is the corresponding EMUCURS.DEF file for use by a resource editor.
|
| NOTE: Because the mouse cursors are not really ICONBLKs (though they are
| stored as such within the resource), editing them with a standard resource
| editor is difficult.  Thorsten Otto's ORCS resource editor has special
| support for mouse cursors and is the recommended tool for modifying them.


Open disk window via keyboard shortcut
======================================
You may now use a keyboard shortcut to display the root directory of a
drive in a new window.  To display drive X, hold the Alt key down and
type X, e.g. Alt-C displays drive C, Alt-D displays drive D, and so on.
As in TOS2/3/4, these shortcuts are permanently assigned and cannot be
changed by the user.

NOTE: unlike TOS2/3/4, shortcuts with the Ctrl modifier do NOT update
the drive assigned to the currently topped window; instead, they are
assigned to menu item shortcuts.  See "Desktop configuration" above.


Desktop shortcuts
=================
You may now drag a file or folder to the desktop to create a desktop icon
that is a shortcut to the original file/folder: manipulating the icon
will have the same effect as manipulating the original file or folder.
For example, it may be opened, copied, or moved or deleted; it may have
an "Info/rename" performed on it.  Currently, by design, the shortcut is
NOT updated automatically if the original file or folder is moved or
deleted.

The name and shape of the shortcut icon itself may be modified by the
"Install icon" menu item; this does not change the name of the file or
folder that the icon points to.  The shortcut icon may be deleted by the
"Remove icon" menu item.  To preserve shortcut information across boots,
you must save the desktop.

You may drag a file or folder to a desktop shortcut, with the following
results:
. dragging documents to a desktop shortcut for a folder will copy (or
  move, if the control key is held down) them to the folder
. dragging documents to a desktop shortcut for a program will launch the
  program, passing the full pathname of the first document
. dragging documents to a desktop shortcut for a non-executable file will
  do nothing

If you open a desktop shortcut that points to a file or folder that no
longer exists, an alert will be issued, giving you the choice of removing
the shortcut, locating the desired file or folder, or cancelling the
action.  If you choose locate, a file selector will be displayed to
allow you to choose the desired file or folder, and the shortcut will be
updated with the new information.


Desktop printer support
=======================
You may now install a printer icon on the desktop (if you do not already
have an EMUDESK.INF file, this icon will be installed automatically).
Dropping one or more files on the icon will cause the contents to be
output via the parallel or serial port; a form feed will be sent at the
end of each file.

By default, the output will go to the parallel port; you may select the
serial port instead by using any CPX, accessory, or program that allows
you to do the same thing under Atari TOS.
