DtHelpDialog(library call) DtHelpDialog(library call)
NAME [Toc] [Back]
DtHelpDialog - DtHelpDialog widget class
SYNOPSIS [Toc] [Back]
#include <Dt/HelpDialog.h>
DESCRIPTION [Toc] [Back]
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 [Toc] [Back]
The DtHelpDialog widget inherits behavior and resources from the Core,
Composite, Constraint, XmManager and XmBulletinBoard classes.
The class pointer is dtHelpDialogClass.
The class name is DtHelpDialog.
- 1 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
New Resources [Toc] [Back]
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 XtCallbackList NULL C
DtNcolumns DtCColumns Dimension 70 CSG
DtNexecutionPolicy DtCExecutionPolicy unsigned char DtHELP_EXECUTE_QUERY_UNALIASED CSG
DtNhelpFile DtCHelpFile char * NULL CSG
DtNhelpOnHelpVolume DtCHelpOnHelpVolume char * See Definition C
DtNhelpPrint DtCHelpPrint char * See Definition CSG
DtNhelpType DtCHelpType unsigned char See Definition CSG
DtNhelpVolume DtCHelpVolume char * NULL CSG
DtNhyperLinkCallback DtCHyperLinkCallback XtCallbackList NULL C
DtNlocationId DtCLocationId char * See Definition CSG
DtNmanPage DtCManPage char * NULL CSG
DtNpaperSize DtCPaperSize unsigned char See Definition C
DtNprinter DtCPrinter char * NULL CSG
DtNrows DtCRows Dimension 25 CSG
DtNscrollBarPolicy DtCScrollBarPolicy unsigned char See Definition C
DtNstringData DtCStringData char * NULL CSG
DtNtopicTitle DtCTopicTitle char * NULL CSG
DtNvisiblePathCount DtCVisiblePathCount int 7 C
DtNcloseCallback [Toc] [Back]
Specifies the list of callbacks called when the user
activates the Close button. The callback reason is
DtCR_HELP_CLOSE.
DtNcolumns [Toc] [Back]
Specifies the number of columns of text to display in the
display area of the DtHelpDialog widget.
DtNexecutionPolicy [Toc] [Back]
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 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
- 2 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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.
DtNhelpType [Toc] [Back]
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
- 3 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
or text string, the user should reset DtNhelpType to the
proper type.
DtNhelpVolume [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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.
- 4 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
DtNprinter [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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.
DtNtopicTitle [Toc] [Back]
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 [Toc] [Back]
Specifies the number of items to display in the topic tree
area of the widget.
Inherited Resources [Toc] [Back]
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 XmCDefaultPosition Boolean True CSG
- 5 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
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 XmString-Direction 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
- 6 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
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 [Toc] [Back]
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: DtHELP_POPUP_WINDOW, DtHELP_CURRENT_WINDOW or
DtHELP_NEW_WINDOW.
Additional Behavior [Toc] [Back]
- 7 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
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" 10 Ignored.
<BDrag> in Topic Tree or Display
Area Text" 10 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" 10
<MCtrl> <KSpace> in Topic Tree
Text" 10
<MCtrl> <KActivate> in Topic
Tree Text" 10 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.
<MCtrl> or <MShift>
<BSelect> in Display Area Hypertext Link Text" 10 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" 10 Selects all text within the topic tree area
or display area.
- 8 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
<KDeSelectAll> in Display Area
or Topic Tree" 10 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" 10 Copies the currently selected text to the
clipboard.
<KPageDown> or <MCtrl>
<KDown> in Display Area or Topic Tree" 10 Displays the next
page of text.
<KPageLeft> or <MCtrl>
<KLeft> in Display Area or Topic Tree" 10 Scrolls the
information to the left.
<KPageRight> or <MCtrl>
<KRight> in Display Area or Topic Tree" 10 Scrolls the
information to the right.
<KPageUp> or <MCtrl>
<KUp> in Display Area or Topic Tree" 10 Displays the
previous page of information.
<KBeginData> in the Display Area
or Topic Tree" 10 Displays the first page of information.
<KEndData> in the Display Area
or Topic Tree" 10 Displays the last page of information.
Virtual Bindings [Toc] [Back]
The bindings for virtual keys are implementation-dependent. For
information about bindings for virtual buttons and keys, see
VirtualBindings(3).
ENVIRONMENT VARIABLES [Toc] [Back]
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.
- 9 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
DTHELPUSERSEARCHPATH
The search path environment variable for locating userspecific
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 [Toc] [Back]
The following messages can be generated as a result of an error or
improperly set resource value in the DtHelpDialog widget. These
messages are displayed in the widget's display area as well as
- 10 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
standard error.
Error Messages [Toc] [Back]
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
- 11 - Formatted: January 24, 2005
DtHelpDialog(library call) DtHelpDialog(library call)
not have the permission to open it.
SEE ALSO [Toc] [Back]
Dt/HelpQuickD.h - DtHelpQuickD(5), Dt/Help.h - DtHelp(5),
DtCreateHelpQuickDialog(3), DtHelpSetCatalogName(3); XmManager(3),
XmBulletinBoard(3), Core(3), Composite(3), Constraint(3),
dthelptagdtd(4).
- 12 - Formatted: January 24, 2005 [ Back ] |
