Commit 91926745 authored by Robert Sprowson's avatar Robert Sprowson

Put ctl in the attic

The ctl part of rlib has various memory leaks (ref https://www.riscosopen.org/forum/forums/4/topics/9503) reflecting its abandoned state. See the FrontEnd module for a more flexible implementation of the same GUI-in-a-text-file scripting language.
The ctl API was not in C release 3 (it post dates that) nor in C release 4 manual, and the whole of rlib was removed from C release 5 in favour of the Toolbox.
The change log at the top of rlib/s/rl_spare shows it was briefly added in early 1990 then removed in April 1991. 26 years later, cull it from the Makefile too.

Version 5.94. Tagged as 'RISC_OSLib-5_94'
parent d89ca652
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
......@@ -190,7 +190,6 @@ HEADERS =\
RISC_OSLib:h.colourpick \
RISC_OSLib:h.colourtran \
RISC_OSLib:h.coords \
RISC_OSLib:h.ctl \
RISC_OSLib:h.dbox \
RISC_OSLib:h.dboxfile \
RISC_OSLib:h.dboxquery \
......@@ -398,7 +397,7 @@ ROM_OBJS =\
#
RLIB_OBJS =\
o_rl.akbd o_rl.alarm o_rl.baricon o_rl.bastxt o_rl.bbc o_rl.colourmenu \
o_rl.colourtran o_rl.coords o_rl.ctl o_rl.dbox o_rl.dboxfile o_rl.dboxquery \
o_rl.colourtran o_rl.coords o_rl.dbox o_rl.dboxfile o_rl.dboxquery \
o_rl.dboxtcol o_rl.dragasprit o_rl.drawcheck o_rl.drawfdiag o_rl.drawfiles \
o_rl.drawfobj o_rl.drawmod o_rl.drawtextc o_rl.event o_rl.fileicon o_rl.flex \
o_rl.font o_rl.fontlist o_rl.fontselect o_rl.heap o_rl.help o_rl.jpeg o_rl.magnify o_rl.menu \
......@@ -413,7 +412,7 @@ RLIB_OBJS =\
#
RLIB_MOD_OBJS =\
m_o_rl.akbd m_o_rl.alarm m_o_rl.baricon m_o_rl.bastxt m_o_rl.bbc \
m_o_rl.colourmenu m_o_rl.colourtran m_o_rl.coords m_o_rl.ctl m_o_rl.dbox \
m_o_rl.colourmenu m_o_rl.colourtran m_o_rl.coords m_o_rl.dbox \
m_o_rl.dboxfile m_o_rl.dboxquery m_o_rl.dboxtcol m_o_rl.dragasprit \
m_o_rl.drawcheck m_o_rl.drawfdiag m_o_rl.drawfiles m_o_rl.drawfobj m_o_rl.drawmod \
m_o_rl.drawtextc m_o_rl.event m_o_rl.fileicon m_o_rl.flex m_o_rl.font \
......@@ -704,7 +703,6 @@ RISC_OSLib:h.colourmenu: rlib.h.colourmenu; ${CP} rlib.h.colourmenu $@ ${CPFLAG
RISC_OSLib:h.colourpick: rlib.h.colourpick; ${CP} rlib.h.colourpick $@ ${CPFLAGS}
RISC_OSLib:h.colourtran: rlib.h.colourtran; ${CP} rlib.h.colourtran $@ ${CPFLAGS}
RISC_OSLib:h.coords: rlib.h.coords; ${CP} rlib.h.coords $@ ${CPFLAGS}
RISC_OSLib:h.ctl: rlib.h.ctl; ${CP} rlib.h.ctl $@ ${CPFLAGS}
RISC_OSLib:h.dbox: rlib.h.dbox; ${CP} rlib.h.dbox $@ ${CPFLAGS}
RISC_OSLib:h.dboxfile: rlib.h.dboxfile; ${CP} rlib.h.dboxfile $@ ${CPFLAGS}
RISC_OSLib:h.dboxquery: rlib.h.dboxquery; ${CP} rlib.h.dboxquery $@ ${CPFLAGS}
......
......@@ -11,13 +11,13 @@
GBLS Module_HelpVersion
GBLS Module_ComponentName
GBLS Module_ComponentPath
Module_MajorVersion SETS "5.93"
Module_Version SETA 593
Module_MajorVersion SETS "5.94"
Module_Version SETA 594
Module_MinorVersion SETS ""
Module_Date SETS "03 Sep 2017"
Module_ApplicationDate SETS "03-Sep-17"
Module_Date SETS "29 Oct 2017"
Module_ApplicationDate SETS "29-Oct-17"
Module_ComponentName SETS "RISC_OSLib"
Module_ComponentPath SETS "castle/RiscOS/Sources/Lib/RISC_OSLib"
Module_FullVersion SETS "5.93"
Module_HelpVersion SETS "5.93 (03 Sep 2017)"
Module_FullVersion SETS "5.94"
Module_HelpVersion SETS "5.94 (29 Oct 2017)"
END
/* (5.93)
/* (5.94)
*
* This file is automatically maintained by srccommit, do not edit manually.
* Last processed by srccommit version: 1.1.
*
*/
#define Module_MajorVersion_CMHG 5.93
#define Module_MajorVersion_CMHG 5.94
#define Module_MinorVersion_CMHG
#define Module_Date_CMHG 03 Sep 2017
#define Module_Date_CMHG 29 Oct 2017
#define Module_MajorVersion "5.93"
#define Module_Version 593
#define Module_MajorVersion "5.94"
#define Module_Version 594
#define Module_MinorVersion ""
#define Module_Date "03 Sep 2017"
#define Module_Date "29 Oct 2017"
#define Module_ApplicationDate "03-Sep-17"
#define Module_ApplicationDate "29-Oct-17"
#define Module_ComponentName "RISC_OSLib"
#define Module_ComponentPath "castle/RiscOS/Sources/Lib/RISC_OSLib"
#define Module_FullVersion "5.93"
#define Module_HelpVersion "5.93 (03 Sep 2017)"
#define Module_LibraryVersionInfo "5:93"
#define Module_FullVersion "5.94"
#define Module_HelpVersion "5.94 (29 Oct 2017)"
#define Module_LibraryVersionInfo "5:94"
This diff is collapsed.
/* Copyright 1996 Acorn Computers Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/****************************************************************************
* This source file was written by Acorn Computers Limited. It is part of *
* the RISCOS library for writing applications in C for RISC OS. It may be *
* used freely in the creation of programs for Archimedes. It should be *
* used with Acorn's C Compiler Release 3 or later. *
* *
***************************************************************************/
/*
* Title: ctl.h
* Purpose: Provide support for Control resource file, for the
* specification of an applications user interface.
*/
#ifndef __ctl
#define __ctl
#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif
#include "wimp.h"
#include "event.h"
typedef union { /* Describes the parent of an entry / icon */
wimp_menustr *parent_menu; /* If entry in a menu */
wimp_w parent_window; /* If an icon in an open dbox. */
}ctl_parentstr;
/* ------------------------ ctl_action_proc -----------------------------
*
* Description: This is the type for action handlers.
*
* Parameters: void *ctlhandle -- The handle given when the
* ctl was attached to the window.
* void *acthandle -- The handle given to
* ctl_add_action when this action
* was defined.
* void *args -- The arguments for the action,
* if the action syntax given to
* ctl_add_action was NULL this is
* a pointer to the text following
* the action in the Control file,
* otherwise it is a pointer to an
* argument buffer as returned from
* OS_ReadArgs.
* int return_code -- The return code returned by the
* previous action executed.
*
* Returns: The return code to be passed to the next action.
*
*/
typedef int (*ctl_action_proc)(void *ctlhandle,
void *acthandle,
void *args,
int return_code);
typedef enum { /* The entry type passed to entry processors, see below */
ctl_ENTRY_ICON = 1, /* An icon in an open dbox. */
ctl_ENTRY_MENUENTRY = 2 /* A menu entry. */
} ctl_entrytype;
/* ---------------------------- ctl_entry_proc --------------------------
*
* Description: This is the type for functions passed to ctl_find_entries.
*
* Parameters: parent -- If type is ctl_ENTRY_ICON parent.parent_window
* is a wimp window number of an open dbox.
* If type is ctl_ENTRY_MENUENTRY
* parent.parent_menu is a pointer to a
* wimp_menustr.
*
* entry -- For menu entries this is the entry number
* (starting from 1), for icons this is the icon
* number (starting from 0).
*
* type -- ctl_ENTRY_ICON when this is an icon.
* ctl_ENTRY_MENUENTRY when this is an entry in
* a menu.
* Returns: void.
*
*/
typedef void (*ctl_entry_proc)
(ctl_parentstr parent,int entry,ctl_entrytype type);
/* -------------------------------- ctl_init -------------------------
*
* Description: Initialises the ctl module, and optionally loads
* the Control file.
*
* Parameters: load -- If true, loads the control file and ignores any
* undefined actions.
*
* Returns: void.
*
*
* Other Info: This function should be called once before any other
* function in this module.
*
* It should be called with TRUE for development work,
* as it allows you to have undefined actions in the Control
* file. For a working program, this should be called with
* FALSE, then all actions should be defined, and then the
* Control file should be loaded using ctl_load(),
* this enables the ctl module to do syntax checking when the
* application starts and produce errors if there are
* undefined actions in the Control file.
*
* You must call:
* wimpt_init(),
* res_init(),
* resspr_init(),
* template_init(),
* msgs_init(),
* and dbox_init()
* before calling this function.
*
*/
void ctl_init(BOOL load);
/* -------------------------------- ctl_load ---------------------------
*
* Description: Load the Control file.
*
* Parameters: None.
*
* Returns: void.
*
* Other Info: If ctl_init() was called with FALSE, this function should
* be called after all actions have been defined. This will
* load the Control file, and produce FATAL errors if there
* are any undefined actions in the file.
*
* It should be called ONCE after all actions have been
* defined but before any other function in this module.
* (i.e. only a call to ctl_init(FALSE), followed by calls to
* ctl_add_action() can come before this call)
*
*/
void ctl_load(void);
/* -------------------------- ctl_attach_menu --------------------------
*
* Description: Attach the given ctl structure and a menu from it to a
* window.
*
* Parameters: w -- The window handle.
*
* *ctlname -- The name of a ctl defined in the Control file.
*
* *menuname -- The name of a menu in the ctl.
*
* oid *handle -- A handle to be passed to any action function
* executed from the ctl as a result of user
* actions in this window.
*
* Returns: TRUE if able to attach menu.
*
*
* Other Info: To attach a ctl for icons on the iconbar attach the ctl to
* win_ICONBAR.
*
*
*/
#ifndef win_ICONBAR
#define win_ICONBAR -3
#endif
BOOL ctl_attach_menu(event_w w,char *ctlname,char *menuname,void *handle);
/* -------------------------- ctl_add_action ---------------------------
*
* Description: Add an action to the known actions list.
*
* Parameters: *name -- The action name.
* *syntax -- If NULL, the action_handler function will be passed
* a pointer to the action's argument string when the
* function is called.
*
* If not NULL this should point to a syntax string
* in the form passed to OS_ReadArgs, on entry the
* action handler function will be passed a result
* buffer in the format returned from OS_ReadArgs,
* after the arguments have been evaluated.
*
* ctl_action_proc -- The action handler.
*
* void *hndl -- A handle to be passed to the action handler
* when this action is executed, this enables you to
* implement more than one action using a single
* function.
*
* Returns: void.
*
* Other Info: 1. Actions are global to the application.
* 2. Pointers are kept to the action name and syntax string,
* so their life span should be long enough.
*/
void
ctl_add_action(char *name,char *syntax,ctl_action_proc func,void *hndl);
/* -------------------------- ctl_tick_action ---------------------------
*
* Description: Puts a tick next to any menu entry, and selects any icon
* leading to the execution of the given action (even if it is
* not the only action executed by the menu entry or icon).
*
*
* Parameters: *ctlname -- A ctl name.
* *action -- The action name.
*
* Returns: void.
*
* Other Info:
* Non leaf menu entries which lead to a menu or dbox which has
* the action on its onopen,onreopen or onclose action list will
* also be ticked.
*/
void ctl_tick_action(char *ctlname,char *actname);
/* ------------------------ ctl_untick_action -----------------------------
*
* Description: Unticks any menu entry, and deselects any icon,
* leading to the execution of the given action (even if it is
* not the only action executed by the menu entry or icon).
*
* Parameters: *ctlname -- A ctl name.
* *action -- The action name.
*
* Returns: void.
*
* Other Info:
* Non leaf menu entries which lead to a menu or dbox which has
* the action on its onopen, onreopen or onclose action list will
* also be unticked.
*
*/
void ctl_untick_action(char *ctlname,char *actname);
/* ------------------- ctl_set_action_text --------------------------------