<chapter id="commands/index">
  <title>Director commands</title>

  <section id="commands/menus">
    <title>Menus</title>

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

    <para>Director keeps a list of menus which you can see from Director's main menu. 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.</para>

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

    <para><programlisting>	Menu ...
		Option ...
			Command ...
		Option ...
			Command ...
	Dash
		.
		.
		.
		Option ...
	EndMenu</programlisting></para>

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

    <para>The syntax for the menu command is:
      <cmdsynopsis>
        <command>Menu</command>
          <arg choice=plain><replaceable>title</replaceable></arg>
          <arg><replaceable>alias</replaceable></arg>
          <arg>-key <replaceable>key</replaceable></arg>
          <arg>-temp</arg>
          <arg>-remove</arg>
      </cmdsynopsis>
      See the section <xref linkend="director/commands/menu"> for an overview of the command and explanation of the accepted arguments.</para>

    <para>Possible examples are</para>

    <para><programlisting>
	Menu &quot;Mode&quot;</programlisting>
Starts a menu with title and internal name both &quot;Mode&quot;</para>

    <para><programlisting>
	Menu Mode</programlisting>
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.</para>

    <para><programlisting>
	Menu &quot;Lots of Modes&quot; Mode</programlisting>
Starts a menu with title &quot;Lots of Modes&quot; and internal name &quot;Mode&quot;</para>

    <para><programlisting>
	Menu &quot;DDE&quot; -key ^D</programlisting>
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)</para>

    <para><programlisting>
	Menu &quot;Temporary&quot; -temp</programlisting>
This will make a menu which will be displayed only once and then destroyed. This is useful for dynamic menus, and for menus displayed with DirectorShowMenu</para>

    <para><programlisting>
	Menu &quot;DDE&quot; -remove</programlisting>
This will remove from director's memory the menu called &quot;DDE&quot;. This is useful for tidying up. If the menu named isn't found then it will not return an error</para>

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

    <para>The syntax for the endmenu command:
    <cmdsynopsis>
      <command>EndMenu</command>
      <arg>-sort</arg>
    </cmdsynopsis>
    See the section <xref linkend="director/commands/endmenu"> for an overview of the command and explanation of the accepted arguments.</para>

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

    <para>The syntax for the endmenu command:
    <cmdsynopsis>
      <command>Dash</command>
    </cmdsynopsis>
    See the section <xref linkend="director/commands/command"> for an overview of the command.</para>

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

    <para>The syntax for the Option command:
    <cmdsynopsis>
      <command>Option</command>
        <group choice=plain>
          <arg><replaceable>text</replaceable></arg>
          <arg>-path <replaceable>file/directory</replaceable></arg>
        </group>
        <arg>-tick</arg>
        <arg>-bg <replaceable>colour</replaceable></arg>
        <arg>-fg <replaceable>colour</replaceable></arg>
        <arg>-sub <group>
          <arg><replaceable>menu</replaceable></arg><arg>*</arg>
        </group></arg>
        <arg>-len <replaceable>len</replaceable>
          <arg>-allow <replaceable>characters</replaceable></arg>
        </arg>
        <arg>-dash</arg>
        <arg>-grey</arg>
        <arg>-key <replaceable>number</replaceable></arg>
        <arg>-up</arg>
        <arg>-nosprite</arg>
        <arg>-sprite <replaceable>name</replaceable></arg>
    </cmdsynopsis>
    See the section <xref linkend="director/commands/option"> for an overview of the command and explanation of the accepted arguments.</para>

    <para>The Option command must be supplied with a text or a path or both. For
example</para>

    <para><programlisting>
	Option &quot;Mode 31&quot;</programlisting>
      Will produce a menu entry with the text &quot;Mode 31&quot; which could have a command attached (see later).</para>

    <para><programlisting>
	Option -path ADFS::4.$.Apps</programlisting>
      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 !.</para>

    <para><programlisting>
	Option &quot;Applications&quot; -path ADFS::4.$.Apps</programlisting>
      As above except the text in the menu option will be &quot;Applications&quot; rather than &quot;Apps&quot;.</para>

    <para>A text option may have nothing, one or two Commands attached (see later) or a SubMenu.</para>

    <para><programlisting>
	Option &quot;Modes&quot; -sub &quot;Modes&quot;</programlisting>
      This produces a menu entry with the text &quot;Modes&quot; and a right pointing arrow. When pointer moves over the arrow the Menu &quot;Modes&quot; will be opened as a sub menu. If the user clicks on the item (or uses a hotkey) the &quot;Modes&quot; menu will be opened as the root menu.</para>

    <para><programlisting>
	Option &quot;Modes&quot; -sub *</programlisting>
      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.</para>

    <para>A menu option may be activated by a key, eg.</para>

    <para><programlisting>
	Option -path ADFS::4.$.Apps -key ^A</programlisting>
      Opens the Apps directory on CTRL-A</para>

    <para><programlisting>
	Option &quot;Modes&quot; -sub * -key M</programlisting>
      Opens the modes SubMenu (if no command attached) or does the attached command if M is pressed.</para>

    <para><programlisting>
	Option &quot;Command&quot; -key <inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject>^Z</programlisting>
      If a command is attached then it does it on SHIFT-CTRL-Z otherwise it does nothing.</para>

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

    <para><programlisting>
Option &quot;Format&quot; -fg 11</programlisting>
      Produces Red text on the default background</para>

    <para><programlisting>
	Option &quot;Boot&quot; -fg 0 -bg 8</programlisting>
      Produces White text on a Dark Blue background</para>

    <para>Mention &lt;Director${Colour} sys vars. Warn about setting background colours in RISC OS 4 and later -&gt; leads to non 3D menu.</para>

    <para>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 &lt;MenuText&gt; which can be used in commands. In fact &lt;MenuText&gt; is written for non-writable items and when creating a submenu too.</para>

    <para><programlisting>
	Option &quot;13&quot; -len 3</programlisting>
      Might be used for typing in a mode number of maximum length 3 characters. The command attached would then use &lt;MenuText&gt; to set the actual mode. The string &quot;13&quot; is the default text.</para>

    <para><programlisting>
	Option &quot;&quot; -len 200</programlisting>
      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.</para>

    <para><programlisting>
	Option &quot;&quot; -len 16 -allow &quot;0-9&quot;</programlisting>
      The allow option lets you specify what characters can be typed in. In this case it will only allow the user to type in numbers.</para>

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

    <para>-dash Writes a dash under the menu item. This is equivalent to the Dash command.</para>

    <para>-grey Makes the menu entry grey and unselectable. Useful occasionally.</para>

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

    <para>-nosprite Stops a sprite appearing in a -path menu. It also stops the menu entry being greyed out if the path did not exist.</para>

    <para>-sprite adds the named sprite into the menu entry. The sprite must be the correct size (the same size as small filer icons). If it is not found it is replaced with a file_xxx sprite (a blank white square).</para>

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

    <para>The syntax for the Command command:
    <cmdsynopsis>
      <command>Command</command>
      <arg><replaceable>*command</replaceable></arg>
    </cmdsynopsis>
    See the section <xref linkend="director/commands/command"> for an overview of the command and explanation of the accepted arguments.</para>

    <para>For example:</para>

    <para><programlisting>
	Option &quot;Mode 13&quot;
		Command WimpMode 13</programlisting>
      Sets Mode 13 when clicked on.</para>

    <para><programlisting>
	Option &quot;13&quot; -len 3</programlisting>
		Command WimpMode &lt;MenuText&gt;
      Sets the mode typed in when clicked on.</para>

    <para><programlisting>
	Option &quot;&quot; -len 200
		Command &lt;MenuText&gt;</programlisting>
      Runs the command typed in when clicked on.</para>

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

    <para>For example</para>

    <para><programlisting>
	Option &quot;A&quot;
		Command FontInstall Fonts:!A.
		Command FontRemove Fonts:!A.</programlisting></para>

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

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

    <para>This also means that multiple OS commands can be put on one line by separating them with |M.</para>

    <para>For example:</para>

    <para><programlisting>
	Option &quot;Reset SysFont&quot;
		Command fx 20|MSWI Wimp_CommandWindow -1</programlisting>
    Which resets the system font with *FX 20 and then redraws the screen with the SWI Wimp_CommandWindow.</para>
  </section>

  <section id="commands/showmenus">
    <title>Showing a menus</title>
    <para>A menu can be shown immediately with the command</para>

    <para>	DirectorShowMenu &lt;menu_name&gt;</para>

    <para>This will open the menu named immediately. You can make obey files which define menus and then open them immediately with this command. If you add -temp to the menu then it will be deleted after it has been shown.</para>
  </section>

  <section id="commands/sysvars">
    <title>System variables</title>

    <para>These system variables are set whenever a path sub menu is opened or a path item is chosen</para>

    <para><programlisting>
	Director$CurrentPath
		full path of object
	Director$CurrentDir
		directory object lives in
	Director$CurrentLeaf
		leaf name of object</programlisting></para>

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

    <para>The last Command that was run can be seen in the system variable</para>

    <para><programlisting>
	Alias$DirectorRun</programlisting></para>

    <para>To issue *Show Alias$DirectorRun at the command line to see what it was.</para>

    <para>Whenever a text option is chosen</para>

    <para><programlisting>
	MenuText</programlisting></para>

    <para>Whenever menu is clicked over the File 'xxx' option in a Filer Menu</para>

    <para><programlisting>
	Leaf</programlisting></para>

    <para>is set to the leaf name of the file (&quot;xxx&quot; in this case).</para>

    <para>When Director quits it looks though any system variables of the form</para>

    <para>	Director$AtExit*</para>

    <para>and runs the associated text as a command. This is useful for setting Director to do something on shutdown or when Director is killed.</para>

    <para>Technical note: these commands won't get run if you restart Director while it is running. This is because Director isn't running as a task when it is killed (and can't do) so it can't launch the commands as tasks. If anyone feels strongly about this then I might change it.)</para>
  </section>

  <section id="commands/gstrans">
    <title>GSTrans</title>

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

    <para>As a rule every string parameter passed to Director is GSTransed when it is parsed. This means that</para>

    <para><programlisting>
	Option -path &lt;Wimp$Scrap&gt;</programlisting></para>

    <para>Will be GSTransed into (something like)</para>

    <para><programlisting>
	Option -path ADFS::HardDisc4.$.!Boot.!Scrap.ScrapDirs.ScrapFile</programlisting></para>

    <para>Which means that if Wimp$Scrap changes, the option won't be looking in the right place. The menu text will read &quot;ScrapFile&quot;. Better is</para>

    <para><programlisting>
	Option -path |&lt;Wimp$Scrap&gt;</programlisting></para>

    <para>Which GSTranses into</para>

    <para><programlisting>
	Option -path &lt;Wimp$Scrap&gt;</programlisting></para>

    <para>which is what you want. The menu text will read &quot;&lt;Wimp$Scrap&gt;&quot;. Probably best (for this use) is</para>

    <para><programlisting>
	Option &quot;Scrap&quot; -path |&lt;Wimp$Scrap&gt;</programlisting></para>

    <para>Which has the menu text &quot;Scrap&quot; but is otherwise identical to the one above.</para>

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

    <para><programlisting>
	Option &quot;13&quot; -len 3
		Command WimpMode &lt;MenuText&gt;</programlisting></para>

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

    <para><programlisting>
	Option &quot;Open App&quot;
		Command Filer_OpenDir &amp;lt;Obey$Dir&amp;gt;
	Option &quot;Open App&quot;
		Command Filer_OpenDir |&lt;Obey$Dir&gt;</programlisting></para>

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

    <para>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 &lt;Obey$Dir&gt; which should not normally be allowed.)</para>
  </section>

  <section id="commands/specmenus">
    <title>Special forms of Menus and Commands</title>

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

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

    <para>&quot;Text&quot;		For normal command or sub-menu (ie action unchanged)</para>

    <para>&quot;Menu:Name&quot;	To bring up named menu</para>

    <para>&quot;Save:Path&quot;	For save box of the given Path (*)</para>

    <para>&quot;Path:Path&quot;	For a directory menu of that Path (*)</para>

    <para>&quot;Command:Text&quot;	Runs the Text as if it were a command</para>

    <para>&quot;Quit:&quot;		Quits Director</para>

    <para>&quot;Info:&quot;		Brings up Director's info window</para>

    <para>&quot;OldMenu:&quot;	To open the last filtered menu (for getting pinboard menu)</para>

    <para>&quot;MenuMenu:Path&quot;	Takes Path, adds .&lt;leaf&gt; to it and opens the MenuMenu
		pointing at that file. Used internally. (*)</para>

    <para>&quot;Memoriser:&quot;	Opens a menu of recently used files.
		(See Memoriser section.)</para>

    <para>&quot;Dynamic:Text&quot;	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.</para>

    <para>&quot;GSTrans:Text&quot;	GSTranses the Text and then reinterprets it as an extended
		command.</para>

    <para>(*) If the path is missing eg &quot;Path:&quot; or &quot;Save:&quot; 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.</para>

    <para>For example</para>

    <para><programlisting>
	Option &quot;Floppy&quot; -sub &quot;Path:ADFS::0.$&quot;</programlisting></para>

    <para>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</para>

    <para><programlisting>
	Option &quot;Floppy&quot; -path ADFS::0.$</programlisting></para>

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

    <para><programlisting>
	Option &quot;Root&quot; -sub &quot;Command:Filer_OpenDir ADFS::4.$&quot;</programlisting></para>

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

    <para><programlisting>
	Option &quot;Pinboard&quot; -sub &quot;OldMenu:&quot;</programlisting></para>

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

    <para><programlisting>
	Option Here -sub &quot;Path:&lt;Director$CurrentDir&gt;&quot;
	Option Copy -sub &quot;Save:&lt;Director$CurrentPath&gt;&quot;</programlisting></para>

    <para>These options are useful for the MenuMenu (see the section titled MenuMenu and the section titled SaveBox).</para>

    <para><programlisting>
	Option Info -sub Info:
	Option Quit
		Command Quit:</programlisting></para>

    <para>Helps bring an air of normality to Director by providing the standard Quit and Info choices!</para>
  </section>

  <section id="commands/memoriser">
    <title>Memoriser</title>

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

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

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

    <para>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. If in the mean time you have deleted the file then it will not be shown in the menu.</para>

    <para>It is possible to make the memoriser display only applications,  directories or files by adding a numeric parameter after the Memoriser:</para>

    <para><programlisting>
	Memoriser:1 - memoriser shows applications
	Memoriser:2 - memoriser shows directories and images
	Memoriser:4 - memoriser shows files</programlisting></para>

    <para>The parameters can be combined in a linear fashion, eg Memoriser:6 shows directories, images and applications but not files.</para>

    <para>The total number of items that are kept in the Memoriser menu is definable with the command</para>

    <para>	Syntax: MemoriserItems &lt;number&gt;</para>

    <para>If you set it to 0 then you won't get any items in the menu, effectively turning the feature off. 0 is the default value.</para>

    <para>You can save and restore the memoriser with:</para>

    <para><programlisting>
	MemoriserSave &lt;file&gt;
	MemoriserLoad &lt;file&gt;</programlisting></para>

    <para>This will save the contents of the memoriser or replace it with that in the file. The file is a simple text file with a file path on each line. The file at the top of the menu appears at the bottom of the file.</para>

    <para>You can clear the memoriser with</para>

    <para><programlisting>
	MemoriserClear</programlisting></para>

    <para>By default Director saves and restores the memoriser settings to the file &lt;Director$Write&gt;.Memoriser on startup and shutdown. You could also use MemoriserLoad to prime the memoriser with often used files.</para>
  </section>

  <section id="commands/menumenu">
    <title>MenuMenu</title>

    <para>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 &quot;File '!Run'&quot; or &quot;Selection&quot;) provided one and only one file is selected in the Filer window.</para>

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

    <para>Here is an example of a MenuMenu</para>

    <para>Set Director$MenuMenu MenuMenu</para>

    <para><programlisting>
	Menu &quot;FileMenu&quot; &quot;MenuMenu&quot;
	Option Here -sub &quot;Path:|&lt;Director$CurrentDir&gt;&quot;</programlisting></para>

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

    <para><programlisting>
	Option Copy -sub &quot;Save:|&lt;Director$CurrentPath&gt;&quot;</programlisting></para>

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

    <para><programlisting>
	Option &quot;Set CSD&quot;
		Command Dir &lt;Director$CurrentDir&gt;</programlisting></para>

    <para>Sets the Current Directory to the directory in which the file or directory was found.</para>

    <para><programlisting>
	Option &quot;Open Directory&quot;
		Command Filer_OpenDir &lt;Director$CurrentDir&gt;</programlisting></para>

    <para>This opens a Filer Window onto the directory in which the file or directory was found.</para>

    <para><programlisting>
	Option &quot;Filer_Run&quot;
		Command Filer_Run &lt;Director$CurrentPath&gt;</programlisting></para>

    <para>This is equivalent to double clicking on the File or Directory.</para>

    <para><programlisting>
	Option &quot;Filer_Run&quot;
		Command Filer_Run &lt;Director$CurrentPath&gt;</programlisting></para>

    <para>This is equivalent to double clicking on the File or Directory.</para>

    <para><programlisting>
	Option &quot;Pin&quot;
		Command SWI OS_Mouse TO x y|M
			Pin &lt;Director$CurrentPath&gt; |&lt;x&gt;-90 |&lt;y&gt;+45</programlisting></para>

    <para>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 |&lt;x&gt;, this is GSTransed to at run time &lt;x&gt; when the Command is being prepared, which is then GSTransed to the mouse x co-ordinate when the Pin command is run.)</para>

    <para><programlisting>
	Option &quot;IconSprites&quot;
		Command IconSprites &lt;Director$CurrentPath&gt;</programlisting></para>

    <para>This IconSprites the file or directory. (Only really useful over a sprite file.)</para>

    <para>EndMenu</para>

    <para>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.</para>
  </section>

  <section id="commands/pinboard">
    <title>Pinboard</title>

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

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

    <para>Alternatively on your Pinboard menu you can have an option</para>

    <para><programlisting>
	Option Pinboard -sub OldMenu:</programlisting></para>

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

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

  <section id="commands/savebox">
    <title>SaveBox</title>

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

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

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

    <para>You may also drag files to the SaveBox from the pinboard or Filer and it will update to show the file you dragged.</para>

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

  <section id="commands/keys">
    <title>Keys</title>

    <para>Any Menu or Menu Option can have a hot key assigned.</para>

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

    <para>Keys are added by name and possibly with a modifier.</para>

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

    <para>Some keys are referred to by name (case insensitive), and these are:</para>

    <para>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, WinLogo and WinMenu.</para>

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

    <para>Possible modifiers are:</para>
    <para><inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject> SHIFT</para>
    <para>^ CTRL</para>
    <para>~ ALT</para>

    <para>(To get the <inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject> 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).)</para>

    <para>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.:</para>

    <para><programlisting>
	^M		CTRL-M
	<inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject>A		SHIFT-A
	^<inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject>F1 = <inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject>^F1	SHIFT-CTRL-F1</programlisting></para>

    <para>Note that -key <inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject>A = -key <inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject>a which is not equal to -key A = -key a.</para>

    <para>Some key combinations don't work, eg.:</para>

    <para>CTRL Number keys don't work, CTRL KeyPad numbers should. No keys work with ALT!</para>

    <para>These may be fixed in a future release!</para>

    <para>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 <inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject> or is one of the long form named keys above.</para>
  </section>

  <section id="commands/colours">
    <title>Colours</title>

    <para>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 &lt; 3.5). The numbers of each colour are given below.</para>

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

    <para>These names are defined in the file Director:Library.!Core and are defined by default so you may use &quot;Director$&quot; + colour name wherever a colour is needed, </para>

    <para>eg.:<programlisting>
	Option &quot;Unreadable&quot; -bg &lt;Director$Red&gt; -fg &lt;Director$Khaki&gt;</programlisting></para>
  </section>

  <section id="commands/dynamenus">
    <title>Dynamic Menus</title>

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

    <para>They are used from an extended menu &quot;Dynamic:Filename&quot;. When this command is run the file or command &quot;Filename&quot; 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.</para>

    <para>A simple example of a dynamic menu would be this</para>

    <para><programlisting>
	Option &quot;Time&quot; -sub &quot;Dynamic:DirectorObey Director:Menus.Time&quot;</programlisting></para>

    <para>This will run the command &quot;DirectorObey Director:Menus.Time&quot; when this menu option is run. The contents this file might be</para>

    <para><programlisting>
	Menu &quot;&quot; Time -temp
		Option &quot;**TheTimeWas**&quot; -fg 11
		Option &quot;&lt;Sys$Time&gt;&quot;
		Option &quot;&lt;Sys$Date&gt;&lt;Sys$Year&gt;&quot;
	EndMenu

	Set Director$Menu Time</programlisting></para>

    <para>This creates a temporary menu called Time with the current time and date in it and returns the string &quot;Time&quot; in Director$Menu for Director to use as the name of a menu to open.</para>

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

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

    <para>It would be possible 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 maybe a future version of Director will do this for you.</para>

    <para>Dynamic menus set Director$Window and Director$Icon to the window handle and icon number that the request was over respectively. This is useful for more advanced menus like the CloseBox menu example.</para>
  </section>

  <section id="commands/icons">
    <title>Icons</title>

    <para>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 an already existing one then the existing icon will be deleted without warning and the new one created.</para>

    <para>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)</para>

    <para><programlisting>
Syntax: *DirectorIcon
	&lt;sprite&gt;
		Name of the sprite, must be provided and exist in the
		Wimp sprite pool
	[-alias &lt;name&gt;]
		Internal name of the Icon. If this is not supplied
		then the icon is referred to by its sprite name.
	[-text &lt;text&gt;]
		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 &lt;priority&gt;]
		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 &lt;format&gt; | -free &lt;drive spec&gt; | -freemem]
		This makes the text under the icon display a piece of
		information about the system. The
		length of the time is set by the -text option which must be
		given a string which is as long as the longest time string,
		and preferably of the same format
		-time &lt;format&gt;
			This makes the text under the icon display the current
			time, which is updated once per second. The usual time
			format is %24:%mi and it is recomended that the text
			option is &quot;00:00&quot;. See the Applications Guide, under
			!Alarm, &quot;Time and date formats&quot; for more details or
			the RISCOS 3 PRMs 1-402.
		-free &lt;drive spec&gt;
			This makes the text under the icon display the free
			space left on a drive. 'Drive spec' can be in the
			format of 'ADFS::4.$' or 'ADFS::HardDisc4'. This
			facility does not work on removable drives.
			The routine uses an internal algorythm to convert the
			free space into a human readable form. This may result
			in a slightly different value to what is displayed by
			the Free space windows.
		-freemem
			This makes the text under the icon display the free
			memory on the machine.
	[-menu &lt;menu&gt;]
	[-select &lt;menu&gt;]
	[-adjust &lt;menu&gt;]
		These allow you to attach menus or commands to the 3 mouse
		buttons.
	[-dragto &lt;menu&gt;]
		This specifies a menu to be run when a file is dragged onto the
		icon. The path of the object dragged can be found from
		Director$CurrentPath &hellip;Leaf and &hellip;Dir.
	[-dragfrom &lt;path&gt;|*&lt;menu&gt;]
		This either takes a path which then acts exactly like the
		SaveBox or takes a menu preceded by * which will be run with
		Director$CurrentPath &hellip;Leaf and &hellip;Dir set up.
	[-remove]
		If this is specified then the named icon is removed rather than
		created.</programlisting></para>

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

    <para><programlisting>
	DirectorIcon romapps Apps -left -priority &50000000
		-menu &quot;Path:Resources:$&quot;
		-select &quot;Command:Filer_OpenDir Resources:$.Apps&quot;
		-adjust Pinboard</programlisting></para>

    <para>This provides a replacement Apps icon which has the Pinboard menu on Adjust, does the normal thing on select, and on menu (which would normally say &quot;Open$&quot;) produce a directory menu of the whole of Resources which is usually much more useful.</para>

    <para><programlisting>
	DirectorIcon !Director &quot;00:00:00&quot; -left -priority &0E000000
		-menu IconMenu
		-select IconClick
		-adjust Pinboard
		-time &lt;37&gt;24:%MI:%SE</programlisting></para>

    <para>This produces an icon with Director's own icon, the current time in 24 hour format and 3 menus, IconClick, IconMenu and Pinboard.</para>

    <para>[NB &lt;37&gt; 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! &lt;37&gt; is used rather than %% so the file will work with Obey and DirectorObey]</para>

    <para><programlisting>
	DirectorIcon trashcan -left
		-dragto &quot;Command:Wipe |&lt;Director$CurrentPath&gt; ~CFR~V&quot;</programlisting></para>

    <para>This will create a trash can icon which will delete all the items dragged onto it.</para>

    <para><programlisting>
	DirectorIcon directory -left
		-dragfrom &quot;*Command:Dir |&lt;Director$CurrentPath&gt;&quot;</programlisting></para>

    <para>his when you drag the directory icon from the icon bar to a filer window then it will set the current directory.</para>

    <para><programlisting>
	DirectorIcon file_fff Text
		-select &quot;Filer_Run $.Text&quot;
		-dragfrom &quot;$.Text&quot;</programlisting></para>

    <para>This will make an icon which works quite like a TinyDir but for one file $.Text. You can drag the icon to copy the file or put it into a document and click on the icon to run the file (in the case of a text file load it into a text editor).</para>

    <para><programlisting>
	DirectorIcon ramfs -free Ram::RamDisc0.$ -text &quot;0000k&quot;
		-priority &40000000
		-select &quot;Command:Filer_OpenDir Ram::RamDisc0.$&quot;
		-adjust &quot;Command:Filer_OpenDir Ram::RamDisc0.$&quot;</programlisting></para>

    <para>Director is now able show the free space left on a drive.</para>

    <para><programlisting>
	DirectorIcon !configure -freemem -text &quot;0000k&quot;
		-right -priority &20000000</programlisting></para>

    <para>Director can also show the free memory available</para>
  </section>

  <section id="commands/windows">
    <title>Windows</title>

    <para>Windows are created in a similar way to both menus and icons. Each one must be named (case insensitive) by its window name or an alias name provided by you and there can only be one of each name. If you create a window with the name of an already existing one then the existing window will be deleted without warning and the new one created in its place.</para>

    <para>In order for Director to fully implement windows it needs the help of a supporting program. This program will get informed of all events which happen to the window and it decides which one(s) it responds to.</para>

    <para>This creates a new window. The window is referred to by the name in the template file or the alias name if supplied.</para>

    <para><programlisting>
	Syntax:	*DirectorWindow
		&lt;template_name&gt;
			Name of the window which must be provided. It must
			exist in the template file specified.
		[-alias &lt;name&gt;]
			Internal name of the window. If this is not supplied
			then the window is referred to by its name.
		[-file &lt;template_file&gt;]
			Template file containing definition for the named
			window.
		[-command &lt;program&gt;]
			This is full filename of the support program which lets
			the window react to key presses and mouse clicks
		[-callevery &lt;seconds&gt;]
			This repeatedly calls the support program every
			&lt;seconds&gt; seconds.
		[-background]
			Keep polling the window even when it's closed.
		[-temp]
			Once closed, the window is removed.
		[-remove]
			If this is specified then the named window is removed
			rather than created.</programlisting></para>

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

    <para><programlisting>
	DirectorWindow Info -alias DirectorInfo
		-file &lt;Director$Resources&gt;Templates
		-command &lt;Director$Dir&gt;.Menus.Internal.Templates</programlisting></para>

    <para>This command setups up the Info window as displayed by Director. This loads the window Info from the template file &lt;Director$Resources&gt;Templates . The support program is &lt;Director$Dir&gt;.Menus.Internal.Templates which setups up the
window and handle clicks on the buttons: Web, Email and Help.</para>
   </section>

  <section id="commands/dirmenus ">
    <title>Directory Menus</title>

    <para>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) in the default set up. They are also produced by -path &quot;directory&quot; or Command &quot;Path:Directory&quot; etc.</para>

    <para>A menu will appear with all the files that are in the directory in it. It is intended to be complementary to the Filer, quicker to use, but not as powerful. The entries are sorted by name.</para>

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

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

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

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

    <para>Directory menus come in 2 flavours, with and without &quot;Up Menus&quot;. 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 has the Menu Menu as a sub-menu (its contents are always visible below the dotted line).</para>

    <para>A directory menu made by &quot;Path:&quot; 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.</para>
  </section>

  <section id="commands/filters">
    <title>Filters</title>
    <para>Filters are a powerful way to change the appearance of your desktop. You may add new menus or commands to existing desktop features without having to patch anything. For instance you could add a new menu onto the task switcher icon or cause menu over any close icon to come up with a menu.</para>

    <para>Filters are referred to by name (case insensitive) as supplied in the command. There can only be one filter of any given name, and if you attempt to create a filter with the same name as an existing one then the existing filter will be deleted without warning.</para>

    <para><programlisting>
	DirectorFilter &lt;name&gt; &lt;task&gt; &lt;menu&gt;
		[-icon &lt;n&gt;]
		[-select] [-menu] [-adjust]
		[-shift] [-ctrl] [-alt]
		[-remove]</programlisting></para>

    <para>&lt;name&gt; is the name of the filter to be defined</para>

    <para>&lt;task&gt; is the name of the task to filter on or * for all tasks. This task does not not have to be running when the command is executed and director will keep track of the task if it is shut down and re-started.</para>

    <para>&lt;menu&gt; is the menu (or command) to be executed by the filter</para>

    <para>-icon &lt;n&gt; defines an icon number for the filter to execute. If this number is &gt;= 0 then it will define a normal icon (load the template of the window you are interested in into a template editor to discover the icon number or use trial and error). The file Director:Menus.Aliases contains names for a number special icons which are probably more  useful</para>

    <para><programlisting>
WorkArea		- background of a window with no icons
BackIcon		- back icon in the top left of a window
CloseIcon		- close icon in the top left of a window
TitleBar		- title bar at the top of a window
ToggleSizeIcon		- toggle size icon at the top right of a window
ScrollUpArrow		- scroll up arrow
VerticalScrollBar	- vertical scroll bar
ScrollDownArrow		- scroll down arrow
AdjustSizeIcon		- adjust size icon at the bottom right of a window
ScrollLeftArrow		- scroll left arrow
HorizontalScrollBar	- horizontal scroll bar
ScrollRightArrow	- scroll right arrow
OuterWindowFrame	- outer frame of the window (1 pixel wide)
IconBar			- an icon bar icon only</programlisting></para>

    <para>-select -menu -adjust -shift -ctrl -alt are the conditions in which the filter executes. The button named must be down for the command to execute. They may be used in any combination and are exclusive (ie -shift -adjust will only execute if SHIFT and ADJUST are pressed and not if SHIFT ALT ADJUST are pressed ).</para>

    <para>-remove removes a filter from director's memory and stops it executing.</para>

    <para>Examples (these have been split over lines for readability but should be entered on one line)</para>

    <para><programlisting>
	DirectorFilter &quot;Title Bar Directory&quot; * Path: -icon TitleBar -menu
		This filter makes a directory menu when you press menu over
		the title bar of any window.
	DirectorFilter &quot;Alt Menu Directory&quot; Filer Path: -menu -alt
		This filter makes a directory menu when you press ALT MENU
		over a filer window
	DirectorFilter &quot;Pinboard&quot; Pinboard Pinboard -icon WorkArea -menu
		This opens a menu called pinboard when menu is pressed over
		the work area of the pinboard. If you press menu over an
		icon on the pinboard then you will get the pinboard menu.
	DirectorFilter &quot;Close Icon&quot; *
		&quot;Dynamic:DirectorObey Director:Menus.System.Close&quot;
		-icon CloseIcon -menu
		This makes a menu appear when you press menu over any close
		box. The menu is a dynamic menu because it adjusts itself to
		the window it was used over using Director$Window and
		Director$Icon.
	DirectorFilter &quot;Display Manager Adjust&quot; &quot;Display Manager&quot; &quot;Mode&quot;
		-icon IconBar -adjust
		This adds an extra menu to the display manager icon bar icon
		when it is clicked with adjust.
	DirectorFilter &quot;Task Manager Adjust&quot; &quot;Task Manager&quot;
		&quot;Dynamic:DirectorObey Director:Menus.System.Time&quot;
		-icon IconBar -adjust
		This shows the time when adjust is clicked over the switcher
		icon</programlisting></para>

    <para>You may attach the original action of the filtered object by including OldMenu: as an option in the filter menu.</para>
  </section>

  <section id="commands/other">
    <title>Other Commands</title>

    <para><programlisting>
	Syntax: *DirectorObey &lt;file&gt; [-verbose]</programlisting></para>

    <para>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!</para>

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

    <para>DirectorObey will also throwback errors if you have the DDEUtils module loded. Any errors produced will have the file name and line number of the error embedded in them to aid debugging.</para>

    <para><programlisting>
	Syntax: *MenuProcessing &lt;On|Off|1|0|Yes|No|Y|N|Smash|S|X|2&gt;</programlisting></para>

    <para>1, Yes, and Y are all synoms for On. 0, No and N are all synmos for Off. S X and 2 are all synmos for Smash.</para>

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

    <para>Menu Processing is now nestable. This means that you can have a menu segment like:</para>

    <para><programlisting>
	Menu
	Option ...
	If "..." Then MenuProcessing Off
		Option
		If "..." Then MenuProcessing Off
			Option
		MenuProcessing On
		Option
		MenuProcessing On
	Option
	EndMenu</programlisting></para>

    <para><programlisting>
	MenuProcessing Smash</programlisting></para>

    <para>Breaks out of all levels of nesting</para>

    <para>The level of nesting is now reported in the system variable &lt;Director$MenuProcessing&gt;. A value of 0 means that menu processing is on and commands like Menu, Option EndMenu (etc). will be obeyed. If the value is higher, then menu processing has been turned off that many times. If the variable is unset then a level of 0 (menu processing is on) should be assumed.</para>

    <para><programlisting>
	Syntax: *DirectorDo &lt;command&gt;</programlisting></para>

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

    <para><programlisting>
	Syntax: *ProcessKeys [[<inlinemediaobject><imageobject><imagedata fileref="&images2;Up.gif"></imageobject><textobject><phrase>&uarr;</phrase></textobject></inlinemediaobject>][^]&lt;key&gt;|&quot;&lt;string&gt;&quot;]^</programlisting></para>
    <para>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</para>

    <para><programlisting>
	ProcessKeys &quot;Modules&quot; Return
	ProcessKeys F6 ^Left Down F6 ^Up ^V
	ProcessKeys &quot;Show Obey$Dir&quot; ^M
	ProcessKeys &quot;42 Solution Road&quot; ^M &quot;Toytown&quot; ^M &quot;Shireshire&quot; ^M
	ProcessKeys TAB &quot;Option -path &quot;</programlisting></para>

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

    <para><programlisting>
	Syntax: *DirectorEdit &lt;file&gt; [-q | -quiet]</programlisting></para>

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

    <para>If you sypply the quiet (q) switch then Director won't complain if it couldn't load the file.</para>

    <para><programlisting>
	Syntax: *DirectorParsePath &lt;path&gt;</programlisting></para>

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

    <para><programlisting>
	Syntax: *DirectorMouseDir &lt;var_name&gt; [-file]</programlisting></para>

    <para>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 (&quot;&quot;).</para>

    <para>If -file is specified then the system variable may be set to point to a file (if over an Edit or Zap window for example), otherwise it will be set to the directory in which the file resides.</para>

    <para><programlisting>
	Syntax: *DirectorSortMenu &lt;menu&gt; [&lt;from&gt; [&lt;to&gt;]]</programlisting></para>

    <para>This sorts the menu named alphabetically (ignoring case) by option text. From and to are numeric parameters indicating option numbers (starting at 0) if you only want to sort part of a menu. Don't sort menus with key shortcuts!</para>

    <para><programlisting>
	Syntax: *DirectorURL &lt;url&gt; [&lt;-q | -quiet&gt;]</programlisting></para>

    <para>This tries to open a URL in whatever application supports the supplied URL. If loaded it will try to use the AcornURI module to launch the URL. If that fails or the module isn't loaded then it will use the ANT/InetSuite protocol to try to launch the URL. If that fails then it will look for the system variable 'Alias$URLOpen_&lt;protocol&gt;', where &lt;protocol&gt; is the likes of http and mailto.</para>

    <para>If you sypply the quiet (q) switch then Director won't complain if it couldn't launch the URL.</para>
  </section>

  <section id="commands/debugging">
    <title>Debugging your Menus</title>

    <para>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 &quot;DirectorObey -v &quot; 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.</para>

    <para><programlisting>
	Option &quot;Debug&quot;
		Command TaskWindow &quot;DirectorObey -v Director:Menus.Menu&quot;</programlisting></para>

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

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

    <para><programlisting>
	Option &quot;Hello&quot; -sub &quot;NotThere&quot;</programlisting></para>

    <para>Where menu &quot;NotThere&quot; 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).</para>

    <para>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.</para>
  </section>

</chapter>