 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
DtHelpDialog(3)
CDE
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.
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).
_____________________________________________________________________________________
Name Class Type Default Access
_____________________________________________________________________________________
NULL C
DtNcloseCallback
DtCCloseCallback
XtCallbackList
DtNcolumns DtCColumns Dimension 70 CSG
unsigned char DtHELP_- CSG
DtNexecutionPolicy
DtCExecutionPolicy
EXECUTE-
_QUERY-
_UNALIASED
DtNhelpFile DtCHelpFile char * NULL CSG
char * C
DtNhelpOnHelpVolume
DtCHelpOnHelpVolume
See
Definition
DtNhelpPrint DtCHelpPrint char * CSG
See
Definition
DtNhelpType DtCHelpType unsigned char CSG
See
Definition
DtNhelpVolume DtCHelpVolume char * NULL CSG
NULL C
DtNhyperLinkCallback
DtCHyperLinkCallback
XtCallbackList
DtNlocationId DtCLocationId char * CSG
See
Definition
DtNmanPage DtCManPage char * NULL CSG
DtNpaperSize DtCPaperSize unsigned char C
See
Definition
DtNprinter DtCPrinter char * NULL CSG
DtNrows DtCRows Dimension 25 CSG
unsigned char C
DtNscrollBarPolicy
DtCScrollBarPolicy
See
Definition
DtNstringData DtCStringData char * NULL CSG
DtNtopicTitle DtCTopicTitle char * NULL CSG
int 7 C
DtNvisiblePathCount
DtCVisiblePathCount
_____________________________________________________________________________________
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 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.
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
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.
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
_________________________________________________________________________________
Boolean True CSG
XmNallowOverlap
XmCAllowOverlap
Boolean True CG
XmNautoUnmanage
XmCAutoUnmanage
XmFontList dynamic CSG
XmNbuttonFontList
XmCButtonFontList
XmCWidget Widget dynamic SG
XmNcancelButton
XmCWidget Widget dynamic SG
XmNdefaultButton
Boolean True CSG
XmNdefaultPosition
XmCDefaultPosition
unsigned char dynamic CSG
XmNdialogStyle
XmCDialogStyle
XmString NULL CSG
XmNdialogTitle
XmCDialogTitle
XmCCallback NULL C
XmNfocusCallback
XtCallbackList
XmFontList dynamic CSG
XmNlabelFontList
XmCLabelFontList
XmCCallback NULL C
XmNmapCallback
XtCallbackList
Dimension 10 CSG
XmNmarginHeight
XmCMarginHeight
Dimension 10 CSG
XmNmarginWidth
XmCMarginWidth
XmNnoResize XmCNoResize Boolean False CSG
unsigned char XmRESIZE_ANY CSG
XmNresizePolicy
XmCResizePolicy
XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG
XmFontList dynamic CSG
XmNtextFontList
XmCTextFontList
NULL C
XmNtextTranslations
XmCTranslations
XtTranslations
XmCCallback NULL C
XmNunmapCallback
XtCallbackList
_________________________________________________________________________________
XmManager Resource Set:
__________________________________________________________________________________
Name Class Type Default Access
__________________________________________________________________________________
XmNbottom- XmCBottom- Pixel dynamic CSG
ShadowColor
ShadowColor
XmNbottom- XmCBottom- Pixmap CSG
XmUNSPECIFIED-
_PIXMAP
ShadowPixmap
ShadowPixmap
XmNforeground XmCForeground Pixel dynamic CSG
XmCCallback NULL C
XmNhelpCallback
XtCallbackList
Pixel dynamic CSG
XmNhighlightColor
XmCHighlightColor
Pixmap dynamic CSG
XmNhighlightPixmap
XmCHighlightPixmap
Widget dynamic CSG
XmNinitialFocus
XmCInitialFocus
XmNavigation- XmTAB_GROUP CSG
XmNnavigationType
XmCNavigationType
Type
Dimension dynamic CSG
XmNshadowThickness
XmCShadowThickness
XmString- dynamic CG
XmNstringDirection
XmCStringDirection
Direction
Pixel dynamic CSG
XmNtopShadowColor
XmCTopShadowColor
Pixmap dynamic CSG
XmNtopShadowPixmap
XmCTopShadowPixmap
Boolean True CSG
XmNtraversalOn
XmCTraversalOn
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData XtPointer NULL CSG
__________________________________________________________________________________
Composite Resource Set:
________________________________________________________________
XmNchildren XmCReadOnly WidgetList NULL G
________________________________________________________________
XtOrderProc NULL CSG
XmNinsertPosition
XmCInsertPosition
XmCReadOnly Cardinal 0 G
XmNnumChildren
________________________________________________________________
Core Resource Set:
___________________________________________________________________________________________
Name Class Type Default Access
___________________________________________________________________________________________
dynamic N/A
XmNaccelerators
XmCAccelerators
XtAccelerators
XmCSensitive Boolean dynamic G
XmNancestorSensitive
XmNbackground XmCBackground Pixel dynamic CSG
XmCPixmap Pixmap CSG
XmNbackgroundPixmap
XmUNSPECIFIED-
_PIXMAP
Pixel CSG
XmNborderColor
XmCBorderColor
XtDefaultForeground
XmCPixmap Pixmap CSG
XmNborderPixmap
XmUNSPECIFIED-
_PIXMAP
Dimension 0 CSG
XmNborderWidth
XmCBorderWidth
XmNcolormap XmCColormap Colormap dynamic CG
XmNdepth XmCDepth int dynamic CG
XmCCallback NULL C
XmNdestroyCallback
XtCallbackList
XmNheight XmCHeight Dimension dynamic CSG
Boolean True C
XmNinitialResources-
XmCInitialResources-
Persistent Persistent
Boolean True CSG
XmNmappedWhen-
XmCMappedWhen-
Managed Managed
XmNscreen XmCScreen Screen * dynamic CG
XmNsensitive XmCSensitive Boolean True CSG
dynamic CSG
XmNtranslations
XmCTranslations
XtTranslations
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: DtHELP_POPUP_WINDOW, DtHELP_CURRENT_WINDOW or
DtHELP_NEW_WINDOW.
Additional Behavior
The DtHelpDialogwidget 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.
<MCtrl> or <MShift> <BSelect> in Display Area Hypertext Link Text
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
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.
The following operations are supported, but the key bindings are
implementation-dependent:
implementation-dependent
Moves the traversal highlight up, down, left or right to the next
hypertext link item.
Virtual Bindings
The bindings for virtual keys are implementation-dependent. For information
about bindings for virtual buttons and keys, see VirtualBindings(3X).
APPLICATION USAGE
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 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.
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
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
SEE ALSO
Dt/HelpQuickD.h5, Dt/Help.h5, DtCreateHelpQuickDialog(3),
DtHelpSetCatalogName(3); XmManager(3X), XmBulletinBoard(3X), Core(3X),
Composite(3X), Constraint(3X), dthelptagdtd(4). XmManager and
XmBulletinBoard in the X/Open CAE Specification, X/Open Motif Toolkit API
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|