DwtHelp(3Dwt) DwtHelp(3Dwt)
Name
DwtHelp, DwtHelpCreate - Creates a help menu widget.
Syntax
Widget DwtHelp(parent_widget, name, default_position,
x, y, application_name,
library_type, library_spec, first_topic,
overview_topic, glossary_topic, unmap_callback)
Widget parent_widget;
DwtCompString name;
Boolean default_position;
Position x, y;
DwtCompString application_name;
int library_type;
DwtCompString library_spec;
DwtCompString first_topic;
DwtCompString overview_topic;
DwtCompString glossary_topic;
DwtCallbackPtr unmap_callback;
Widget DwtHelpCreate (parent_widget, name,
override_arglist, override_argcount)
Widget parent_widget;
char *name;
ArgList override_arglist;
int override_argcount;
Arguments
parent_widget
Specifies the parent widget ID.
name Specifies the name of the created widget.
default_position
Specifies a boolean value that, when True, indicates that DwtNx and DwtNy will be ignored forcing the default. By default the
help widget is positioned so that it does not occlude the parent widget on the screen. This argument sets the DwtNdefaultPosi-
tion attribute associated with DwtHelpCreate.
x Specifies the placement, in pixels, of the left side of the widget window relative to the inner upper left corner of the parent
window. This argument sets the DwtNx core widget attribute.
y Specifies, in pixels, the placement of the upper left corner of the widget window relative to the inner upper left corner of the
parent window. This argument sets the DwtNy core widget attribute.
application_name
Specifies the application name to be used in the widget title bar. This argument sets the DwtNapplicationName attribute associ-
ated with DwtHelpCreate.
library_type
Specifies the type of help topic library specified by DwtNlibrarySpec. You can pass DwtTextLibrary, which is an ULTRIX help
directory. This argument sets the DwtNlibraryType attribute associated with DwtHelpCreate.
library_spec
Specifies a host system file specification that identifies the help topic library, for example, /usr/help/decwhelp on UNIX-based
systems. This argument sets the DwtNlibrarySpec attribute associated with DwtHelpCreate.
first_topic
Specifies the first help topic to be displayed. If you pass a NULL string, the help menu widget displays a list of level one
topics. This argument sets the DwtNoverviewTopic attribute associated with DwtHelpCreate.
overview_topic
Specifies the application overview topic. This argument sets the DwtNoverviewTopic attribute associated with DwtHelpCreate.
glossary_topic
Specifies the application glossary topic. If you pass a NULL string, the Visit Glossary entry does not appear in the widget's
View pull-down menu. This argument sets the DwtNglossaryTopic attribute associated with DwtHelpCreate.
unmap_callback
Specifies the callback function or functions called when the help menu widget window was unmapped. For this callback, the reason
is DwtCRUnmap. This argument sets the DwtCRUnmap attribute associated with DwtHelpCreate.
override_arglist
Specifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override argument list (override_arglist).
Description
The DwtHelp and DwtHelpCreate functions create an instance of a help menu widget and return its associated widget ID.
The help menu widget is a modeless widget that allows the application to display appropriate user assistance information in response to a
user request. The help menu widget displays an initial help topic and then gives the user the ability to select and view additional help
topics.
The DwtNfirstTopic attribute allows the application to provide context-sensitive help by selecting a specific topic based on implicit or
explicit cues from the user.
The format of the DwtNfirstTopic, DwtNoverviewTopic, and DwtNglossaryTopic compound-strings depends on DwtNlibraryType. If DwtNlibraryType
is DwtTextLibrary, the topic string is a sequence of help library keys separated by one or more spaces.
Once the widget has been created, you can change the help topic by specifying a new DwtNfirstTopic by calling XtSetValues, and then causing
the help menu widget to appear by calling XtManageChild.
When the user terminates a help session (using the Exit function), the widget is automatically unmanaged.
Inherited Attributes
------------------------------------------------------------------
Attribute Name Data Type Default
------------------------------------------------------------------
Core Attributes
DwtNx Position Determined by the geome-
try manager
DwtNy Position Determined by the geome-
try manager
DwtNwidth Dimension Cannot be set by the
caller. The help menu
widget calculates the
width, based on the size
of the text window (Dwt-
Ncols and DwtNrows).
DwtNheight Dimension Cannot be set by the
caller. The help menu
widget calculates the
height, based on the
size of the text window
(DwtNcols and DwtNrows).
DwtNborderWidth Dimension One pixel
DwtNborder Pixel Default foreground color
DwtNborderPixmap Pixmap NULL
DwtNbackground Pixel Default background color
DwtNbackgroundPixmap Pixmap NULL
DwtNcolormap Colormap Default color map
DwtNsensitive Boolean True
DwtNancestorSensitive Boolean The bitwise AND of the
parent widget's DwtNsen-
sitive and DwtNances-
torSensitive attributes
DwtNaccelerators XtTranslations NULL
DwtNdepth int Depth of the parent win-
dow
DwtNtranslations XtTranslations NULL
DwtNmappedWhenManaged Boolean True
DwtNscreen Screen * The parent screen
DwtNdestroyCallback DwtCallbackPtr NULL
Common Attributes
DwtNforeground Pixel Default foreground color
DwtNhighlight Pixel Default foreground color
DwtNhighlightPixmap Pixmap NULL
DwtNuserData Opaque * NULL
DwtNdirectionRToL unsigned char DwtDirectionRightDown
DwtNfont DwtFontList The default XUI Toolkit
font
DwtNhelpCallback DwtCallbackPtr NULL
------------------------------------------------------------------
Widget-Specific Attributes
---------------------------------------------------------------------------
Attribute Name Data Type Default
---------------------------------------------------------------------------
DwtNaboutLabel DwtCompString "About"
DwtNaddtopicLabel DwtCompString " Additional topics"
DwtNapplicationName DwtCompString NULL
DwtNbadframeMessage DwtCompString "Couldn't find frame
!CS"
DwtNbadlibMessage DwtCompString "Couldn't open library
!CS"
DwtNcacheHelpLibrary Boolean False
DwtNcloseLabel DwtCompString "Exit"
DwtNcols int Language-dependent.
The American English
default is 55.
DwtNcopyLabel DwtCompString "Copy"
DwtNdefaultPosition Boolean True
DwtNdismissLabel DwtCompString "Dismiss"
DwtNeditLabel DwtCompString "Edit"
DwtNerroropenMessage DwtCompString "Error opening file
!CS"
DwtNexitLabel DwtCompString "Exit"
DwtNfileLabel DwtCompString "File"
DwtNfirstTopic DwtCompString NULL
DwtNglossaryLabel DwtCompString "Glossary"
DwtNglossaryTopic DwtCompString NULL
DwtNgobackLabel DwtCompString "Go Back"
DwtNgobacktopicLabel DwtCompString "Go Back"
DwtNgooverLabel DwtCompString "Go To Overview"
DwtNgotoLabel DwtCompString "Go To"
DwtNgototopicLabel DwtCompString "Go To Topic"
DwtNhelpAcknowledgeLabel DwtCompString "Acknowledge"
DwtNhelpFont DwtFontList Language-dependent.
The American English
default is "-*-TERMI-
NAL-MEDIUM-R-NAR-
ROW--*-140-*-*-C-*-ISO8859-1"
DwtNhelpLabel DwtCompString "Using Help"
DwtNhelphelpLabel DwtCompString "Overview"
DwtNhelpOnHelpTitle DwtCompString "Using Help"
DwtNhelpontitleLabel DwtCompString "Help on "
DwtNhelptitleLabel DwtCompString "Help"
DwtNhistoryLabel DwtCompString "History..."
DwtNhistoryboxLabel DwtCompString "Search Topic History"
DwtNkeywordLabel DwtCompString "Keyword..."
DwtNkeywordsLabel DwtCompString "Keyword "
DwtNlibrarySpec DwtCompString NULL
DwtNlibraryType int DwtTextLibrary
DwtNnokeywordMessage DwtCompString "Couldn't find keyword !CS"
DwtNnotitleMessage DwtCompString "No title to match string
!CS"
DwtNnulllibMessage DwtCompString "No library specified\n"
DwtNmapCallback DwtCallbackPtr NULL
DwtNoverviewTopic DwtCompString NULL
DwtNrows int Language-dependent. The
American English default is
20.
DwtNsaveasLabel DwtCompString "Save As..."
DwtNsearchapplyLabel DwtCompString "Apply"
DwtNsearchkeywordboxLabel DwtCompString "Search Topic Keywords"
DwtNsearchLabel DwtCompString "Search"
DwtNsearchtitleboxLabel DwtCompString "Search Topic Titles"
DwtNselectallLabel DwtCompString "Select All"
DwtNtitleLabel DwtCompString "Title..."
DwtNtitlesLabel DwtCompString "Title "
DwtNtopictitlesLabel DwtCompString "Topic Titles "
DwtNunmapCallback DwtCallbackPtr NULL
DwtNviewLabel DwtCompString "View"
DwtNvisitglosLabel DwtCompString "Visit Glossary"
DwtNvisitLabel DwtCompString "Visit"
DwtNvisittopicLabel DwtCompString "Visit Topic"
---------------------------------------------------------------------------
DwtNaboutLabel Specifies the text for one of the pull-down menu entries displayed when the user clicks on the Help entry on the menu bar.
DwtNaddtopicLabel
Specifies the text for the label indicating additional topics for help.
DwtNapplicationName
Specifies the application name to be used in the widget title bar.
DwtNbadframeMessage
Specifies the text for the message displayed when a frame could not be found.
DwtNbadlibMessage
Specifies the text for the message displayed when a requested library could not be found.
DwtNcacheHelpLibrary
Specifies a boolean value that, when True, indicates that the text is stored in cache memory. If False, the text is not
stored in cache memory.
DwtNcloseLabel Specifies the label for the Exit push button in the help widget window.
DwtNcols Specifies the width, in characters, of the Help Menu text window.
DwtNcopyLabel Specifies the text for the copy entry on the pull-down menu under Edit on the help widget menu bar.
DwtNdefaultPosition
Specifies a boolean value that, when True, indicates that DwtNx and DwtNy will be ignored forcing the default. By default
the help widget is positioned so that it does not occlude the parent widget on the screen.
DwtNdismissLabel
Specifies the text for the push button label used to dismiss a help widget dialog box (for example, Search History, Search
Title, Search Keyword boxes).
DwtNeditLabel Specifies the text for the edit entry on the help window menu bar.
DwtNerroropenMessage
Specifies the text for the error message displayed when a file cannot be opened.
DwtNexitLabel Specifies the text for the push button or pull-down menu entry that allows the user to exit from help.
DwtNfileLabel Specifies the text for the file entry on the help window menu bar.
DwtNfirstTopic Specifies the first help topic to be displayed. If you pass a NULL string, the help menu widget displays a list of level
one topics.
DwtNglossaryLabel
Specifies the text for the glossary entry on the pull-down menu under Help on a help window menu bar.
DwtNglossaryTopic
Specifies the application glossary topic. If you pass a NULL string, the Visit Glossary entry does not appear in the wid-
get's View pull-down menu.
DwtNgobackLabel
Specifies the text for a label used on the pull-down menu under View. Clicking on this object returns the user to the pre-
vious topic displayed.
DwtNgobacktopicLabel
Specifies the label for the Go Back push button in the help widget window.
DwtNgooverLabel
Specifies the text for a label used on the pull-down menu under View. Clicking on this label causes the Overview of Help to
appear in the Help window.
DwtNgotoLabel Specifies the text for the label used on a push button in the help widget's dialog boxes. Clicking on this object after
selecting a new topic displays help on the new topic in the same Help window.
DwtNgototopicLabel
Specifies the label for the Go To Topic menu entry in the View pull-down menu.
DwtNhelpAcknowledgeLabel
Specifies the label for the Acknowledge push button in the error message box.
DwtNhelpFont Specifies the font of the text displayed in the help menu widget.
DwtNhelphelpLabel
Specifies the label for the Overview menu item in the Using Help pull-down menu.
DwtNhelpLabel Specifies the text for the label on the pull-down menu under Help.
DwtNhelpOnHelpTitle
Specifies the label for the title bar in the Help-on-Help help widget.
DwtNhelpontitleLabel
Specifies the label for the help widget title bar used in conjunction with the application name.
DwtNhelptitleLabel
Specifies the label for the help widget title bar when no application name is specified.
DwtNhistoryLabel
Specifies the text for the label in the pull-down menu under Help.
DwtNhistoryboxLabel
Specifies the text for the label used in a history box.
DwtNkeywordLabel
Specifies the text for the label in the pull-down menu under Help.
DwtNkeywordsLabel
Specifies the text for the label used in a Search Topic Keyword box to identify the text entry field.
DwtNlibrarySpec
Specifies a host system file specification that identifies the help topic library, for example, /usr/help/decwhelp on UNIX-
based systems.
DwtNlibraryType
Specifies the type of help topic library specified by DwtNlibrarySpec. You can pass DwtTextLibrary, which is an ULTRIX help
directory.
DwtNmapCallback
Specifies the callback function or functions called when the help widget is about to be mapped.
DwtNnokeywordMessage
Specifies the text for the message displayed when a requested keyword cannot be found.
DwtNnotitleMessage
Specifies the text for the message displayed when a requested title cannot be found.
DwtNnulllibMessage
Specifies the text for the message displayed when no library has been specified.
DwtNoverviewTopic
Specifies the application overview topic.
DwtNrows Specifies the height, in characters, of the Help Menu text window.
DwtNsaveasLabel
Specifies the text for an entry on a pull-down menu under File on the Help menu bar. Clicking on this entry allows a user
to save the current help text in a file. A file selection dialog box is displayed.
DwtNsearchapplyLabel
Specifies the text for the push button label used to initiate a search action in a Search dialog box.
DwtNsearchkeywordboxLabel
Specifies the text for the label used in a Search Topic Keywords box.
DwtNsearchLabel
Specifies the text for an entry on a Help window menu bar.
DwtNsearchtitleboxLabel
Specifies the text for the title of a Search Topic Titles box.
DwtNselectallLabel
Specifies the text for an entry on the pull-down menu under Edit. Clicking on this entry selects all the text in the work
area (text widget only).
DwtNtitleLabel Specifies the text for an entry on the pull-down menu under Search. Clicking on this entry allows a user to search for a
topic by title.
DwtNtitlesLabel
Specifies the text for the label that identifies the text entry field on the Search Topic Titles box.
DwtNtopictitlesLabel
Specifies the text for the label that identifies the topics found as a result of a title search in a Search Topic Titles
box.
DwtNviewLabel Specifies the text for the View entry on a help menu bar.
DwtNvisitglosLabel
Specifies the text for the pull-down menu entry under View. Clicking on this entry causes the glossary to be displayed in a
new Help window.
DwtNvisitLabel Specifies the text for an entry on a push button in a help widget's dialog boxes. Clicking on this object causes informa-
tion on a new topic to be displayed in a new window.
DwtNvisittopicLabel
Specifies the label for the Visit Topic menu entry in the View pull-down menu.
DwtNunmapCallback
Specifies the callback function or functions called when the help menu widget window was unmapped. For this callback, the
reason is DwtCRUnmap.
Return Values
These functions return the ID of the created widget.
Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;
The reason member is set to a constant that represents the reason why this callback was invoked. For this callback, the reason member can
be set to:
DwtCRUnmap The help window was
unmapped.
The event member is a pointer to the Xlib structure XEvent, which describes the event that generated this callback. This structure is a
union of the individual structures declared for each event type. For information on XEvent and event processing, see the Guide to the Xlib
Library: C Language Binding.
See Also
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding
DwtHelp(3Dwt)