
Window Open Module
====== ==== ======

 1991-2002 DEEJ Technology PLC

The Window Open module privides commands to control the operation of tasks
and thier windows. The module enables standard working enviroments to be set
up and recreated via an Obey file. Applications can be started windows moved
to the desired postions. Editors can be made to automatically load files,
and options set via an applications menu system.

The Window Open module only uses standard legal RISC OS operations.

The Window Open Module is implemented as a RISC OS task, and will not be
active if it is RMLoad'ed. If it is RMRun'd at the begining of an Obey file,
any subsequent commands will not be exectuted. To ensure that the WindOpen
moudule is active and to execute commands from the same Obey file, the
following procedure should be followed:-

        | Check for presence of WindOpen
        |
        Set WO$start FALSE
        RMEnsure WindOpen 0.00 *Set WO$start TRUE
        |
        | Replace <Path_to_WindOpen> with pathname
        |
        IF "<WO$start>" = "TRUE" THEN *RMLoad <Path_to_WindOpen>.WindOpen
        |
        | ---------------------
        | Rest of Obey file....
        | ---------------------
        |
        | Any Window Open commands will be queued
        | until the task is started
        |
        | Start WindOpen task if just loaded
        |
        IF "<WO$start>" = "TRUE" THEN *Desktop_WindOpen
        |
        | End of file


WindOpen Version History
------------------------
1.00 (27 Dec 1991)  Initial revision
1.10 (15 Feb 1992)  First release version
1.20 (27 Jan 1993)  Support for !WorkSpace added
1.30 (12 Feb 1994)  WO_WorkSpaceModes added, Faster, needs less RMA memory
1.31 (15 Apr 1994)  Workspace messages changed and registered with Acorn.
1.40 (19 Jul 1995)  WO_OpenWindow fixed (message has your_ref=0) and doesnot
                    attempt to load the file if a window is already open
                    (move still works if coords are supplied).
                    Wildcard for task and window name added.
1.50 (02 Jul 1995)  Support for !WorkSpace 3.60 with 6 workspaces.
                    Change to use Wimp Poll Word instead of null events.
1.60 (31 Oct 1995)  WO_Wait added to indert delays in scripts
1.70 (08 Feb 1996)  All window names OS_GSTrans to allow <variable> in names.
                    WO_CloseWind doesnot report error if window doesnot exist
                    WO_TypeString now requires quotes around string if it
                    contains spaces. Partial Task/Window names now only match
                    if the end of a match is at a space.
1.82 (13 May 1998)  New service entry format for Ursula
1.83 (24 Jun 1998)  Canacolise file name in WO_OpenWind to allow "path:filename"
                    in WO_OpenWind calls
1.84 (27 Jul 1998)  BUG Canacolise buffer length writen incorrectly
1.85 (11 Nov 1998)  Use X forms of SWIs everywhere - temp fix to Wimp_Transfer
1.86 (04 Mar 1999)  Check windows have titles, and exclude from WO_WindowDump
1.87 (28 Mar 1999)  Titleless windows reinstated to work with !CPUload & !Mirror
1.88 (05-Mar-2000)  OpenWind with only x0,y0 fixed
1.90 (05-Mar-2000)  32bit safe
1.91 (04-Aug-2001)  Fixed bug in WO_OpenWind with no coordinates supplied
1.92 (29-Oct-2002)  32bit neutral version


!WorkSpace is also available from DEEJ Technology PLC


Commands provided:
Desktop_WindOpen
WO_EnsureTask
WO_RemoveTask
WO_OpenWind
WO_MoveWind
WO_CloseWind
WO_MenuSelect
WO_TypeString
WO_ProcessKey
WO_IconBarClick
WO_WindowDump
WO_WorkSpace
WO_WindWorks
WO_WorkSpaceModes

It has help on:
WindOpen

==> Help on keyword WindOpen
Provides *commands to control windows and tasks which can issued from Obey
files.

In all cammands <taskname> is the name of a task as shown in the Task Manager
display, <window name> is the full or partial name of a window, case is
ignored when matching, names contaning spaces should be given in quotes. A
wildcard of '*' matches all characters upto the next given character.

NOTE: commands do not execute immediately, and may take a number of WimpPoll
      events to complete. Subsequent commands are queued.

==> Help on keyword WO_EnsureTask
*WO_EnsureTask executes a *command if a task is not present.
The task must have a bar icon or a window open to be recognised.
Syntax: *WO_EnsureTask <taskname> <*command>

==> Help on keyword WO_RemoveTask
*WO_RemoveTask kills the named task, no error is given if it is not present.
The task must have a bar icon or a window open to be recognised.
Syntax: *WO_RemoveTask <taskname>

==> Help on keyword WO_OpenWind
*WO_OpenWind attempts to get a task to load a file. If the name of the window
created is the same as the filename, the window can be moved to the position
x0,y0 x1,y1 (see WO_MoveWind). No error is given if the task fails to load
the file unless coords are supplied.
Syntax: *WO_OpenWind <taskname> <full filename> [<x0> <y0> [<x1> <y1>] [-t|-b]]

==> Help on keyword WO_MoveWind
*WO_MoveWind moves a tasks window to a given postion. Supplying two
coordinates will move the lower left corner of the window to x0,y0 leaving
the size unchanged, an extra two coordinates will move the upper right hand
corner to x1,y1 altering its size. -t or -b can be used to force the window
to the top or bottom of the window stack. Prefix negatives with zero e.g.
0-100
Syntax: *WO_MoveWind <taskname> <window name> <x0> <y0> [<x1> <y1>] [-t|-b]

==> Help on keyword WO_CloseWind
*WO_CloseWind closes the named window.
Syntax: *WO_CloseWind <taskname> <window name>

==> Help on keyword WO_MenuSelect
*WO_MenuSelect delivers a menu selction to a tasks window. Sel1 to Sel10 are
the numbers of selected menu entries in the main menu and submenus, the first
item in a menu has number 1. Care should be taken not to select faded menu
items. A window name of "IconBar" can be used for the tasks iconbar menu.
Syntax: *WO_MenuSelect <taskname> <window name|IconBar> <Sel1> [<Sel2> [... <Sel10>]]

==> Help on keyword WO_TypeString
*WO_TypeString is equivelent to typing a string into a tasks window at the
current caret position.
Syntax: *WO_TypeString <taskname> <window name> <string>

==> Help on keyword WO_ProcessKey
*WO_ProcessKey delivers a key press event to a tasks window. <Key> can be in
the range 0-255 for ASCII values, or greater than 256 for function keys and
special WIMP actions.
Syntax: *WO_ProcessKey <taskname> <window name> <Key>

==> Help on keyword WO_IconBarClick
*WO_IconBarClick is equivelent to clicking on a tasks bar icon.
Syntax: *WO_IconBarClick <taskname>

==> Help on keyword WO_WindowDump
*WO_WindowDump writes the position of all currently active windows to the
named file, in a format suitable to be OBEYed as a serise of WO_MoveWind
commands.
Syntax: *WO_WindowDump <filename>

==> Help on keyword WO_WorkSpace
IF the !WorkSpace application is present *WO_WorkSpace will change the
current workspace. Workspaces are numbered 1 to 4.
Syntax: *WO_WorkSpace <workspace>

==> Help on keyword WO_WindWorks
IF the !WorkSpace application is present *WO_WindWorks will change the
workspaces a window occupies. The window will appear on the specified
workspaces and will be reomoved from the others. -all means occupy all
workspaces.
Syntax: *WO_WindWorks <taskname> <window name> {[-1] [-2] [-3] [-4] [-5] [-6]} | -all

==> Help on keyword WO_WorkSpaceModes
IF the !WorkSpace application is present *WO_WorkSpaceModes will change the
modes used by each workspace. Modes can be any valid desktop mode number, a
new format sprite mode number, a mode specifier (pointing to a mode
descriptor which MUST be in the RMA), or '0-1' to disable fixed mode
operation for the workspace. Four or six mode numbers may be given depending
on the version of !WorkSpace.
Syntax: *WO_WorkSpaceModes <mode> <mode> <mode> <mode> [<mode> <mode>]
