Responding to Hyperlink Events

Your application needs to provide support only for the types of hyperlinks used within the help volume to be displayed. In general, it is recommended that you provide support for all link types.

For your application to be notified when a hyperlink is chosen, it must add a hyperlink callback to the help dialog. You must write a callback function that handles the hyperlink appropriately.

To Provide a Hyperlink Callback

1. Add a hyperlink callback to each help dialog as shown:

   XtAddCallback (helpDialog, DtNhyperlLinkCallback,
                   HyperlinkCB, (XtPointer)NULL);

   Where helpDialog is the widget ID of the help dialog and HyperlinkCB is the name of the callback function for handling hyperlinks.

2. Write the HyperlinkCB function to handle the hyperlink events that can occur within the dialog.

   Within the hyperlink callback, you have access to the following callback structure (which is declared in <Dt/Help.h>):

   typedef struct
    	{
   		int      reason;
   		XEvent  *event;
   		char    *locationId; 
   		char    *helpVolume;
   		char    *specification;
   		int      hyperType;
   		int      windowHint;
   } DtHelpDialogCallbackStruct;

   The hyperType element indicates which type of link was executed. Its possible values are: DtHELP_LINK_TOPIC, DtHELP_LINK_MAN_PAGE, DtHELP_LINK_APP_DEFINE, or DtHELP_LINK_TEXT_FILE. For a description of which structure elements are valid for different types refer to the DtHelpDialog(3) man page.

   The windowHint element indicates a window type. Its possible values are: DtHELP_CURRENT_WINDOW, DtHELP_POPUP_WINDOW, or DtHELP_NEW_WINDOW.

Example

The following function, HyperlinkCB(), illustrates the general structure needed to handle hyperlink callbacks.

XtCallbackProc
HyperlinkCB (widget, clientData, callData)
      Widget     widget;
      XtPointer  clientData;
      XtPointer  callData;
   {
      DtHelpDialogCallbackStruct *hyperData =
         (DtHelpDialogCallbackStruct *) callData;
      switch ((int)hyperData-> hyperType)
         {
            case DtHELP_LINK_TOPIC:
              /* Handles  "jump new view"hyperlinks. */
              break;
            case DtHELP_LINK_MAN_PAGE:
              /* Handles  "man page" hyperlinks. */
              break;
            case DtHELP_LINK_APP_DEFINE:
              /* Handles ``application-defined" hyperlinks. */
              break;
            case DtHELP_LINK_TEXT_FILE:
              /* Handles ``text file" hyperlinks. */
              break;
            default:
              break;
    }