NAME

XvhHelpDialog − the HelpDialog widget class.

SYNOPSIS

#include <Xvh/HelpDialog.h>

DESCRIPTION

The Help Dialog provides the primary help window display area for an application.  It can display HelpTag authored documents, ASCII files, dynamically created strings and man pages.  It provides multi-font display with embedded graphics, hypertext links between documents, keyword search capabilities, and WYSIWYG printing.  For a complete description of HelpDialog’s capabilities and for information on authoring documents using HelpTag, refer to The Help System Programming and Authoring Guide.

The Help Dialog created consists of the following areas:

Menu Bar − The menu bar spans the top of the Help Dialog and provides access to the printing, search, navigation and help. 

Topic Hierarchy − HelpTag documents are authored as a tree of topics.  The topic hierarchy, which is displayed immediately below the menu bar, displays the current topic and its parent topics. 

Display Area − The display area, located immediately below the topic hierarchy, displays the HelpTag topic, man page, or ASCII file. 

Classes

HelpDialog inherits behavior and resources from Core, Composite, Constraint, XmManager, and XmBulletinBoard classes. 

The class pointer is xvhHelpDialogWidgetClass. 

The class name is XvhHelpDialog. 

New Resources

The following table defines a set of widget resources used by the programmer to specify data.  The programmer can also set the resource values for the inherited classes to set attributes for this widget.  To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters.  To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lower case or upper case, but include any underscores between words).  The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 

XmNcloseCallback
Specifies the list of callbacks called when the user activates the Close button.  The callback reason is XvhCR_CLOSE.

XmNcolumns
Specifies the number of columns of text to display in the created help dialog.

XmNhelpFile
Specifies the file name of an ASCII file to be read and displayed in the current help dialog.  This resource is used when the XmNhelpType is set to XvhHELP_TYPE_FILE.

XmNhelpOnHelpVolume
Specifies the help volume that contains the help files that is displayed when the Help Menu is accessed.

XmNhelpPrint
Specifies the location of the helpprint executable used in printing help topics.  This value defaults to the standard directory for helpprint: "helpprint"

XmNhelpType
Specifies the current topic type.  The XmNhelpType resource can have the following values. 

•XvhHELP_TYPE_TOPIC − The value for the XmNlocationId resource is used and the given help topic is displayed. 

•XvhHELP_TYPE_FILE − The value for the XmNhelpFile resource is used and the ASCII file is displayed. 

•XvhHELP_TYPE_STRING − The value for the XmNstringData resource is used and the given string is displayed. 

•XvhHELP_TYPE_DYNAMIC_STRING − The value for the XmNstringData resource is used and the given string is displayed. 

•XvhHELP_TYPE_MAN − The value for XmNmanPage resource is used and the given Unix man page is displayed. 

The default value is XvhHELP_TYPE_TOPIC.

XmNhelpVolume.
Specifies the help volume to use.  This resource is used in conjunction with the XmNlocationId resource to display help topics.

XmNhyperLinkCallback
Specifies the list of callbacks that are called when a hypertext link is selected.  The reason sent by this callback is XvhCR_LINK_ACTIVATE.

XmNhyperLinkCallback allows developers to register a callback procedure that is used to process one of three hypertext link types: XvhLINK_JUMP_NEW, XvhLINK_MAN or XvhLINK_APP_DEFINE.

XmNlocationId
Specifies a topic to display.  Applications reference topics within a help volume via a location id.  Location id’s are author defined at help volume creation time.  Developers use these location ID’s to display the desired help topic.  XmNhelpVolume must be set to the help volume in which the corresponding location id resides, and the resource XmNhelpType must be set to XvhHELP_TYPE_TOPIC.

XmNmanPage
Specifies the Unix Man Page to display in the current help dialog.  This resource is used when the XmNhelpType is set to XvhHELP_TYPE_MAN_PAGE.

XmNprinter
Specifies the printer name to be used when printing.  A NULL value causes the print program to default to "lp". 

XmNrows
Specifies the number of rows of text to display in the help dialog.

XmNscrollBarDisplayPolicy
Controls the automatic placement of the scrollbars.  This resource can have one of three values.

•XvhAS_NEEDED_SCROLLBARS − The scrollbars are displayed only if the display area exceeds the clip area in one or both dimensions. 

•XvhSTATIC_SCROLLBARS − The display area will display the scrollbars whenever the help dialog is managed, regardless of the relationship between the clip window and the display area. 

•XvhNO_SCROLLBARS − No scrollbars will appear within the help dialog. 

XmNstringData
Specifies the string data (char *) to display in the current help dialog. This resource is used when the XmNhelpType is set to XvhHELP_TYPE_STRING.

XmNtopicTitle
Specifies the topic title (char *) to be used in conjunction with either the XmNstringData or XmNhelpFile resource. The topic title is required in order to maintain the history list display non help topic information. 

XmNvisiblePathCount
Specifies the number of items that can fit in the visible space of the topic hierarchy.  The topic hierarchy uses this value to determine it’s initial height.

Inherited Resources

HelpDialog inherits behavior and resources from the following superclasses.  For a complete description of each resource, refer to the man page for that superclass. 

Callback Information

A pointer to the following structure is passed to each callback. 
typedef struct
{
    int reason;
    XEvent * event;
    char * locationId;
    char * helpVolume;
    char * specification;
    int hyperType;

} XvhHelpDialogCallbackStruct;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback. 

locationId
Contains the current help topic.  This has a value of NULL if there is no topic being displayed. 

helpVolume
Contains the current help volume.  This has a value of NULL if there is no topic being displayed. 

specification
Contains any developer defined data that was contained within the selected hypertext link.  This has a value of NULL if no author/developer defined data was provided. 

hyperType
Contains the hypertext link type.  This has either a value of XvhLINK_JUMP_NEW, XvhLINK_APP_DEFINE or XvhLINK_MAN.

Translations

XvhHelpDialog inherits translations from XmBulletinBoard. 

RELATED INFORMATION

Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmManager(3X) and XmCreateHelpDialog(3X). 

The HP Help Developer’s Guide.

Hewlett-Packard Company  —  April 21, 1994