# Handling Events in Help Dialogs

This chapter describes several Help dialog events that an application must be equipped to handle.

HRDC.DiaEv.mkr.2
HRDC.DiaEv.mkr.3
HRDC.DiaEv.mkr.5
HRDC.DiaEv.mkr.6

## Supporting Help Dialog Events

Like other widgets within your application, help windows have some behavior that must be supported by the application.

### Hyperlink Events

Most standard hyperlink events are handled internally by the Help System. However, there are four types of hyperlinks that your application is responsible for handling:

- Jump-new-view hyperlinks —Your application must create a new help dialog to honor the author's request for a topic to be displayed in a new help window.

- Man page links—Your application must create a new quick help dialog (or get one from your cache) to display a man page. Typically, the size of man page windows is different from all other help windows.

- Application-defined links—Your application must interpret the data associated with these links. Application-defined links exist only if you and the author have collaborated to create them.

- Text file links—Your application must create a quick help dialog (or get one from you cache) to display the text file.

### When Dialogs Are Dismissed

When the user closes a help dialog, your application needs to know so it can store the dialog in its cache, or destroy it. The general help dialog supports a help closed callback. To detect when a quick dialog is dismissed, add a callback to its Close button.

### Quick Help Buttons

The behavior for some of the buttons in quick help dialogs must be handled by your application. These buttons can be managed and unmanaged as needed. You add behavior just like any other push button: using an activate callback.

#### See Also

- describes the types of links supported by the Help System and explains how to create them.

## 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;
       }

## Detecting When Help Dialogs Are Dismissed

To detect when a general help dialog is closed, add the following callback to the dialog:

    XtAddCallback (helpDialog, DtNcloseCallback,
                   HelpCloseCB, (XtPointer)NULL);

Where helpDialog is the widget ID for the help dialog and HelpCloseCB is the name of the callback procedure you've written to handle closing dialogs.

To detect when a quick help dialog is closed, add the following callback to the dialog's OK button:

    XtAddCallback (DtHelpQuickDialogGetChild ( helpDialog,
    DtHELP_QUICK_OK_BUTTON), XmNactivateCallback, HelpCloseCB,
    (XtPointer)NULL);

Where helpDialog is the widget ID for the help dialog and HelpCloseCB is the name of the callback procedure you've written to handle closing dialogs.

## Using the Application-Configured Button

The quick help dialog's application-configured button lets you add custom behavior to any quick help dialog. This button can be used for anything you want, but its intended purpose is to provide a path to more help in one of these two ways:

- Lets the user progressively ask for more information. This is sometimes called progressive disclosure. In this case, the default button label (More) is appropriate.

- Lets the user open a general help dialog for general browsing of the application's help volume. In this case, Browse… is the most appropriate button label.

### To Enable the Application-Configured Button

1. Get the button's ID.

2. Add an activate callback to the button.

3. Manage the button.

#### Example

The following code segment gets the button's ID, assigns a callback, and manages the button. It assumes that `quickHelpDialog` was just created.

    Widget  moreButton;
    moreButton = DtHelpQuickDialogGetChild (quickHelpDialog,
                                         DtHELP_QUICK_MORE_BUTTON);
    XtAddCallback (moreButton, XmNactivateCallback,
                   MoreHelpCB, NULL);
    XtManageChild (moreButton);

#### See Also

- HRDC.CrDia.mkr.7

- `DtHelpDialog`(3) man page

- `DtHelpQuickDialog`(3) man page

### To Access DtInfo by Using the "More" Button

As an extension to the desktop DtHelp facility, an application may add a local callback for the "More" button on the quick help dialog, which subsequently invokes dtinfo for additional information related to the quick help presentation, and/or directly invokes DtInfo for detailed help (such as for "On Application" or "On Window").

If you want your application to provide the user access to a local information corpus at a specific point of relevance, you use the built-in function `DtActionInvoke()`. The anchor point may be as broad as the top of a bookcase, or as fine as a specific section. Targets within sections are also possible, as long as they have been given externally unique link IDs during construction of the data.

#### Example

This section describes the use of the CDE desktop action API to invoke (or connect to) DtInfo.

Before `DtActionInvoke` is called, the application must first call `DtInitialize` to initialize the desktop services library, and `DtDbLoad` to load the actions and datatypes database. Since the DtInfo actions and datatype entries are part of the CDE desk top, there is no need to use the `DtDbReloadNotify` function for these alone.

    #include <Dt/Action.h>
    #include <limits.h>
    #include <locale.h>
       ...
    int info_bridge( char * infolib, char* uulocator)
    {
      char info_uuid[ MAXFQLOCATORBUFSIZE ];
      char exec_host[ MAXHOSTNAMESIZE ];
      DtActionArg* args = NULL;
      Xegetshorthostname(localhost, MAXHOSTNAMESIZE);
      args = (DtActionArg*) XtCalloc( 2, sizeof(DtActionArg) );
       ...
      args[0].argclass = DtACTION_BUFFER;
      args[0].u.buffer.bp = (void*) infolib;
      args[0].u.buffer.size = strlen( infolib) + 1;
      args[0].u.buffer.writable = False;
         ...
      sprintf( info_uuid, "%s%s", "mmdb:LOCATOR=", uulocator );
        args[1].argclass = DtACTION_BUFFER;
      args[1].u.buffer.bp = (void*) info_uuid;
      args[1].u.buffer.size = strlen( info_uuid) + 1;
      args[1].u.buffer.writable = False;

      actionId = DtActionInvoke(
        w,
        "DtShowInfoAtLOC",
        args,
        2,
        NULL,
        exec_host,
        NULL,
        True,
        NULL,
        NULL
      );
         ...
      XtFree( args );
    }