NAME

OlRegisterHelp − associates help information with either a widget instance or class

SYNOPSIS

#include <X11/Intrinsic.h>
#include <Xol/OpenLook.h>
 . . .
void OlRegisterHelp(

OlDefine id_type,
XtPointer id,
String tag,
OlDefine source_type,
XtPointer source);

DESCRIPTION

These resources define the look of the Help window. 

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 id_type identifies whether it is a widget or a widget class using one of the values OL_WIDGET_HELP, OL_CLASS_HELP, or OL_FLAT_HELP, respectively.  Use OL_WIDGET_HELP 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 OL_WIDGET_HELP. 

To register help for individual items in a flat widget container, use OlRegisterHelp with id_type set to OL_FLAT_HELP.  Use the following structure to specify object that gets the help message:

typedef struct {
Widgetwidget;
Cardinalitem_index;
}  OlFlatHelpId;

Format of Help

The help message is identified in source; source_type identifies the form of the help message:

OL_STRING_SOURCE The source is of type String and contains 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.

OL_DISK_SOURCE 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. 

OL_INDIRECT_SOURCE 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)(id_type,id,src_x,src_y,&source_type,&source);

id_type

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.

src_x

src_y are the coordinates of the pointer when HELP was pressed. These are relative to the upper-left corner of the window.

source_type

source are pointers to values the application’s routine should set for the help source it wants to display.  The only source_type values accepted are OL_STRING_SOURCE and OL_DISK_SOURCE. 

OL_TRANSPARENT_SOURCE
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)(id_type, id, src_x, src_y);

id_type

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.

src_x

src_y 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 OL_STRING_SOURCE, OL_DISK_SOURCE, and OL_INDIRECT_SOURCE help sources.  (It is popped up after the indirect routine returns for the OL_INDIRECT_SOURCE help source.)  The application is responsible for popping up a help window (if needed) for the OL_TRANSPARENT_SOURCE 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 OL_STRING_SOURCE and OL_DISK_SOURCE) or the application routine is called (for source types OL_INDIRECT_SOURCE and OL_TRANSPARENT_SOURCE). 

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 OL_WIDGET_HELP.  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 OL_WIDGET_HELP 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 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 OL_STRING_SOURCE and OL_DISK_SOURCE 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 10 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.

Version 3.0.1  —  Last change: June 92