home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / filemanager / director_1 / !Director / !Help < prev    next >
Text File  |  1995-08-04  |  52KB  |  1,476 lines
  1. ¤ Help file for Director version 0.21
  2. =====================================
  3.  
  4. Director is Copyright (C) Nick Craig-Wood 1994
  5.  
  6. If you are reading this in !Edit then you might like to do Expand tabs on the
  7. Edit menu to turn those [09]'s into something useful!
  8.  
  9. At the start of each section title is a ¤ character (ALT-164 if your keyboard
  10. doesn't have it) which can be used to search this file.
  11.  
  12.  
  13. ¤ Contents
  14. ==========
  15.  
  16. - Contents
  17. - License
  18. - Introduction
  19. - Motivation
  20. - Switching from Pinboard+ to Director
  21. - Switching from TreeMenu (or DirMenu) to Director
  22. - Upgrading from Director 0.11 (first public release)
  23. - Menus
  24. - Showing a Menu
  25. - System Variables
  26. - GSTrans
  27. - Special forms of Menus and Commands
  28. - Memoriser
  29. - MenuMenu
  30. - Pinboard
  31. - SaveBox
  32. - Keys
  33. - Colours
  34. - Dynamic Menus
  35. - Icons
  36. - Directory Menus
  37. - Filters
  38. - Other Features
  39. - Other Commands
  40. - External Interface
  41. - SWIs
  42. - Debugging your Menus
  43. - Oddities
  44. - Utils
  45. - Planned Extensions
  46. - Thanks
  47. - Contacts
  48.     
  49.  
  50. ¤ License
  51. =========
  52.  
  53. Director (The Software) is Copyright (C) Nick Craig-Wood 1994 (NCW) and may
  54. not be used or copied except as in accord with the terms and conditions
  55. below.
  56.  
  57. You may NOT Make the Software available to any third party EXCEPT with these
  58. terms and conditions imposed on said party.
  59.  
  60. You may NOT Make the Software available to any third party EXCEPT at no
  61. benefit to yourself or any third party, excepting that benefit contained
  62. within the Software.
  63.  
  64. You MUST make sure the Software is distributed whole, intact and unmodified,
  65. including all the files in the original distribution.
  66.  
  67. You may NOT may not sell, hire or include the Software in a package which is
  68. sold or hired, modify, translate, disassemble, decompile, reverse engineer,
  69. or create derivative works based upon the Software or include whole or part
  70. of the Software into other works. 
  71.  
  72. The Software is supplied "as is", NCW makes no warranty, express or implied,
  73. as to the merchantability or its fitness for any particular purpose.  It may
  74. or may not perform in accordance with the documentation or your expectations.
  75.  
  76. In no circumstances will NCW be liable for any damage, loss of profits,
  77. goodwill or for any indirect or consequential loss arising out of the use of
  78. the Software, or inability to use the Software, even if NCW has been advised
  79. of the possibility of such loss.
  80.  
  81. These conditions supersede any prior agreement, oral or written, between you
  82. and NCW relating to the Software.
  83.  
  84. You agree that except for written separate agreements between NCW and you,
  85. this agreement is a complete and exclusive statement of the rights and
  86. liabilities of the parties.
  87.  
  88. You acknowledge that you have read this agreement, that you understand this
  89. agreement, and by loading, running or copying the Software you agree to be
  90. bound by this agreement's terms and conditions.
  91.  
  92.  
  93. ¤ Introduction
  94. ==============
  95.  
  96. Director is a general purpose desktop tool.  It allows you to customise your
  97. desktop by creating menus of useful commands and icons to attach the menus
  98. to.  Any number of menus or icons can be created and attached in any order to
  99. each other.
  100.  
  101. Director also allows an alternative and faster view onto files in the form of
  102. directory menus and allows these menus to be attached to other menus also.
  103.  
  104. Director has some other useful features such as remembering the most recently
  105. used files, the ability to add key strokes into the keyboard buffer and the
  106. ability to produce directory menus over drive icons.
  107.  
  108. Director is fully customisable by the user, and can do many or all of the
  109. functions of Pinboard+, TreeMenu (AKA DirMenu), Filer-, QuickDir, DeskUtils,
  110. Memorizer, Menon and some of the functions of Filer+.
  111.  
  112. Director will only run on RISC OS 3.10 or later.
  113.  
  114.  
  115. ¤ Motivation
  116. ============
  117.  
  118. Director was initially conceived as a replacement for Pinboard+ (by Thomas
  119. Olsson).  For those of you who don't know, Pinboard+ is a replacement
  120. Pinboard module which allows user definable menus when clicking menu over the
  121. backdrop.
  122.  
  123. The initial design of Director was in order to overcome the fact that
  124. Pinboard+ needed a replacement pinboard module loaded (which did not work
  125. fully under RISCOS 3.5) and the fact that there was no easy way of specifying
  126. that you wanted the contents of a directory as a sub menu.
  127.  
  128. This then led on to the idea of incorporating the functions of TreeMenu (by
  129. Julian Smith) into Director.  This would then enable a directory tree listing
  130. to be attached to a menu at any point.
  131.  
  132. These ideas led onto Director being more of a general purpose program,
  133. merging several utilities into one compact package.
  134.  
  135. Memory usage was another of the main reasons for coding Director.  Here's a
  136. before and after on the memory front.
  137.  
  138. Before:
  139.  
  140. TreeMenu          65,536
  141. Pinboard+         18,812 (module)
  142.                   43,324 (menu)
  143. DeskUtils         32,768
  144. Memorizer         14,128
  145. ————————————————————————
  146. Total            174,568 Bytes
  147.  
  148. After:
  149.  
  150. Program code      18,672
  151. Workspace          3,600
  152. Heap              18,416 (119 blocks)
  153. ————————————————————————
  154. Total             40,688 Bytes
  155.  
  156. Thus giving a saving of 133,880 bytes or 130 kBytes!
  157.  
  158. Director will use a dynamic area if they are available.  (This has several
  159. advantages, the main one being less RMA fragmentation.)
  160.  
  161. Director also includes some ideas from Filer+ (by Jens H. Ovesen), Filer- (by
  162. Franz Philipps), and Memorizer (by Ben Summers).
  163.  
  164. Director is written entirely in ObjAsm assembler for its compactness and ease
  165. of making module tasks.
  166.  
  167. Although not all the ideas may have been my own, the coding is all mine
  168. (including all the bugs)!
  169.  
  170.  
  171. ¤ Switching from Pinboard+ to Director
  172. ======================================
  173.  
  174. If you run the ExpandMenu program in the Utils directory you can convert your
  175. old Pinboard+ menus into the new form expected by Director.  This is a
  176. textual form based on the Obey file and is a lot easier to maintain than a
  177. graphical form.  However if you prefer you can maintain your menus using the
  178. Pinboard+ menu designer and ExpandMenu, however some of the new features of
  179. Director will be unavailable to you.
  180.  
  181.  
  182. ¤ Switching from TreeMenu (or DirMenu) to Director
  183. ==================================================
  184.  
  185. Director has almost all the features of TreeMenu.  By default it will enable
  186. Directory menus over title bars of filer windows and other windows.  You may
  187. create icons as per TreeMenu also, see the section on Icons, and also the
  188. example Menus.
  189.  
  190.  
  191. ¤ Upgrading from Director 0.11 (first public release)
  192. =====================================================
  193.  
  194. The major change is Filters, so you will need to read that section.  You will
  195. also need to add the DirectorFilter commands at the start of the example menu
  196. to your own menu otherwise lots of things won't work.
  197.  
  198. A number of problems have been fixed and a number of new features
  199. introduced.  See the ChangeLog for full details.  But in brief
  200.  
  201.     Added    OpenFiles and Tasks dynamic menus
  202.     Changed    MenuMenu improving its speed and function
  203.     Fixed    Director + Filer Short cuts interaction
  204.     Fixed    "Please insert disc..." messages on Memoriser:
  205.     Fixed     (with work around) problems with CDFS
  206.     Added    lots of features to Memoriser:
  207.     Added    dynamic area support if available
  208.     Added    DirectorShowMenu to show a menu immediately
  209.     Added    -remove options to DirectorIcon and Menu
  210.     Added    colours and icon numbers to Menu.Aliases
  211.     Added    DirectorFilter for versatile desktop enhancements!
  212.     Added    Director_Enumerate & menus/icons/filters menus to main menu
  213.     Added    Director_Memory & menu to display the result
  214.     Removed    DirectorMemory and ListMenus as they are now redundant
  215.     Added    -dragto and dragfrom to DirectorIcon
  216.     Added    -file to DirectorMouseDir
  217.  
  218.  
  219. ¤ Menus
  220. =======
  221.  
  222. Menus are referred to by name (case insensitive), either by the text of the
  223. menu title or an alias as given by you.  There can only be one menu of any
  224. given name, and if you attempt to create a menu with the same name as an
  225. existing one then the existing menu will be deleted without warning.  This is
  226. useful because you can update your menus at any time you like, or even create
  227. new menus on the fly.
  228.  
  229. Director keeps a list of menus which you can see from Director's main menu. 
  230. Menus can be temporary or permanent.  Temporary menus are created by Director
  231. for making Directory Menus and then deleted afterwards.  Permanent Menus are
  232. created by you.
  233.  
  234. To create a menu you need to create an Obey file with the following format.
  235. (Indentation and spacing are generally unimportant.  The menus are described
  236. indented here to aid comprehension of the structure.)
  237.  
  238.     Menu ...
  239.         Option ...
  240.             Command ...
  241.         Option ...
  242.             Command ...
  243.     Dash
  244.         .
  245.         .
  246.         .
  247.         Option ...
  248.     EndMenu
  249.  
  250. The Menu command signals to Director to start a new Menu with the name and
  251. alias you give it.
  252.  
  253.     Syntax: Menu <title> [<alias>] [-key <key>] [-temp] [-remove]
  254.  
  255. Possible examples are,
  256.  
  257.     Menu "Mode"
  258.         Starts a menu with title and internal name both "Mode"
  259.     Menu Mode
  260.         Same as above.  In general if you want to supply a string
  261.         to a command, you can supply it with or without quotes.
  262.         However if the string has spaces in it it must be supplied
  263.         with quotes.
  264.     Menu "Lots of Modes" Mode
  265.         Starts a menu with title "Lots of Modes" and internal name
  266.         "Mode"
  267.     Menu "DDE" -key ^D
  268.         Starts a menu called DDE with internal name DDE to be opened
  269.         on a CTRL-D key press (see the section called Keys for more
  270.         on what is allowed as a parameter to -keys)
  271.     Menu "Temporary" -temp
  272.         This will make a menu which will be displayed only once and
  273.         then destroyed.  This is useful for dynamic menus, and for
  274.         menus displayed with DirectorShowMenu
  275.     Menu "DDE" -remove
  276.         This will remove from director's memory the menu called
  277.         "DDE".  This is useful for tidying up.  If the menu named
  278.         isn't found then it will not return an error
  279.  
  280. The EndMenu command signals to Director to stop making the menu.  The menu is
  281. available for display as soon as the Menu command has been issued though.
  282.  
  283.     Syntax: EndMenu
  284.  
  285. The Dash command writes a dashed line across the menu at that point in the
  286. menu structure.  It is useful for organising large menus.
  287.  
  288.     Syntax: Dash
  289.  
  290. The Option command is at the heart of Director's menus.  It has many options
  291. which you won't need immediately, but which may become useful later.
  292.  
  293.     Syntax: Option <text> | -path <file|directory>
  294.         [-tick]
  295.         [-bg <col>]
  296.         [-fg <col>]
  297.         [-sub [<menu>|*]]
  298.         [-len <len>]
  299.         [-dash]
  300.         [-grey]
  301.         [-key <number>]
  302.         [-up]
  303.         [-nosprite]
  304.         [-sprite <name>]
  305.  
  306. The Option command must be supplied with a text or a path or both.  For
  307. example
  308.  
  309.     Option "Mode 31"
  310.         Will produce a menu entry with the text "Mode 31" which could
  311.         have a command attached (see later).
  312.     Option -path ADFS::4.$.Apps
  313.         Will produce a menu entry with a directory icon in it and the
  314.         Apps directory attached.  If the Apps directory is not
  315.         present then it will produce a greyed out menu option with
  316.         an unknown file icon.  Director will use the leaf name of
  317.         the path for the text of the menu (in this case Apps) minus
  318.         an initial !.
  319.     Option "Applications" -path ADFS::4.$.Apps
  320.         As above except the text in the menu option will be
  321.         "Applications" rather than "Apps".
  322.  
  323. A text option may have a 0, 1 or 2 Commands attached (see later) or a
  324. SubMenu.
  325.  
  326.     Option "Modes" -sub "Modes"
  327.         This produces a menu entry with the text "Modes" and a right
  328.         pointing arrow.  When pointer moves over the arrow the Menu
  329.         "Modes" will be opened as a sub menu.  If the user clicks on
  330.         the item (or uses a hotkey) the "Modes" menu will be opened
  331.         as the root menu.
  332.     Option "Modes" -sub *
  333.         This is equivalent to the Option above.  It is quite common
  334.         to have a SubMenu with the same name as the Option which
  335.         activates it, so this is shorthand for that.
  336.  
  337. A menu option may be activated by a key, eg
  338.  
  339.     Option -path ADFS::4.$.Apps -key ^A
  340.         Opens the Apps directory on CTRL-A
  341.     Option "Modes" -sub * -key M
  342.         Opens the modes SubMenu (if no command attached) or does the
  343.         attached command if M is pressed.
  344.     Option "Command" -key ⇧^Z
  345.         If a command is attached then it does it on SHIFT-CTRL-Z
  346.         otherwise it does nothing.
  347.  
  348. A menu option may have its foreground and background colours defined (see the
  349. section on colours for details of which numbers make which colours).  If the
  350. colours are not defined then they default foreground Black and background
  351. White.
  352.  
  353.     Option "Format" -fg 11
  354.         Produces Red text on the default background
  355.     Option "Boot" -fg 0 -bg 8
  356.         Produces White text on a Dark Blue background
  357.  
  358. Any menu can be made writable by including a -len option.  The parameter to
  359. len is the maximum length of the string writable into the icon.  When the
  360. item is selected the text is written into the system variable <MenuText>
  361. which can be used in commands.  In fact <MenuText> is written for
  362. non-writable items and when creating a submenu too.
  363.  
  364.     Option "13" -len 3
  365.         Might be used for typing in a mode number of maximum length 3
  366.         characters.  The command attached would then use <MenuText>
  367.         to set the actual mode.  The string "13" is the default text.
  368.     Option "" -len 200
  369.         Might be used by a general purpose command (eg the New Task
  370.         option in the TaskManager).  The default string is empty.
  371.         It must be supplied though or Director will complain.
  372.  
  373. -tick Ticks the menu item (useful for when you have 2 attached commands, this
  374. provides the initial ticked state).
  375.  
  376. -dash Writes a dash under the menu item.  This is equivalent to the Dash
  377. command.
  378.  
  379. -grey Makes the menu entry grey and unselectable.  Useful occasionally.
  380.  
  381. -up Makes -path have the directories above the path (Up Menus - see Directory
  382. Menus section) in the menu.  If -up is applied to a file then it will have a
  383. submenu arrow.
  384.  
  385. -nosprite Stops a sprite appearing in a -path menu.  It also stops the menu
  386. entry being greyed out if the path did not exist.
  387.  
  388. -sprite adds the named sprite into the menu entry.  The sprite must be the
  389. correct size (the same size as small filer icons).  If it is not found it is
  390. replaced with a file_xxx sprite (a blank white square).
  391.  
  392. The Command command is for attaching commands to menu options.  Only text
  393. type menu options (ie not -path options) may have Commands attached.  You may
  394. have both SubMenus and commands attached to a menu option.
  395.  
  396.     Syntax: Command <*command>
  397.  
  398. For example
  399.  
  400.     Option "Mode 13"
  401.         Command WimpMode 13
  402.             Sets Mode 13 when clicked on
  403.     Option "13" -len 3
  404.         Command WimpMode <MenuText>
  405.             Sets the mode typed in when clicked on
  406.     Option "" -len 200
  407.         Command <MenuText>
  408.             Runs the command typed in when clicked on.
  409.  
  410. A menu option may have two commands attached.  Which command is run depends
  411. upon the ticked state of the option.
  412.  
  413. For example
  414.  
  415.     Option "A"
  416.         Command FontInstall Fonts:!A.
  417.         Command FontRemove Fonts:!A.
  418.  
  419. When this it not ticked then the first command will be run.  This will
  420. install the fonts in !A and to show that they have been installed the menu
  421. option will be ticked.  To remove the fonts the option is clicked again and
  422. the second command is run, removing the fonts, and returning the menu to the
  423. non-ticked state.
  424.  
  425. Commands are GSTransed before being run (see the section on GSTrans for more
  426. info) as a WimpTask.  Running commands as a WimpTask means that they don't
  427. interfere with Director, however if the command produces an error, an
  428. anonymous error box is produced.
  429.  
  430. This also means that multiple OS commands can be put on one line by
  431. separating them with |M.  For example
  432.  
  433.     Option "Reset SysFont"
  434.         Command fx 20|MSWI Wimp_CommandWindow -1
  435.  
  436. Which resets the system font with *FX 20 and then redraws the screen with the
  437. SWI Wimp_CommandWindow.
  438.  
  439.  
  440. ¤ Showing a Menu
  441. ================
  442.  
  443. A menu can be shown immediately with the command
  444.  
  445.     DirectorShowMenu <menu_name>
  446.  
  447. This will open the menu named immediately.  You can make obey files which
  448. define menus and then open them immediately with this command.  If you add
  449. -temp to the menu then it will be deleted after it has been shown.
  450.  
  451.  
  452. ¤ System Variables
  453. ==================
  454.  
  455. These system variables are set whenever a path sub menu is opened or a path
  456. item is chosen
  457.  
  458.     Director$CurrentPath
  459.         full path of object
  460.     Director$CurrentDir
  461.         directory object lives in
  462.     Director$CurrentLeaf
  463.         leaf name of object
  464.     
  465. If the object is a root directory (eg ADFS::4.$ or Root:) then CurrentPath =
  466. CurrentDir = CurrentLeaf
  467.  
  468.  
  469. The last Command that was run can be seen in the system variable
  470.  
  471.     Alias$DirectorRun
  472.  
  473. So issue *Show Alias$DirectorRun at the command line to see what it was.
  474.  
  475.  
  476. Whenever a text option is chosen
  477.  
  478.     MenuText
  479.  
  480. Is set to the text of that option
  481.  
  482.  
  483. Whenever menu is clicked over the File 'xxx' option in a Filer Menu
  484.  
  485.     Leaf
  486.  
  487. is set to the leaf name of the file ("xxx" in this case).
  488.  
  489.  
  490. ¤ GSTrans
  491. =========
  492.  
  493. If you are uncertain what GSTrans is, look it up in the index of your user
  494. guide.  The few pages referenced will teach you the basics (I won't attempt
  495. to explain them here).
  496.  
  497. As a rule every string parameter passed to Director is GSTransed when it is
  498. parsed.  This means that
  499.  
  500.     Option -path <Wimp$Scrap>
  501.  
  502. Will be GSTransed into (something like)
  503.  
  504.     Option -path ADFS::HardDisc4.$.!Boot.!Scrap.ScrapDirs.ScrapFile
  505.  
  506. Which means that if Wimp$Scrap changes, the option won't be looking in the
  507. right place.  The menu text will read "ScrapFile".  Better is
  508.  
  509.     Option -path |<Wimp$Scrap>
  510.  
  511. Which GSTranses into
  512.  
  513.     Option -path <Wimp$Scrap>
  514.  
  515. which is what you want.  The menu text will read "<Wimp$Scrap>".  Probably
  516. best (for this use) is
  517.  
  518.     Option "Scrap" -path |<Wimp$Scrap>
  519.  
  520. Which has the menu text "Scrap" but is otherwise identical to the one above.
  521.  
  522. The only strings which don't get GSTransed on their way into Director are the
  523. parameters to Command.  These are GSTransed just before being run.
  524.  
  525.     Option "13" -len 3
  526.         Command WimpMode <MenuText>
  527.  
  528. The above command will only be GSTransed when it is run with the actual value
  529. of MenuText, not the value of MenuText when the command was installed.
  530.  
  531.     Option "Open App"
  532.         Command Filer_OpenDir <Obey$Dir>
  533.     Option "Open App"
  534.         Command Filer_OpenDir |<Obey$Dir>
  535.  
  536. These two commands in practice do the same thing.  This is because in the
  537. first Command the <Obey$Dir> is GSTransed (when the Command is being
  538. prepared) to the proper path which is then passed to Filer_OpenDir.  In the
  539. second case |<Obey$Dir> is GSTransed to <Obey$Dir> and passed to
  540. Filer_OpenDir.  Filer_OpenDir GSTranses the argument and comes up with the
  541. same answer.
  542.  
  543. If the commands had been Filer_Run in the above example then they would have
  544. done two different things.  The first would have worked (running the
  545. application) and the second would not because Filer_Run does not GSTrans its
  546. input.  (In fact the second command would have opened a directory onto the
  547. application for some obscure reason, with the Filer title set to <Obey$Dir>
  548. which should not normally be allowed.)
  549.  
  550.  
  551. ¤ Special forms of Menus and Commands
  552. =====================================
  553.  
  554. Whenever a Menu, SubMenu or Command is specified it may take one of several
  555. special forms.  These enable Director to be much more general, running
  556. commands instead of opening a sub menu or vice versa.  It also means that
  557. Commands can be attached to clicks on icons as well as menus.
  558.  
  559. When a Menu, SubMenu or Command is being processed, it is first checked to
  560. see if it is prefixed in one of the ways below.  If it is then its action is
  561. modified.
  562.  
  563. "Text"        For normal command or sub-menu (ie action unchanged)
  564.  
  565. "Menu:Name"    To bring up named menu
  566.  
  567. "Save:Path"    For save box of the given Path (*)
  568.  
  569. "Path:Path"    For a directory menu of that Path (*)
  570.  
  571. "Command:Text"    Runs the Text as if it were a command
  572.  
  573. "Quit:"        Quits Director
  574.  
  575. "Info:"        Brings up Director's info window
  576.  
  577. "OldMenu:"    To open the last filtered menu (for getting pinboard menu)
  578.  
  579. "MenuMenu:Path"    Takes Path, adds .<leaf> to it and opens the MenuMenu
  580.         pointing at that file.  Used internally. (*)
  581.  
  582. "Memoriser:"    Opens a menu of recently used files.
  583.         (See Memoriser section.)
  584.  
  585. "Dynamic:Text"    Runs the Text as if it were a command.  When the command
  586.         returns Director tries to open the menu whose name is in
  587.         the system variable Director$Menu.
  588.  
  589. "GSTrans:Text"    GSTranses the Text and then reinterprets it as an extended
  590.         command.
  591.  
  592. (*) If the path is missing eg "Path:" or "Save:" then it will use the path of
  593. the window that the pointer is over.  If the path is present it is GS_Transed
  594. before use.
  595.  
  596. For example
  597.  
  598.     Option "Floppy" -sub "Path:ADFS::0.$"
  599.  
  600. This will make a directory menu of the floppy disc drive if you click on the
  601. option or move the pointer over the SubMenu.  This is better than
  602.  
  603.     Option "Floppy" -path ADFS::0.$
  604.  
  605. because this will produce a greyed out path with an unknown file icon if the
  606. floppy is empty when the Option is run.
  607.  
  608.     Option "Root" -sub "Command:Filer_OpenDir ADFS::4.$"
  609.  
  610. This will open a filer window of your root directory if you click on the
  611. option or move the pointer over the SubMenu.
  612.  
  613.     Option "Pinboard" -sub "OldMenu:"
  614.  
  615. This will open the menu that should have been opened when you clicked the
  616. pointer.  So if you opened the menu over the pinboard, but wanted to see the
  617. pinboard menu then you could click or slide this option.
  618.  
  619.     Option Here -sub "Path:<Director$CurrentDir>"
  620.     Option Copy -sub "Save:<Director$CurrentPath>"
  621.  
  622. These options are useful for the MenuMenu (see the section titled MenuMenu
  623. and the section titled SaveBox).
  624.  
  625.     Option Info -sub Info:
  626.     Option Quit
  627.         Command Quit:
  628.  
  629. Helps bring an air of normality to Director by providing the standard Quit
  630. and Info choices!
  631.  
  632.  
  633. ¤ Memoriser
  634. ===========
  635.  
  636. Director notices whenever you load a file or click on a drive and keeps a
  637. record of the fact.
  638.  
  639. If you then ask for the menu Memoriser: to be opened then you will get a menu
  640. with these files or directories in it.
  641.  
  642. This acts exactly like a normal directory Menu, except it has all your most
  643. recently used files/directories in it.
  644.  
  645. This is exceedingly useful when you traverse a large directory tree, open a
  646. file to have a look at it, close it, and then realise that you want to see
  647. the file again.  All you have to do is open the Memoriser menu and it will be
  648. there sitting at the top.  If in the mean time you have deleted the file then
  649. it will not be shown in the menu.
  650.  
  651. It is possible to make the memoriser display only applications, directories
  652. or files by adding a numeric parameter after the Memoriser:
  653.  
  654.     Memoriser:1 - memoriser shows applications
  655.     Memoriser:2 - memoriser shows directories and images
  656.     Memoriser:4 - memoriser shows files
  657.  
  658. The parameters can be combined in a linear fashion, eg Memoriser:6 shows
  659. directories, images and applications but not files.
  660.  
  661. The total number of items that are kept in the Memoriser menu is definable
  662. with the command
  663.  
  664.     Syntax: MemoriserItems <number>
  665.  
  666. This will not affect the currently built up number of items.  If you set it
  667. to 0 then no more items will be added to the menu.  This effectively turns
  668. the feature off.  0 is the default value.
  669.  
  670. You can save and restore the memoriser with
  671.  
  672.     MemoriserSave <file>
  673.     MemoriserLoad <file>
  674.  
  675. This will save the contents of the memoriser or replace it with that in the
  676. file.  The file is a simple text file with a file path on each line.  You
  677. could use this to prime the memoriser with often used files or to save and
  678. restore it.
  679.  
  680.  
  681. ¤ MenuMenu
  682. ==========
  683.  
  684. A menu with name defined by the system variable Director$MenuMenu (defined by
  685. you) is opened whenever you click Menu on a path item or click Menu on the
  686. second option in a Filer Menu (the one that reads "File '!Run'" or
  687. "Selection") provided one and only one file is selected in the Filer window.
  688.  
  689. This menu deals with files and directories.  You should put on it things
  690. which you want to do to files.
  691.  
  692. Here is an example of a MenuMenu
  693.  
  694. Set Director$MenuMenu MenuMenu
  695.  
  696. Menu "File Menu" "MenuMenu"
  697.     Option Here -sub "Path:|<Director$CurrentDir>"
  698.  
  699. This allows you to see a directory Menu of where the selected file or
  700. directory is.  (See the section on GSTrans for the reason behind the | in the
  701. -sub string.)
  702.  
  703.     Option Copy -sub "Save:|<Director$CurrentPath>"
  704.  
  705. This allows the current file or directory to be copied to a filer window,
  706. dragged to an application or pinned to the pinboard (drag the icon onto the
  707. pinboard).
  708.  
  709.     Option "Set CSD"
  710.         Command Dir <Director$CurrentDir>
  711.  
  712. Sets the Current Directory to the directory in which the file or directory
  713. was found.
  714.  
  715.     Option "Open Directory"
  716.         Command Filer_OpenDir <Director$CurrentDir>
  717.  
  718. This opens a Filer Window onto the directory in which the file or directory
  719. was found.
  720.  
  721.     Option "Filer_Run"
  722.         Command Filer_Run <Director$CurrentPath>
  723.  
  724. This is equivalent to double clicking on the File or Directory.
  725.  
  726.     Option "Pin"
  727.         Command SWI OS_Mouse TO x y|M
  728.             Pin <Director$CurrentPath> |<x>-90 |<y>+45
  729.  
  730. This pins the file or Directory to the pinboard. (The command should be
  731. written all on one line).  It uses the SWI Module to read the current
  732. position of the mouse and then pins the centre of the icon there.  (Note the
  733. |<x>, this is GSTransed to at run time <x> when the Command is being
  734. prepared, which is then GSTransed to the mouse x co-ordinate when the Pin
  735. command is run.)
  736.  
  737.     Option "IconSprites"
  738.         Command IconSprites <Director$CurrentPath>
  739.  
  740. This IconSprites the file or directory.  (Only really useful over a sprite
  741. file.)
  742.  
  743. EndMenu
  744.  
  745. There are many other possibilities for the MenuMenu, such as SetType,
  746. ToolSprites, Delete, Wipe, Access etc.  A MenuMenu is perhaps best defined as
  747. a dynamic Menu.
  748.  
  749.  
  750. ¤ Pinboard
  751. ==========
  752.  
  753. A menu of this name (defined by you) is opened whenever you click Menu on the
  754. pinboard backdrop or on a TinyDirs icon.
  755.  
  756. If the pinboard module isn't loaded or running, no error is produced, but
  757. none of the things in this section will work.
  758.  
  759. If you want to use the Pinboard's menu then you can press any of SHIFT, CTRL,
  760. ALT when clicking Menu and the old Menu will appear.
  761.  
  762. Alternatively on your Pinboard menu you can have an option
  763.  
  764.     Option Pinboard -sub OldMenu:
  765.  
  766. Which when clicked on or slid over will open the menu that would have been
  767. opened if Pinboard had been left to its own devices.  It will also move the
  768. pointer to be in the correct place.
  769.  
  770. (I debated long and hard about moving the pointer (which I dislike), but
  771. decided this was the least confusing option.  Try it for yourself!)
  772.  
  773.  
  774. ¤ SaveBox
  775. =========
  776.  
  777. Read the section on special forms of Menus and commands if you haven't
  778. already done so.
  779.  
  780. The SaveBox is not like a true SaveBox it is more like a miniature Filer
  781. window (except you can't (yet) double click on the icon).
  782.  
  783. You may drag the icon from a SaveBox to an application (equivalent to
  784. dragging it from the Filer) the pinboard (ditto) or a Filer window, which
  785. will copy the File in the way you have configured (possibly bringing up a
  786. Filer Action window etc).
  787.  
  788. You may also drag files to the SaveBox from the pinboard or Filer and it will
  789. update to show the file you dragged.
  790.  
  791. There is only one SaveBox and if you try to open it twice the first one
  792. disappears/changes into the new file/directory.
  793.  
  794.  
  795. ¤ Keys
  796. ======
  797.  
  798. Any Menu or Menu Option can have a hot key assigned.
  799.  
  800. A hot key assigned to a menu (in the Menu command) will open the Menu when
  801. used and a hot key assigned to a Menu Option will be equivalent to clicking
  802. with select on a Menu Option when used.
  803.  
  804. Keys are added by name and possibly with a modifier.
  805.  
  806. A single letter key refers to that key eg -key M or -key 8.  Keys are case
  807. insensitive (and independent of CapsLock) so -key m is equivalent to -key M.
  808.  
  809. Some keys are referred to by name (case insensitive), and these are
  810.  
  811.     Home, Return, Ret, Enter, Backspace, BkSp, Space, Delete,
  812.     Del, Esc, Print, Pnt, F1, F2, F3, F4, F5, F6, F7, F8, F9,
  813.     Tab, Copy, Cpy, End, Left, Right, Down, Up, PageDown, PgDn,
  814.     PageUp, PgUp, F10, F11, F12, Insert, Ins
  815.  
  816. Some of them are named twice for your convenience.  So -key F1, -key f1 or
  817. -Key Insert would be valid.
  818.  
  819. Possible modifiers are
  820.  
  821.     ⇧    SHIFT
  822.     ^     CTRL
  823.     ~     ALT
  824.  
  825. (To get the ⇧ symbol, hold down ALT, type 139 on the numeric keypad and
  826. release ALT.  Alternatively map character 139 to a key in your favourite
  827. editor (CTRL-6 is a good mapping).)
  828.  
  829. These can be added (in any order) before a key name, indicating that you have
  830. to press the modifier keys indicated with the main key in order to activate
  831. the hot key.  eg
  832.  
  833.     ^M        CTRL-M
  834.     ⇧A        SHIFT-A
  835.     ^⇧F1 = ⇧^F1    SHIFT-CTRL-F1
  836.  
  837. Note that -key ⇧A = -key ⇧a which is not equal to -key A = -key a.
  838.  
  839. Some key combinations don't work, eg
  840.  
  841.     CTRL Number keys don't work, CTRL KeyPad numbers should
  842.     No keys work with ALT!
  843.  
  844. These may be fixed in a future release!
  845.  
  846. If an Option or a Menu has a key definition it is added to the text/title
  847. with a space before it.  If you want the items to line up then you will have
  848. to add spaces after the text/title.  RISCOS 3.5 will line them up for you
  849. provided the key definitions starts with ^ or ⇧ or is one of the long form
  850. named keys above.
  851.  
  852.  
  853. ¤ Colours
  854. =========
  855.  
  856. Any colours in Director are specified numerically from the 16 Wimp colours. 
  857. These colours can be seen by clicking on the Palette icon (supplied with
  858. versions of RISCOS < 3.5).  The numbers of each colour are given below.
  859.  
  860. White    0    Grey4    4    Blue    8    Cream    12
  861. Grey1    1    Grey5    5    Yellow    9    Khaki    13
  862. Grey2    2    Grey6    6    Green    10    Orange    14
  863. Grey3    3    Black    7    Red    11    Cyan    15
  864.  
  865. These names are defined in the file Director:Library.!Core and are defined by
  866. default so you may use these names wherever a colour is needed, eg
  867.  
  868.     Option "Unreadable" -bg Red -fg Khaki
  869.  
  870.  
  871. ¤ Dynamic Menus
  872. ===============
  873.  
  874. These are menus that are created just before the menu is opened rather than
  875. when you run Director.
  876.  
  877. They are used from an extended menu "Dynamic:Filename".  When this command is
  878. run the file or command "Filename" is run.  When the command or file finishes
  879. executing Director will try to open the menu whose name is in the system
  880. variable Director$Menu.
  881.  
  882. A simple example of a dynamic menu would be this
  883.  
  884.     Option "Time" -sub "Dynamic:DirectorObey Director:Menus.Time"
  885.  
  886. This will run the command "DirectorObey Director:Menus.Time" when this menu
  887. option is run.  The contents this file might be
  888.  
  889.     Menu "" Time -temp
  890.         Option "**The Time Was**" -fg 11
  891.         Option "   <Sys$Time>   "
  892.         Option "<Sys$Date> <Sys$Year>"
  893.     EndMenu
  894.  
  895.     Set Director$Menu Time
  896.  
  897. This creates a temporary menu called Time with the current time and date in
  898. it and returns the string "Time" in Director$Menu for Director to use as the
  899. name of a menu to open.
  900.  
  901. Because the menu was created as a temporary menu it will be deleted once it
  902. has been displayed to conserve memory (since it is rebuilt each time it is
  903. needed).
  904.  
  905. Dynamic menus are very useful for displaying lists of things that could vary
  906. whilst Director is running (such as modules or filetypes).  A few examples of
  907. dynamic menus are provided in the Menus directory inside Director.
  908.  
  909. It would be possible to simulate most of the other features of Director using
  910. dynamic menus, however in their current implementation they require a disc
  911. access per use.  It would be possible to register the dynamic menu files in
  912. the resource filing system to avoid this and maybe a future version of
  913. Director will do this for you.
  914.  
  915. Dynamic menus set Director$Window and Director$Icon to the window handle and
  916. icon number that the request was over respectively.  This is useful for more
  917. advanced menus like the CloseBox menu example.
  918.  
  919.  
  920. ¤ Icons
  921. =======
  922.  
  923. Icons are created in a similar way to menus.  Each one must be named (case
  924. insensitive) by its sprite name or an alias name provided by you and there
  925. can only be one of each name.  If you create an icon with the name of an
  926. already existing one then the existing icon will be deleted without warning
  927. and the new one created.
  928.  
  929. You may attach menus for Select, Adjust and Menu for the icon.  Remember that
  930. the menus can also be commands (see the section on Special forms of Menus and
  931. Commands)
  932.  
  933. This creates a new icon bar icon with attached menus. The icon is referred to
  934. by the name of its sprite or the alias name if supplied.
  935.  
  936.     Syntax: *DirectorIcon
  937.         <sprite>
  938.             Name of the sprite, must be provided and exist in the
  939.             Wimp sprite pool
  940.         [-alias <name>]
  941.             Internal name of the Icon.  If this is not supplied
  942.             then the icon is referred to by its sprite name.
  943.         [-text <text>]
  944.             Text to go under the Icon.  Optional.  If the -time
  945.             option is used then this Text defines the length of
  946.             the time string.
  947.         [-left|-right]
  948.             Whether the icon goes on the left of the Icon bar or
  949.             the right.  If omitted will default to -left.
  950.         [-priority <priority>]
  951.             This controls the positioning of the icon.  Larger
  952.             numbers are to the outside of the icon bar. Range
  953.             from 0 (inside) - &7FFFFFFF (outside).  Experiment to
  954.             see where your icons gets placed or look at 3-98 in
  955.             the RISCOS 3 PRMs.
  956.         [-time <format>]
  957.             This makes the text under the icon be interpreted as
  958.             a time, which is updated once per second.  The
  959.             length of the time is set by the -text option which
  960.             must be given a string which is as long as the
  961.             longest time string, and preferably of the same
  962.             format, eg 00:00 for %24:%mi.  See the Applications
  963.             Guide, under !Alarm, "Time and date formats" for
  964.             more details or the RISCOS 3 PRMs 1-402.
  965.         [-menu <menu>]
  966.         [-select <menu>]
  967.         [-adjust <menu>]
  968.             These allow you to attach menus or commands to the 3
  969.             mouse buttons.
  970.         [-dragto <menu>]
  971.             This specifies a menu to be run when a file is
  972.             dragged onto the icon.    The path of the object
  973.             dragged can be found from Director$CurrentPath …Leaf
  974.             and …Dir.
  975.         [-dragfrom <path>|*<menu>]
  976.             This either takes a path which then acts exactly like
  977.             the SaveBox or takes a menu preceded by * which will
  978.             be run with Director$CurrentPath …Leaf and …Dir set
  979.             up.
  980.         [-remove]
  981.             If this is specified then the icon named is removed
  982.             rather than created.
  983.  
  984. For example (these should be typed in on 1 line, but have been split for
  985. clarity)
  986.  
  987.     DirectorIcon romapps Apps -left -priority &50000000
  988.         -menu "Path:Resources:$"
  989.         -select "Command:Filer_OpenDir Resources:$.Apps"
  990.         -adjust Pinboard
  991.  
  992. This provides a replacement Apps icon which has the Pinboard menu on Adjust,
  993. does the normal thing on select, and on menu (which would normally say
  994. "Open $") produce a directory menu of the whole of Resources which is usually
  995. much more useful.
  996.  
  997.     DirectorIcon !Director "00:00:00" -left -priority &0E000000
  998.         -menu IconMenu
  999.         -select IconClick
  1000.         -adjust Pinboard
  1001.         -time <37>24:%MI:%SE
  1002.  
  1003. This produces an icon with Director's own icon, the current time in 24 hour
  1004. format and 3 menus, IconClick, IconMenu and Pinboard.
  1005.  
  1006. [NB <37> GSTranses to %.  This odd looking construction is necessary because
  1007. %2 refers to the second argument supplied (when Obeying the file, not in
  1008. DirectorObey).  Since no arguments were supplied then the time string is
  1009. converted to 4:%MI:%SE which is not what was required!  <37> is used rather
  1010. than %% so the file will work with Obey and DirectorObey]
  1011.  
  1012.     DirectorIcon trashcan -left
  1013.         -dragto "Command:Wipe |<Director$CurrentPath> ~CFR~V"
  1014.  
  1015. This will create a trash can icon which will delete all the items dragged
  1016. onto it.
  1017.  
  1018.     DirectorIcon directory -left
  1019.         -dragfrom "*Command:Dir |<Director$CurrentPath>"
  1020.  
  1021. This when you drag the directory icon from the icon bar to a filer window
  1022. then it will set the current directory.
  1023.  
  1024.     DirectorIcon file_fff Text
  1025.         -select "Filer_Run $.Text"
  1026.         -dragfrom "$.Text"
  1027.  
  1028. This will make an icon which works quite like a TinyDir but for one file
  1029. $.Text.  You can drag the icon to copy the file or put it into a document and
  1030. click on the icon to run the file (in the case of a text file load it into a
  1031. text editor).
  1032.  
  1033.  
  1034. ¤ Directory Menus
  1035. =================
  1036.  
  1037. Directory menus are automatically created and destroyed by Director when you
  1038. click with Menu on the title bar of a Filer or other window with a valid path
  1039. in it (eg an Edit window) in the default set up.  They are also produced by
  1040. -path "directory" or Command "Path:Directory" etc.
  1041.  
  1042. A menu will appear with all the files that are in the directory in it.  It is
  1043. intended to be complementary to the Filer, quicker to use, but not as
  1044. powerful.
  1045.  
  1046. Each item in the menu has the name of a file or directory and its icon.  This
  1047. is very similar to a filer window with sort by name, small icons and adjusted
  1048. to be tall and thin.
  1049.  
  1050. Items in the menu that are directories (or image files) will have a SubMenu
  1051. arrow by them.  You may traverse this arrow to see the next directory down.
  1052.  
  1053. Clicking with Select or Adjust is equivalent to double clicking the file in a
  1054. filer window.
  1055.  
  1056. Clicking with Menu over an Item will bring up the MenuMenu (see that section
  1057. for more details).  If a MenuMenu is not defined then it will do nothing.
  1058.  
  1059. Directory menus come in 2 flavours, with and without "Up Menus".  Up Menus
  1060. are the directories above the dotted line.  These show the directories up to
  1061. the root from where you are now.  The first item above the dotted line never
  1062. has a sub-menu because the item or the contents of that item are always
  1063. visible.
  1064.  
  1065. A directory menu made by "Path:" has Up Menus (eg the ones produced by
  1066. clicking Menu over a title bar).  A directory menu made by -path does not
  1067. have Up Menus by default unless you use the -up switch.
  1068.  
  1069.  
  1070. ¤ Filters
  1071. =========
  1072.  
  1073. Filters are a powerful way to change the appearance of your desktop.  You may
  1074. add new menus or commands to existing desktop features without having to
  1075. patch anything.  For instance you could add a new menu onto the task switcher
  1076. icon or cause menu over any close icon to come up with a menu.
  1077.  
  1078. Filters are referred to by name (case insensitive) as supplied in the
  1079. command.  There can only be one filter of any given name, and if you attempt
  1080. to create a filter with the same name as an existing one then the existing
  1081. filter will be deleted without warning.
  1082.  
  1083.     DirectorFilter <name> <task> <menu>
  1084.         [-icon <n>]
  1085.         [-select] [-menu] [-adjust]
  1086.         [-shift] [-ctrl] [-alt]
  1087.         [-remove]
  1088.  
  1089. <name> is the name of the filter to be defined
  1090.  
  1091. <task> is the name of the task to filter on or * for all tasks.  This task
  1092. does not not have to be running when the command is executed and director
  1093. will keep track of the task if it is shut down and re-started.
  1094.  
  1095. <menu> is the menu (or command) to be executed by the filter
  1096.  
  1097. -icon <n> defines an icon number for the filter to execute.  If this number
  1098. is >= 0 then it will define a normal icon (load the template of the window
  1099. you are interested in into a template editor to discover the icon number or
  1100. use trial and error).  The file Director:Menus.Aliases contains names for a
  1101. number special icons which are probably more useful
  1102.  
  1103. WorkArea        - background of a window with no icons
  1104. BackIcon        - back icon in the top left of a window
  1105. CloseIcon        - close icon in the top left of a window
  1106. TitleBar        - title bar at the top of a window
  1107. ToggleSizeIcon        - toggle size icon at the top right of a window
  1108. ScrollUpArrow        - scroll up arrow
  1109. VerticalScrollBar    - vertical scroll bar
  1110. ScrollDownArrow        - scroll down arrow
  1111. AdjustSizeIcon        - adjust size icon at the bottom right of a window
  1112. ScrollLeftArrow        - scroll left arrow
  1113. HorizontalScrollBar    - horizontal scroll bar
  1114. ScrollRightArrow    - scroll right arrow
  1115. OuterWindowFrame    - outer frame of the window (1 pixel wide)
  1116. IconBar            - an icon bar icon only
  1117.  
  1118. -select -menu -adjust -shift -ctrl -alt are the conditions in which the
  1119. filter executes.  The button named must be down for the command to execute. 
  1120. They may be used in any combination and are exclusive (ie -shift -adjust will
  1121. only execute if SHIFT and ADJUST are pressed and not if SHIFT ALT ADJUST are
  1122. pressed ).
  1123.  
  1124. -remove removes a filter from director's memory and stops it executing.
  1125.  
  1126. Examples (these have been split over lines for readability but should be
  1127. entered on one line)
  1128.  
  1129.     DirectorFilter "Title Bar Directory" * Path: -icon TitleBar -menu
  1130.         This filter makes a directory menu when you press menu over
  1131.         the title bar of any window.
  1132.     DirectorFilter "Alt Menu Directory" Filer Path: -menu -alt
  1133.         This filter makes a directory menu when you press ALT MENU
  1134.         over a filer window
  1135.     DirectorFilter "Pinboard" Pinboard Pinboard -icon WorkArea -menu
  1136.         This opens a menu called pinboard when menu is pressed over
  1137.         the work area of the pinboard.  If you press menu over an
  1138.         icon on the pinboard then you will get the pinboard menu.
  1139.     DirectorFilter "Close Icon" *
  1140.         "Dynamic:DirectorObey Director:Menus.System.Close"
  1141.         -icon CloseIcon -menu
  1142.         This makes a menu appear when you press menu over any close
  1143.         box.  The menu is a dynamic menu because it adjusts itself to
  1144.         the window it was used over using  Director$Window and
  1145.         Director$Icon.
  1146.     DirectorFilter "Display Manager Adjust" "Display Manager" "Mode"
  1147.         -icon IconBar -adjust
  1148.         This adds an extra menu to the display manager icon bar icon
  1149.         when it is clicked with adjust.
  1150.     DirectorFilter "Task Manager Adjust" "Task Manager"
  1151.         "Dynamic:DirectorObey Director:Menus.System.Time"
  1152.         -icon IconBar -adjust
  1153.         This shows the time when adjust is clicked over the switcher
  1154.         icon
  1155.  
  1156. You may attach the original action of the filtered object by including
  1157. OldMenu: as an option in the filter menu.
  1158.  
  1159.  
  1160. ¤ Other Features
  1161. ================
  1162.  
  1163. If you do an Adjust click on a drive icon on the icon bar it should open a
  1164. Directory Menu rather than a Filer window.  Works for ADFS, Acorn SCSI, MOFS,
  1165. RAMFS, Memphis, CFS, CDFS, ICS’s IDEFS and Resources.  It will work for other
  1166. filing systems provided they have been written in the way suggested in the
  1167. PRMs!
  1168.  
  1169.  
  1170. ¤ Other Commands
  1171. ================
  1172.  
  1173.     Syntax: *DirectorObey <file> [-verbose]
  1174.  
  1175. This command is equivalent to *Obey except it searches for Director *commands
  1176. with high priority.  Obey is quite slow when processing lots of commands so
  1177. this speeds up loading a file with lots of Director commands in it. 
  1178. DirectorObey cut the loading time of a 14k menu from 5.2 seconds (with Obey)
  1179. to 0.75 seconds, ie a speed up of nearly 7 times!
  1180.  
  1181. It should be exactly equivalent to Obey, excepting the fact that it doesn't
  1182. substitute arguments (eg %0 and %%).  This means you have to be a bit careful
  1183. with %'s if you want your menus to work with Obey and DirectorObey.  (See the
  1184. Icons section about -time for an example.) The -verbose or -v option is
  1185. useful for debugging.
  1186.  
  1187.     Syntax: *MenuProcessing <On|Off|1|0|Yes|No>
  1188.  
  1189. This stops and restarts the processing of Menu, EndMenu, Option, Command and
  1190. Dash (ie all the menu commands).  This is so that you can comment out bits of
  1191. your menus.  For example if the machine you are running the menu on has no
  1192. SCSI card installed then there is no point having the SCSI menus installed
  1193. and you could check for this at menu load time.
  1194.  
  1195.     Syntax: *DirectorDo <command>
  1196.  
  1197. This GSTrans the command line and then runs it.  This is useful for commands
  1198. such as Filer_Run which don't GSTrans their input, but you want to give a
  1199. string with a system variable in it.  You can also run a command from a
  1200. system variable with this command.
  1201.  
  1202.     Syntax: *ProcessKeys [[⇧][^]<key>|"<string>"]^
  1203.  
  1204. This sends the parameters to the current input focus, or hot key grabber.  It
  1205. should work outside the Wimp, provided the keys are mapped as in the Wimp. 
  1206. It takes a space separated list of either strings to be put into the keyboard
  1207. buffer or key descriptions (see Keys section). You can of course map these
  1208. onto keys for hot key actions.  For example
  1209.  
  1210.     ProcessKeys "Modules" Return
  1211.     ProcessKeys F6 ^Left Down F6 ^Up ^V
  1212.     ProcessKeys "Show Obey$Dir" ^M
  1213.     ProcessKeys "42 Solution Road" ^M "Toytown" ^M "Shireshire" ^M
  1214.     ProcessKeys TAB "Option -path "
  1215.  
  1216. A chars menu could be provided using this, or a menu of frequently used
  1217. commands for command based application.
  1218.  
  1219.     Syntax: *DirectorEdit <file>
  1220.  
  1221. This loads the file given into an text editor (if one is loaded).  It is
  1222. useful for transferring files that are not type Text to an editor.
  1223.  
  1224.     Syntax: *DirectorParsePath <path>
  1225.  
  1226. This parses the path supplied into 3 system variables Director$CurrentPath
  1227. Director$Leaf and Director$Dir.  This is the routine that is used internally
  1228. by Director to set these variables and can occasionally be useful externally.
  1229.  
  1230.     Syntax: *DirectorMouseDir <var_name> [-file]
  1231.  
  1232. This sets the supplied system variable to the path of the window the pointer
  1233. is over.  This is used to set the current directory from a key in the default
  1234. menu.  It also works over Edit or Zap windows and will return the directory
  1235. that the file is in.  If the pointer is not over a window with a valid path
  1236. in the title then the system variable will be set to the null string ("").
  1237.  
  1238. If -file is specified then the system variable may be set to point to a file
  1239. (if over an Edit or Zap window for example), otherwise it will be set to the
  1240. directory in which the file resides.
  1241.  
  1242.  
  1243. ¤ External Interface
  1244. ====================
  1245.  
  1246. If you Broadcast the following UserMessage
  1247.  
  1248. 0    Total length of message rounded up to nearest 4
  1249. 12    0
  1250. 16    &4A100
  1251. 20    X Co-ord
  1252. 24    Y Co-ord
  1253. 28    Mouse button state
  1254. 32    Window handle
  1255. 36    Icon number
  1256. 40    Null terminated menu name (or extended menu)
  1257.  
  1258. Director will display the menu (or run the command etc) at the position
  1259. specified.
  1260.  
  1261. Note bytes 20-39 are as returned from Wimp_GetPointerInfo.
  1262.  
  1263.  
  1264. ¤ SWIs
  1265. ======
  1266.  
  1267. &4A100    Director_Menu
  1268. &4A101    Director_EndMenu
  1269. &4A102    Director_Option
  1270. &4A103    Director_Dash
  1271. &4A104    Director_Command
  1272.  
  1273.     Entry
  1274.         r0 = pointer to the command line for the equivalent *command
  1275.     Exit
  1276.  
  1277. These are defined because processing star commands is very slow and in
  1278. dynamic menus especially it is important that items can be added to menus
  1279. quickly.
  1280.  
  1281. &4A105    Director_Enumerate
  1282.  
  1283.     This enumerates lists held by director
  1284.  
  1285.     Entry
  1286.         r0 = pointer to block or to start
  1287.             0 = stored menus
  1288.             1 = displayed menus
  1289.             2 = icons
  1290.             3 = filters
  1291.     Exit
  1292.         r0 = new pointer to block (0 for end)
  1293.         r1 = pointer to name of block
  1294.  
  1295. Dynamic menus to view these lists and act on them can be found on Director's
  1296. main menu.
  1297.  
  1298. &4A106    Director_Memory
  1299.  
  1300.     This returns the memory used by director
  1301.  
  1302.     Entry
  1303.     Exit
  1304.         r0    module size (constant)
  1305.         r1    main workspace size (constant)
  1306.         r2    total size of all allocated blocks
  1307.         r3    number of blocks allocated
  1308.         r4    dynamic area size (0 for no dynamic area)
  1309.         r5    bytes free in dynamic area
  1310.         r6    largest block in dynamic area
  1311.  
  1312. A dynamic menu to display this information can be found on Director's main
  1313. menu
  1314.  
  1315.  
  1316. ¤ Debugging your Menus
  1317. ======================
  1318.  
  1319. If you are having trouble with your menus when you load them (they give a
  1320. funny error and you don't know why) try opening a TaskWindow (CTRL-F12) type
  1321. in "DirectorObey -v " and SHIFT drag your menu file to the window.  This will
  1322. print out commands as they are executed and you should be able to spot
  1323. exactly when it goes wrong.
  1324.  
  1325.     Option "Debug"
  1326.         Command TaskWindow "DirectorObey -v Director:Menus.Menu"
  1327.  
  1328. Would put this on a Director menu for you!  (Substitute the correct name and
  1329. path of your Menu.)
  1330.  
  1331. Another thing to bear in mind is that if you reference a menu that you
  1332. haven't created eg
  1333.  
  1334.     Option "Hello" -sub "NotThere"
  1335.  
  1336. Where menu "NotThere" hasn't been created, this will not produce an error at
  1337. load time, and at run time it will just fail to produce the menu (not
  1338. producing an error either).  Originally it produced an error, but this proved
  1339. very annoying in other circumstances (eg when you haven't defined a Pinboard
  1340. menu because you don't want one).
  1341.  
  1342. You may refer to one menu more than once in a menu tree, however menus can
  1343. only be on the screen once so if you tried to open a SubMenu of a Menu that
  1344. was already displayed then nothing would happen.  However if you clicked on
  1345. the Option (provided it had no Command attached) it would then open the Menu
  1346. referred to.
  1347.  
  1348.  
  1349. ¤ Oddities
  1350. ==========
  1351.  
  1352. If you are running RISCOS 3.5 and wonder why your Menu titles are justified
  1353. all wrong (my menu is called "Nick's Menu" and the Menu gets right justified)
  1354. it is because you have included a reserved key name as the last word.  This
  1355. is RISCOS being helpful and lining up your key short cuts in Menus.  It
  1356. doesn't line up a key short cut of M for instance and will attempt to line up
  1357. anything with the last word "Menu"!  The solution is to put a hard space
  1358. before the "Menu" (hard space is ALT-SPACE).
  1359.  
  1360. If you put a -path <Director$CurrentDir> on your MenuMenu then beware,
  1361. looking at this Directory Menu will cause Director$CurrentDir and
  1362. Director$CurrentPath to change, so if you look at it again, you will be
  1363. looking up one level in the directory viewer.  This can be fixed by using a
  1364. dynamic menu as your MenuMenu (the default menu can be configured to do this,
  1365. look at its start).
  1366.  
  1367. Director menus with sprites in are sometimes the wrong width under
  1368. RISCOS 3.5.  I think this is a bug in the OS.  If you re-open the menu then
  1369. it may correct itself.
  1370.  
  1371. If you put Director in your boot sequence, make sure that you Filer_Run it
  1372. (not just Run) otherwise it won't start up properly.
  1373.  
  1374.  
  1375. ¤ Utils
  1376. =======
  1377.  
  1378. There are a few utilities provided with Director to make Commands more
  1379. powerful and to make your life easier.
  1380.  
  1381.     ExpandMenu    For converting old Pinboard+ menus to Director form
  1382.     RunFilerAc    For starting off Filer_Action tasks (see examples)
  1383.     SwiModule    To be able to issue SWIs from the command line
  1384.     IfPodule    For finding out whether a podule is installed
  1385.     IfThereIs    For finding out whether a file/directory exists
  1386.     DriveName    For discovering the name of a drive from a path
  1387.  
  1388. You'll find these in the Utils directory within Director.  See there for
  1389. further documentation.
  1390.  
  1391. The SWI Module is very useful for building interesting commands but is not
  1392. essential to the operation of Director so you can stop it being loaded by
  1393. default by commenting out that line in the !Run file if you desire.
  1394.  
  1395.  
  1396. ¤ Planned Extensions
  1397. ====================
  1398.  
  1399. These go from will do definitely, to probably won't ever do, but nice idea!
  1400.  
  1401. A command to add options to previously created menu (technically very easy).
  1402.  
  1403. Save and restore memoriser settings automatically.
  1404.  
  1405. A command to define menu colours for permanent and temporary menus.  Should
  1406. be able to define the title bar colours as well.
  1407.  
  1408. Auto scrolling for menus.
  1409.  
  1410. Auto IconSprites or Filer_Boot applications
  1411.     1) Never
  1412.     2) When building permanent menus
  1413.     3) All the time
  1414.  
  1415. Holding down CTRL when making an auto menu could Filer_Boot the applications
  1416. within.
  1417.  
  1418. A Command run when Menu is pressed over a normal text item.
  1419.  
  1420. Make Director menus into windows.  Make the path options draggable and the
  1421. menu options clickable.  Make the menus persistent if torn off.
  1422.  
  1423.  
  1424. ¤ Thanks
  1425. ========
  1426.  
  1427. For interesting menu options, bug reports, comments, ideas, donations or even
  1428. just telling me that they were using Director, thanks are due to :-
  1429.  
  1430. Stefan Wiesner, Sam Kington, Paul Hedderly, Denis Howe, Kevin Bagust,
  1431. Ferro Marco, Brian Howlett, Simon Hatliff, Dominic Symes, Chris Knight,
  1432. Sergio Monesi, Jonathan Mist, James Freeman, Colin Hogben, Aidan Corey,
  1433. Mike Brown, Julian Smith, Matthew Bloch, Andrew Garrard, Bernhard Ege,
  1434. Simon Middleton, Trevor Johnson, Richard Payne, Paul Moore, Ian Hinder,
  1435. Reuben Thomas
  1436.  
  1437. Thomas Olsson, Julian Smith, Ben Summers, Jens Ovesen and Franz Philipps for
  1438. writing a set of excellent utilities which gave me lots of ideas for
  1439. Director.
  1440.  
  1441. Jonathan Coxhead for OSLib.
  1442.  
  1443. Julian Smith for generously supplying the source code for auto scrolling
  1444. menus (which I haven't had time to implement yet).
  1445.  
  1446. Jens Ovesen for very kindly allowing me to distribute his excellent and
  1447. indispensable SWI module with this application.
  1448.  
  1449. Dominic Symes for Zap.  No programmer should be without it.
  1450.  
  1451. Phil Slingsby for thinking of the name.
  1452.  
  1453. Dave Lawrence for testing, the original idea (and code) of creating Pinboard+
  1454. menus from a textual form, ExpandMenu, IfPodule, IfThereIs, DriveName and
  1455. loads of other ideas and suggestions (some of which I've almost certainly
  1456. credited to myself ;-)
  1457.  
  1458. My wife Loveday.
  1459.  
  1460.  
  1461. ¤ Contacts
  1462. ==========
  1463.  
  1464. Post:    Nick Craig-Wood
  1465.     Chalk Barton
  1466.     Shere Road
  1467.     West Horsley
  1468.     LEATHERHEAD
  1469.     Surrey KT24 6EW
  1470.  
  1471. EMail:    director@axis.demon.co.uk
  1472.  
  1473. BBS:    Arcade (0181 654 2212), User 939 (Nick Craig-Wood)
  1474.  
  1475. Any bug reports, ideas or donations gratefully received.
  1476.