This chapter describes the Help dialog widgets and how to create them. creatinghelp dialog boxes managing help dialog boxesdialog boxescreating and managingdialog boxesquick helpdialog boxes general helpgeneral help dialog boxfeatures For application programmers, the Help System provides a programming library that adds help dialog boxes to any 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. widget resources resourceshelp dialog boxesIn terms of programming, you interact with the help dialogs the same as you do with any other 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 . Integrating the Help System into an application requires a working knowledge of the C programming language, the 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. 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, . general help dialog boxfeaturesgeneral help dialog box dialog buttonsdialog boxesgeneral help

Include the appropriate header files: #include <Help.h> #include <HelpDialog.h> Create an instance of the general help dialog widget: Use the DtCreateHelpDialog() convenience function. Or, use the XtCreateManagedWidget() function. Add a callback for handling hyperlink events that occur within the dialog. (For more information, see .) Add a close callback for handling the Close command. 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); DtCreateHelpDialog(3) man page DtHelpDialog(3) man page quick help dialog boxbuttonsThe quick help dialog box is designed to help you meet the primary 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.

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: Use the DtCreateHelpQuickDialog() convenience function. Or, use the XtCreateManagedWidget() function. Add a callback for handling hyperlink events that occur within the dialog. (For more information, see .) 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.” 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 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. DtCreateHelpQuickDialog(3) man page DtHelpQuickDialog(3) man page DtHelpQuickDialogGetChild(3) man page 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: dtdocbook(1) dthelpview(1) dthelpgen(1) dthelpaction(5) dtmanaction(5) Document Type Definitions: dtdocbookdtd(4) dtsdldtd(4)