Control Files
=============

Author: William Stoye
History:
  0.01
  0.02
  0.03 - 19-June-89 - remarks about help, and icons.
  0.04 - 04-July-89 - ctl_make becomes ctl_init()
  0.05 - 11-July-89 - more updates
  0.06 - 12-July-89 - more updates
         02-Jan-90 - I realise now that there are various shortcomings,
                     this thing has lain fallow for some time.
                     Key-bindings must be specific to specific contexts, 
                     as different windows might have different ones.
                     Interactive help on menu entries (perhaps via Messages
                     file) should be supported. Should better use of
                     DecodeArgs be made? None of these issues have yet been
                     investigated.

  0.10 - 31-Jan-90 RMokady - Major changes to syntax !
                             * actions use OS_ReadArgs.
                             * Nested action blocks.
                           - Added interactive help support.
                           - Changed key bindings.  
  0.11 - 08-Feb-90 RMokady - Some more changes to syntax.
                             * added external menus. 
                             * added colourmenu menu.
                             * added action on non leaf entries.
                             * added noreopen option for dbox.
                             * added submenu -1 support.
                           - added section about built in actions.
                           - added onclick section.


To do:
------
   Escape sequences in quoted strings.
   Help actions.
   Better key names.

The 'ctl' module is a set of library facilities, written in C, allowing a
program to put a great deal of user event decoding into a resource file.
This file controls the mapping of menu, dialogue box and key events into
textually named actions, which are then executed by the program. It makes
programs easier to construct, and means that the result is customisable (to
some extent) by the user.

This is always called Control, and is a resource file within an application
directory.

File Syntax
-----------

# starts a comment line. Blank lines are ignored.

Each line is split into symbols, separated by spaces.

A symbol is any character sequence in matching quote marks, OR any
alphanumeric char sequence (underscore is also allowed, and the first
character may not be a number). 

Escape sequences within quoted symbols are currently not supported.

Examples:  hello
           delete_file
           "Hello there"

Symbol comparison is case-sensitive. Conventionally all keywords within a
Control file are entirely in lower case.

In the ensuring descriptions, items in angle brackets (unless otherwise
stated) are all symbols.

Actions and Action sequences
----------------------------

An action is a symbol. 
Anything after the action on the same line is treated as arguments to the
action, arguments can be continued on the next line if the NL is immediately
preceded by \, otherwise a NL character is treated as space.

The symbol is the name of an operation that the application supports,
the actual set of operations available is defined by the application.

An action block is a sequence of one or more actions grouped inside
matching '{' , '}'. Action blocks can appear anywhere a single action can 
appear. Action blocks can be nested. The closing '}' should be on a separate
line, otherwise it will be taken to be part of the argument list for the
preceding action.
so an action block should look something like: 

       ... {
            action1 args
            action2 args
            action3 args
           } ...

You can have other symbols on the line following the '}' as it is not 
an action.

Actions return an integer return code which is then passed on to the next 
action executed.


Built in actions.
-----------------

The following built-in actions are always available:

   error <error message> -- Produce the specified error message,
                           in the standard Wimp error message
                           window.

   oscli ....            -- The argument is passed to the OS_CLI.
OR * ...


   showdbox <dbox name>  -- Cancel the current menu and show
                           this dialogue box as a menu. (I.E. clicks
                           outside it close it).

   quit                  -- Quit the application (I.E. calls exit(0)).

   process               -- See hot keys section below.

   if  <expr>            -- Tests the return code returned from the last
                           action, if it is equal to <expr> the following
                           action or action block is executed, if not
                           the action or action block is skipped.

   else                  -- Can only come after an if action, if the if
                           test failed the action or action block following
                           this action will be executed, if not it will be
                           skipped.

   <Number>              -- A number on its own simply sets the return code
                           to its value.
                           For example:
                                 5 an_action 
                           will pass a return code of 5 into an_action.



A control object header
-----------------------

Syntax: ctl <logical control object name>

This starts entries in a named control object.

A menu header
-------------

Syntax: menu <menu name> <menu title> <menu body>
     OR menu <menu name> <menu title> colourmenu
     OR menu <menu name> external

Used to start the declaration of a menu.

The first form defines a simple menu:

<menu title> is the text used for the menu title, if it is a valid
             message token from the Messages file, the message text is used,
             otherwise the actual text is used.

<menu body>  is the menu body in the syntax used for menu_new, again this is
             first matched against message tokens in the Messages file.
             
             Note:
                  The menu body text should not include the ! and > symbols,
                  as submenus, and greying of menu entries is handled by the
                  ctl module (see below).

The second form is like the first form, but the menu body is a colour
selection menu (like the one used by edit to set the text colours).

  The third form defines a menu who's title and body are specified by the
application at run time. Range checking on entry and submenu numbers is only
done when the application attaches the wimp menu structure at run time. 


A Menu help token /action
--------------------------

Syntax: help token <token> 
     OR help action <action> (or action block) <-- NOT YET IMPLEMENTED

The first form gives a token for the interactive help messages to be used
with this menu the entry number (starting with 1) will be appended to the 
token before it is searched for in the Messages file.

The second form gives  the action sequence to be performed when help is
requested, the result code passed to the first (or only) action is the menu
entry number.

A menu open action
------------------

Syntax: onopen <action> (or action block)

This describes the actions to be performed when the menu is opened. 


A menu reopen action
--------------------

Syntax: onreopen <action> (or action block)

This describes the actions to be performed when the menu is reopened,
as a result of the user using the ADJUST button. 


A menu entry
------------

Syntax: entry <entry number>  action (or action block)

This describes the actions to be performed when the user clicks
on the entry.

Entry numbers are checked against the number of entries in the menu, 
and errors are generated if you try to specify an out of range entry number.

Entries on the menu which don't have actions defined for them, are greyed
out (unless they have submenus attached to them, see below).

An entry number of -1 means 'default' , if actions are specified for entry
-1 , entries with no actions will not be greyed out, but the actions
specified for entry -1 will be used for them.


The return code passed to the first action is the entry number on which
the user clicked.

A submenu 
----------

Syntax: submenu <entry number> menu <submenu name>
     OR submenu <entry number> dbox <dbox name>
     OR submenu <entry number> warning action (or action block)
     OR submenu <entry number> menu <submenu name> action (or action block)
     OR submenu <entry number> dbox <dbox name> action (or action block)



The first form indicates a non-leaf menu entry. The submenu name must refer
to a previously defined menu, and matches the menu name given in the menu
header.

The second form indicates a non-leaf menu leading to a dbox. The dbox name
must refer to a previously defined dbox, and matches the dbox name given in
the dbox header.

The third form indicates a non-leaf menu entry which leads to some actions
this is different from entry n action ... because a right arrow will be
displayed in this position on the parent menu.

The fourth form is like the first form but allows you to specify the actions
to be performed if the user clicks on the menu entry leading to the submenu.

The fifth form is like the second form but allows you to specify the actions
to be performed if the user clicks on the menu entry leading to the dbox.

You can not have both 
                 entry   n action ...
            and  submenu n ...

for the same menu.

If you use -1 as the entry number, all entries without specific actions / or
submenus will lead to the submenu / dbox specified.


The end of a menu
-----------------

Syntax: endmenu

This should appear at the end of a menu description. Menu descriptions
cannot be nested.



A dialogue box header
---------------------

Syntax: dbox <dbox name> 

Used to start the declaration of a dbox. 

A dialogue box template name.
-----------------------------

Syntax template <template name>

The correspondingly named template
(typically in the resource file Templates) will be used to describe the
visual appearance of the dialogue box. The template directive must appear 
before any icon actions in the dbox description.

A dialogue box help token /action 
---------------------------------

Syntax: help token <token> 
     OR help action <action> (or action block) <-- NOT YET IMPLEMENTED

The first form gives a token for the interactive help messages to be used
with this dbox the icon number (starting with 0) will be appended to the 
token before it is searched for in the Messages file. Unless the pointer is
not over an icon in which case the unmodified token will be used.

The second form gives  the action sequence to be performed when help
is requested, the result code passed to the first (or only) action
is the icon number (or -1 if not over an icon).


A dialogue box open action
--------------------------

Syntax: onopen <action sequence>

This describes the actions to be obeyed every time a dialogue box is opened
(and just before it is first displayed).

A dialogue box reopen action
----------------------------

Syntax: onreopen <action sequence>

This describes the actions to be obeyed every time a dialogue box is
reopened (as a result of the user clicking ADJUST on an icon).

Dialogue boxes with noreopen.
-----------------------------

Syntax: noreopen

This prevents the dbox from being reopened by a right click.
If the user right clicks in the dbox the menu tree from which the dbox is
hanging will remain open, but the dbox will be closed.

You can not have both onreopen and noreopen in the same dbox description.


A dialogue box close action
---------------------------

Syntax: onclose <action sequence>

This describes the actions to be obeyed every time a dialogue box is closed.

A dialogue box icon action
--------------------------

Syntax: icon <icon number> <action sequence>

This describes the action to be taken when a hit occurs on the specified
icon.

Icons which don't have an action defined for them will be greyed out, unless
their button type is 'Never'.

An icon number of -1 means 'Default', if actions are specified for icon -1,
icons without actions will not be greyed out, but the actions specified for
icon -1 will be used for them.

The return code passed to the first action is the icon number.

The end of a dbox
-----------------

Syntax: enddbox

This should appear at the end of a dbox description. Dialogue box
descriptions cannot be nested.


Keystrokes
----------

Syntax: onkey keycode <action> (or action block)
    OR: onkey [S][C] <keyname> <action> (or action block)
    OR: onkey <Default> <action> (or action block)

with the first form the keycode (as returned by the W)mp is given)

with the second form, the key name is given, key names are:
For any normal key the symbol on the key (i.e. a for unshifted a or A for
shift+a). For special keys <keyname> (i.e. <f5> or <Print> with the angle
brackets as part of the name). The key name can be preceded by C to specify
Control+key or by S to specify Shift+key. S and C can be combined, so SC<f1>
is Shift+Control+<f1>.

Example:
     onkey Sa action
     onkey A  action
     onkey 65 action
  
are all equivalent.

Note:  To specify Uppercase s or Uppercase c use Ss & Sc as S or C will
result in a syntax error. to specify # use S3 as # will begin a comment.

The key name <Default> is used to mean any other key.

The result code passed to the first action on the list is the key code.

The action process passes the key to the wimp, so 

onkey <Default> process

will result in all undefined key presses being passed to the wimp.



The onclick action.
-------------------

Syntax: onclick action (or action block)

This specifies the actions to be executed when the user clicks on an icon in
the window to which the ctl is attached. The main use of this is for ctls
attached to the iconbar. 

The return code passed to the first action on executed is the mouse button
state as returned from the wimp in the wimp_EBUT event.

The end of a 'ctl'
------------------

Syntax: endctl