10 Responding to Help Requests

widget

The widget where you want to activate the help key.

HelpRequestCB()

The function in your application that handles the help request when the user presses the help key.

clientData

The data you want passed to the HelpRequestCB() function. Typically, this data identifies the topic to be displayed.

If no help callbacks are found, nothing happens. Therefore, it is recommended that you add a help callback to each shell in your application. This ensures that no user requests for help are lost.

Adding a help callback to a dialog shell automatically enables the Help button on the dialog to invoke the help callback.

Importance of Client Data

Example

For this example, assume that the application's user interface is just a main window with three input fields: Name, Address, and Telephone Number. Here's what the HelpEntryIds.h file would contain:

#define HELP_volumeName            "MyVolume"

#define HELP_MainWindow            100 
#define HELP_MainWindow_ID         "basic-tasks" 
#define HELP_MainWindow_ITEM_ID    "main-window-desc" 


#define HELP_NameField             101 
#define HELP_NameField_ID          "specifying-a-name" 
#define HELP_NameField_ITEM_ID     "name-field-desc" 


#define HELP_AddressField          102 
#define HELP_AddressField_ID       "specifying-an-address" 
#define HELP_AddressField_ITEM_ID  "address-field-desc" 


#define HELP_PhoneField            103 
#define HELP_PhoneField_ID         "specifying-a-phone-no" 
#define HELP_PhoneField_ITEM_ID    "phone-field-desc"

XtAddCallback (mainWindow, DtNhelpCallback,
               HelpRequestCB, HELP_MainWindow); 
XtAddCallback (nameField, DtNhelpCallback,
               HelpRequestCB, HELP_NameField); 
XtAddCallback (addressField, DtNhelpCallback,
               HelpRequestCB, HELP_AddressField);
XtAddCallback (phoneField, DtNhelpCallback,
               HelpRequestCB, HELP_PhoneField);

XtCallbackProc HelpRequestCB (
      Widget     w,
      XtPointer  clientData,
      XtPointer  callData )
{
   char    *topicToDisplay;
   Boolean  useQuickHelpDialog;
   /* Determine the topic ID for the given ` clientData.' */
   switch ((int)clientData)
     {
       case HELP_MainWindow:
         useQuickHelpDialog = False;
         if (itemHelpFlag)
           topicToDisplay = HELP_MainWindow_ITEM_ID;
         else
           topicToDisplay = HELP_MainWindow_ID;
         break;       case HELP_NameField:
         useQuickHelpDialog = True;
         if (itemHelpFlag)
           topicToDisplay = HELP_NameField_ITEM_ID;
         else
           topicToDisplay = HELP_NameField_ID;
         break;       case HELP_AddressField:
         useQuickHelpDialog = True;
         if (itemHelpFlag)
           topicToDisplay = HELP_AddressField_ITEM_ID;
         else
           topicToDisplay = HELP_AddressField_ID;
         break;       case HELP_PhoneField:
         useQuickHelpDialog = True;
         if (itemHelpFlag)
           topicToDisplay = HELP_PhoneField_ITEM_ID;
         else
           topicToDisplay = HELP_PhoneField_ID;
         break;       default:
         /* An unknown clientData was received. */
         /* Put your error handling code here. */
         return;
         break;
     }
   /* Display the topic. */
   ac = 0;
   XtSetArg (al[ac], DtNhelpType,   DtHELP_TYPE_TOPIC); ac++;
   XtSetArg (al[ac], DtNhelpVolume, HELP_volumeName);    ac++;
   XtSetArg (al[ac], DtNhelpType,   topicToDisplay);     ac++;
   if (useQuickHelpDialog)
     {
        XtSetValues (mainQuickHelpDialog, al, ac);
        XtManageChild (mainQuickHelpDialog);
     }
   else
     {
        XtSetValues (mainHelpDialog, al, ac);
        XtManageChild (mainHelpDialog);
     }
   /* Clear the ` item help' flag. */
   itemHelpFlag = False;
 }

Providing a Help Menu

The most important commands include:

• Introduction displays the home topic of your application's help, allowing the user to use hyperlinks to navigate to any desired information.

• Using Help displays help on help. This is information that tells the user how to use the Help System.

• Version displays your application's version and copyright information. The copyright topic (created using the <copyright> element) has the ID _copyright.

See Also

• "To Create a Home Topic" describes how authors create the home topic for a help volume.

• "To Create a Meta Information Section" describes how authors create a copyright topic.

• Chapter 12, "Providing Help on Help," describes how help on help is found and how to add it to your application.

Supporting Item Help Mode

The convenience function, DtHelpReturnSelectedWidgetId(), changes the pointer to a question mark and waits for the user to pick a widget. The ID of the selected widget is returned. This function is similar to the XmTrackingLocate() function except that DtHelpReturnSelectedWidgetId() returns NULL if the user presses Escape to cancel the operation.

To display help on the selected item, your application can simply invoke the help callback for the returned widget. This is equivalent to the user pressing F1 while using that widget.

If you want the application to differentiate between item help and F1 help, you can set a flag before calling the widget's help callback. The help callback procedure can then use that flag to determine that the callback was invoked as a result of item help and alter its response accordingly.

To Add Support for Item Help

1. Write a function that uses the DtHelpReturnSelectedWidgetId() function. Within this function, invoke the help callback for the selected widget. In the following steps, this function is called ProcessOnItemHelp(), but you can name it whatever you want.

2. Add to your Help menu a command button labeled On Item. Add an activate callback that invokes your ProcessOnItemHelp() function.

3. Add a help callback to each widget in your application where you want item help to be available.

Example

void  ProcessOnItemHelp(
   Widget widget)
{
 /* Declare a variable for the selected widget. */ 
  Widget selWidget=NULL;
  int status=DtHELP_SELECT_ERROR;
  /* Get an application shell widget from our widget hierarchy to
       * pass into DtHelpReturnSelectedWidgetId().
   */
  while (!XtIsSubclass(widget, applicationShellWidgetClass))
                   widget = XtParent(widget);
  status = DtHelpReturnSelectedWidgetId(widget, NULL, &selWidget);
  switch ((int)status)
    {
      case DtHELP_SELECT_ERROR:
        printf("Selection Error, cannot continue\n");
      break;
      case DtHELP_SELECT_VALID:
         /* We have a valid widget selection, now let's look for a  registered help
                       * callback to invoke.
          */
         while (selWidget != NULL)
          {
            if ((XtHasCallbacks(selWidget, XmNhelpCallback)
                                     == XtCallbackHasSome))
              {
                /* Found a help callback, so just call it */
                XtCallCallbacks((Widget)selWidget,
                                XmNhelpCallback,NULL);
                break;
              }
            else
              /* No help callback on current widget, so try the widget's parent  */
                 selWidget = XtParent(selWidget);
          }
      break;
      case DtHELP_SELECT_ABORT:
        printf("Selection Aborted by user.\n");
      break;
      case DtHELP_SELECT_INVALID:
        printf("You must select a component within your app.\n");
      break;
    }
}