/* 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 --------------------------------
*
* Description: Sets the text of any menu entry, and 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.
* *text -- The text to set the action to.
*
* Returns: void.
*
* Other Info: The text of any 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 set.
*
* If any icon leading to the execution of the action is
* not an indirected text icon, an error is produced.
* If an icon's buffer is too small to contain the text, the
* text is truncated.
*/
void ctl_set_action_text(char *ctlname,char *actname,char *text);
/* ---------------------- ctl_set_caret_in_action -------------------------
*
* Description: Sets the caret in the icon which leads to the execution
* of the given action. (even if it is not the only action
* executed by the icon).
*
* Parameters: *ctlname -- A ctl name.
* *action -- The action name.
*
* Returns: void.
*
* Other Info: A FATAL error is produced if more than one icon leads to
* the execution of the action or if the icon is not an
* indirected text icon.
*
*/
void ctl_set_caret_in_action(char *ctlname,char *actname);
/* ---------------------------- ctl_disable_action ------------------------
*
* Description: Disables (greys out) any menu entry and 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: This will also disable any defined hot keys which lead
* to the action and non leaf menu entries which lead to a
* menu or dbox which has the action on its onopen, onreopen
* or onclose action list.
*
*/
void ctl_disable_action(char *ctlname,char *actname);
/* ------------------------- ctl_enable_action -----------------------------
*
* Description: Enables (ungreys) any menu entry, and any icon,
* leading to the execution of the given action.
*
* Parameters: *ctlname -- A ctl name.
* *action -- The action name.
*
* Returns: void.
*
* Other Info: This will only ungrey the entry or icon if there are
* no other disabled actions executed by the entry or icon.
*
* It also enables any hot keys leading to this action,
* again only if there are no other disabled actions on
* their action list.
*
*/
void ctl_enable_action(char *ctlname,char *actname);
/* --------------------- ctl_make_action_writeable -------------------------
*
* Description: Makes any menu entry, and any icon leading to the
* execution of the given action writeable.
*
* Parameters: *ctlname -- A ctl name.
* *action -- The action name.
* len -- Length of indirected data.
* *valid -- Pointer to validation string.
*
* Returns: Pointer to indirected text buffer.
*
* Other Info: If the action is executed by an icon, a check is made that
* the icon is a writeable indirected text icon with a
* buffer length of at least len characters, and that its
* validation string matches the required one, if not a FATAL
* error results.
*
* The ctl module keeps a pointer to the validation string,
* so its life span should be long enough.
*
*/
char *
ctl_make_action_writeable(char *ctlname,char *actname,int len,char *valid);
/* ----------------------------- ctl_find_entries --------------------------
*
* Description: Calls an entry handler function for every menu entry and
* every icon which leads to the execution of the given
* action.
*
* Parameters: *ctlname -- A ctl name.
* *action -- The action name.
* ctl_entry_proc func -- A function to process the entries.
* see ctl_entry_proc above.
* Returns: void.
*
* Other Info: This can be used for special processing of entries and
* icons leading to the action, for example making them
* a sprite.
*
*/
void ctl_find_entries(char *ctlname,char *actname,ctl_entry_proc func);
/* --------------------------- ctl_process -------------------------------
*
* Description: Should be used in place of event_process(), for
* applications which use this module.
*
* The ctl module tries to process the event, if it can't
* the event is passed to event_process().
*
* Parameters: None.
*
* Returns: Void.
*
*
*/
void ctl_process(void);
/* ----------------------- ctl_attach_external_menu -----------------------
*
* Description: Attaches a wimp menu structure to a menu which is defined
* as external in the Control file.
*
* Parameters: *ctlname -- A ctl name.
* *menuname -- The name of an external menu.
* *m -- The wimp menu structure.
*
* Returns: void.
*
* Other Info: A FATAL error is produced if the menu is not defined
* or is not an external menu.
*
*/
void ctl_attach_external_menu(char *ctlname,char *menuname,wimp_menustr *m);
/* ----------------------- ctl_return_external_hit -----------------------
*
* Description: Return a menu hit for a submenu of an external menu.
*
* Parameters: None.
*
* Returns: The hit array as for a menu_selectproc
* Starting from the external menu.
*
* Other Info: Ctl will treat hits on submenus of an external menu
* (Real submenus, not ones attached using ctl).
* As hits on the external menu, this function enables you
* to get the complete hit list.
*
*
*/
char * ctl_return_external_hit(void);
#endif /* __ctl */