(*
 * Title: h.help
 * Purpose: Provide support for interactive help.
 *
 *)

#ifndef __help_h
#define __help_h

# ifndef __wimp_h
# include "wimp.h"
# endif

# ifndef __event_h
# include "event.h"
# endif

# ifndef __dbox_h
# include "dbox.h"
# endif

(* ---------------------------- help_process ------------------------------
 * Description:   Returns TRUE if the given event is a menu interactive
 *                help message, which has now been processed.
 *
 * Parameters:    e -- the event to be considered.
 * Returns:       TRUE if the event has now been processed.
 * Other Info:    This should be called by the unknown event handler of
 *                the program. For it to work, you must inform wimpt that
 *                you are aware of Wimps beyond version 2.00. The the rest
 *                of this interface for the handling facilities that this
 *                call invokes.
 *
 *)
function help_process(e : wimp_eventstr_ptr) : boolean; extern;


(* ---------------------------- help_register_handler ---------------------
 * Description:   Record the handler to be used when help_process is next
 *                called.
 *
 * Parameters:    event_menu_proc -- the handler procedure
 *                handle -- a data handle for the handler procedure
 * Returns:       void
 * Other Info:    This should be called by the menu-maker proc of every 
 *                menu in the program. When help_process is called, the 
 *                most recently installed event_menu_proc handler is 
 *                assumed to be the correct one. Call with NULL as a proc 
 *                if no help is available on this menu.
 *
 *)
procedure help_register_handler(proc : event_menu_proc;
                handle : pointer) : os_error; extern;


(* ---------------------------- help_genmessage ---------------------------
 * Description:   From a given menu hit and prefix, generate a message tag
 *                which is looked up in msgs_lookup. If a message is found
 *                then return it as the interactive help message, and return
 *                TRUE. If not, return FALSE.
 *
 * Parameters:    prefix -- the prefix for all message tags used
 *                hit -- the hit string handed to the event_menu_proc
 *                       registered using help_register_handler
 * Returns:       TRUE if this was a menu help message which has now been
 *                handled
 * Other Info:    The tag for the msgs_lookup call is generated by:
 *                  start with the prefix (maximum length - 20 characters)
 *                  append '0'..'9' or 'a'..'z' for each character in the 
 *                  hit (e.g. character 1 counts as '0', character 10 
 *                  counts as '9', character 11 counts as 'a', etc. More 
 *                  than 35 seems unlikely in a menu of fixed size).
 *                example: original hit 0,1,2 gets translated to string
 *                "\x001\x002\x003", which gets turned into tag "FOO012" for
 *                prefix "FOO". A prefix consisting entirely of upper case
 *                letters is conventional. If there's only one menu tree,
 *                the prefix "HELP" is conventional. For the icon bar,
 *                "IHELP" is conventional.
 *
 *)
function help_genmessage(prefix, hit : string) : os_error; extern;


(* ---------------------------- help_simplehandler ------------------------
 * Description:   A simple event_menu_proc suitable for giving to a help
 *                handler.
 *
 * Parameters:    handle -- prefix to pass to help_genmessage
 *                hit -- the menu hit string being processed
 * Returns:       void
 * Other Info:    This will suffice for cases where there are no
 *                alternatives or additional cases to consider. For menus
 *                where the message can vary at run time, a more complex
 *                handler will be required which parses the hit string, or
 *                which calls help_genmessage more than once, or perhaps a
 *                combination of the two.
 *
 *)
procedure help_simplehandler(handle : pointer;
                hit : string) : os_error; extern;


(* ---------------------------- help_dboxrawevents ------------------------
 * Description:   A routine suitable for passing to dbox_raw_eventhandler,
 *                for providing help on dialogue boxes.
 *
 * Parameters:    dbox -- the dbox for which help is being provided
 *                event -- the wimp event being processed
 *                handle -- message tag prefix, really a char*
 * Returns:       TRUE if this was a menu help message which has now been 
 *                handled
 * Other Info:    The handle passed to it should be a message prefix. A
 *                single character suffix may be added to it in the style of
 *                help_genmessage, containing the icon number. If this is
 *                not found (or if no icon is being pointed to), then a the
 *                prefix alone will be used as a message tag. There is no
 *                error if the message is not found.
 *
 *                Typical use:
 *                    dbox d = dbox_new("foo");
 *                    dbox_raw_eventhandler(d, help_dboxrawevents, "FOO");
 *                    dbox_show(d);
 *                    ... now fill in the dbox as normal ...
 *                The test used in implementing this is:
 *                  if (
 *                       (e->e == wimp_ESEND || e->e == wimp_ESENDWANTACK)
 *                       &&
 *                       e->data.msg.hdr.action == wimp_MHELPREQUEST
 *                     )
 *                     ... construct a reply, and send it using help_reply ...
 *                The Messages file should contain:
 *                  FOO:This message will appear in the dbox background.
 *                  FOO0:This message will appear for icon 0 of the dbox
 *                  etc.
 *
 *)
function help_dboxrawevents(d : dbox;
                event : pointer;
                handle : pointer) : boolean; extern;


(* ---------------------------- help_reply ------------------------------
 * Description:   Reply to the help message in wimpt_last_event() with
 *                the (already translated) message provided.
 *
 * Parameters:    m -- help message to display in interactive help window
 * Returns:       void
 * Other Info:    This is useful when creating your own versions of
 *                help_dboxrawevents, which must also handle other events.
 *
 *)
procedure help_reply(m : string); extern;

#endif

(* end help.h *)
