HELP REGISTRATION ROUTIM
NA
E(
I8
N)
TENANCE COH
ME
MA
LN
PDR
SEGISTRATION ROUTINE(8)
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
Associating Help with Widgets, Windows, or Gadgets The OlRe-
gisterHelp() routine associates help information with either
a widget instance, a widget class, or a window. The widget
ID, widget class pointer, or window ID is given in id, and
idtype identifies whether it is a widget, widget class, or
window using one of the values OLWIDGETHELP,
OLCLASSHELP, OLWINDOWHELP, or OLFLATHELP, respec-
tively. 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. 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
Amiga Unix Last change: 1
HELP REGISTRATION ROUTIM
NA
E(
I8
N)
TENANCE COH
ME
MA
LN
PDR
SEGISTRATION ROUTINE(8)
name of a file that contains the text. The OlRe-
gisterHelp() 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 rou-
tine. 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, widget
instance, or window 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.
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 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
Amiga Unix Last change: 2
HELP REGISTRATION ROUTIM
NA
E(
I8
N)
TENANCE COH
ME
MA
LN
PDR
SEGISTRATION ROUTINE(8)
id are the values for the widget class, widget
instance, or window 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 appli-
cation 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 rou-
tine 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 ances-
tors, 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 original widget. If the class help is
not found, the help routine checks the widget's window for
help of type OL_WINDOW_HELP. 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 applica-
tions can display their separate help messages simultane-
ously, 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 new-
lines are recognized for format control; all other non-
printable characters are silently ignored. Up to ten lines
Amiga Unix Last change: 3
HELP REGISTRATION ROUTIM
NA
E(
I8
N)
TENANCE COH
ME
MA
LN
PDR
SEGISTRATION ROUTINE(8)
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 stati-
cally defined (or allocated and not freed). Using automatic
variables here will almost always fail.
Amiga Unix Last change: 4