!QuickDir -  1992, 6am Digital Playground
=========

1) Instructions
---------------

This is a simple and compact utility to aid navigation of file structures,
especially complex directory trees on large hard discs. It only works under
RiscOS 3.

Load the software by double-clicking the application icon in the usual way.
There will be no visible effect, but the software will be installed.

To activate QuickDir, click Menu over a filer window while holding down the
Alt key. Instead of the normal Filer menu, you will be presented with a menu
of the form:
  +-------------+
  | Quick Dirs  |
  +-------------+
  | Set CSD     |
  | Set Lib     |
  | ----------- |
  | adfs::4.$  |
  | Library    |
  | Utils      |
  +-------------+

The 'Set CSD' and 'Set Lib' options set your CSD and Library respectively to
be the directory for which the menu was invoked.

Below the line are a series of directories. The lowest one is the directory
for which the menu was invoked. Above that is its parent, and so on, until the
root of the filesystem is reached. In the example above, Alt-Menu was clicked
over directory "adfs::4.$.Library.Utils", so there are three layers of
directory shown.

If you wander rightwards into the submenu off one of these directories, you
will be given a list of files in that directory. Any subdirectories off that
directory have submenus for their contents, etc. The tree is built up as you
explore it from the disc, so there may be slight pauses on slow devices.

Choosing an object off the menus will run it, or open a directory viewer
onto it, as appropriate. The action is essentially identical to that
achieved by double-clicking the file in a filer window. Holding down shift
while choosing an object modifies this behavior:
  For an application or directory, the directory viewer is opened.
  For a file, it is loaded as a text file.
This is equivalent to a shift-double-click in the filer.

Naturally, choosing an object with the Adjust button instead of Select will
keep the menu open.

Using Alt-Shift-Menu over an iconised filer window works as expected,
however QuickDir has no effect on icon-bar or pinboard icons.

To quit QuickDir, you must use the task manager.

2) Technical Details
--------------------

QuickDir uses a module called "FilerAltKey", which attaches as a postfilter
on the filer task, and intercepts button events which indicate alt-menu
clicks. When such events are found, Wimp_SendMessage is used to send them to
the QuickDir task, and the original event to the filer is replaced by a null
event. The filer is found by using the TaskManager_EnumerateTasks SWI,
looking for a task with the right name. A single SWI, FilerAltMenu_Task
(&C1300) is used by the main program to communicate with the module.

The main program is written in Acorn Desktop C, but uses little of RiscOSLib
because it needs to do things with menus that Acorn clearly didn't
anticipate! It keeps open only the parts of the menu structure that are on
screen, creating new bits and disposing of now-vanished sections as it
receives Message_MenuWarning messages from the Wimp. It relies on the
property of RiscOS3 Wimp whereby sprites not found in the window's sprite
pool are sought in the wimp sprite pool - otherwise there would be no way to
specify a text-with-sprite icon in a menu. The name of the directory
represented by the filer window is extracted from the window title bar using
Wimp_GetWindowInfo, and is assumed to be an indirected string that can be
read directly - since the Filer task has no WimpSlot, this is safe.

Splitting of pathnames into chunks for the top level menu is performed by
splitting at full stops, until a component containing a dollar or colon is
found. This covers all known cases at the moment.

Icons are picked on the basis of the object type and filetype returned by
new RiscOS3 OS_File and OS_GBPB calls. These calls unfortunately treat
image filing system files as directories, so they show up as such under
QuickDir. I regard this as a bug, but I would have to revert to using
clunkier RiscOS2 facilities to circumvent it.

3) Distribution Permissions
---------------------------

This program is public domain, but may NOT be distributed by, or in
conjunction with any profit-making means. This notice must be left intact in
any copies made. Permission may be given to distribute this software in
other ways - please contact the author.

--
Clive Jones <crj10@phx.cam.ac.uk>
Christ's College, Cambridge, CB2 3BU, UK.
