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.
nameSpecifies 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 DwtNdefaultPosition attribute associated with DwtHelpCreate.
xSpecifies 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.
ySpecifies, 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 associated with DwtHelpCreate.
library_typeSpecifies 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_specSpecifies 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_topicSpecifies 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 geometry manager |
| DwtNy | Position | Determined by the geometry manager |
| DwtNwidth | Dimension | Cannot be set by the caller. The help menu widget calculates the width, based on the size of the text window (DwtNcols 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 DwtNsensitive and DwtNancestorSensitive attributes |
| DwtNaccelerators | XtTranslations | NULL |
| DwtNdepth | int | Depth of the parent window |
| 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 "-*-TERMINAL-MEDIUM-R-NARROW--*-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" |
DwtNaboutLabelSpecifies 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.
DwtNcloseLabelSpecifies the label for the Exit push button in the help widget window.
DwtNcolsSpecifies the width, in characters, of the Help Menu text window.
DwtNcopyLabelSpecifies 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).
DwtNeditLabelSpecifies 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.
DwtNexitLabelSpecifies the text for the push button or pull-down menu entry that allows the user to exit from help.
DwtNfileLabelSpecifies the text for the file entry on the help window menu bar.
DwtNfirstTopicSpecifies 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 widget’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 previous 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.
DwtNgotoLabelSpecifies 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.
DwtNhelpFontSpecifies 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.
DwtNhelpLabelSpecifies 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.
DwtNrowsSpecifies 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).
DwtNtitleLabelSpecifies 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.
DwtNviewLabelSpecifies 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.
DwtNvisitLabelSpecifies the text for an entry on a push button in a help widget’s dialog boxes. Clicking on this object causes information 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