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

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 contruct, and means that the result is customisable (to
some extent) by the user.

The 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"
           'Say "boo"'

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

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

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

An action sequence is just a sequence of one or more symbols. Each symbol
is the name of an operation that the application supports, the actual
set of operations available is defined by the application.

It's also possible for an action to take arguments, if an action
requires an argument then the next symbol in the action sequence is
interpreted as this.

The following built-in actions are always available:

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

  opendbox <dbox name> -- cancel the current menu and show
                          this dialogue box. This can only occur
                          at the end of an action sequence.

  closedbox            -- close the current dialogue box.
                          This should occur at the end of an
                          action sequence whose normal operation
                          is to close the dialogue box. A
                          right-click will override this,
                          leaving the dialogue box open.

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

Syntax: ctl <logical control object name>

This starts entries in a named control object.

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

Syntax: menu <menu text> <menu name>

Used to start the declaration of a menu.

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

Syntax: entry <entry text> <action sequence>
     OR entry <entry text> submenu <submenu name>
     OR entry <entry text> submenu <submenu name> action <action sequence>

An entry statement describes an entry in a menu.
The first form indicates a conventional menu entry, with the sequence
of actions that should be performed if the user clicks on that menu
entry.

The second 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 third form indicates a non-leaf menu which can also lead to some action
when clicked.

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> <template name>

Used to start the declaration of a dbox. The correspondingly named template
(typically in the resource file Templates) will be used to describe the
visual appearance of the dialogue box.

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 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.

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

Syntax: enddbox

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

(key definitions)
(complete example)
(error messages)

Keystrokes
----------
(WRS: not yet done)

keycode <key code> <action sequence>
fnkey <fn key number> <action sequence>
shfnkey <fn key number> <action sequence>
ctlfnkey <fn key number> <action sequence>
shctlfnkey <fn key number> <action sequence>
key <character> <action sequence>
ctlkey <character> <action sequence>

An example file (incomplete)
----------------------------

# Control file for Edit

ctl IconControl # define control machine for icon on icon bar

menu Create create
entry "New Text file"    newtextfile
entry "New Data file"    newdatafile
entry "New Command file" newcommandfile
entry "New Obey file"    newobeyfile
entry "New Task window"  newtaskwindow
endmenu

dbox proginfo progInfo
onopen proginfo_setversion
enddbox

menu Edit edit
entry Info dbox proginfo
entry Create submenu create
entry Quit edit_quit
endmenu

ctl Control # control for main window

menu Misc misc
entry Info dbox proginfo
entry File dbox fileinfo
entry "New view"           txtedit_newview
entry "Column tab (sh-f3)" txtedit_coltab
entry "Overwrite  (sh-f1)" txtedit_overwrite
entry "Wordwrap  (ctl_f5)" txtedit_wordwrap
entry "Trace"              trace
entry "No trace"           notrace
endmenu

dbox indent selindent
onentry indent_init
icon 0 indent_do
enddbox

menu Select select
entry Save sel_save
entry "Copy   (ctl-C)" sel_copy
entry "Move   (ctl-V)" sel_move
entry "Delete (ctl-X)" sel_delete
entry "Clear  (ctl-Z)" sel_clear
entry "Indent" dbox indent

menu "Format width" formatwidth
entry "" format # will be filled in by program
endmenu

menu Edit edit
entry "Find  (f4)" dbox edit_find
entry "Goto  (f5)" dbox edit_goto
entry "Undo  (f8)" edit_undo
entry "Redo  (f9)" edit_redo
entry "CR<->LF"    edit_crlf
entry "Expand tabs" edit_tabs
entry "Format text" submenu formatwidth

menu Display display
entry Font fontmenu
entry "Font size" submenu fontsize
entry "Font height" submenu fontheight
entry "Line spacing" submenu linespacing
entry "Margin" submenu margin
entry "Invert" invert
entry "Wrap" wrap
entry "Foreground" fcolour
entry "Background" bcolour
endmenu

menu Edit main
entry Misc submenu misc
entry Save save
entry Select submenu select
entry Edit submenu edit
entry Display submenu display
endmenu
