OlRegisterHelp(3W) UNIX System V OlRegisterHelp(3W)
NAME
OlRegisterHelp - associates help information with either a widget
instance or class
SYNOPSIS
#include <Intrinsic.h>
#include <OpenLook.h>
void OlRegisterHelp(idtype, id, tag, sourcetype, source);
OlDefine idtype;
XtPointer id;
String tag;
OlDefine sourcetype;
XtPointer source;
DESCRIPTION
These resources define the look of the Help window.
____________________________________________
| Default Window Decorations |
|__________________|___________|____________|
| Resource | Type | Default |
|__________________|___________|____________|
|__________________|___________|____________|
| XtNmenuButton | Boolean | FALSE |
|__________________|___________|____________|
| XtNpushpin | OlDefine | OL_IN |
|__________________|___________|____________|
| XtNresizeCorners | Boolean | FALSE |
|__________________|___________|____________|
| XtNwindowHeader | Boolean | TRUE |
|__________________|___________|____________|
Associating Help with Widgets or Gadgets
The OlRegisterHelp() routine associates help information with either a
widget instance or a widget class. The widget ID or widget class pointer
is given in id, and idtype identifies whether it is a widget or a widget
class using one of the values OLWIDGETHELP, OLCLASSHELP, or
OLFLATHELP, respectively. Use OLWIDGETHELP to register help on
gadgets.
The tag value is shown in the title of the help window, as suggested
below:
app-name: tag Help
where app-name is the name of the application. More than one help
message can be registered with the same tag. tag can be null, in which
case only app-name: Help is printed.
Help for Flat Widgets
To set the same help message for all items in a flat widget container,
use the OlRegisterHelp routine with id_type set to OLWIDGETHELP.
10/89 Page 1
OlRegisterHelp(3W) UNIX System V OlRegisterHelp(3W)
To register help for individual items in a flat widget container, use
OlRegisterHelp with id_type set to OLFLATHELP. Use the following
structure to specify object that gets the help message:
typedef struct {
Widget widget;
Cardinal itemindex;
} OlFlatHelpId;
Format of the Help
The help message is identified in source; sourcetype identifies the form
of the help message:
OLSTRINGSOURCE
The source is of type String and contains simple text with
embedded newlines. The OlRegisterHelp() routine does not copy
this source; the application is expected to maintain the original
as long as it is registered with a tag.
OLDISKSOURCE
The source is also of type String, but contains the name of a
file that contains the text. The OlRegisterHelp() routine does
not copy this filename; the application is expected to maintain
the original as long as it is registered. The file content is
considered to be simple text with embedded newlines.
OLINDIRECTSOURCE
The source is of type void(*)() and is a pointer to an
application defined routine. The routine is called after HELP
has been clicked. The application is expected to define the type
of source in the routine. After the routine has returned, the
help information is displayed.
The routine is called as follows:
(*source)(idtype,id,srcx,srcy,&sourcetype,&source);
idtype
id are the values for the widget class or widget instance
that was under the pointer when HELP was pressed. These
are the same values registered with the tag.
srcx
srcy are the coordinates of the pointer when HELP was pressed.
These are relative to the upper-left corner of the
window.
Page 2 10/89
OlRegisterHelp(3W) UNIX System V OlRegisterHelp(3W)
sourcetype
source are pointers to values the application's routine should
set for the help source it wants to display. The only
sourcetype values accepted are OLSTRINGSOURCE and
OLDISKSOURCE.
OLTRANSPARENTSOURCE
The source is of type void(*)() and is a pointer to an
application defined routine. The routine is called after HELP
has been invoked. The application is expected to handle the HELP
event completely. This might be used by an application that does
not want the standard help window (for example, xterm simply
generates an escape sequence).
The routine is called as follows:
(*source)(idtype, id, srcx, srcy);
idtype
id are the values for the widget class or widget instance
that was under the pointer when HELP was pressed. These
are the same values registered with the tag.
srcx
srcy are the coordinates of the pointer when HELP was pressed.
These are relative to the upper-left corner of the
window.
The help window is automatically popped up for the OLSTRINGSOURCE,
OLDISKSOURCE, and OLINDIRECTSOURCE help sources. (It is popped up
after the indirect routine returns for the OLINDIRECTSOURCE help
source.) The application is responsible for popping up a help window (if
needed) for the OLTRANSPARENTSOURCE help source.
Handling the Help Key Event
When the end user clicks HELP, if the event occurs within a widget or
window registered with the OlRegisterHelp() routine, the corresponding
help message is automatically displayed (for source types
OLSTRINGSOURCE and OLDISKSOURCE) or the application routine is called
(for source types OLINDIRECTSOURCE and OLTRANSPARENTSOURCE). If the
event occurs elsewhere, a default help message is displayed.
If the help key is pressed on a widget, the help routine attempts to look
up help on that widget of type OLWIDGETHELP. If no help is found, the
help routine searches up the widget tree (i.e., goes to the widget's
parent) looking for the first widget that has help of type OLWIDGETHELP
registered. If it finds help registered on one of the original widget's
ancestors, the help message for the ancestor will be used. If help is
not found, the help routine looks for help of type OL_CLASS_HELP on the
10/89 Page 3
OlRegisterHelp(3W) UNIX System V OlRegisterHelp(3W)
original widget. If no help is found, the default message is used.
Separate Help per Application
An application will have, at most, one help message displayed. However,
several applications can display their separate help messages
simultaneously, in different help windows.
Displaying the Help Message
A help source of type OLSTRINGSOURCE and OLDISKSOURCE is displayed in
a help window that is 50 ens wide and 10 lines tall. (An en is S/2
points, where S is the current point size.) Lines longer than 50 ens are
wrapped at the space(s) between words, or at the nearest character
boundary if there is no space at which to wrap. Lines are also wrapped
at embedded newlines regardless of their length.
Only spaces and newlines are recognized for format control; all other
non-printable characters are silently ignored.
Up to ten lines of the message are visible at once. Messages longer than
ten lines have a scrollbar control that allows scrolling non-visible
lines into view.
Static Variables
The tag and source values should be statically defined (or allocated and
not freed). Using automatic variables here will almost always fail.
Page 4 10/89