DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
NAME
DtHelpDialog - DtHelpDialog widget class
SYNOPSIS
#include <Dt/HelpDialog.h>
DESCRIPTION
The DtHelpDialog widget provides users with functionality
for viewing and navigating structured online information
(CDE help volumes). This functionality includes text and
graphics rendering, embedded hypertext links and various
navigation methods to move through online help information.
The widget supports rendering of CDE help volumes, system
manual pages, text files and character string values.
When the user resizes the window, the DtHelpDialog 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 widgets and gadgets contained within the
DtHelpDialog widget hierarchy. The following list
identifies the names of these widgets (or gadgets):
Topic Tree - TocArea
Display Area - DisplayArea
Button Box - BtnBox
The DtHelpDialog widget honors all default and user-
specified resource settings, with one exception. In the
case where an error occurs due to an invalid request, the
DtHelpDialog widget posts the proper error message in its
display area and modifies the DtNhelpType resource to
reflect the current contents of the display area (that is, a
string message). Applications and users should set the
DtNhelpType resource to the appropriate value with each
setting of the DtHelpDialog widget.
Classes
The DtHelpDialog widget inherits behavior and resources from
the Core, Composite, Constraint, XmManager and
XmBulletinBoard classes.
The class pointer is dtHelpDialogClass.
Page 1 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
The class name is DtHelpDialog.
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).
DtHelpDialog Resource Set
__________________________________________________________________________
Name Class Type Default Access
__________________________________________________________________________
DtNcloseCallback DtCCloseCallback XtCallbackListNULL C
DtNcolumns DtCColumns Dimension 70 CSG
DtNexecutionPolicy DtCExecutionPolicy unsigned char DtHELP_- CSG
EXECUTE-
_QUERY-
_UNALIASED
DtNhelpFile DtCHelpFile char * NULL CSG
DtNhelpOnHelpVolume DtCHelpOnHelpVolume char * See DefinitionC
DtNhelpPrint DtCHelpPrint char * See DefinitionCSG
DtNhelpType DtCHelpType unsigned char See DefinitionCSG
DtNhelpVolume DtCHelpVolume char * NULL CSG
DtNhyperLinkCallbackDtCHyperLinkCallbackXtCallbackListNULL C
DtNlocationId DtCLocationId char * See DefinitionCSG
DtNmanPage DtCManPage char * NULL CSG
DtNpaperSize DtCPaperSize unsigned char See DefinitionC
DtNprinter DtCPrinter char * NULL CSG
DtNrows DtCRows Dimension 25 CSG
DtNscrollBarPolicy DtCScrollBarPolicy unsigned char See DefinitionC
DtNstringData DtCStringData char * NULL CSG
DtNtopicTitle DtCTopicTitle char * NULL CSG
DtNvisiblePathCount DtCVisiblePathCount int 7 C
DtNcloseCallback
Specifies the list of callbacks called when the
user activates the Close button. The callback
reason is DtCR_HELP_CLOSE.
DtNcolumns
Specifies the number of columns of text to display
in the display area of the DtHelpDialog widget.
DtNexecutionPolicy
Specifies how to handle ``Execute'' hypertext link
types and embedded scripts. The default value is
Page 2 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
set to DtHELP_EXECUTE_QUERY_UNALIASED and supports
different semantics based on the usage of a command
alias. Refer to the CDE 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.
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 DtHelpDialog 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(1)
utility used to print help topics, manual-page
files or help messages from the DtHelpDialog
widget. This value defaults to
/usr/dt/bin/dthelpprint.
Page 3 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
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_PAGE, 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 that is called when a
client-specific hypertext link is activated in the
display area of the DtHelpDialog widget. Links are
activated when the user presses mouse button 1 over
a hypertext link, or presses <return> 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 that is 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
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
Page 4 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
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 DtHelpDialog widget. This resource is used
when the DtNhelpType is set to DtHELP_TYPE_-
MAN_PAGE.
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 to be used when printing
within the DtHelpDialog widget. If the value is
NULL, the default value is taken from the LPDEST
environment variable.
DtNrows
Specifies the number of rows of text to display in
the display area of the DtHelpDialog 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
DtHelpDialog 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 DtHelpDialog widget.
The default value is DtHELP_AS_NEEDED_SCROLLBARS.
DtNstringData
Specifies the string data (char *) to display in
the current DtHelpDialog widget. This resource is
used when the DtNhelpType is set to DtHELP_TYPE_-
STRING.
Page 5 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
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.
DtNvisiblePathCount
Specifies the number of items to display in the
topic tree area of the widget.
Inherited Resources
The DtHelpDialog 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 XmCDefaultPositionBoolean True CSG
XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG
XmNdialogTitle XmCDialogTitle XmString NULL CSG
XmNfocusCallback XmCCallback XtCallbackListNULL C
XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG
XmNmapCallback XmCCallback XtCallbackListNULL C
XmNmarginHeight XmCMarginHeight Dimension 10 CSG
XmNmarginWidth XmCMarginWidth Dimension 10 CSG
XmNnoResize XmCNoResize Boolean False CSG
XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANYCSG
XmNshadowType XmCShadowType unsigned char XmSHADOW_OUTCSG
XmNtextFontList XmCTextFontList XmFontList dynamic CSG
XmNtextTranslationsXmCTranslations XtTranslationsNULL C
XmNunmapCallback XmCCallback XtCallbackListNULL C
Page 6 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
XmManager Resource Set
______________________________________________________________________
Name Class Type Default Access
______________________________________________________________________
XmNbottom- XmCBottom- Pixel dynamic CSG
ShadowColor ShadowColor
XmNbottom- XmCBottom- Pixmap XmUNSPECIFIED-CSG
ShadowPixmap ShadowPixmap _PIXMAP
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackListNULL C
XmNhighlightColor XmCHighlightColor Pixel dynamic CSG
XmNhighlightPixmapXmCHighlightPixmapPixmap dynamic CSG
XmNinitialFocus XmCInitialFocus Widget dynamic CSG
XmNnavigationType XmCNavigationType XmNavigation- XmTAB_GROUP CSG
Type
XmNshadowThicknessXmCShadowThicknessDimension dynamic CSG
XmNstringDirectionXmCStringDirectionXmString- dynamic CG
Direction
XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG
XmNtopShadowPixmapXmCTopShadowPixmapPixmap 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 XtAcceleratorsdynamic N/A
XmNancestorSensitiveXmCSensitive Boolean dynamic G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED- CSG
_PIXMAP
XmNborderColor XmCBorderColor Pixel XtDefaultForegroundCSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED- CSG
_PIXMAP
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap dynamic CG
XmNdepth XmCDepth int dynamic CG
XmNdestroyCallback XmCCallback XtCallbackListNULL C
XmNheight XmCHeight Dimension dynamic CSG
XmNinitialResources-XmCInitialResources-Boolean True C
Page 7 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
Persistent Persistent
XmNmappedWhen- XmCMappedWhen- Boolean True CSG
Managed Managed
XmNscreen XmCScreen Screen * dynamic CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslationsdynamic 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 is NULL whenever the hyperType value is not
DtHELP_LINK_TOPIC or DtHELP_LINK_APP_DEFINE.
The specification argument indicates any author-defined data
that was contained within the hypertext link selected. 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 (quick help, existing or new window) to use. This
value contains one of the following three types:
Page 8 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
DtHELP_POPUP_WINDOW, DtHELP_CURRENT_WINDOW or
DtHELP_NEW_WINDOW.
Additional Behavior
The DtHelpDialog 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 Topic Tree Text
Opens the help topic currently selected, displays
that topic in the display area and updates the
topic tree to match the newly displayed topic.
<KSpace>, <KActivate> or <BSelect> in Display Area Text
Invokes the hypertext link that contains the
current selection.
<DoubleClick> in Topic Tree or Display Area Text
Ignored.
<BDrag> in Topic Tree or 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.
<MCtrl> or <MShift> <BSelect> in Topic Tree Text
<MCtrl> <KSpace> in Topic Tree Text
<MCtrl> <KActivate> in Topic Tree Text
Invokes the DtNhyperLinkCallback for the
DtHelpDialog widget, setting the helpType to
DtHELP_LINK_TOPIC, the windowHint to
DtHELP_NEW_WINDOW, the helpVolume to the current
volume name and the locationId to the selected
item's location ID. If no DtNhyperLinkCallback is
supplied, the action is ignored.
Text
<MCtrl> or <MShift> <BSelect> in Display Area Hypertext Link
Invokes the DtNhyperLinkCallback for the
DtHelpDialog widget, honoring all existing link
settings, but forces the windowHint to
DtHELP_NEW_WINDOW. If no DtNhyperLinkCallback is
supplied, the hypertext link is handled internally.
<KSelectAll> in Display Area or Topic Tree
Page 9 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
Selects all text within the topic tree area or
display area.
<KDeSelectAll> in Display Area or Topic Tree
Deselects all text within the topic tree area or
display area.
<KUp> or <KLeft> in Display Area or Topic Tree
Moves the traversal highlight up or left to the
next hypertext link item.
<KDown> or <KRight> in Display Area or Topic Tree
Moves the traversal highlight down or right to the
next hypertext item.
<KCopy> in the Display Area or Topic Tree
Copies the currently selected text to the
clipboard.
<KPageDown> or <MCtrl> <KDown> in Display Area or Topic Tree
Displays the next page of text.
<KPageLeft> or <MCtrl> <KLeft> in Display Area or Topic Tree
Scrolls the information to the left.
<KPageRight> or <MCtrl> <KRight> in Display Area or Topic Tree
Scrolls the information to the right.
<KPageUp> or <MCtrl> <KUp> in Display Area or Topic Tree
Displays the previous page of information.
<KBeginData> in the Display Area or Topic Tree
Displays the first page of information.
<KEndData> in the Display Area or Topic Tree
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(3X).
ENVIRONMENT VARIABLES
The DtHelpDialog 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
Page 10 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
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:
/etc/dt/appconfig/help/%L/%H:
/etc/dt/appconfig/help/%L/%H.sdl:
/etc/dt/appconfig/help/%L/%H.hv:
/etc/dt/appconfig/help/C/%H:
/etc/dt/appconfig/help/C/%H.sdl:
/etc/dt/appconfig/help/C/%H.hv:
/usr/dt/appconfig/help/%L/%H:
/usr/dt/appconfig/help/%L/%H.sdl:
/usr/dt/appconfig/help/%L/%H.hv:
/usr/dt/appconfig/help/C/%H:
/usr/dt/appconfig/help/C/%H.sdl:
/usr/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 DtHelpDialog
Page 11 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
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.
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.
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 has been
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.
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 to handle these
link types.
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.
Page 12 (printed 9/3/04)
DtHelpDialog(3) UNIX System V (1 August 1995) DtHelpDialog(3)
SEE ALSO
DtHelpQuickD(5), DtHelp(5), DtCreateHelpQuickDialog(3),
DtHelpSetCatalogName(3); XmManager(3X), XmBulletinBoard(3X),
Core(3X), Composite(3X), Constraint(3X), dthelptagdtd(4).
Page 13 (printed 9/3/04)
