ctl

/* 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 */