'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | mmdoc
'\"macro stdmacro
.if n .pH g3w.olHelpRegtrn @(#)olHlpRegtrn	40.3 of 1/8/90
.tr ~
.ds oS HELP
.nr oN 0
.nr X
.if \nX=0 .ds x} ""HELP REGISTRATION ROUTINE" 8 "\&"
.if \nX=1 .ds x} ""HELP REGISTRATION ROUTINE" 8
.if \nX=2 .ds x} ""HELP REGISTRATION "" "\&"
.if \nX=3 .ds x} ""HELP "" "" "\&"
.TH \*(x}
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Intrinsic.h>
#include <OpenLook.h>
.P
\s-1\f4void OlRegisterHelp(id_type, id, tag, source_type, source);
Ol_Define id_type;
XtPointer id;
String tag;
Ol_Define source_type;
XtPointer source;\f1\s+1
.fi
.SH "DESCRIPTION"
.sp
\f3Associating Help with Widgets, Windows, or Gadgets\f1
.P
The
\f4OlRegisterHelp()\f1
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
\f4id\f1,
and
\f4id_type\f1
identifies whether it is a widget, widget class, or window
using one of the values
\f4OL_WIDGET_HELP\f1,
\f4OL_CLASS_HELP\f1,
\f4OL_WINDOW_HELP\f1,
or
\f4OL_FLAT_HELP\f1,
respectively.  Use \f4OL_WIDGET_HELP\f1 to register help on gadgets.
.P
The \f4tag\f1 value is shown in the title of the help window,
as suggested below:
.sp0.5
.ce 1
\f2app-name:  \f4tag \f1Help
.sp 0.5
where \f2app-name\f1 is the name of the application.  More
than one help message can be registered with the same \f4tag\f1.
\f4tag\f1 can be null, in which case 
only  \f2app-name:\f1 Help  is printed.
.sp
\f3Help for Flat Widgets\f1
.P
To set the same help message for all items in a flat widget container, 
use the \f(CWOlRegisterHelp\f1 routine with \f(CWid_type\fP
set to \f4OL_WIDGET_HELP\f1.
.P  
To register help for
individual items in a flat widget container,
use \f(CWOlRegisterHelp\f1 with \f(CWid_type\f1 set to \f4OL_FLAT_HELP\f1.
Use the following structure to specify object that gets the help
message: 
.sp
.nf
\f4typedef struct {
	Widget	widget;
	Cardinal	item_index;
}  OlFlatHelpId;
.fi
.sp
\f3Format of the Help\f1
.P
The help message is identified in
\f4source\f1;
\f4source_type\f1
identifies the form of the help message:
.IP \f4OL_STRING_SOURCE\f1 8
The
\f4source\f1
is of type
\f4String\f1
and contains simple text with embedded newlines.
The
\f4OlRegisterHelp()\f1
routine does not copy this source;
the application is expected to maintain the original as
long as it is registered with a
\f4tag\f1.
.IP \f4OL_DISK_SOURCE\f1 8
The
\f4source\f1
is also of type
\f4String\f1,
but contains the name of a file that contains the text.
The \f4OlRegisterHelp()\f1
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.
.IP \f4OL_INDIRECT_SOURCE\f1 8
The
\f4source\f1
is of type
\f4void(*)()\f1
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.
.P
.IP \& 8
The routine is called as follows:
.P
.IP \& 8
.nf
\f4(*source)(id_type,id,src_x,src_y,&source_type,&source);\f1
.fi
.RS 8
.IP \f4id_type\f1 8
.sp -.5
.IP \f4id\f1 8
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
\f4tag\f1.
.IP \f4src_x\f1 8
.sp -.5
.IP \f4src_y\f1 8
are the coordinates of the pointer when HELP was pressed.
These are relative to the upper-left corner of the window.
.IP \f4source_type\f1 8
.sp -.5
.IP \f4source\f1 8
are pointers to values the application's routine should set
for the help source it wants to display.
The only
\f4source_type\f1
values accepted are
\f4OL_STRING_SOURCE\f1
and
\f4OL_DISK_SOURCE\f1.
.RE
.IP \f4OL_TRANSPARENT_SOURCE\f1 8
The
\f4source\f1
is of type
\f4void(*)()\f1
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, \f4xterm\f1
simply generates an escape sequence).
.IP \& 8
The routine is called as follows:
.RS 8
.P
.nf
\f4(*source)(id_type, id, src_x, src_y);\f1
.fi
.IP \f4id_type\f1 8
.sp -.5
.IP \f4id\f1 8
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
\f4tag\f1.
.IP \f4src_x\f1 8
.sp -.5
.IP \f4src_y\f1 8
are the coordinates of the pointer when HELP was pressed.
These are relative to the upper-left corner of the window.
.RE
.P
The help window is automatically popped up for the
\f4OL_STRING_SOURCE\f1,
\f4OL_DISK_SOURCE\f1,
and
\f4OL_INDIRECT_SOURCE\f1
help sources.
(It is popped up after the indirect routine returns for the
\f4OL_INDIRECT_SOURCE\f1
help source.)
The application is responsible for popping up a help window
(if needed)
for the
\f4OL_TRANSPARENT_SOURCE\f1
help source.
.sp
\f3Handling the Help Key Event\f1
.P
When the end user clicks HELP,
if the event occurs within a widget or window registered with the
\f4OlRegisterHelp()\f1
routine,
the corresponding help message is automatically displayed
(for source types
\f4OL_STRING_SOURCE\f1
and
\f4OL_DISK_SOURCE\f1)
or the application routine is called
(for source types
\f4OL_INDIRECT_SOURCE\f1
and
\f4OL_TRANSPARENT_SOURCE\f1).
If the event occurs elsewhere, a default help message is
displayed.
.P
If the help key is pressed on a widget, the help routine
attempts to look up help on that widget of type \f4OL_WIDGET_HELP\f1.
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 \f4OL_WIDGET_HELP\f1 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
\f(CWOL_CLASS_HELP\f1 on the original widget.  If the class help is
not found, the help routine checks the widget's window for help
of type \f(CWOL_WINDOW_HELP\f1.  If no help is found, the default
message is used.
.ig
The use of \f4OlRegisterHelp()\f1, therefore, is considered
across allapplications. In other words, even though a regular
application does not register help for the root window (the
"workspace"),
it does not mean that pressing HELP on the root window causes a
default message.
Another application (typically the workspace manager) may
have registered the help.
..
.sp
\f3Separate Help per Application\f1
.P
An application will have, at most, one help message
displayed. 
However,
several applications can display their separate help messages
simultaneously,
in different help windows.
.sp
\f3Displaying the Help Message\f1
.P
'\"
.ds hW "50 ens
.ds hH "10 lines
'\"
.EQ
delim $$
.EN
A help source of type
\f4OL_STRING_SOURCE\f1
and
\f4OL_DISK_SOURCE\f1
is displayed in a help window that is
\*(hW wide and \*(hH tall.~~~~~~~
(An en is \fI\s-1S/2\fP\s+1 points,
where \fIS\fP is the current point size.)
Lines longer than \*(hW 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.
.P
Only spaces and newlines are recognized for format control;
all other non-printable characters are silently ignored.
.P
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.
.EQ
delim off
.EN
.sp
\f3Static Variables\f1
.P
The \f4tag\f1 and \f4source\f1 values should be statically
defined (or allocated and not freed).  Using automatic variables
here will almost always fail.
.ig
\f3Pointer Jumping\f1
.P
When the help window pops up,
the pointer is moved to center it over the window mark on the
help window.
If the pointer is never moved outside the help window,
the original position of the pointer is restored after the
window is popped down.
..
