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