HP OpenVMS Systems Documentation

1. The name of the key-1 module is overview. You pass the string overview to the help widget. The help widget then searches the OpenVMS help library for a module with this name and displays the text. A module is terminated by either another key-1 name or by an end-of-file record.
2. The title that the help widget displays for the On Window topic is Overview of the Help Widget.
3. The name of the keyword topic to search for with the help widget Search function is overview.
4. The included topic key name from the programming module is programming creating create_help_widget. The title of the key identified by the =INCLUDE tag is displayed as an additional topic.
5. The name of the key-2 subentry in the Overview module is functions_1. The functions_1 subentry appears as an additional topic.

The help widget is a pop-up dialog box that is preconfigured to contain the child widgets, called subwidgets, it needs to implement its functions. Figure 4-2 shows a help widget with its component parts.

Figure 4-2 Help Widget Components

You can use the following help widget resources to modify the appearance of the help widget:

• XmNbuttonFontList
• XmNlabelFontList
• XmNtextFontList
• DXmNcols
• DXmNrows
• DXmNdefaultPosition

For example, the DXmNcols resource specifies the width, in characters, of the help text displayed by the help widget. The default is language dependent; the American English default is 55 characters.

The following UIL code fragment reduces the value of the DXmNcols resource to 50 columns.

object main_help : DXmHelpDialog
            {
            arguments
               {
               DXmNapplicationName = compound_string("Help Example");
               DXmNglossaryTopic   = compound_string("glossary");
               DXmNoverviewTopic = compound_string("overview");
               DXmNcols  = 50;
               };

            };

The help widget appearance resources are described in the DECwindows Extensions to Motif manual.

4.4.1 Modifying Help Widget Labels and Mnemonics

You can use the help widget label resources, described in the DECwindows Extensions to Motif manual, to modify the help widget labels.

For example, the DXmNapplicationName resource specifies the application name to be used in the help widget Help on... title bar. The default is null.

The following UIL code fragment sets the DXmNapplicationName resource to "Help Example":

object main_help : DXmHelpDialog
            {
            arguments
               {
               DXmNapplicationName = compound_string("Help Example");
               DXmNglossaryTopic   = compound_string("glossary");
               DXmNoverviewTopic = compound_string("overview");
               };
            };

The mnemonics resources allow you to change the key a user presses to activate a help widget menu item. For example, the DXmNhelpLabelMnem resource specifies which key the user can press (instead of clicking MB1) to activate the Help pull-down menu. The default is the letter U.

The following UIL code fragment sets the DXmNhelpLabelMnem resource to "H":

object main_help : DXmHelpDialog
            {
            arguments
               {
               DXmNapplicationName = compound_string("Help Example");
               DXmNglossaryTopic   = compound_string("glossary");
               DXmNoverviewTopic = compound_string("overview");
               DXmNhelpLabelMnem = keysym("H");
               };
            };

The help widget mnemonics resources are described in DECwindows Extensions to Motif.

The most common reason to modify the help widget label and mnemonics resources is for internationalization purposes.

4.4.2 Help Widget Messages

The help widget uses messages to provide status information to the user. You can use help widget resources to modify the text of these messages. The help widget message resources are described in DECwindows Extensions to Motif. Note that for OpenVMS applications, the !CS variable is replaced by the relevant compound string in the actual messages.

For example, the following UIL code fragment from an OpenVMS application changes the value of the DXmNbadlibMessage resource from "Couldn't open library !CS" to "TEST_HELP.HLB is missing":

object main_help : DXmHelpDialog
            {
            arguments
               {
               DXmNapplicationName = compound_string("Help Example");
               DXmNglossaryTopic   = compound_string("glossary");
               DXmNoverviewTopic = compound_string("overview");
               DXmNlibrarySpec  = compound_string("test_help.hlb");
               DXmNbadlibMessage = compound_string("TEST_HELP.HLB is missing");
               };

            };

The help widget supports the callbacks described in Table 4-3.

You can use the help widget resources described in Table 4-4 to specify the topics of the help widget.

If you specify a help topic identified by a subkey name, you must also specify the key names that form the path to the subkey name. The key names must be separated by at least one space.

For example, suppose you have the following module:

1 programming
2 creating
3 create_help_widget

If you want to display the create_help_widget key-3 help text as the first topic in the help widget, pass the compound string "programming creating create_help_widget".

This section describes general programming considerations for using the help widget.

The most basic approach to using the help widget is to create it, manage it to cause the help window to appear, and destroy it using the unmap callback routine when the user is finished. However, any changes to the help window, such as resizing, are lost when the widget is destroyed.

If your application destroys a help widget and then re-creates it, your application assumes the help widget creation overhead. On OpenVMS systems, an OpenVMS help library is initialized when it is first opened by the help widget and is cached in memory until the application closes down. Once a help widget initializes an OpenVMS help library on behalf of your application, the library is not reinitialized unless your application is restarted.

The recommended approach is to create the help widget once and use the same help widget each time the user requests help by specifying a new first topic in the DXmNfirstTopic resource (using the XtSetValues routine) and managing the widget (using the XtManageChild routine) to cause the help window to appear.

To use the help widget, perform the following steps:

1. If you are creating an application for OpenVMS systems, use the OpenVMS Librarian Utility to create an OpenVMS help library. See Section 4.2 for more information.
2. Create a Help menu bar item for your application. To conform with the guidelines of the OSF/Motif Style Guide, use the menu_help_widget resource of the menu bar widget to position the Help menu item at the right end of the menu bar. If the menu bar widget wraps onto additional lines, the menu bar widget positions the Help menu item at the bottom right of the menu bar.
3. Create a help pull-down menu widget with items such as On Context, On Window, On Version, and On Help.
   An application that does not support a specific Help menu item should not include that item in its help pull-down menu widget.
4. Create the help buttons for the pull-down menu widget. Create one push button widget for each topic on the help pull-down menu widget. The push button widgets are associated with the routines to call when the buttons are pressed.
5. Use any of the widget creation routines listed in Table 4-5 to create an instance of the help widget.

   Table 4-5 Help Widget Creation Routines

   UIL object type	Use the DXmHelpDialog object type identifier to create a help widget in a UIL module.
   Toolkit routine	Use the DXmCreateHelpDialog routine to create a help widget.

6. Optionally, specify the callback routine to be called when the help widget is unmapped.

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.

An example of a help callback routine (sens_help_proc) is described in Example 4-5.

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

4.7.1.1 Creating the On Context Push Button in UIL

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

   .
   .
   .

object help_menu_entry : XmCascadeButton {
            arguments {
                XmNlabelString = k_help_label_text;
                XmNmnemonic = keysym("H");
                };
            controls {
                XmPulldownMenu help_menu;
                };
            callbacks
                {
                XmNhelpCallback = procedure sens_help_proc(k_help_help);
                };
            };


object help_menu : XmPulldownMenu
            {
            controls
                {
                XmPushButton help_sensitive;
                XmPushButton help_window;
                XmPushButton help_version;
                XmPushButton help_onhelp;
                };
            callbacks
                {
                XmNhelpCallback = procedure sens_help_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 sens_help_proc(k_sensitive_help);
                };
            };

   .
   .
   .

1. When the user clicks the On Context push button, the activate callback calls a routine to enter context-sensitive help mode. The On Context push button also has a context-sensitive help callback.

The activate callback for the On Context push button calls a routine to enter context-sensitive help mode, as shown in Example 4-3. Note that all of the push buttons in OpenVMS DECburger call back to the activate_proc routine. However, your application could directly invoke the context-sensitive help callback from the On Context push button.

   .
   .
   .

static void activate_proc(w, tag, reason)
    Widget              w;
    int                 *tag;
    XmAnyCallbackStruct *reason;
{
    int      widget_num = *tag;       /* Convert tag to widget number. */
    int      i, value;
    XmString topic;

    switch (widget_num) {
    .
    .
    .

        (1)case k_help_sensitive:
            tracking_help();
            break;

   .
   .
   .
static void tracking_help()

{
      (2)DXmHelpOnContext(toplevel_widget, FALSE);
}

   .
   .
   .

1. When the activate_proc routine is called with a tag that identifies the On Context push button, a context-sensitive help routine (tracking_help) is called.
2. The DXmHelpOnContext changes the pointer cursor to the help cursor and grabs it. (The application is in context-sensitive help mode.) The user then moves the pointer cursor to the object for which context-sensitive help is required and clicks MB1.
   If the selected widget has a help callback, that help callback is invoked. If the selected widget does not have a help callback, the widget's ancestors are tested until a help callback is found or the top of the widget hierarchy is reached.
   The DXmHelpOnContext routine is called with the name of the application's top-level widget and a Boolean value that indicates whether you want the locating activity confined to that widget.
   If you confine the help pointer cursor to the application's top-level widget (a Boolean value of TRUE), the user will not be able to move the help pointer cursor outside the boundaries of the main window. This means that the user cannot get context-sensitive help on pop-up widgets that extend beyond the boundaries of the top-level widget.
   If you do not confine the help pointer cursor to the application's top-level widget (a Boolean value of FALSE), the user can potentially get context-sensitive help on any of the application's widgets.
   The previous example does not confine the help pointer cursor.

Your application uses the XmNhelpCallback resource to associate a help callback routine with the widgets for which you want to provide help.

Your application can use the callback's tag argument to supply application-specific data. For example, the widgets in the OpenVMS DECburger application supply the help callback routine with a compound string value that specifies the help topic, as shown in Example 4-4.

The string value for the Help System callback is described in Chapter 5.

   .
   .
   .
!Compound strings to use for context-sensitive help callbacks

value
        k_order_help            :  compound_string ("order");
        k_print_help            :  compound_string ("print");
        k_options_help          :  compound_string ("options");
        k_menu_bar_help         :  compound_string ("menu_bar");
        k_file_help             :  compound_string ("file_menu");
        k_edit_help             :  compound_string ("edit_menu");
        k_order_menu_help       :  compound_string ("order_menu");
        k_help_help             :  compound_string ("help");
        k_sensitive_help        :  compound_string ("sensitive");
        k_onhelp_help           :  compound_string ("onhelp");
        k_about_help            :  compound_string ("about");
        k_overview_help         :  compound_string ("overview");
        k_nyi_help              :  compound_string ("not_implemented");


!String value to use for the Help System callback

value
        helpsys_order_help            :  'order';

   .
   .
   .


object
    s_menu_bar : XmMenuBar {

        arguments {
            XmNorientation = XmHORIZONTAL;
            XmNmenuHelpWidget = XmCascadeButton help_menu_entry;
        };

        controls {
            XmCascadeButton file_menu_entry;
            XmCascadeButton edit_menu_entry;
            XmCascadeButton order_menu_entry;
            XmCascadeButton options_menu_entry;
            XmCascadeButton help_menu_entry;
        };
        callbacks {
            MrmNcreateCallback = procedure create_proc (k_menu_bar);
            (1)XmNhelpCallback    = procedure sens_help_proc(k_menu_bar_help);
        };
    };
   .
   .
   .

1. The help callback routine uses this compound string to set the DXmNfirstTopic resource.

Example 4-5 shows how the OpenVMS DECburger application help callback routine calls a creation routine (create_help) to set the DXmNfirstTopic resource. See Example 4-7 for a complete description of create_help.

   .
   .
   .
static void sens_help_proc(w, tag, reason)
    Widget              w;
    XmString            *tag;
    XmAnyCallbackStruct *reason;
{
     create_help(tag);
}

   .
   .
   .