 |
    
Common Desktop Environment: Help System Author's and Programmer's Guide
Contents of Chapter:
- Help Dialog Boxes
-
- Standard Xt Paradigm
-
- General Help Dialog
-
 To Create a General Help Dialog-
- Quick Help Dialog
-
- To Create a Quick Help Dialog
-
- Summary of Application Program Interface
-
This chapter describes the Help dialog widgets and how to create them.
For application programmers, the Help System provides a programming library that adds help dialog boxes to any OSF/Motif application. The library provides two types of help dialog boxes:
- General help dialogs have a menu bar, a topic tree, and a help topic display area. The topic tree lists the help volume's topics and subtopics. Users use the topic tree to select topics to view, to browse available topics, and to locate where they are in the help volume.
- Quick help dialogs contain a topic display area and one or more dialog buttons at the bottom.
Standard Xt Paradigm
In terms of programming, you interact with the help dialogs the same as you do with any other OSF/Motif widgets in your applications. The two types of help dialog boxes are defined as two new widget classes: DtHelpDialog and DtHelpQuickDialog.
Nearly every attribute of the help windows--including the volume name and topic ID--are manipulated as widget resources. For instance, to display a new topic, you just execute an XtSetValues() call to set the DtNhelpVolume, DtNlocationId, and DtNhelpType resources. For more information, refer to "Displaying Help Topics."
Note: Integrating the Help System into an application requires a working knowledge of the C programming language, the OSF/Motif programmer's toolkit, and the Xt Intrinsics toolkit.
A general help dialog has two display areas: the topic tree and topic display area. The topic tree provides a scrollable list of help topics. The home topic title is always the first item. When a user chooses a title, an arrow ( ) marks the title and its help information is displayed in the topic display area. Figure 9-1 shows the topic tree and topic display area of a general help window. The current topic, "To select a palette", is displayed.
The general help dialog includes three dialog buttons: Backtrack, History, and Index. These commands are also available in the Help menus. For an overview of the Help dialogs and the graphical user interface, refer to the section, "Help User Interface."
Figure 9-1 General help dialog
- Include the appropriate header files:
#include <Help.h>
#include <HelpDialog.h>
- Create an instance of the general help dialog widget:
- Add a callback for handling hyperlink events that occur within the dialog. (For more information, see "Responding to Hyperlink Events.")
- Add a close callback for handling the Close command.
Example
The following code segment creates a general help dialog (as a child of parent) using the convenience function. The dialog is left unmanaged--presumably it is managed elsewhere in the application when a help request is made.
Widget mainHelpDialog, moreButton, helpButton;
ac = 0;
XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
XtSetArg (al[ac], DtNhelpVolume, "My Help Volume"); ac++;
XtSetArg (al[ac], DtNlocationId, "Getting Started"); ac++;
XtSetArg (al[ac], DtNhelpType, "DtHELP_TYPE_TOPIC"); ac++;
mainHelpDialog =
DtCreateHelpDialog (parent, "mainHelpDialog", al, ac);
The following two calls add the hyperlink and close callbacks to the dialog. Presumably, the functions HyperlinkCB() and CloseHelpCB() are declared elsewhere in the application.
XtAddCallback (mainHelpDialog, DtNhyperLinkCallback,
HyperlinkCB, (XtPointer)NULL);
XtAddCallback (mainHelpDialog, DtNcloseCallback,
CloseHelpCB, (XtPointer)NULL);
See Also
The quick help dialog box is designed to help you meet the first objective of online help: Get the user back on task as quickly and successfully as possible. This simple user interface helps keep the user focused on the information. The information should be useful enough that the user dismisses the dialog after reading it and continues working.
Figure 9-2 Quick help dialog with four standard buttons
The quick help dialog has five buttons, four of which are managed. The remaining dialog button is configurable, so this button can be used for anything. However, its intended purpose is to provide a path to more help in one of these two ways:
- Let the user ask for more detailed information. In this case, the default button label (More) is appropriate. This is called progressive disclosure.
- Let 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.
The Developer's toolkit includes a convenience function, DtHelpQuickDialogGetChild(), for determining the widget ID for any of the quick help dialog buttons.
- Include the appropriate header files:
#include <Help.h>
#include <HelpQuickD.h>
- Create an instance of the quick help dialog widget:
- Add a callback for handling hyperlink events that occur within the dialog. (For more information, see "Responding to Hyperlink Events.")
- Add a close callback for handling the OK button.
- Configure the dialog buttons that you want to use:
- If you intend to use the application-configured button, manage it and add an activate callback.
- If you want to disallow printing, unmanage the Print button.
- Manage the Help button and add a help callback to the dialog to allow the user to get help on help.
Example
The following code segment creates a quick help dialog (as a child of parent) using the convenience function. The dialog is left unmanaged; presumably, it is managed elsewhere in the application when a help request is made. In this example, the application-configured button is enabled and used to request more help.
Widget quickHelpDialog, moreButton, helpButton;
ac = 0;
XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
XtSetArg (al[ac], DtNhelpVolume, "My Help Volume"); ac++;
XtSetArg (al[ac], DtNlocationId, "Getting Started"); ac++;
XtSetArg (al[ac], DtNhelpType, "DtHELP_TYPE_TOPIC"); ac++;
quickHelpDialog =
DtCreateHelpQuickDialog (parent, "quickHelpDialog", al, ac);
The following two calls add the hyperlink and close callbacks to the dialog. Presumably, the functions HyperlinkCB() and CloseHelpCB() are declared elsewhere in the application.
XtAddCallback (quickHelpDialog, DtNhyperLinkCallback,
HyperlinkCB, (XtPointer)NULL);
XtAddCallback (quickHelpDialog, DtNcloseCallback,
CloseHelpCB, (XtPointer)NULL);
Here, the application-configured button is managed and assigned an activate callback that invokes the application's MoreHelpCB() function.
moreButton = DtHelpQuickDialogGetChild (quickHelpDialog,
DT_HELP_QUICK_MORE_BUTTON);
XtManageChild (moreButton);
XtAddCallback (moreButton, XmNactivateCallback,
MoreHelpCB, (XtPointer)NULL);
To provide "help on help," the dialog's Help button is managed and a help callback is added to the dialog.
helpButton = DtHelpQuickDialogGetChild (quickHelpDialog,
DT_HELP_QUICK_HELP_BUTTON);
XtManageChild (helpButton);
XtAddCallback (quickHelpDialog,DtNhelpCallback,
HelpRequestCB, USING_HELP);
Like other OSF/Motif dialogs, when you add a help callback to a quick help dialog, it is used by both the F1 key and the Help button.
See Also
Related man pages for the Help System are:
- Functions for creating and working with dialogs:
DtHelp(5)
DtHelpDialog(5)
DtHelpQuickD(5)
DtCreateHelpDialog()
DtCreateHelpQUickDialog()
DtHelpQuickDialogGetChild()
- Function for implementing item help mode:
DtHelpReturnSelectedWidgetId()
- Function for specifying the message catalog for the Help library:
DtHelpSetCatalogName()
- Applications and actions for creating and viewing a help volume:
dthelptag(1)
dthelpview(1)
dthelpgen(1)
dthelpaction(5)
dtmanaction(5)
- Document Type Definitions:
dthelptagdtd(4)
dtsdldtd(4)
|
