help

/* 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: h.help
 * Purpose: Provide support for interactive help.
 *
 */

#ifndef __help_h
#define __help_h

#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif

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

BOOL help_process(wimp_eventstr *e);


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

void help_register_handler(event_menu_proc, void *handle);


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

BOOL help_genmessage(char *prefix, char *hit);


/* ---------------------------- help_simplehandler ------------------------
 * Description:   A simple event_menu_proc suitable for giving to a help
 *                handler. The implementation is simply
 *                    { help_genmessage((char*) handle, hit); }
 *
 * 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.
 *
 */

void help_simplehandler(void *handle, char *hit);


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

BOOL help_dboxrawevents(dbox, void *event, void *handle);


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

void help_reply(char *m);

#endif

/* end help.h */