23
Help Facilities
This chapter addresses the general-usage Help facilities that apply to all XView packages.
The help mechanism is available for the application programmer to register help information
in response to user requests.
OPEN LOOK describes a help mechanism that enables the user to get help from anywhere in
the user interface. The user requests help using the Help key on the keyboard, or, if one does
not exist, the F1 function key. When this key is used, the window under the pointer receives
the ACTION_HELP event. In such cases, a Help window is displayed as shown in Figure 23-1.
Figure 23-1. A sample Help window
Note that when you request help on a menu or a menu item, this action will dismiss the menu.
This dismissal is required, since the Menu package must relinquish its pointer and keyboard
grabs in order for the help request to be processed.
Help Facilities
Help Facilities 557
23.1 Using XV_HELP_DATA
The attribute XV_HELP_DATA is used to provide XView with information about where to find
the text for the help frame. The attribute’s value is a string in the form of:
"
filename:token
"
The
filename
is found from a list of directories set in the $HELPPATH environment vari-
able. The actual filename has the .info suffix appended to its base name. Thus, the complete
path to the filename that contains the help information is:
$HELPPATH/
filename
.info
If $HELPPATH is not set, the directory /usr/lib/help is used. However, if $HELPPATH is set,
then that path is searched exclusively and /usr/lib/help is not searched unless it is
explicitly listed in the variable’s setting. Therefore, users should always have the default
path in their environment setting. Since $HELPPATH may be set to any number of direc-
tories, a possible setting would be (for the C shell):
setenv HELPPATH /usr/lib/help:/path/to/other/help/directories:.
Or, for the Bourne shell:
HELPPATH=/usr/lib/help:/path/to/other/help/directories:.
export HELPPATH
The trailing “.” indicates that the current directory is included.
Once the filename is found, the token is searched for within the file. The file must contain the
string "
:token
" at the beginning of the line. All the text following the token, starting on
the next line, is displayed in the scrolling text subwindow within the help frame. A maxi-
mum of 10 lines of text, each terminated by a newline, is visible in the help text subwindow.
If the help text exceeds 10 lines, a scrollbar is provided. Each line of help text may not
exceed 50 characters. Scrollbars do not appear when a line is too long vertically to fit in the
help window. You need to manually type a return in the help text to trim help text lines to fit
within the 50-character limit. The text ends when a line is found that starts with a “#"
or a “:”.
23.2 HELP Key Binding
Servers that know about the XK_HELP keysym because they use a key labeled Help, as on
Type-4 Sun keyboards, provide help messages when the HELP key is selected. On servers
that don’t know about XK_HELP, the user cannot get help unless some key is mapped to
XK_HELP (OPEN LOOK requires that some key be mapped to provide help messages). The
user, or system administrator, may define a help key by mapping the resource OpenWin-
dows.KeyboardCommand.Help to a key such as F1.
OPEN LOOK also describes a method to access additional on-line information when a “More”
button is placed in the help window. XView allows the More button to be selected with the
mouse, or used with an accelerator (see Table 23-1). Selecting the More button allows the
application to provide additional help according to the current help context.
558 XView Programming Manual
Help for a text subwindow is also provided. Table 23-1 shows the default bindings for the
various types of help functions provided by OPEN LOOK.
Table 23-1. Modified Help Keystrokes
Key Type of Help
<Help> Spot Help
Shift-Help More Spot Help (an accelerator)
Ctrl-Help Help on Text
Shift-Ctrl-Help More Help on Text (an accelerator)
23.2.1 Attaching Help Data
Let’s say you have written a program called my_program. In this program, there is a panel
with a button labeled “Save.” The user wants to know exactly what this button will do if
selected. The user can select the Help key over the panel item in order to obtain help associ-
ated with the item. To support this action, you must attach help data to the panel items in the
following manner:
...
extern Frame frame;
extern void save_it();
Panel panel;
panel = (Panel)xv_create(frame, PANEL, NULL);
xv_create(panel, PANEL_BUTTON,
XV_HELP_DATA, "my_program:save",
PANEL_LABEL_STRING, "Save",
PANEL_NOTIFY_PROC, save_it,
NULL);
xv_create(panel, PANEL_TEXT,
XV_HELP_DATA, "my_program:target",
PANEL_LABEL_STRING, "Filename: ",
NULL);
...
The value for XV_HELP_DATA contains the name of the program as the “filename” to search
for and the token is :save. The filename was chosen based on the name of the application
for easier administration of the help files. The next step is to create the file my_program.info
and add the help text. The file might look like this:
Help Facilities
Help Facilities 559
:save
When selecting this panel item, all changes made
to the current document will be saved in the target
file. To change the target file, type in a new
name at the "Filename:" text item.
#
:target
This filename represents the name of the file to use
to load a new file or to store editing changes. Full
pathnames should be specified to insure that you get
the correct filename.
#
The “#” used to terminate help text makes the file more readable. Otherwise, it could be
omitted, in which case the text would terminate at the next "
:token
" or the end of the
file—whichever comes first.
23.2.2 More Help
The Spot Help window displays a More Help button when “More Help” is available. Alter-
natively, when Shift-Help is depressed, More Help is requested on the graphical object under
the pointer, but the Spot Help window is not displayed. The help mechanism provides More
Help when a field is added to the .info file, and More help is requested. The More Help field
specifies a shell command that is executed to provide additional help information.
:spot_help_token:more_help_shell_command
The more_help_shell_command includes everything from the character after the sec-
ond colon (:), to the character before the newline (\n). The More Help field should contain a
string that is used as an argument for an invocation with the system library routine. This
executes a command that provides help messages, or executes a help viewer (More Help).
For example, an entry in a .info file containing a token and description for the topic back,
and providing more help with the helpopen command, contains two fields as well as the
Spot Help text.
:Back:$OPENWINHOME/bin/helpopen handbooks/workspace.handbook
Choose Back to send the selected window to the
back of the window stack.
#
Prior to executing the system command, if the -display switch was specified on the com-
mand line, the help mechanism calls putenv() on the
DISPLAY environment variable. This
ensures that the help viewer, for example, helpopen above, is invoked on the display on
which the More Help request was issued.
560 XView Programming Manual
23.2.3 Text Help
Help information for a selected text string is presented using XView’s text help feature and
the HELP_STRING_FILENAME attribute. Text help allows XView to search for a string of text
and to display help information that is stored in a help file associated with the string of text.
The Ctrl-HELP sequence produces an ACTION_TEXT_HELP event which begins the text
help search. The window under the pointer will get an ACTION_HELP event and XView then
requests the contents of the primary selection, a text string. XView opens the file associated
with the window’s HELP_STRING_FILENAME attribute and searches for a matching text
string. If a match is found, the text’s associated filename and target, which are stored in a
second field in the HELP_STRING_FILENAME file, provide Spot Help, and/or More Help. If
any condition is not met, then a notice is displayed.
The sequence Shift-Ctrl-Help produces the semantic action ACTION_MORE_TEXT_HELP for
More help on a text string.
The HELP_STRING_FILENAME attribute contains the name of a file with a list of string pairs.
The file is searched for in the directories listed in the environment variable HELPPATH. Each
line in the file contains two words: the first word, which must be less than 128 characters, is
the string on which help is available. The second word, which must be less than 64 charac-
ters, is of the form “file:target,” which XView uses to find the Spot Help text.
HELP_STRING_FILENAME is set on the paint window, or on any of its owners where the help
strings are painted.
23.2.4 Displaying Help Manually
If the window corresponds to an XView package that handles its own events, such as Panels
or Menus, then XView displays the help frame automatically. All you need to provide is the
data for the help message by using the attribute
XV_HELP_DATA.
If you are handling events (such as a canvas) in the window, then you are responsible for dis-
playing the help frame as well as providing the help data. The function to accomplish this is
xv_help_show(). It takes the following form:
xv_help_show(window, help_data, event)
Xv_Window window;
char *help_data; /* "file:key" */
Event *event;
The window parameter is an XView window associated with an XView object. The
help_data parameter is a string identical to the value of XV_HELP_DATA discussed in the
previous section. The event parameter represents the event that caused the need for the
help window to be displayed. This event structure may be modified upon return, so it should
not be referenced after use.
Help Facilities
Help Facilities 561

Get Volume 7A: XView Programming Manual now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.