Common Desktop Environment: Help System Author's and Programmer's Guide

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.

    If the selected widget does not have a help callback, the application should try its parent widget. Similarly, if the parent does not have a help callback, the application should continue to walk up the widget hierarchy until it finds a help callback.


The following procedure is a sample ProcessOnItemHelp() function that would be invoked by choosing On Item from the Help menu.

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");
          /* 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 */
              /* No help callback on current widget, so try the widget's parent  */
                 selWidget = XtParent(selWidget);
       case DtHELP_SELECT_ABORT:
         printf("Selection Aborted by user.\n");
         printf("You must select a component within your app.\n");