ARM Club 3/TheARMClub_PDCD3.iso/mag_discs/15/director/!Director/!Help

Text File | 1994-10-29 | 42KB | 1,210 lines

Help file for Director version 0.11
===================================

Director is Copyright (C) Nick Craig-Wood 1994

If you are reading this in !Edit then you might like to do Expand tabs on the
Edit menu to turn those [09]'s into something useful!


License
=======

Director (The Software) is Copyright (C) Nick Craig-Wood 1994 (NCW) and may
not be used or copied except as in accord with the terms and conditions
below.

You may NOT Make the Software available to any third party EXCEPT with these
terms and conditions imposed on said party.

You may NOT Make the Software available to any third party EXCEPT at no
benefit to yourself or any third party, excepting that benefit contained
within the Software.

You MUST make sure the Software is distributed whole, intact and unmodified,
including all the files in the original distribution.

You may NOT may not sell, hire or include the Software in a package which is
sold or hired, modify, translate, disassemble, decompile, reverse engineer,
or create derivative works based upon the Software or include whole or part
of the Software into other works.

The Software is supplied "as is", NCW makes no warranty, express or implied,
as to the merchantability or its fitness for any particular purpose.  It may
or may not perform in accordance with the documentation or your expectations.

In no circumstances will NCW be liable for any damage, loss of profits,
goodwill or for any indirect or consequential loss arising out of the use of
the Software, or inability to use the Software, even if NCW has been advised
of the possibility of such loss.

These conditions supersede any prior agreement, oral or written, between you
and NCW relating to the Software.

You agree that except for written separate agreements between NCW and you,
this agreement is a complete and exclusive statement of the rights and
liabilities of the parties.

You acknowledge that you have read this agreement, that you understand this
agreement, and by loading, running or copying the Software you agree to be
bound by this agreement's terms and conditions.


Introduction
============

Director is a general purpose desktop tool.  It allows you to customise your
desktop by creating menus of useful commands and icons to attach the menus
to.  Any number of menus or icons can be created and attached in any order to
each other.

Director also allows an alternative and faster view onto files in the form of
directory menus and allows these menus to be attached to other menus also.

Director has some other useful features such as remembering the most recently
used files, the ability to add key strokes into the keyboard buffer and the
ability to produce directory menus over drive icons.

Director is fully customisable by the user, and can do many or all of the
functions of Pinboard+, TreeMenu (AKA DirMenu), Filer-, QuickDir, DeskUtils,
Memorizer, Menon and some of the functions of Filer+.

Director will only run on RISC OS 3.10 or later.


Motivation
==========

Director was initially conceived as a replacement for Pinboard+ (by Thomas
Olsson).  For those of you who don't know, Pinboard+ is a replacement
Pinboard module which allows user definable menus when clicking menu over the
backdrop.

The initial design of Director was in order to overcome the fact that
Pinboard+ needed a replacement pinboard module loaded (which did not work
fully under RISCOS 3.5) and the fact that there was no easy way of specifying
that you wanted the contents of a directory as a sub menu.

This then led on to the idea of incorporating the functions of TreeMenu (by
Julian Smith) into Director.  This would then enable a directory tree listing
to be attached to a menu at any point.

These ideas led onto Director being more of a general purpose program,
merging several utilities into one compact package.

Memory usage was another of the main reasons for coding Director.  Here's a
before and after on the memory front.

Before:

TreeMenu          65,536
Pinboard+         18,812 (module)
                  43,324 (menu)
DeskUtils         32,768
Memorizer         14,128
————————————————————————
Total            174,568 Bytes

After:

Program code      18,672
Workspace          3,600
Heap              18,416 (119 blocks)
————————————————————————
Total             40,688 Bytes

Thus giving a saving of 133,880 bytes or 130 kBytes!

Director also includes some ideas from Filer+ (by Jens H. Ovesen), Filer- (by
Franz Philipps), and Memorizer (by Ben Summers).

Director is written entirely in ObjAsm assembler for its compactness and ease
of making module tasks.

Although the not all ideas may not have been my own, the coding is all mine
(including all the bugs)!


Switching from Pinboard+ to Director
====================================

If you run the ExpandMenu program in the Utils directory you can convert your
old Pinboard+ menus into the new form expected by Director.  This is a
textual form based on the Obey file and is a lot easier to maintain than a
graphical form.  However if you prefer you can maintain your menus using the
Pinboard+ menu designer and ExpandMenu, however some of the new features of
Director will be unavailable to you.


Switching from TreeMenu (or DirMenu) to Director
================================================

Director has almost all the features of TreeMenu.  By default it will enable
Directory menus over title bars of filer windows and other windows.  You may
create icons as per TreeMenu also, see the section on Icons, and also the
example Menus.


Menus
=====

Menus are referred to by name (case insensitive), either by the text of the
menu title or an alias as given by you.  There can only be one menu of any
given name, and if you attempt to create a menu with the same name as an
existing one then the existing menu will be deleted without warning.  This is
useful because you can update your menus at any time you like, or even create
new menus on the fly.

Director keeps a list of menus which you can ask for with the "ListMenus"
command.  Menus can be temporary or permanent.  Temporary menus are created
by Director for making Directory Menus and then deleted afterwards.
Permanent Menus are created by you.

To create a menu you need to create an Obey file with the following format.
(Indentation and spacing are generally unimportant.  The menus are described
indented here to aid comprehension of the structure.)

    Menu ...
        Option ...
            Command ...
        Option ...
            Command ...
    Dash
        .
        .
        .
        Option ...
    EndMenu

The Menu command signals to Director to start a new Menu with the name and
alias you give it.

    Syntax: Menu <title> [<alias>] [-key <key>] [-temp]

Possible examples are,

    Menu "Mode"
        Starts a menu with title and internal name both "Mode"
    Menu Mode
        Same as above.  In general if you want to supply a string
        to a command, you can supply it with or without quotes.
        However if the string has spaces in it it must be supplied
        with quotes.
    Menu "Lots of Modes" Mode
        Starts a menu with title "Lots of Modes" and internal name
        "Mode"
    Menu "DDE" -key ^D
        Starts a menu called DDE with internal name DDE to be opened
        on a CTRL-D key press (see the section called Keys for more
        on what is allowed as a parameter to -keys)
    Menu "Temporary" -temp
        This will make a menu which will be displayed only once and
        then destroyed.  This is useful for dynamic menus.

The EndMenu command signals to Director to stop making the menu.  The menu is
available for display as soon as the Menu command has been issued though.

    Syntax: EndMenu

The Dash command writes a dashed line across the menu at that point in the
menu structure.  It is useful for organising large menus.

    Syntax: Dash

The Option command is at the heart of Director's menus.  It has many options
which you won't need immediately, but which may become useful later.

    Syntax: Option <text> | -path <file|directory>
        [-tick]
        [-bg <col>]
        [-fg <col>]
        [-sub [<menu>|*]]
        [-len <len>]
        [-dash]
        [-grey]
        [-key <number>]
        [-up]

The Option command must be supplied with a text or a path or both.  For
example

    Option "Mode 31"
        Will produce a menu entry with the text "Mode 31" which could
        have a command attached (see later).
    Option -path ADFS::4.$.Apps
        Will produce a menu entry with a directory icon in it and the
        Apps directory attached.  If the Apps directory is not present
        then it will produce a greyed out menu option with an unknown
        file icon.  Director will use the leaf name of the path for
        the text of the menu (in this case Apps) minus an initial !.
    Option "Applications" -path ADFS::4.$.Apps
        As above except the text in the menu option will be
        "Applications" rather than "Apps".

A text option may have a 0, 1 or 2 Commands attached (see later) or a
SubMenu.

    Option "Modes" -sub "Modes"
        This produces a menu entry with the text "Modes" and a right
        pointing arrow.  When pointer moves over the arrow the Menu
        "Modes" will be opened as a sub menu.  If the user clicks on
        the item (or uses a hotkey) the "Modes" menu will be opened
        as the root menu.
    Option "Modes" -sub *
        This is equivalent to the Option above.  It is quite common
        to have a SubMenu with the same name as the Option which
        activates it, so this is shorthand for that.

A menu option may be activated by a key, eg

    Option -path ADFS::4.$.Apps -key ^A
        Opens the Apps directory on CTRL-A
    Option "Modes" -sub * -key M
        Opens the modes SubMenu (if no command attached) or does the
        attached command if M is pressed.
    Option "Command" -key ⇧^Z
        If a command is attached then it does it on SHIFT-CTRL-Z
        otherwise it does nothing.

A menu option may have its foreground and background colours defined (see the
section on colours for details of which numbers make which colours).  If the
colours are not defined then they default foreground Black and background
White.

    Option "Format" -fg 11
        Produces Red text on the default background
    Option "Boot" -fg 0 -bg 8
        Produces White text on a Dark Blue background

Any menu can be made writable by including a -len option.  The parameter to
len is the maximum length of the string writable into the icon.  When the
item is selected the text is written into the system variable <MenuText>
which can be used in commands.  In fact <MenuText> is written for
non-writable items and when creating a submenu too.

    Option "13" -len 3
        Might be used for typing in a mode number or maximum length 3
        characters.  The command attached would then use <MenuText>
        to set the actual mode.  The string "13" is the default text.
    Option "" -len 200
        Might be used by a general purpose command (eg the New Task
        option in the TaskManager).  The default string is empty.
        It must be supplied though or Director will complain.

-tick Ticks the menu item (useful for when you have 2 attached commands, this
provides the initial ticked state).

-dash Writes a dash under the menu item.  This is equivalent to the Dash
command.

-grey Makes the menu entry grey and unselectable.  Useful occasionally.

-up Makes -path have the directories above the path (Up Menus - see Directory
Menus section) in the menu.  If -up is applied to a file then it will have a
submenu arrow.

The Command command is for attaching commands to menu options.  Only text
type menu options (ie not -path options) may have Commands attached.  You may
have both SubMenus and commands attached to a menu option.

    Syntax: Command <*command>

For example

    Option "Mode 13"
        Command WimpMode 13
            Sets Mode 13 when clicked on
    Option "13" -len 3
        Command WimpMode <MenuText>
            Sets the mode typed in when clicked on
    Option "" -len 200
        Command <MenuText>
            Runs the command typed in when clicked on.

A menu option may have two commands attached.  Which command is run depends
upon the ticked state of the option.

For example

    Option "A"
        Command FontInstall Fonts:!A.
        Command FontRemove Fonts:!A.

When this it not ticked then the first command will be run.  This will
install the fonts in !A and to show that they have been installed the menu
option will be ticked.  To remove the fonts the option is clicked again and
the second command is run, removing the fonts, and returning the menu to the
non-ticked state.

Commands are GSTransed before being run (see the section on GSTrans for more
info) as a WimpTask.  Running commands as a WimpTask means that they don't
interfere with Director, however if the command produces an error, an
anonymous error box is produced.

This also means that multiple OS commands can be put on one line by
separating them with |M.  For example

    Option "Reset SysFont"
        Command fx 20|MSWI Wimp_CommandWindow -1

Which resets the system font with *FX 20 and then redraws the screen with the
SWI Wimp_CommandWindow.


System Variables
================

These system variables are set whenever a path sub menu is opened or a path
item is chosen

    Director$CurrentPath
        full path of object
    Director$CurrentDir
        directory object lives in
    Director$CurrentLeaf
        leaf name of object

If the object is a root directory (eg ADFS::4.$ or Root:) then CurrentPath =
CurrentDir = CurrentLeaf


The last Command that was run can be seen in the system variable

    Alias$DirectorRun

So issue *Show Alias$DirectorRun at the command line to see what it was.


Whenever a text option is chosen

    MenuText

Is set to the text of that option


Whenever menu is clicked over the File 'xxx' option in a Filer Menu

    Leaf

is set to the leaf name of the file ("xxx" in this case).


GSTrans
=======

If you are uncertain what GSTrans is, look it up in the index of your user
guide.  The few pages referenced will teach you the basics (I won't attempt
to explain them here).

As a rule every string parameter passed to Director is GSTransed when it is
passed.  This means that

    Option -path <Wimp$Scrap>

Will be GSTransed into (something like)

    Option -path ADFS::HardDisc4.$.!Boot.!Scrap.ScrapDirs.ScrapFile

Which means that if Wimp$Scrap changes, the option won't be looking in the
right place.  The menu text will read "ScrapFile".  Better is

    Option -path |<Wimp$Scrap>

Which GSTranses into

    Option -path <Wimp$Scrap>

which is what you want.  The menu text will read "<Wimp$Scrap>".  Probably
best (for this use) is

    Option "Scrap" -path |<Wimp$Scrap>

Which has the menu text "Scrap" but is otherwise identical to the one above.

The only strings which don't get GSTransed on their way into Director are the
parameters to Command.  These are GSTransed just before being run.

    Option "13" -len 3
        Command WimpMode <MenuText>

The above command will only be GSTransed when it is run with the actual value
of MenuText, not the value of MenuText when the command was installed.

    Option "Open App"
        Command Filer_OpenDir <Obey$Dir>
    Option "Open App"
        Command Filer_OpenDir |<Obey$Dir>

These two commands in practice do the same thing.  This is because in the
first Command the <Obey$Dir> is GSTransed (when the Command is being
prepared) to the proper path which is then passed to Filer_OpenDir.  In the
second case |<Obey$Dir> is GSTransed to <Obey$Dir> and passed to
Filer_OpenDir.  Filer_OpenDir GSTranses the argument and comes up with the
same answer.

If the commands had been Filer_Run in the above example then they would have
done two different things.  The first would have worked (running the
application) and the second would not because Filer_Run does not GSTrans its
input.  (In fact the second command would have opened a directory onto the
application for some obscure reason, with the Filer title set to <Obey$Dir>
which should not normally be allowed.)


Special forms of Menus and Commands
===================================

Whenever a Menu, SubMenu or Command is specified it may take one of several
special forms.  These enable Director to be much more general, running
commands instead of opening a sub menu or vice versa.  It also means that
Commands can be attached to clicks on icons as well as menus.

When a Menu, SubMenu or Command is being processed, it is first checked to
see if it is prefixed in one of the ways below.  If it is then its action is
modified.

"Text"        For normal command or sub-menu (ie action unchanged)

"Menu:Name"    To bring up named menu

"Save:Path"    For save box of the given Path (*)

"Path:Path"    For a directory menu of that Path (*)

"Command:Text"    Runs the Text as if it were a command

"Quit:"        Quits Director

"Info:"        Brings up Director's info window

"OldMenu:"    To open the last filtered menu (for getting pinboard menu)

"MenuMenu:Path"    Takes Path, adds .<leaf> to it and opens the MenuMenu
        pointing at that file.  Used internally. (*)

"Memoriser:"    Opens a menu recently used files.  (See Memoriser section.)

"Dynamic:Text"    Runs the Text as if it were a command.  When the command
        returns Director tries to open the menu whose name is in
        the system variable Director$Menu.

"GSTrans:Text"    GSTran-es the Text and then reinterprets it as an extended
        command.

(*) If the path is missing eg "Path:" or "Save:" then it will use the path of
the window that the pointer is over.  If the path is present it is GS_Transed
before use.

For example

    Option "Floppy" -sub "Path:ADFS::0.$"

This will make a directory menu of the floppy disc drive if you click on the
option or move the pointer over the SubMenu.  This is better than

    Option "Floppy" -path ADFS::0.$

because this will produce a greyed out path with an unknown file icon if the
floppy is empty when the Option is run.

    Option "Root" -sub "Command:Filer_OpenDir ADFS::4.$"

This will open a filer window of your root directory if you click on the
option or move the pointer over the SubMenu.

    Option "Pinboard" -sub "OldMenu:"

This will open the menu that should have been opened when you clicked the
pointer.  So if you opened the menu over the pinboard, but wanted to see the
pinboard menu then you could click or slide this option.

    Option Here -sub "Path:<Director$CurrentDir>"
    Option Copy -sub "Save:<Director$CurrentPath>"

These options are useful for the MenuMenu (see the section titled MenuMenu
and the section titled SaveBox).

    Option Info -sub Info:
    Option Quit
        Command Quit:

Helps bring an air of normality to Director by providing the standard Quit
and Info choices!


Memoriser
=========

Director notices whenever you load a file or click on a drive and keeps a
record of the fact.

If you then ask for the menu Memoriser: to be opened then you will get a menu
with these files or directories in it.

This acts exactly like a normal directory Menu, except it has all your most
recently used files/directories in it.

This is exceedingly useful when you traverse a large directory tree, open a
file to have a look at it, close it, and then realise that you want to see
the file again.  All you have to do is open the Memoriser menu and it will be
there sitting at the top.

The number of items that are kept in the Memoriser menu is definable by you
with the command

    Syntax: MemoriserItems <number>

This will not affect the currently built up number of items.  If you set it
to 0 then no more items will be added to the menu.  This effectively turns
the feature off.  0 is the default value.


MenuMenu
========

A menu with name defined by the system variable Director$MenuMenu (defined by
you) is opened whenever you click Menu on a path item or click Menu on the
second option in a Filer Menu (the one that reads "File '!Run'" or
"Selection") provided one and only one file is selected in the Filer window.

This menu deals with files and directories.  You should put on it things
which you want to do to files.

Here is an example of a MenuMenu

Set Director$MenuMenu MenuMenu

Menu "File Menu" "MenuMenu"
    Option Here -sub "Path:|<Director$CurrentDir>"

This allows you to see a directory Menu of where the selected file or
directory is.  (See the section on GSTrans for the reason behind the | in the
-sub string.)

    Option Copy -sub "Save:|<Director$CurrentPath>"

This allows the current file or directory to be copied to a filer window,
dragged to an application or pinned to the pinboard (drag the icon onto the
pinboard).

    Option "Set CSD"
        Command Dir <Director$CurrentDir>

Sets the Current Directory to the directory in which the file or directory
was found.

    Option "Open Directory"
        Command Filer_OpenDir <Director$CurrentDir>

This opens a Filer Window onto the directory in which the file or directory
was found.

    Option "Filer_Run"
        Command Filer_Run <Director$CurrentPath>

This is equivalent to double clicking on the File or Directory.

    Option "Pin"
        Command SWI OS_Mouse TO x y|M
            Pin <Director$CurrentPath> |<x>-90 |<y>+45

This pins the file or Directory to the pinboard. (The command should be
written all on one line).  It uses the SWI Module to read the current
position of the mouse and then pins the centre of the icon there.  (Note the
|<x>, this is GSTransed to at run time <x> when the Command is being
prepared, which is then GSTransed to the mouse x co-ordinate when the Pin
command is run.)

    Option "IconSprites"
        Command IconSprites <Director$CurrentPath>

This IconSprites the file or directory.  (Only really useful over a sprite
file.)

EndMenu

There are many other possibilities for the MenuMenu, such as SetType,
ToolSprites, Delete, Wipe, Access etc.  A MenuMenu is perhaps best defined as
a dynamic Menu.


Pinboard
========

A menu of this name (defined by you) is opened whenever you click Menu on the
pinboard backdrop or on a TinyDirs icon.

If the pinboard module isn't loaded or running, no error is produced, but
none of the things in this section will work.

If you want to use the Pinboard's menu then you can press any of SHIFT, CTRL,
ALT when clicking Menu and the old Menu will appear.

Alternatively on your Pinboard menu you can have an option

    Option Pinboard -sub OldMenu:

Which when clicked on or slid over will open the menu that would have been
opened if Pinboard had been left to its own devices.  It will also move the
pointer to be in the correct place.

(I debated long and hard about moving the pointer (which I dislike), but
decided this was the least confusing option.  Try it for yourself!)


SaveBox
=======

Read the section on special forms of Menus and commands if you haven't
already done so.

The SaveBox is not like a true SaveBox it is more like a miniature Filer
window (except you can't (yet) double click on the icon).  You may drag the
icon from a SaveBox to an application (equivalent to dragging it from the
Filer) the pinboard (ditto) or a Filer window, which will copy the File in
the way you have configured (possibly bringing up a Filer Action window etc).

There is only one SaveBox and if you try to open it twice the first one
disappears/changes into the new file/directory.


Keys
====

Any Menu or Menu Option can have a hot key assigned.

A hot key assigned to a menu (in the Menu command) will open the Menu when
used and a hot key assigned to a Menu Option will be equivalent to clicking
with select on a Menu Option when used.

Keys are added by name and possibly with a modifier.

A single letter key refers to that key eg -key M or -key 8.  Keys are case
insensitive (and independent of CapsLock) so -key m is equivalent to -key M.

Some keys are referred to by name (case insensitive), and these are

    Home, Return, Ret, Enter, Backspace, BkSp, Space, Delete,
    Del, Esc, Print, Pnt, F1, F2, F3, F4, F5, F6, F7, F8, F9,
    Tab, Copy, Cpy, End, Left, Right, Down, Up, PageDown, PgDn,
    PageUp, PgUp, F10, F11, F12, Insert, Ins

Some of them are named twice for your convenience.  So -key F1, -key f1 or
-Key Insert would be valid.

Possible modifiers are

    ⇧    SHIFT
    ^     CTRL
    ~     ALT

(To get the ⇧ symbol, hold down ALT, type 139 on the numeric keypad and
release ALT.  Alternatively map character 139 to a key in your favourite
editor (CTRL-6 is a good mapping).)

These can be added (in any order) before a key name, indicating that you have
to press the modifier keys indicated with the main key in order to activate
the hot key.  eg

    ^M        CTRL-M
    ⇧A        SHIFT-A
    ^⇧F1 = ⇧^F1    SHIFT-CTRL-F1

Note that -key ⇧A = -key ⇧a which is not equal to -key A = -key a.

Some key combinations don't work, eg

    CTRL Number keys don't work, CTRL KeyPad numbers should
    No keys work with ALT!

These may be fixed in a future release!

If an Option or a Menu has a key definition it is added to the text/title
with a space before it.  If you want the items to line up then you will have
to add spaces after the text/title.  RISCOS 3.5 will line them up for you
provided the key definitions starts with ^ or ⇧ or is one of the long form
named keys above.


Colours
=======

Any colours in Director are specified numerically from the 16 Wimp colours.
These colours can be seen by clicking on the Palette icon (supplied with
versions of RISCOS < 3.5).  The numbers of each colour are given below.

If you are using a lot of colours or just want to make your menus neater, you
can define names for the colours using SetEval.  Just put this block of
definitions in your menu before you use the named colour.

SetEval White    0
SetEval Grey1    1
SetEval Grey2    2
SetEval Grey3    3
SetEval Grey4    4
SetEval Grey5    5
SetEval Grey6    6
SetEval Black    7
SetEval Blue    8
SetEval Yellow    9
SetEval Green    10
SetEval Red    11
SetEval Cream    12
SetEval Khaki    13
SetEval Orange    14
SetEval Cyan    15

These can be used wherever a colour is needed, eg

    Option "Unreadable" -bg Red -fg Khaki


Dynamic Menus
=============

These are menus that are created just before the menu is opened rather than
when you run Director.

They are used from an extended menu "Dynamic:Filename".  When this command is
run the file or command "Filename" is run.  When the command or file finishes
executing Director will try to open the menu whose name is in the system
variable Director$Menu.

A simple example of a dynamic menu would be this

    Option "Time" -sub "Dynamic:DirectorObey Director:Menus.Time" -key ^⇧T

This will run the command "DirectorObey Director:Menus.Time" when this menu
option is run (or ⇧^T is pressed).  The contents this file might be

    Menu "" Time -temp
        Option "**The Time Was**" -fg 11
        Option "   <Sys$Time>   "
        Option "<Sys$Date> <Sys$Year>"
    EndMenu

    Set Director$Menu Time

This creates a temporary menu called Time with the current time and date in
it and returns the string "Time" in Director$Menu for Director to use as the
name of a menu to open.

Because the menu was created as a temporary menu it will be deleted once it
has been displayed to conserve memory (since it is rebuilt each time it is
needed).

Dynamic menus are very useful for displaying lists of things that could vary
whilst Director is running (such as modules or filetypes).  A few examples of
dynamic menus are provided in the Menus directory inside Director.

It would be posible to simulate most of the other features of Director using
dynamic menus, however in their current implementation they require a disc
access per use.  It would be possible to register the dynamic menu files in
the resource filing system to avoid this and mybe a future version of
Director will do this for you.


Icons
=====

Icons are created in a similar way to menus.  Each one must be named (case
insensitive) by its sprite name or an alias name provided by you and there
can only be one of each name.  If you create an icon with the name of a
already existing one then the existing icon will be deleted without warning
and the new one created.

You may attach menus for Select, Adjust and Menu for the icon.  Remember that
the menus can also be commands (see the section on Special forms of Menus and
Commands)

This creates a new icon bar icon with attached menus. The icon is referred to
by the name of its sprite or the alias name if supplied.

    Syntax: *DirectorIcon
        <sprite>
            Name of the sprite, must be provided and exist in the
            Wimp sprite pool
        [-alias <name>]
            Internal name of the Icon.  If this is not supplied
            then the icon is referred to by its sprite name.
        [-text <text>]
            Text to go under the Icon.  Optional.  If the -time
            option is used then this Text defines the length of
            the time string.
        [-left|-right]
            Whether the icon goes on the left of the Icon bar or
            the right.  If omitted will default to -left.
        [-priority <priority>]
            This controls the positioning of the icon.  Larger
            numbers are to the outside of the icon bar. Range
            from 0 (inside) - &7FFFFFFF (outside).  Experiment to
            see where your icons gets placed or look at 3-98 in
            the RISCOS 3 PRMs.
        [-time <format>]
            This makes the text under the icon be interpreted as
            a time, which is updated once per second.  The length of
            the time is set by the -text option.  See the
            Applications Guide, under !Alarm, "Time and date
            formats" for more details or the RISCOS 3 PRMs 1-402.
        [-menu <menu>]
        [-select <menu>]
        [-adjust <menu>]
            These allow you to attach menus or commands to the 3
            mouse buttons.

For example (these should be typed in on 1 line, but have been split for
clarity)

    DirectorIcon romapps Apps -left -priority &50000000
        -menu "Path:Resources:$"
        -select "Command:Filer_OpenDir Resources:$.Apps"
        -adjust Pinboard

This provides a replacement Apps icon which has the Pinboard menu on Adjust,
does the normal this on select, and on menu (which would normally say
"Open $") produce a directory menu of the whole of Resources which is usually
much more useful.

    DirectorIcon !Director "00:00:00" -left -priority &0E000000
        -menu IconMenu
        -select IconClick
        -adjust Pinboard
        -time <37>24:%MI:%SE

This produces an icon with Director's own icon, the current time in 24 hour
format and 3 menu IconClick, IconMenu and Pinboard.

[NB <37> GSTranses to %.  This odd looking construction is necessary because
%2 refers to the second argument supplied (when Obeying the file, not in
DirectorObey).  Since no arguments were supplied then the time string is
converted to 4:%MI:%SE which is not what was required!  <37> is used rather
than %% so the file will work with Obey and DirectorObey]


Directory Menus
===============

Directory menus are automatically created and destroyed by Director when you
click with Menu on the title bar of a Filer or other window with a valid path
in it (eg an Edit window).  They are also produced by -path "directory" or
Command "Path:Directory" etc.

A menu will appear with all the file that are in the directory in it.  It is
intended to be complementary to the  Filer, quicker to use, but not as
powerful.

Each item in the menu has the name of a file or directory and its icon.  This
is very similar to a filer window with sort by name, small icons and adjusted
to be tall and thin.

Items in the menu that are directories (or image files) will have a SubMenu
arrow by them.  You may traverse this arrow to see the next directory down.

Clicking with Select or Adjust is equivalent to double clicking the file in a
filer window.

Clicking with Menu over an Item will bring up the MenuMenu (see that section
for more details).  If a MenuMenu is not defined then it will do nothing.

Directory menus come in 2 flavours, with and without "Up Menus".  Up Menus
are the directories above the dotted line.  These show the directories up to
the root from where you are now.  The first item above the dotted line never
has a sub-menu because the item or the contents of that item are always
visible.

A directory menu made by "Path:" has Up Menus (eg the ones produced by
clicking Menu over a title bar).  A directory menu made by -path does not
have Up Menus by default unless you use the -up switch.


Other Features
==============

If you do an Adjust click on a drive icon on the icon bar it should open a
Directory Menu rather than a Filer window.  Works for ADFS, Acorn SCSI, MOFS,
RAMFS, Memphis, CFS, CDFS and Resources.  It will work for other filing
systems provided they have been written in the way suggested in the PRMs!


Other Commands
==============

    Syntax: *DirectorMemory

This shows the memory used by Director in the following form

    Program code      18000
    Workspace          3536
    Heap              16496 (117 blocks)
    ———————————————————————
    Total             38032 Bytes


    Syntax: *DirectorObey <file> [-verbose]

This command is equivalent to *Obey except it searches for Director *commands
with high priority. Obey is quite slow when processing lots of commands so
this speeds up loading a file with lots of Director commands in it.
DirectorObey cut the loading time of a 14k menu from 5.2 seconds (with Obey)
to 0.75 seconds, ie a speed up of nearly 7 times!

It should be exactly equivalent to Obey, excepting the fact that it doesn't
substitute arguments (eg %0 and %%).  This means you have to be a bit careful
with %'s if you want your menus to work with Obey and DirectorObey.  (See the
Icons section about -time for an example.) The -verbose or -v option is
useful for debugging.

    Syntax: *MenuProcessing <On|Off|1|0|Yes|No>

This stops and restarts the processing of Menu, EndMenu, Option, Command and
Dash (ie all the menu commands).  This is so that you can comment out bits of
your menus.  For example if the machine you are running the menu on has no
SCSI card installed then there is no point having the SCSI menus installed
and you could check for this at menu load time.

    Syntax: *DirectorDo <command>

This GSTrans the command line and then runs it.  This is useful for commands
such as Filer_Run which don't GSTrans their input, but you want to give a
string with a system variable in it.  You can also run a command from a
system variable with this command.

    Syntax: *ListMenus

This lists the currently defined menus.

    Syntax: *ProcessKeys [[⇧][^]<key>|"<string>"]^

This sends the parameters to the current input focus, or hot key grabber.  It
should work outside the Wimp, provided the keys are mapped as in the Wimp.
It takes a space separated list of either strings to be put into the keyboard
buffer or key descriptions (see Keys section). You can of course map these
onto keys for hot key actions.  For example

    ProcessKeys "Modules" Return
    ProcessKeys F6 ^Left Down F6 ^Up ^V
    ProcessKeys "Show Obey$Dir" ^M
    ProcessKeys "42 Solution Road" ^M "Toytown" ^M "Shireshire" ^M
    ProcessKeys TAB "Option -path "

A chars menu could be provided using this, or a menu of frequently used
commands for command based application.

    Syntax: *DirectorEdit <file>

This loads the file given into an text editor (if one is loaded).  It is
useful for transferring files that are not type Text to an editor.

    Syntax: *DirectorParsePath <path>

This parses the path supplied into 3 system variables Director$CurrentPath
Director$Leaf and Director$Dir.  This is the routine that is used internally
by Director to set these variables and can occasionally be useful externally.

    Syntax: *DirectorMouseDir <var_name>

This sets the supplied system variable to the path of the window the pointer
is over.  This is used to set the current directory from a key in the default
menu.  It also works over Edit or Zap windows and will return the directory
that the file is in.  If the pointer is not over a window with a valid path
in the title then the system variable will be set to the null string ("").


External Interface
==================

If you Broadcast the following UserMessage

0    Total length of message rounded up to nearest 4
12    0
16    &4A100
20    X Co-ord
24    Y Co-ord
28    Mouse button state
32    Window handle
36    Icon number
40    Null terminated menu name (or extended menu)

Director will display the menu (or run the command etc) at the position
specified.

Note bytes 20-39 are as returned from Wimp_GetPointerInfo.


SWIs
====

&4A100    Director_Menu
&4A101    Director_EndMenu
&4A102    Director_Option
&4A103    Director_Dash
&4A104    Director_Command

Pass a pointer to the command line for the equivalent star command in r0.
These are defined because processing star commands is very slow and in
dynamic menus especially it is important that items can be added to menus
quickly.


Debugging your Menus
====================

If you are having trouble with your menus when you load them (they give a
funny error and you don't know why) try opening a TaskWindow (CTRL-F12) type
in "DirectorObey -v " and SHIFT drag your menu file to the window.  This will
print out commands as they are executed and you should be able to spot
exactly when it goes wrong.

    Option "Debug"
        Command TaskWindow "DirectorObey -v <Director$Dir>.Menus.Menu"

Would put this on a Director menu for you!  (Substitute the correct name and
path of your Menu.)

Another thing to bear in mind is that if you reference a menu that you
haven't created eg

    Option "Hello" -sub "NotThere"

Where menu "NotThere" hasn't been created, this will not produce an error at
load time, and at run time it will just fail to produce the menu (not
producing an error either).  Originally it produced an error, but this proved
very annoying in other circumstances (eg when you haven't defined a Pinboard
menu because you don't want one).

You may refer to one menu more than once in a menu tree, however menus can
only be on the screen once so if you tried to open a SubMenu of a Menu that
was already displayed then nothing would happen.  However if you clicked on
the Option (provided it had no Command attached) it would then open the Menu
referred to.


Oddities
========

If you are running RISCOS 3.5 and wonder why your Menu titles are justified
all wrong (my menu is called "Nick's Menu" and the Menu gets right justified)
it is because you have included a reserved key name as the last word.  This
is RISCOS being helpful and lining up your key short cuts in Menus.  It
doesn't line up a key short cut of M for instance and will attempt to line up
anything with the last word "Menu"!  The solution is to put a hard space
before the "Menu" (hard space is ALT-SPACE).

If you put a -path <Director$CurrentDir> on your MenuMenu then beware,
looking at this Directory Menu will cause Director$CurrentDir and
Director$CurrentPath to change, so if you look at it again, you will be
looking up one level in the directory viewer.  This can be fixed by using a
dynamic menu as your MenuMenu (the default menu can be configured to do this,
look at its start).


Utils
=====

There are a few utilities provided with Director to make Commands more
powerful and to make your life easier.

    ExpandMenu    For converting old Pinboard+ menus to Director form
    RunFilerAc    For starting off Filer_Action tasks (see example menus)
    SwiModule    To be able to issue SWIs from the command line
    IfPodule    For finding out whether a podule is installed
    IfThereIs    For finding out whether a file/directory exists
    DriveName    For discovering the name of a drive from a path

You'll find these in the Utils directory within Director.  See there for
further documentation.

The SWI Module is very useful for building interesting commands but is not
essential to the operation of Director so you can stop it being loaded by
default by commenting out that line in the !Run file if you desire.


Planned Extensions
==================

These go from will do definitely, to probably won't ever do, but nice idea!

A command to allow general purpose filtering of MouseClicks on other tasks.
This would mean you could configure the Menu over Pinboard function.  This
would also allow ALT-Menu over Filer windows.

A command to allow general purpose filtering of low level mouse clicks.  This
would mean you could configure the clicks over the title bars (and over any
other icon in the window surround).

A command to open a menu.

A command to Delete a Menu, all Menus, an Icon or all Icons.

A command to add options to previously created menu (technically very easy).

-icon for Option to specify an icon in a text entry.

-noicon for a Path option for suppressing the icon.

A command to define menu colours for permanent and temporary menus.  Should
be able to define the title bar colours as well.

Auto scrolling for menus.

An extension to the Icon command to allow a command to be run when a file is
dragged to the icon.

An extension to the Icon command to allow a command to be run when the Icon
is dragged to a filer window or possibly an application.

Auto IconSprites or Filer_Boot applications
    1) Never
    2) When building permanent menus
    3) All the time

Holding down CTRL when making an auto menu could Filer_Boot the applications
within.

A Command run when Menu is pressed over a normal text item.

Make Director menus into windows.  Make the path options draggable and the
menu options clickable.  Make the menus persistent if torn off.


Thanks
======

[Your name could go here if you send me interesting menu options, bug
reports, comments, ideas or even just tell me that you are using Director!]

Thomas Olsson, Julian Smith, Ben Summers, Jens Ovesen and Franz Philipps for
writing a set of excellent utilities which gave me lots of ideas for
Director.

Jonathan Coxhead for OSLib.

Jens Ovesen for very kindly allowing me to distribute his excellent and
indispensable SWI module with this application.

Dominic Symes for Zap.  No programmer should be without it.

Phil Slingsby for thinking of the name.

Dave Lawrence for testing, the original idea (and code) of creating Pinboard+
menus from a textual form, ExpandMenu, IfPodule, IfThereIs, DriveName and
loads of other ideas and suggestions (some of which I've almost certainly
credited to myself ;-)

My wife Loveday.


Contacts
========

Post:    Nick Craig-Wood
    4 Victoria St
    Wolverton
    MILTON KEYNES
    MK12 5HL

EMail:    [e-mail]

BBS:    Arcade (0181 654 2212), User 939 (Nick Craig-Wood)

Any bug reports, ideas, donations gratefully accepted.