NAME

DtHelpQuickDialog — DtHelpQuickDialog widget class

SYNOPSIS

#include &<Dt/HelpQuickD.h>

DESCRIPTION

The DtHelpQuickDialog widget provides users with a constrained set of functionality for viewing and and navigating structured online information (XCDE help volumes). This functionality includes text and graphics rendering, embedded hypertext links and limited navigation methods to move through online help information. The widget supports rendering of XCDE help volume, system manual pages, text files and character string values.

When the user resizes the window, the DtHelpQuickDialog widget dynamically reformats its contents to fit the new window size if the DtNhelpType of the contents is DtHELP_TYPE_TOPIC or DtHELP_TYPE_DYNAMIC_STRING. If the DtNhelpType of the contents is DtHELP_TYPE_STRING, DtHELP_TYPE_MAN_PAGE or DtHELP_TYPE_FILE, the contents are not reformatted. Instead, scroll bars may appear when the user resizes the window smaller than the help contents. The exact scrollbar behavior is controlled by the DtNscrollBarPolicy resource.

Users can re-specify certain resources for the automatically created widget contained within the DtHelpQuickDialog hierarchy. The following is the name of the widget:

Display Area - DisplayArea

The DtHelpQuickDialog widget honors all default and user-specified resource settings, with one exception. In the case where an error occurs due to a non-valid request, the widget posts the proper error message in its display area, and modifies the DtNhelpType to reflect the current contents of the display area (that is, a string message). Applications and users should set the DtNhelpType to the appropriate value with each setting of the help value.

Classes

The DtHelpQuickDialog widget inherits behavior and resources from the Core, Composite, Constraint, XmManager and XmBulletinBoard classes.

The class pointer is dtHelpQuickDialogClass.

The class name is DtHelpQuickDialog.

New Resources

To reference a resource by name or by class in a .Xdefaults file, the application must remove the DtN or DtC prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, the application must remove the Dt prefix and use the remaining letters (in either lower case or upper case, but including 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).

DtHelpQuickDialog Resource Set

Name	Class	Type	Default	Access

DtNbackLabelString	DtCBackLabelString	XmString	Back Track	CSG
DtNcloseCallback	DtCCloseBtnCallback	XtCallbackList	NULL	C
DtNcloseLabelString	DtCcloseLabelString	XmString	Close	CSG
DtNcolumns	DtCColumns	Dimension	50	CSG
DtNexecutionPolicy	DtCExecutionPolicy	unsigned char	DtHELP_EXECUTE_QUERY_UNALIASED	CSG
DtNhelpFile	DtCHelpFile	char *	NULL	CSG
DtNhelpLabelString	DtCHelpLabelString	XmString	Help	CSG
DtNhelpOnHelpVolume	DtCHelpOnHelpVolume	char *	See Definition	C
DtNhelpPrint	DtCHelpPrint	char *	See Definition	CSG
DtNhelpType	DtCHelpType	unsigned char	DtHELP_TYPE_TOPIC	CSG
DtNhelpVolume	DtCHelpVolume	char *	NULL	CSG
DtNhyperLinkCallback	DtCHyperLinkCallback	XtCallbackList	NULL	C
DtNlocationId	DtCLocationId	char *	See Definition	CSG
DtNmanPage	DtCManPage	char *	NULL	CSG
DtNminimizeButtons	DtCMinimizeButtons	Boolean	True	C
DtNmoreLabelString	DtCMoreLabelString	XmString	More	CSG
DtNpaperSize	DtCPaperSize	unsigned char	See Definition	C
DtNprinter	DtCPrinter	char *	NULL	CSG
DtNprintLabelString	DtCPrintLabelString	XmString	Print...	CSG
DtNrows	DtCRows	Dimension	15	CSG
DtNscrollBarPolicy	DtCScrollBarPolicy	unsigned char	DtHELP_AS_NEEDED_SCROLLBARS	C
DtNstringData	DtCStringData	char *	NULL	CSG
DtNtopicTitle	DtCTopicTitle	char *	NULL	CSG

DtNbackLabelString: Specifies the string label for the Back button.
DtNcloseCallback: Specifies the list of callbacks called when the application activates the Close button. The callback reason is DtCR_HELP_CLOSE.
DtNcloseLabelString: Specifies the string label for the Close button.
DtNcolumns: Specifies the number of columns of text to display in the DtHelpQuickDialog widget display area.
DtNexecutionPolicy: Specifies how to handle ``Execute'' hypertext link types and embedded scripts. The default value is set to DtHELP_EXECUTE_QUERY_UNALIASED and supports different semantics based on the usage of a command alias. Refer to the XCDE Help System Author's and Programmer's Guide for more information on command alias usage. With the default value and no command alias, a query dialog will be posted upon user selection of an execute hypertext link. The dialog will show the command that has been specified and give the user the option to ``Execute Anyway,'' ``Don't Execute'' or request help for more information. When a command alias is present for the selected link, the command will execute silently, and no query dialog will be posted.
: Other values for this resource are DtHELP_EXECUTE_NONE, DtHELP_EXECUTE_ALL and DtHELP_EXECUTE_QUERY_ALL. DtHELP_EXECUTE_NONE forces all execute hypertext links to be ignored. DtHELP_EXECUTE_ALL allows all execute hypertext links to be executed silently upon link selection by the user, and DtHELP_EXECUTE_QUERY_ALL forces the query dialog to be posted with every link invocation.
DtNhelpFile: Specifies the absolute pathname of a text file to be read and displayed. This resource is used when the DtNhelpType is set to DtHELP_TYPE_FILE. The topic title is required in order to maintain an accurate and descriptive history list.
DtNhelpLabelString: Specifies the string label for the Help button.
DtNhelpOnHelpVolume: Specifies the help volume that contains the help topics for the help user interface components in the widget. This is displayed in an instance of the DtHelpQuickDialog widget when the user requests help from within the widget. The default value for this resource is Help4Help, which refers to the default supported help volume. This resource supports absolute pathnames and pathless help volume names. When just a volume name is used, the volume must be placed or linked to one of the default search locations, or one of the two help search path environment variables must be properly set. See the ENVIRONMENT VARIABLES section for more information on setting and modifying these variables.
DtNhelpPrint: Specifies the location of the dthelpprint utility used to print help topics, manual pages, files or help messages from the DtHelpQuickDialog widget. This value defaults to /usr/local/dt/bin/dthelpprint.
DtNhelpType: Specifies the current topic type. When the value is DtHELP_TYPE_TOPIC, the DtNlocationId and DtNhelpVolume resources are used and the requested help topic is displayed. When the value is DtHELP_TYPE_STRING or DtHELP_TYPE_DYNAMIC_STRING, the DtNstringData resource is used and the requested string is displayed. When the value is DtHELP_TYPE_FILE, the DtNhelpFile resource is used and the requested text file is displayed. When the value is DtHELP_TYPE_MAN, the DtNmanPage resource is used and the requested system manual page is displayed. The initial default value is DtHELP_TYPE_TOPIC; however, each time there is a request to display a help topic, text file, manual page or text string, the user should reset DtNhelpType to the proper type.
DtNhelpVolume: Specifies the help volume to use. This resource is used in conjunction with the DtNlocationId resource to display help topics. This resource supports absolute pathnames and pathless help volume names. When using just a volume name, the volume must be placed in or linked to one of the default search locations, or one of the two help search path environment variables must be properly set. See the ENVIRONMENT VARIABLES section for more information on setting and modifying these variables.
DtNhyperLinkCallback: Specifies the callback called when a client-specific hypertext link type is activated in the display area of the DtHelpQuickDialog widget. Links are activated when the user presses mouse button 1 over a hypertext link, or presses <KActivate> with the keyboard focus on the hypertext link item. The callback reason is DtCR_HELP_LINK_ACTIVATE. DtNhyperLinkCallback allows applications to register a callback procedure used to process one of four hypertext link types: DtHELP_LINK_APP_DEFINE, DtHELP_LINK_TOPIC, DtHELP_LINK_MAN_PAGE or DtHELP_LINK_TEXT_FILE. For the DtHELP_LINK_TOPIC, the callback is made only when the windowHint value in the callback structure is DtHELP_NEW_WINDOW.
DtNlocationId: Specifies a help topic to display. Applications reference topics within a help volume using a location ID. Location IDs are author-defined at help volume creation time. Applications use these location IDs to display the desired help topic. The default value for this resource is _HOMETOPIC, which refers to the help volume's top level topic. DtNhelpVolume must be set to the help volume in which the corresponding location ID resides, and DtNhelpType must be set to DtHELP_TYPE_TOPIC.
DtNmanPage: Specifies the system manual page to display in the current DtHelpQuickDialog widget. This resource is used when the DtNhelpType is set to DtHELP_TYPE_MAN_PAGE.
DtNminimizeButtons: Sets the buttons to the width of the widest button and the height of the tallest button if False. If True, button width and height are not modified.
DtNmoreLabelString: Specifies the string label for the More button.
DtNpaperSize: Controls the value used in the Help-Print dialog for paper size. The default value is set to DtHELP_PAPERSIZE_LETTER. Other supported values for this resource are: DtHELP_PAPERSIZE_LEGAL, DtHELP_PAPERSIZE_EXECUTIVE, DtHELP_PAPERSIZE_A4, DtHELP_PAPERSIZE_B5.
DtNprinter: Specifies the printer name used to print within the DtHelpQuickDialog widget. If the value is NULL, the default value is taken from the LPDEST environment variable.
DtNprintLabelString: Specifies the string label for the Print button.
DtNrows: Specifies the number of rows of text to display in the display area of the DtHelpQuickDialog widget.
DtNscrollBarPolicy: Controls the automatic placement of scroll bars in the text display area. If it is set to DtHELP_AS_NEEDED_SCROLLBARS, the scroll bars are displayed only if the display area exceeds the clip area in one or both dimensions. A resource value of DtHELP_STATIC_SCROLLBARS causes the display area to display the scroll bars whenever the DtHelpQuickDialog widget is managed, regardless of the relationship between the clip window and the display area. A value of DtHELP_NO_SCROLLBARS removes scroll bars from the DtHelpQuickDialog widget. The default value is DtHELP_AS_NEEDED_SCROLLBARS.
DtNstringData: Specifies the string data (char *) to display in the current DtHelpQuickDialog widget. This resource is used when the DtNhelpType is set to DtHELP_TYPE_STRING.
DtNtopicTitle: Specifies the topic title (char *) to be used in conjunction with either the DtNstringData or DtNhelpFile resource. The topic title is required in order to maintain an accurate and descriptive history list. The topic title is also used as the default heading for the banner page and page header when printing. When printing help topics, this resource may be ignored.

Inherited Resources

The DtHelpQuickDialog widget inherits behavior and resources from the following named superclasses. For a complete description of each resource, see the man page for that superclass.

XmBulletinBoard Resource Set

Name	Class	Type	Default	Access

XmNallowOverlap	XmCAllowOverlap	Boolean	True	CSG
XmNautoUnmanage	XmCAutoUnmanage	Boolean	True	CG
XmNbuttonFontList	XmCButtonFontList	XmFontList	dynamic	CSG
XmNcancelButton	XmCWidget	Widget	dynamic	SG
XmNdefaultButton	XmCWidget	Widget	dynamic	SG
XmNdefaultPosition	XmCDefaultPosition	Boolean	True	CSG
XmNdialogStyle	XmCDialogStyle	unsigned char	dynamic	CSG
XmNdialogTitle	XmCDialogTitle	XmString	NULL	CSG
XmNfocusCallback	XmCCallback	XtCallbackList	NULL	C
XmNlabelFontList	XmCLabelFontList	XmFontList	dynamic	CSG
XmNmapCallback	XmCCallback	XtCallbackList	NULL	C
XmNmarginHeight	XmCMarginHeight	Dimension	10	CSG
XmNmarginWidth	XmCMarginWidth	Dimension	10	CSG
XmNnoResize	XmCNoResize	Boolean	False	CSG
XmNresizePolicy	XmCResizePolicy	unsigned char	XmRESIZE_ANY	CSG
XmNshadowType	XmCShadowType	unsigned char	XmSHADOW_OUT	CSG
XmNtextFontList	XmCTextFontList	XmFontList	dynamic	CSG
XmNtextTranslations	XmCTranslations	XtTranslations	NULL	C
XmNunmapCallback	XmCCallback	XtCallbackList	NULL	C

XmManager Resource Set

Name	Class	Type	Default	Access

XmNbottomShadowColor	XmCBottomShadowColor	Pixel	dynamic	CSG
XmNbottomShadowPixmap	XmCBottomShadowPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNforeground	XmCForeground	Pixel	dynamic	CSG
XmNhelpCallback	XmCCallback	XtCallbackList	NULL	C
XmNhighlightColor	XmCHighlightColor	Pixel	dynamic	CSG
XmNhighlightPixmap	XmCHighlightPixmap	Pixmap	dynamic	CSG
XmNinitialFocus	XmCInitialFocus	Widget	dynamic	CSG
XmNnavigationType	XmCNavigationType	XmNavigationType	XmTAB_GROUP	CSG
XmNshadowThickness	XmCShadowThickness	Dimension	dynamic	CSG
XmNstringDirection	XmCStringDirection	XmStringDirection	dynamic	CG
XmNtopShadowColor	XmCTopShadowColor	Pixel	dynamic	CSG
XmNtopShadowPixmap	XmCTopShadowPixmap	Pixmap	dynamic	CSG
XmNtraversalOn	XmCTraversalOn	Boolean	True	CSG
XmNunitType	XmCUnitType	unsigned char	dynamic	CSG
XmNuserData	XmCUserData	XtPointer	NULL	CSG

Composite Resource Set

Name	Class	Type	Default	Access

XmNchildren	XmCReadOnly	WidgetList	NULL	G
XmNinsertPosition	XmCInsertPosition	XtOrderProc	NULL	CSG
XmNnumChildren	XmCReadOnly	Cardinal	0	G

Core Resource Set

Name	Class	Type	Default	Access

XmNaccelerators	XmCAccelerators	XtAccelerators	dynamic	N/A
XmNancestorSensitive	XmCSensitive	Boolean	dynamic	G
XmNbackground	XmCBackground	Pixel	dynamic	CSG
XmNbackgroundPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderColor	XmCBorderColor	Pixel	XtDefaultForeground	CSG
XmNborderPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderWidth	XmCBorderWidth	Dimension	0	CSG
XmNcolormap	XmCColormap	Colormap	dynamic	CG
XmNdepth	XmCDepth	int	dynamic	CG
XmNdestroyCallback	XmCCallback	XtCallbackList	NULL	C
XmNheight	XmCHeight	Dimension	dynamic	CSG
XmNinitialResourcesPersistent	XmCInitialResourcesPersistent	Boolean	True	C
XmNmappedWhenManaged	XmCMappedWhenManaged	Boolean	True	CSG
XmNscreen	XmCScreen	Screen *	dynamic	CG
XmNsensitive	XmCSensitive	Boolean	True	CSG
XmNtranslations	XmCTranslations	XtTranslations	dynamic	CSG
XmNwidth	XmCWidth	Dimension	dynamic	CSG
XmNx	XmCPosition	Position	0	CSG
XmNy	XmCPosition	Position	0	CSG

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;


        int     windowHint;
} DtHelpDialogCallbackStruct;

The reason argument indicates why the callback was invoked.

The event argument points to the XEvent that triggered the callback.

The locationId argument indicates the DtNlocationId for the current topic. This value is NULL whenever the hyperType value is not DtHELP_LINK_TOPIC or DtHELP_LINK_APP_DEFINE.

The helpVolume argument indicates the current help volume. This value returns NULL whenever the hyperType value is not DtHELP_LINK_TOPIC or DtHELP_LINK_APP_DEFINE.

The specification argument indicates any author-defined data contained within the selected hypertext link. This value returns NULL if no author-defined data was given. For hyperlinks of type DtHELP_MAN_PAGE, the specification argument contains the name of the manual page. For hyperlinks of type DtHELP_LINK_TEXT_FILE, the specification argument contains that name of the file.

The hyperType argument indicates the hypertext link type. Possible values are: DtHELP_LINK_TOPIC, DtHELP_LINK_MAN_PAGE, DtHELP_LINK_APP_DEFINE or DtHELP_LINK_TEXT_FILE.

The windowHint argument indicates a hint for the type of window (current window, DtHelpQuickDialog widget window or new window) to use. This value contains one of the following three types: DtHELP_POPUP_WINDOW, DtHELP_CURRENT_WINDOW or DtHELP_NEW_WINDOW.

Additional Behavior

The DtHelpQuickDialog widget has the additional behavior described below:

&<MAny> &<KCancel>: Calls the active callbacks for the Close button. If a &<BDrag> for either a selection or scrollbar movement is in process, the KCancel aborts that action.
&<KSpace>, &<KActivate> or &<BSelect> in Display Area Text: Invokes the hypertext link that contains the current selection.
&<DoubleClick> in Display Area Text: Ignored.
&<BDrag> in Display Area Text: Selects the text from the drag start point to the drag end point. Moving and holding the &<BDrag> outside the topic tree or display area, scrolls the window, selecting the newly exposed text.
&<Close Button Activated>: Closes the DtHelpQuickDialog widget, and calls the DtNcloseCallback callbacks with reason DtCR_HELP_CLOSE.
&<Backtrack Button Activated>: Forces the DtHelpQuickDialog widget to display the data previously displayed in the dialog. If the current item was the first item displayed in the DtHelpQuickDialog widget, the Backtrack button is insensitive.
&<Print Button Activated>: Forces the DtHelpQuickDialog widget to display the Help-Print dialog.
&<Help Button Activated>: Forces the DtHelpQuickDialog widget to display the Help-On-Help dialog.
&<MCtrl> or &<MShift> &<BSelect> in Display Area Hypertext Link Text
&<MCtrl> &<KSpace> in Display Area Hypertext Link Text
&<MCtrl> &<KActivate> in Display Area Hypertext Link Text: Invokes the DtNhyperLinkCallback for the DtHelpQuickDialog widget, honoring all existing link settings, but forces the windowHint to DtHELP_NEW_WINDOW. If no DtNhyperLinkCallback was supplied, the hypertext link is handled internally.
&<KSelectAll> in Display Area: Selects all text within the display area.
&<KDeSelectAll> in Display Area: Deselects all text within the display area.
&<KUp> or &<KLeft> in Display Area: Moves the traversal highlight up or left to the next hypertext link item.
&<KDown> or &<KRight> in Display Area: Moves the traversal highlight down or right to the next hypertext item.
&<KCopy> in the Display Area: Copies the currently selected text to the clipboard.
&<KPageDown> or &<MCtrl> &<KDown> in the Display Area: Displays the next page of text.
&<KPageLeft> or &<MCtrl> &<KLeft> in Display Area: Scrolls the information to the left.
&<KPageRight> or &<MCtrl> &<KRight> in Display Area: Scrolls the information to the right.
&<KPageUp> or &<MCtrl> &<KUp> in Display Area: Displays the previous page of information.
&<KBeginData> in the Display Area: Displays the first page of information.
&<KEndData> in the Display Area: Displays the last page of information.

Virtual Bindings

The bindings for virtual keys are implementation-dependent. For information about bindings for virtual buttons and keys, see VirtualBindings(3).

ENVIRONMENT VARIABLES

The DtHelpQuickDialog widget uses two environment variables for locating help volumes within the desktop environment:

DTHELPSEARCHPATH: The system search path environment variable for locating help volumes on local and remote NFS mounted systems.
DTHELPUSERSEARCHPATH: The search path environment variable for locating user-specific help volumes on local and remote NFS mounted systems.

The environment variables contain colon-separated lists of directory paths. Each directory path can contain both environment variable names as well as special field descriptors that are expanded at runtime.

Field descriptors consist of a percent-sign character (%) followed by a single character. Field descriptors and their substitution values are:

%H: Replaced with the current volume name being searched for.
%L: Replaced with the current value of the LANG environment variable.
%%: Replaced with a single %.

The default value for DTHELPUSERSEARCHPATH is:

$HOME/.dt/help/$DTUSERSESSION/%H:
$HOME/.dt/help/$DTUSERSESSION/%H.sdl:
$HOME/.dt/help/$DTUSERSESSION/%H.hv:
$HOME/.dt/help/%H:
$HOME/.dt/help/%H.sdl:
$HOME/.dt/help/%H.hv

The DTHELPUSERSEARCHPATH is first searched for the requested volume. If the volume is not found, the DTHELPSEARCHPATH value is searched.

The default value for DTHELPSEARCHPATH path is:

/usr/local/dt/etc/appconfig/help/%L/%H:
/usr/local/dt/etc/appconfig/help/%L/%H.sdl:
/usr/local/dt/etc/appconfig/help/%L/%H.hv:
/usr/local/dt/etc/appconfig/help/C/%H:
/usr/local/dt/etc/appconfig/help/C/%H.sdl:
/usr/local/dt/etc/appconfig/help/C/%H.hv:
/usr/local/dt/appconfig/help/%L/%H:
/usr/local/dt/appconfig/help/%L/%H.sdl:
/usr/local/dt/appconfig/help/%L/%H.hv:
/usr/local/dt/appconfig/help/C/%H:
/usr/local/dt/appconfig/help/C/%H.sdl:
/usr/local/dt/appconfig/help/C/%H.hv

APPLICATION USAGE

The following messages can be generated as a result of an error or improperly set resource value in the DtHelpQuickDialog widget These messages are displayed in the widget's display area as well as standard error.

Error Messages

String data could not be formatted.: The error occurred when formatting help information of type DtHELP_TYPE_STRING.
Dynamic string data could not be formatted.: The error occurred when formatting help information of type DtHELP_TYPE_DYNAMIC_STRING.
Man Page could not be formatted. The requested man page: is either not present, or corrupt." 10 The error occurred when formatting help information of type DtHELP_TYPE_MAN_PAGE.
Text file could not be formatted. The requested text file: is either not present, or corrupt." 10 The error occurred when formatting help information of type DtHELP_TYPE_FILE.
Non-supported DtNhelpType value used.: The application used a non-supported DtNhelpType.
Help topic could not be formatted.: The application attempted to access a corrupt runtime help file.
No DtNhyperLinkCallback supplied for widget.: A hypertext link of type DtHELP_NEW_WINDOW is selected, but the application has not supplied a hypertext callback to handle it. The link is handled like a DtHELP_CURRENT_WINDOW jump.
Nonexistent DtNlocationId.: The requested DtNlocationId is not present in the current help volume.
No DtNhyperLinkCallback supplied for widget to handle
DtHELP_LINK_APP_DEFINE or DtHELP_LINK_MAN_PAGE links.: A hypertext link of type DtHELP_LINK_APP_DEFINE or DtHELP_LINK_MAN_PAGE is selected, but the application has not supplied a hypertext callback.
Could not find DtNhelpVolume.: The Help System is unable to find the help volume requested.
Could not open DtNhelpVolume.: The Help System found the requested help volume, but does not have the permission to open it.