1. The On Window push button in the Help pull-down menu. The topic variable is used to store a compound string that identifies a help library key name, in this case "overview". The string must match the key name in the OpenVMS help library. The compound string is later used as the value of the DXmNfirstTopic resource.
2. The sens_help_proc callback is called as a result of a help callback, as described in Section 4.7.1. The sens_help_proc calls the generic create_help routine.
3. The create_help routine creates an instance of the help widget for the push buttons in the Help pull-down menu and for context-sensitive help callbacks.
   If the help widget does not already exist, create_help fetches it.
   If the help widget exists and is already managed, create_help is obliged to fetch a new instance of the help widget. The help_widget[help_num] variable is an array of help widgets equal to the maximum number of widgets in the OpenVMS DECburger application. Set the DXmNfirstTopic resource using the specified compound string and manage the help widget.
   If the help widget now exists but is not already managed, set the DXmNfirstTopic resource using the specified compound string and manage the help widget.

As described in Section 4.7, you can implement the help widget through UIL or through the Toolkit help widget creation routine.

Example 4-9 demonstrates how to create a help widget using the Toolkit help widget creation routine.

Example 4-9 Creating Help Widget with Toolkit Routine

. . . static Widget help_array[MAX_WIDGETS], /* Array of help widgets for Toolkit*/ . . . static int low_num = 0; /* make sure it starts zero */ . . . /* Initialize help widgets for Toolkit creation. */ for (i = 0; i < MAX_WIDGETS; i++) help_array[i] = NULL; . . . /* * Context sensitive help callback. */ */ (1)static void sens_help_proc(w, tag, reason) Widget w; XmString *tag; XmAnyCallbackStruct *reason; { create_help(tag); } . . . /* Toolkit help creation routine */ static void create_help (topic) XmString topic; { unsigned int ac; Arg arglist[10]; XmString appname, glossarytopic, overviewtopic, libspec; static Widget help_widget = NULL; (2)if (!help_widget) { ac = 0; appname = XmStringCreateLtoR("Toolkit Help", XmSTRING_ISO8859_1); glossarytopic = XmStringCreateLtoR("glossary", XmSTRING_ISO8859_1); overviewtopic = XmStringCreateLtoR("overview", XmSTRING_ISO8859_1); libspec = XmStringCreateLtoR("decburger.hlb", XmSTRING_ISO8859_1); XtSetArg(arglist[ac], DXmNapplicationName, appname); ac++; XtSetArg(arglist[ac], DXmNglossaryTopic, glossarytopic); ac++; XtSetArg(arglist[ac], DXmNoverviewTopic, overviewtopic); ac++; XtSetArg(arglist[ac], DXmNlibrarySpec, libspec); ac++; XtSetArg(arglist[ac], DXmNfirstTopic, topic); ac++; help_widget = DXmCreateHelpDialog (toplevel_widget, "Toolkit Help", arglist, ac); XmStringFree(appname); XmStringFree(glossarytopic); XmStringFree(overviewtopic); XmStringFree(libspec); XtManageChild(help_widget); return; } (3)if (XtIsManaged(help_widget)) { ac = 0; appname = XmStringCreateLtoR("Toolkit Help", XmSTRING_ISO8859_1); glossarytopic = XmStringCreateLtoR("glossary", XmSTRING_ISO8859_1); overviewtopic = XmStringCreateLtoR("overview", XmSTRING_ISO8859_1); libspec = XmStringCreateLtoR("decburger.hlb", XmSTRING_ISO8859_1); XtSetArg(arglist[ac], DXmNapplicationName, appname); ac++; XtSetArg(arglist[ac], DXmNglossaryTopic, glossarytopic); ac++; XtSetArg(arglist[ac], DXmNoverviewTopic, overviewtopic); ac++; XtSetArg(arglist[ac], DXmNlibrarySpec, libspec); ac++; XtSetArg(arglist[ac], DXmNfirstTopic, topic); ac++; help_array[low_num] = DXmCreateHelpDialog (toplevel_widget, "Toolkit Help", arglist, ac); XmStringFree(appname); XmStringFree(glossarytopic); XmStringFree(overviewtopic); XmStringFree(libspec); XtManageChild(help_array[low_num]); low_num++; return; } (4)ac = 0; XtSetArg (arglist[ac], DXmNfirstTopic, topic); ac++; XtSetValues (help_widget, arglist, ac); XtManageChild(help_widget); } . . .

1. The help-callback routine (sens_help_proc) calls the create_help routine to create the help widget.
2. The create_help routine tests to see if the help widget already exists. If it does not already exist, create_help sets the DXmNapplicationName, DXmNglossaryTopic, DXmNoverviewTopic, DXmNlibrarySpec, and DXmNfirstTopic resources and calls the DXmCreateHelpDialog routine. The create_help routine then calls XtManageChild to manage the help widget.
3. If the help widget already exists and is managed, the create_help routine is obliged to create another instance of the help widget. The help_array array is an array of help widgets equal to the maximum number of widgets in the OpenVMS DECburger application.
4. If the help widget now exists but is not managed, set the DXmNfirstTopic resource and manage it.

In addition to the help widget described in Chapter 4, DECwindows Motif applications can use the DECwindows Motif Help System (help system) to display general and context-sensitive information in response to a user request. The help system uses Bookreader and LinkWorks to display and navigate through decw_book (UNIX systems) or DECW$BOOK (OpenVMS systems) format help text and graphics. You can use DECwrite to create the files for Bookreader to display. On OpenVMS for VAX systems, you can also use VAX DOCUMENT to create hyperhelp files. (Note that Bookreader is not available on Windows NT systems, so the information in this chapter is not relevant for applications running only on that operating system.)

This chapter describes how to use the help system in an application. The following topics are discussed:

• An overview of the help system
• Invoking the help system
• Help file information
• Context-sensitive help callbacks
• Implementing the help system

The OpenVMS DECburger demo program uses the help system to implement context-sensitive help for widgets in the Order control box. To become familiar with the operation of the help system, run DECburger and request context-sensitive help for any item in the Order control box.

The help system uses the DECwindows Bookreader as its display window. The help system routines allow your application to invoke Bookreader and specify the book, as well as the specific topic or directory within that book, to display first. In addition, once Bookreader is invoked through the help system, it remains available until the user explicitly closes it or ends the DECwindows session.

The help system provides the following Bookreader features to users of your application:

• Proportional fonts
• Graphics
• Formatted tables
• Hotspots
• The ability to create links between the online help and other pieces of information, such as mail messages and other Bookreader topics, via LinkWorks

Figure 5-1 shows a comparison of the help widget and the help system.

Figure 5-1 Comparison of Help Widget and the Help System Windows

To implement the help system, perform the following steps:

1. Use one of the methods described in Section 5.3 to create a help file.
2. Create a Help pull-down menu with push-button widgets (or gadgets) for your chosen help topics.
   The help menu required to implement the help system is identical to the help menu required for the help widget. If you have already implemented a help menu for the help widget, you can use this menu with only minor modifications to the help callbacks.
   The labels for the push buttons should indicate the types of help available. The OSF/Motif Style Guide suggests that applications include the following topics in the help pull-down menu widget, when appropriate to the application:
   • On Context---Provides context-sensitive information.
   • On Window---Provides overview information for the window.
   • Index---Provides an index, with search capability, for all help information in the application.
   • On Keys---Provides information about the application's use of keys, mnemonics, and keyboard accelerators.
   • Tutorial---Provides access to the application's tutorial, if one exists.
   • On Help---Provides information about how to use the application's help facility.
   • On Version---Provides information about the application, such as its formal name and version number.
   
   You can also add application-specific help topics.
3. Add XmNhelpCallbacks help callbacks for each widget for which you want to provide context-sensitive help, as described in Section 5.5.3.
4. Implement the three help-system routines in your application:
   • DXmHelpSystemOpen does all of the initialization work required by LinkWorks and prepares to display a topic from the help file name passed to it. This routine needs to be called just before the main loop of the application.
   • DXmHelpSystemDisplay displays the topic or directory of the help file in Bookreader, depending on the arguments passed to it. It is also used to open topics and/or directories of books other than the one passed to DXmHelpSystemOpen.
     DXmHelpSystemDisplay is called as the result of the activate callback of the push buttons in the help menu or as the result of a widget's context-sensitive help callback.
   • DXmHelpSystemClose is used to close all of the remaining topic and navigation windows in Bookreader. This routine should be called when the application is closing down all of its other windows.

A user can invoke the help system in four ways:

• The user clicks on a push button in the Help pull-down menu. The push button's activate callback routine calls a routine to invoke the help system.
• The user clicks on the On Context push button in the Help pull-down menu. The push button's activate callback routine invokes the DXmOnContext routine to enter context-sensitive help mode. The user then moves the pointer to some object and clicks MB1. The selected object's help callback is then invoked to display context-sensitive help on the object or on its nearest ancestor with context-sensitive help available. This is called context-sensitive help.
• The user moves the input location to an object and presses the Help key on the keyboard. The selected object's help callback is then invoked to display context-sensitive help on the object or on its nearest ancestor with context-sensitive help available.
  Note that users cannot use the Help key to generate context-sensitive help for widgets that do not accept input focus, such as XmLabel widgets.
• The user types a help topic command string in a command window widget. Your application must include a command window widget to support this mechanism.

As an application developer, you must decide which help invocation methods to support. Most DECwindows applications support invoking help by clicking on a help option in the menu bar and through context-sensitive help.

5.3 Help File Information

You can use VAX DOCUMENT on OpenVMS for VAX systems or DECwrite to create Bookreader files for the help system. The remainder of this section uses a help file created using VAX DOCUMENT for the purpose of example.

5.4 Help File Information---VAX DOCUMENT Example

Help-system help files created with VAX DOCUMENT are standard SDML files processed with the SOFTWARE.ONLINE document type for Bookreader output.

You can use any standard section tag (<HEADn>) as a help topic. The symbol name associated with the tag <HEADn\symbolic_name> must match the topic identifier specified in the UIL file.

Example 5-1 shows the DECBURGER.DECW$BOOK file as a VAX DOCUMENT DECBURGER_HELP.SDML file. Note that topics identified by INCLUDE commands in the HLP file are identified by <HOTSPOT> tags in the SDML file. Also note that for the help system you need to specify only the topic identifier in the symbolic name. (The help widget uses the key name hierarchy to find the help topic and requires the key names that form a path to the topic.)

Example 5-1 DECBURGER_HELP.SDML Help File

(1)<FRONT_MATTER>(dwhlp_front) <TITLE_PAGE> <TITLE>(Help on DECburger) <ENDTITLE_PAGE> <CONTENTS_FILE> <ENDFRONT_MATTER> <HEAD1>(Overview of the Help Widget\overview) <P> A help widget is a modeless widget that allows you to display appropriate, context-sensitive help text in response to a user query. The help widget can be viewed as an independent application that your application calls to provide help functions. <P> The help widget creates and manages one or more help windows and determines the first topic to be displayed to the user. <P> Additional topics: <LIST>(UNNUMBERED) (2)<LE><HOTSPOT>(functions_1) <LE><HOTSPOT>(create_help_widget) <ENDLIST> <HEAD2>(Using the Help widget\functions_1) <P> To use the help widget, you perform the following steps: <LIST>(NUMBERED\1) <LE>Use the OpenVMS Librarian Utility (LIBRARIAN) to create a help library. <LE>Create a Help menu bar item for your application. The Help menu item should be located at the right of the menu bar. If the menu bar is wider than a line, the Help menu item should be located at the bottom right. <ENDLIST> <HEAD1>(About the Help Widget\about) <P> This topic provides version information. <P> Additional topics: <LIST>(UNNUMBERED) <LE><HOTSPOT>(create_help_widget) <ENDLIST> <HEAD1>(Help Widget On Help\onhelp) <P> This topic provides help-on-using-help information. <P> Additional topics: <LIST>(UNNUMBERED) <LE><HOTSPOT>(create_help_widget) <ENDLIST> <HEAD1>(Menu Bar Context Sensitive Help\menu_bar) <HEAD1>(File Menu Context Sensitive Help\file_menu) <HEAD1>(Edit Menu Context Sensitive Help\edit_menu) <HEAD1>(Not Yet Implemented\not_implemented) <HEAD1>(Order Menu Context Sensitive Help\order_menu) <HEAD1>(Order Context Sensitive Help\order) <P> Order menu context-sensitive help <P> Additional topics: <LIST>(UNNUMBERED) <LE><HOTSPOT>(burgers) <LE><HOTSPOT>(fries) <LE><HOTSPOT>(drink) <LE><HOTSPOT>(apply) <LE><HOTSPOT>(dismiss) <LE><HOTSPOT>(create_help_widget) <ENDLIST> <HEAD2>(Burgers For Us\burgers) <P> Additional topics: <LIST>(UNNUMBERED) <LE><HOTSPOT>(burgers_rare) <LE><HOTSPOT>(burgers_medium) <LE><HOTSPOT>(burgers_well) <LE><HOTSPOT>(burgers_ketchup) <LE><HOTSPOT>(burgers_mustard) <LE><HOTSPOT>(burgers_onion) <LE><HOTSPOT>(burgers_mayo) <LE><HOTSPOT>(burgers_pickle) <LE><HOTSPOT>(burgers_quantity) <ENDLIST> <HEAD3>(Burgers For Us\burgers_rare) <HEAD3>(Burgers Medium For Us\burgers_medium) <HEAD3>(Burgers Well For Us\burgers_well) <HEAD3>(Burgers Ketchup For Us\burgers_ketchup) <HEAD3>(Burgers Mustard For Us\burgers_mustard) <HEAD3>(Burgers Onion For Us\burgers_onion) <HEAD3>(Burgers Mayo For Us\burgers_mayo) <HEAD3>(Burgers Pickle For Us\burgers_pickle) <HEAD3>(Burgers Quantity\burgers_quantity) <HEAD2>(Fries For Us\fries) <P> Additional topics: <LIST>(UNNUMBERED) <LE><HOTSPOT>(fries_tiny) <LE><HOTSPOT>(fries_small) <LE><HOTSPOT>(fries_medium) <LE><HOTSPOT>(fries_large) <LE><HOTSPOT>(fries_huge) <LE><HOTSPOT>(fries_quantity) <ENDLIST> <HEAD3>(Tiny Fries\fries_tiny) <HEAD3>(Small Fries\fries_small) <HEAD3>(Medium Fries\fries_medium) <HEAD3>(Large Fries\fries_large) <HEAD3>(Huge Fries\fries_huge) <HEAD3>(Fries Quantity\fries_quantity) <HEAD2>(Drink Choices\drink) <P> Additional topics: <LIST>(UNNUMBERED) <LE><HOTSPOT>(drink_list) <LE><HOTSPOT>(drink_quantity) <LE><HOTSPOT>(drink_add) <LE><HOTSPOT>(drink_sub) <ENDLIST> <HEAD3>(Drink List\drink_list) <HEAD3>(Drink Quantity\drink_quantity) <HEAD3>(Drink Add\drink_add) <HEAD3>(Drink Subtract\drink_sub) <HEAD2>(Help on Apply\apply) <P> This topic provides information on both Apply and Reset. <HEAD2>(Help on Dismiss\dismiss) <HEAD1>(Help on Custom Colors\customize) <HEAD1>(Help on Print Order\print) <HEAD1>(Programming Help\programming) <P> Programming help. <P> Additional topics: <LIST>(UNNUMBERED) <LE><HOTSPOT>(creating) <ENDLIST> <HEAD2>(Creating a Help widget\creating) <P> Creating a help widget. <P> Additional topics: <LIST>(UNNUMBERED) <LE><HOTSPOT>(create_help_widget) <ENDLIST> <HEAD3>(Creating a Help widget\create_help_widget) <P> Programming help for creating a help widget. <HEAD1>(Help Widget Glossary\glossary) <P> This topic provides glossary information. <P> Additional topics: <LIST>(UNNUMBERED) <LE><HOTSPOT>(create_help_widget) <ENDLIST>

1. Because it is processed as a Bookreader book, the file must include front matter tags. The file must also be processed with the /CONTENTS command line qualifier. You can also process the file with the /INDEX command line qualifier if you have index entries in the SDML file.
2. Subordinate <HEADn> tags added are not automatically included in the "additional topics" list of the next-highest previous head (parent). That is, <HEAD2>(Using the Help widget) would not be automatically included as an additional topic under <HEAD1>(Overview of the Help Widget). You must add an <LE><HOTSPOT>(functions_1) tag for this purpose.

When you invoke the help system, you pass a help file specification to the DXmHelpSystemOpen routine. The default location is SYS$HELP and the default file extension is DECW$BOOK, but you can provide your own location or extension along with the help file name. The help system uses this specification to locate and read the help file.

For example, you can define a symbolic name for the help file specification:

#define decburger_help "decw$examples:decburger_help.decw$book"

Then pass this symbolic name as the help file specification:

DXmHelpSystemOpen(&help_context, toplevel_widget, decburger_help, help_error, "Help System Error");

5.5 Context-Sensitive Help Callbacks

In context-sensitive help, the application presents direct help on the current topic rather than starting at a higher level and working down through a help hierarchy. Users do not have to navigate through several layers of help to find the information they need.

All widgets that are a subclass of the XmPrimitive or XmManager widget class support a help callback with a reason of XmCR_HELP. (Other widgets can also support the help callback, but there is no requirement to do so.) Your application uses this help callback to implement context-sensitive help by associating a help callback routine with the widgets for which you want to provide help.

The Toolkit includes a routine, DXmHelpOnContext, that applications can use to enter context-sensitive help mode.

Example 5-4 shows a sample help callback routine.

The remainder of this section describes how to implement context-sensitive help.

5.5.1 Creating the On Context Push Button in UIL

Example 5-2 shows how to create an On Context push button in the Help pull-down menu.

Example 5-2 The On Context Push Button in UIL

. . . object help_menu_entry : XmCascadeButton { arguments { XmNlabelString = k_help_label_text; XmNmnemonic = keysym("H"); }; controls { XmPulldownMenu help_menu; }; callbacks { XmNhelpCallback = procedure help_system_proc(k_help_help); }; }; object help_menu : XmPulldownMenu { controls { XmPushButton help_sensitive; XmPushButton help_window; XmPushButton help_version; XmPushButton help_onhelp; }; callbacks { XmNhelpCallback = procedure help_system_proc(k_help_help); }; }; object help_sensitive : XmPushButton { arguments { XmNlabelString = k_sensitive_label_text; XmNmnemonic = keysym("C"); }; callbacks { (1)XmNactivateCallback = procedure activate_proc (k_help_sensitive); XmNhelpCallback = procedure help_system_proc(k_sensitive_help); }; }; . . .