   _____         _ __       __
  / ___/      __(_) /______/ /_
  \__ \ | /| / / / __/ ___/ __ \
 ___/ / |/ |/ / / /_/ /__/ / / /
/____/|__/|__/_/\__/\___/_/ /_/  version 158 29th May 2003

a WIMP front-end by Harriet Bazley for a program by Nick Craig-Wood

--------------------------------------------------------------------------------
PURPOSE OF PROGRAM:

To list all open windows and allow the user to switch between them.
--------------------------------------------------------------------------------
HARDWARE/SOFTWARE REQUIREMENTS:

Minimal.  36k of free memory and RISC OS 31 or greater.   RISC OS 4 / StrongARM compatible.   May be run from a read-only archive or from floppy disc.  This program supports interactive !Help.
--------------------------------------------------------------------------------
HOW TO USE:

Clicking SELECT on the iconbar icon will display a menu of the titles of all the windows open on the desktop, prefixed by the name of the task to which they belong.  Clicking on the entry for a window title in this menu will bring that window to the top.

Filer windows are listed in blue, <untitled> windows in green, and windows containing unsaved data in red.   Other windows are listed in black.   The window currently at the front of the stack is ticked.   Windows belonging to different tasks are underlined to separate them.   If there is more than one open window belonging to a task, there will also be an entry reading 'ALL WINDOWS' - clicking on this will bring all windows belonging to that task to the top.


For each window there is a submenu offering six options:

Iconise		equivalent to a SHIFT-click on the close icon.   Iconises this window at the position of its top left corner on the backdrop (or to the iconbar under RISC OS 4)
Pin		pins the icon representing the file in this window to the position of its top left corner on the backdrop and closes the window.   If the window's titlebar does not contain the pathname of a file, this menu entry is greyed out.
Top		equivalent to a click on the titlebar of the window (or a click on the main menu).   Brings the window to the front of the stack.   If the window is already at the front, this menu entry is greyed out.
Bottom		equivalent to a click on the window's back icon.   Sends the window to the back of the stack.   If the window is already at the back, this menu entry is greyed out.
Close		equivalent to a click on the close icon.   Closes the window.
Ignore		adds this window to the 'Ignore file' so that it no longer appears on the menu.   See below.

The submenu on an 'ALL WINDOWS' entry provides only three options, Top, Bottom and Close, but these are applied to all windows belonging to the task in question.

Note that, contrary to all RISC OS convention, the menu will *not* be kept open when you select entries from the 'Window' submenu using the ADJUST button.  See 'Technical notes' below.

Clicking MENU on the iconbar icon displays an Info/Help.../Ignore file/Close all/Quit menu.  This gives you access to the info window, the program's !Help file, a sub-menu dealing with the 'Ignore file' - see below - and allows you to quit the program.

Selecting 'Close all' will close *all* currently-open windows on the desktop.
--------------------------------------------------------------------------------
THE IGNORE FILE:

Some programs have invisible 'back windows' to enable them to respond to key shortcuts even when none of their normal windows are open.   Switch attempts to exclude such windows from its menu;  but sometimes it fails to recognise them.

Switch maintains a file called Ignore which lists the titles of specific windows to be ignored, and the tasks to which they belong.   If you have identified a 'back window', you can add it to this list automatically by selecting 'Ignore' from the sub-menu attached to the menu entry for that window.   You will be asked to confirm this, as the window in question will never show up on the Switch menu again.

Clicking MENU on the iconbar icon will bring up the iconbar menu which contains an entry 'Ignore file' leading to a submenu allowing you to view and edit the file manually or to delete it altogether.   If you do make a mistake, you can always use this method to remove the offending line in the Ignore file or to remove the whole file, although you will have to restart Switch before manual changes to the file will take effect.

Ignore file format:

    Each line of this file should contain the name of the task (as given on the start of the line in the Switch menu) followed by a space, a hyphen and another space, followed immediately by the ACTUAL window title (e.g. including any name prefix stripped from the menu entry). Note that the hyphen syntax is fixed, unlike the separator used in the menu (which may be customised by changing the Messages file).

Two example lines might read:
   Doom Launcher - Grab keys
   MiniDisc - MiniDisc Grab keys

The penultimate line of this file must consist of the single word END, followed by a carriage return (blank line). You should not delete all the entries from the file;  instead, you should delete the whole file.   All entries (including END) are case-sensitive.

Every window is checked against this list before an entry is added to the menu of open windows (so making the list too long will slow down the program).
--------------------------------------------------------------------------------
TECHNICAL NOTES:

The program cannot currently display more than 40 menu entries.   If the menu exceeds this length it will be truncated, with a warning beep.   This limit can be increased by altering the parameter passed to PROCinit, although you may need to increase the Wimpslot in the !Run file if you do this.

Also, there can be no more than 40 entries in the Ignore file.

As of version 154, ADJUST-clicking on the 'Window' submenu will no longer keep the menu tree open.   Because of the way the WIMP message system works, any changes to windows triggered by a selection from a Switch menu will not take place until after the menu has been reopened.   This means that the menu data is out of date - in the case of the submenus, potentially fatally so, causing a crash.   After complaints both ways, I finally decided that disabling ADJUST-clicks on the submenu altogether was the lesser of two evils.
--------------------------------------------------------------------------------
CREDITS:

The main routines were created by Russel Thickings and Nick Craig-Wood to generate menus for use with Nick's desktop customisation program !Director.
Stand-alone WIMP front-end added by Harriet Bazley (for the benefit of my brother, who doesn't use Director) using adapted routines from Chris Coe's NPLibrary.

Thanks also to John Kortink for !Creator, which generated the palette used for the application sprites (they should look better in 256 colours now).

Olaf Krumnow and Herbert zur Nedden of the German Archimedes Group wrote the ResFind program used to find the correct resources for different languages.

Full uncompressed source code is provided.
--------------------------------------------------------------------------------
CONTACTING THE AUTHOR:

I have no idea whether any of the three original authors are still in the Acorn community, six years on... but I can be contacted by post as

  Miss H. Bazley
  43, Wilton Grove
  Wimbledon
  London SW19 3QU

or via e-mail at harriet@bazley.freeuk.com
                 chrisbazley@bigfoot.com


--------------------------------------------------------------------------------
HISTORY

Version 110	(14th July 2000)
		Panes are no longer included in the list.
		Icon now appears to right of iconbar.
		Added !Switch.Ignore file to cope with non-standard hotkeys windows (apparently including new Task Manager - tut, tut!)
		Removed bug where long filenames could overwrite string terminator.
Version 120	(25th July 2000)
		Added better error trapping.   Illegal window handles (i.e. banner windows that close after the menu opens and before you click on it) are ignored - all other errors are reported, giving you a choice whether to quit the program or not.   Introduced many new error checks.
		Added interactive help.
		Automated the creation and maintenance of the Ignore file and updated the menus to provide an interface.   Adding a window to the Ignore file now also hides it immediately.
		The Ignore file is now created by preference inside <Choices$Write> if this system variable exists - otherwise the program reverts to the old behaviour of looking for the file inside the actual !Switch directory.
		Circumvented weird bug where the RISC OS 4 version of !Help reports its indirected title data to be located in zero page, which is an illegal address under RISC OS 4.
Version 130	(26th December 2000)
		Fixed bug causing endless loop where a window title exceeded 64 characters and did not contain a "." character.
		Coloured menu backgrounds don't work properly under RISC OS 4.   Changed format of menu  'grey' task name entries no longer exist and groups of windows belonging to each task are underlined to separate them, with window titles prefixed by task names.   This seems a retrograde step and removes the feature whereby clicking on a task name brought *all* windows belonging to that task to the front, but I could find no better way around the weird appearance under RISC-OS 4.
		As a result, format of Ignore file has changed.   This should be transparent to the user, but if in doubt, use the menu option to delete Ignore file and recreate it.
		Programs which prefix their windows with the name of the application (Drawplus, PipeDream, Fireworkz, Webster XL, Oregano etc.) now have this prefix stripped off.   (One of my pet hates, by the way....)
Version 131	(27th December 2000)
		Fixed bug causing endless loop when a window's indirected title was blank (i.e. Webster XL during download).   Such windows are now displayed as <untitled>.
Version 132	(28th December 2000)
		Removed submenu on 'No windows open' menu entry (again!)
Version 133	(7th January 2001)
		Minor patch to behave more intelligently for window titles such as "Make (Completed)"
		Fixed yet another bug causing endless loops, and improved truncation of very long window titles which do not contain pathnames.
		Increased Wimpslot slightly (sorry to all those with RISC OS 31).   Should no longer crash when there are many windows with long titles.
Version 134	(12th January 2001)
		Windows whose titles are prefixed by the app name (Fireworkz etc) can now be pinned.
		'Red' windows (with unsaved data) now have the 'Pin' entry on the submenu greyed out, since you cannot pin an unsaved file.
		The windows at the top and bottom of the stack have the relevant menu entries greyed out.
Version 140	(17th January 2001)
		No longer 'sends ignored windows to the back' since this could cause weird side-effects for some apps.   Now simply ignores them, repeatedly.
		Removed support for old-format Ignore files - sorry, it was causing too many other problems....   Finally got round to altering Ignore file format description in the Help file.
		There is now a fixed limit of 40 entries in the Ignore file.   This is controlled by the global variable ignore_limit%, set in PROCinit, so can be changed if desired - but due to the way it's coded, every new entry makes the program exponentially slower!
Version 141	(20th January 2001)
		Tweaked program slightly in a desperate attempt to differentiate between the (valid path) "Messenger:!RunImage" and the (pseudo path in window title) "Messenger: Incoming mail".   I HATE programs that do this with their window titles;  it completely messes up Director as well.
Version 150	(29th April 2001)
		Re-implemented 'all windows' concept of a menu that acts on all windows belonging to given task, in the hopes of solving some of the ADJUST-click problems (i.e. you won't *need* to keep the menu open).
		Added 'Close all' option to iconbar menu.
Version 151	(3rd May 2001)
		Fixed a bug affecting the 'ALL WINDOWS->Close' option for the last task in the menu.
Version 152	(22nd June 2001) CJB
		Copes with sensibly truncating DOS-style file paths (for listing Oregano window titles).
Version 153	(9th July 2001)
		By request: implemented 'Continue' and 'Quit' buttons in error report window.  The default action is now 'Continue'.
		Attempted to speed up file path truncation.
		Added "Help..." menu entry.
Version 154	(2nd October 2001)
		No longer causes errors when <Choices$Write> is not writable, i.e. when FSLock is in use.
		Gave up and disabled ADJUST-clicking on 'Window' submenu altogether.
Version 155	(2nd May 2002) CJB
		Compares entries in ignore file against actual taskname/window title rather than displayed menu text (was bug). Hence it is now possible to ignore windows that are displayed with a truncated title.
		Internationalised application (new message file/menu code).
		Fixed bug where <untitled> windows were only highlighted green if the parent task had more than one window open.
		ADJUST-click on "ALL WINDOWS" entries in main menu now works.
		Added hourglass for a few operations that can take a while on slow filing systems.
		Now reads ignore file from Choices$Path rather than (erroneously) from Choices$Write.
Version 155b	(30th September 2002)
		Yet another tweak to the task-name-from-window-title stripping code; window 'Linker' belonging to task 'Link' should no longer appear as 'Link - er'
		Removed a couple of bugs affecting colouring of <untitled> windows, and some unused variables.
Version 155c	(3rd October 2002)
		More unimportant tweaks.
Version 156	(25th January 2003) CJB
		Moved 'Help...' option up the iconbar menu in order to follow the new convention suggested by Castle Technology.
Version 157	(8th April 2003) CJB
		Moved various separator strings into the Messages file to allow easier customisation. Specifically, this allowed "..." to be substituted for the elipsis character, which is not present in all fonts. 
		More precise explanation of the ignore file format.
Version 158	(29th May 2003) CJB
		Minor fix: window title transmitted with Message_Iconize is now zero terminated rather than CR terminated. The old behaviour didn't bother the Pinboard, but showed up in WimpMonitor and was probably wrong.
