1. Include the Toolkit widget definitions. The additional include files are needed to set up the mailbox and trap messages.
2. This event flag is passed to the $QIO system service routine and is distinct from the event flag specified in the call to XtAppAddInput. The $QIO system service routine clears this flag when it begins execution and sets the flag when the I/O completes, either successfully or unsuccessfully.
   MISC_EFN is not the same flag specified in the call to XtAppAddInput because that flag must remain set for the Toolkit to notice that input is pending, and because it is more efficient to have XtAppAddInput invoked only when there is input pending.
   Remember that event flag numbers are restricted to cluster 0, which contains event flag numbers 0 to 31.
3. The structure used to store the mailbox message.
4. A control block that contains information about the mailbox message structure. This control block is passed to the I/O completion routine to obtain the string value of the message.
5. This event flag is specified in the call to XtAppAddInput. The AST completion routine (CompletionAst) sets this flag each time it is invoked. It is the same flag specified in the call to XtAppAddInput because that flag must be set for the Toolkit to notice that input is pending.
6. Declare an application context.
7. AllocateAddInputRec is the ASTPRM parameter on asynchronous system service calls. Arguments to AllocateAddInputRec include the application-specific callback routine (ProcessMessageRec) to be called and the parameter (mailbox message) to be passed to that callback.
   In the example, ProcessMessageRec gets the text of the broadcast message, converts it into an XmString, and adds it to the bottom of the list of items in the XmScrolledList widget. Then, ProcessMessageRec starts another $QIO read.
8. Start an asynchronous read on the broadcast mailbox. This routine is called by the StartTrappingMessages routine before the call to MrmFetchWidget.
9. The IOSB is embedded in the message control block so that it is available to the read-completion routine. The IOSB reflects the status of the $QIO read.
10. The AST read-completion routine. CompletionAst is used only for notification and does nothing with the data returned by the read. CompletionAst is called with one argument, the addInputRecP data structure returned by AllocateAddInputRec. This data structure can contain an application (widget) callback and tag.
    CompletionAst uses the LIB$INSQTI routine to insert the data structure on a queue (addInputQueueHeaderA). CompletionAst sets the ADD_INPUT_EFN event flag, which causes the Toolkit to invoke your XtAppAddInput routine for execution at non-AST level as soon as possible.
11. AllocateAddInputRec is used as the ASTPRM parameter. Remember that this is a $QIO system service and not $QIOW. AllocateAddInputRec is invoked after the $QIO read completes, but before the CompletionAst AST read-completion routine is invoked.
    This code is executed as follows:
    1. AllocateAddInputRec sets up the routine to be invoked by XtAppAddInput.
    2. AllocateAddInputRec allocates and initializes a data structure containing allocated space, an application (widget) callback, and a tag to be passed to the CompletionAst routine at AST level. You can use this data structure as needed by your application.
    3. The ProcessMessageRec routine is called with the message data as its argument. Note that ProcessMessageRec is also invoked when the system service completes, but before the CompletionAst AST read-completion routine is invoked. Therefore, by the time that CompletionAst is invoked, ProcessMessageRec has already processed the data and started another $QIO read.
       Note that this implementation queues the next $QIO read request while in the AST routine without waiting for the XtAppAddInput proc to execute.
12. Set up the mailbox and trap messages.
13. Note that this example disables broadcast messages to the terminal. If you do not want to disable broadcast messages to the terminal, you might want to change the code so that it only enables broadcasts to the mailbox.

    { modeBufA[1] |= TT2$M_BRDCSTMBX; Check (sys$qiow (MISC_EFN, devChan, IO$_SETMODE, iosbA, 0, 0, modeBufA, sizeof(modeBufA), 0, 0, 0, 0)); Check (iosbA[0]); }

    
    If you do disable broadcast messages to the terminal, when you exit the program enter the following command:

    $ SET TERMINAL/BROADCAST/NOBRDCSTMBX

    
    This command reenables broadcast messages to the terminal.

14. Start the first asynchronous read on the broadcast mailbox.
15. StartTrappingMessages is called before the call to MrmFetchWidget.
16. The Toolkit has noticed that the ADD_INPUT_EFN flag is set and calls the routine specified in XtAppAddInput, in this case AddInputCallback. Your version of the AddInputCallback routine can perform application-specific functions.
    In the example, AddInputCallback clears the flag and removes the data structure from the queue. The *addInputRecP->routineP field is a widget's callback routine to call and the addInputRecP->closure field is the callback's argument. Neither is used.
    AddInputCallback does not actually do anything with the message data; the ProcessMessageRec routine adds the message data to the XmScrolledList widget.

If you use the MrmFetchxxxx routines to fetch resources allocated through UIL, you should free the memory associated with those resources when you are finished with them.

Table 3-1 lists the UIL value types and the routines your application should use to free their associated resources.

Table 3-1 Freeing Resources Allocated Through UIL

UIL Value	Mrm Value	Routine to Free
string_table	MrmRtypeCStringVector	XtFree
asciz_table	MrmRtypeChar8Vector	XtFree
compound_string	MrmRtypeCString	XmStringFree
string	MrmRtypeChar8	XtFree
integer_table	MrmRtypeIntegerVector	XtFree
integer	MrmRtypeInteger	XtFree
boolean	MrmRtypeBoolean	XtFree
rgb	MrmRtypeColor	XFreeColors
color	MrmRtypeColor	XFreeColors
color_table	MrmRtypeColorTable	XFreeColors for each color in the vector
float	MrmRtypeFloat	XtFree
single_float	MrmRtypeSingleFloat	XtFree
font_table	MrmRtypeFontList	XmFontListFree
font	MrmRtypeFont	XmFontListFree
icon	MrmRtypeIconImage	XFreePixmap
pixmap	MrmRtypeIconImage	XFreePixmap
xbitmapfile	MrmRtypeXBitmapFile	XFreePixmap
class_rec_name	MrmRtypeClassRecName	Do not free
keysym	MrmRtypeKeysym	Do not free
translation_table	MrmRtypeTransTable	Not applicable
identifier	MrmRtypeAddrName	Do not free
any	MrmRtypeAny	Depends on usage

DECwindows applications can use the help widget to display general and context-sensitive information in response to a user request for assistance. This chapter presents an overview of the help widget and describes its components. In addition, the chapter covers help widget callbacks and explains how to use the help widget. Other sections show how to create the help widget with UIL or using the Toolkit help widget creation routine.

The DECwindows Companion to the OSF/Motif Style Guide describes the recommended appearance and behavior of the help widget.

The help widget is a modeless widget that allows you to display appropriate, context-sensitive help text in response to a user query. Figure 4-1 shows a sample help widget from the OpenVMS DECburger demo application.

Figure 4-1 Sample Help Widget

The help widget can be viewed as an independent application that your application calls to provide help functions. Using the help widget, you can create and manage one or more help windows and determine the first topic to be displayed to the user. The modeless behavior of the help widget permits an application to support one or more concurrent help widgets.

Your application is responsible for invoking a help pull-down menu widget with push-button widgets (or gadgets) for your chosen help topics. The labels for the push buttons should indicate the types of help available.

The OSF/Motif Style Guide suggests that applications include the following topics in the help pull-down menu widget, when appropriate to the application:

• On Context---Provides context-sensitive information.
• On Help---Provides information about how to use the application's help facility.
• On Window---Provides overview information for the window.
• On Keys---Provides information about the application's use of keys, mnemonics, and keyboard accelerators.
• Index---Provides an index, with search capability, for all help information in the application. Note that the help widget provides its own search function.
• Tutorial---Provides access to the application's tutorial, if one exists.
• On Version---Provides information about the application, such as its formal name and version number.

You can also add application-specific help topics.

4.1.1 Invoking the Help Widget

A user can invoke the help widget four ways:

• The user clicks on a push button in the Help pull-down menu. Your application calls the help widget to create a help window. Your application can use either UIL or the Toolkit help routine to call the help widget.
• The user clicks on the On Context push button in the Help pull-down menu and the application enters context-sensitive help mode. The user then moves the pointer to some object and clicks MB1. Your application calls routines to display context-sensitive help on the object or on its nearest ancestor with context-sensitive help available.
  You can use a help callback routine to create a help widget (or change an existing help widget) to display appropriate help text. See Section 4.7.1 for more information.
• The user moves the input location to an object and presses the Help key on the keyboard. The Help key displays context-sensitive help on the object that has input focus or on that object's nearest ancestor with context-sensitive help available. Note that users cannot use the Help key to generate context-sensitive help for widgets that do not accept input focus, such as XmLabel widgets.
• The user types a help topic command string in a command window widget. Your application must include a command window widget to support this mechanism.

As an application developer, you must decide which Help invocation methods to support. Most DECwindows applications support invoking the help widget by clicking on a help option in the menu bar and through context-sensitive help.

4.1.2 Help Widget Terminology

This chapter uses the terms defined in Table 4-1 to describe the help widget.

Table 4-1 Help Widget Terminology

Term	Definition
help widget	The general name for all modules that compose the widget.
help window	The window that contains all of the help information. There is one help window for each help widget. Help display is synonymous with help window.
help session	All the help interactions (requests, answers, and so on) that occur while an application is running. A help session can be composed of several help widgets.

4.2 OpenVMS Help Library Information

Neither UNIX systems nor Windows NT systems have a librarian utility. On these systems, the help widget reads the .HLP file directly. The information contained in this section applies only to OpenVMS systems.

This section describes how to use OpenVMS help libraries with the help widget. For general information about the OpenVMS Librarian Utility, see the VMS Librarian Utility Manual.

When you create a help widget on an OpenVMS system, you pass an OpenVMS help library specification to the help widget creation routine. The help widget uses this specification to locate and read the help files. The help libraries for OpenVMS DECwindows applications are conventional OpenVMS help libraries. You can use a command similar to the following to create an OpenVMS help library:

$ LIBRARY/HELP/CREATE DECBURGER.HLB DECBURGER.HLP

The help widget includes two resources that you use to specify the OpenVMS help library and its type. The DXmNlibrarySpec resource specifies an OpenVMS help library file specification. An OpenVMS help library has a default file type of HLB and defaults the file type of input files to HLP.

The DXmNlibraryType resource has a predefined value of DXmTextLibrary.

For applications running on OpenVMS, the help widget uses these resources to identify the location and type of the help topic database. Once you have invoked the help widget, you can navigate only within the selected OpenVMS help library.

The help widget includes an OpenVMS help library cache, specified by the DXmNcacheHelpLibrary resource. The DXmNcacheHelpLibrary resource is a Boolean attribute that specifies whether the text of the OpenVMS help library is stored in the help widget's cache memory. If true, the library is initialized when it is first opened and is cached in memory until the application closes down.

If DXmNcacheHelpLibrary is false, the text is not stored in cache memory. The default is false.

4.2.1 OpenVMS Help Library Modules

The files you insert into OpenVMS help libraries are text files you build using a program or a text editor. Each help input file can contain one or more modules; each module contains a group of related keys numbered key 1 to key 9. Each key represents a hierarchical level within the module.

The OpenVMS Librarian Utility stores a key-1 name as its module name. The key-2 through key-9 names identify subtopics related to the key-1 name. For the purpose of making the HLP file easier to maintain, it is good practice to associate top-level help topics with key-1 names. However, there is no requirement to do so.

4.2.1.1 Accessing OpenVMS Help Library Modules

Your OpenVMS application can access a module from the key-1 name or from any key in the module. For example, if you have help push-button widgets for On Window, On Version, and On Help top-level topics, you might maintain the OpenVMS help library as one file called APPLICATION.HLP and create an OpenVMS help library called APPLICATION.HLB. The APPLICATION.HLP file would contain a separate module, identified by a key-1 name, for each top-level topic. You can also maintain the OpenVMS help library modules in multiple HLP files.

When a user asks for help about the On Window topic, your OpenVMS application could determine from the push-button widget activate callback that the user wanted overview help. Your OpenVMS application could then create a help widget and, through the DXmNfirstTopic resource, pass to the help widget the string that identifies the correct help topic. This string would identify a key-1 name or another key in the module.

The help widget uses the key-name hierarchy to find the help topic. For example, if you want to directly access the help topic identified by a key-3 name, you must also specify the key-1 and key-2 names that form a path to the key-3 name.

The help widget looks in the specified OpenVMS library for the module defined by the string and displays the text. If the string identifies a key-1 name, any key-2 subentries in the Overview module automatically appear as additional topics.

If the user then asks for help on a key-2 subentry, the help widget displays the key-2 text, and the key-3 subentries appear as additional topics, and so on.

4.2.1.2 Specifying OpenVMS Help Library Key Names

There are two ways to specify the OpenVMS help library key names:

• You can directly specify the key name for the help topic in DXmNfirstTopic. The disadvantage to this method is that the key names specified in DXmNfirstTopic must match the key names in the OpenVMS help library. This matching might be difficult to maintain if you have help support for a large number of widgets.
• You can specify the key name as a resource name. Create a UIL module that maps the resource names to the key names for the help topics. If you change the key name of the help topic, you do not have to change application code.

The help widget provides several extensions to the OpenVMS Librarian Utility. These extensions give the help widget more sophisticated search capabilities and take the form of help widget commands (special text lines) in conventional OpenVMS help topics. These commands have the following format:

=name operand(s)

The following syntax rules apply to all commands:

• Commands should be the first lines of text in a help topic.
• The first character of a command line must be an equal sign (=).
• The command name must immediately follow the equal sign.
• Command names are not case sensitive and cannot be abbreviated.
• At least one space must precede the command operand.
• The remainder of the line is the command operand.

The extensions to the OpenVMS Librarian Utility are described in Table 4-2.

Table 4-2 OpenVMS Librarian Utility Extensions

Command Name	Description
=TITLE	Permits a case-sensitive title to be associated with the help topic. This title is displayed in situations where a topic is identified. For example, Overview of the Help Widget. If no title is provided, the OpenVMS help library topic key becomes the topic title. The help widget Search menu lets users search by keyword and title.
=KEYWORD	Permits one or more case-insensitive keywords to be associated with the help topic. If more than one keyword is specified, the individual keywords must be separated by a comma or at least one space. The help widget Search menu lets users search by keyword and title.
=NOSEARCH	Disables search operations for title and keywords on a specific topic.
=INCLUDE	Permits help topics to be shared across modules within a single OpenVMS help library. The operand of the INCLUDE command is a help topic key name. See Section 4.6 for more information about help topic key names. The title of the included topic is automatically added as an additional topic.

Example 4-1 shows a portion of the DECBURGER.HLP help file. Note that the DECBURGER.HLP file is presented only as an example; refer to the DECwindows Companion to the OSF/Motif Style Guide for the recommended content and style of a help file.

Example 4-1 Sample Help File

(1)1 overview (2)=Title Overview of the Help Widget (3)=Keyword overview (4)=Include programming creating create_help_widget A help widget is a modeless widget that allows you to display appropriate, context-sensitive help text in response to a user query. The help widget can be viewed as an independent application that your application calls to provide help functions. The help widget creates and manages one or more help windows and determines the first topic to be displayed to the user. (5)2 functions_1 =Title Using the help widget =Keyword overview functions To use the help widget, you perform the following steps: 1. Use the OpenVMS Librarian Utility (LIBRARIAN) to create an OpenVMS help library. 2. Create a Help menu bar item for your application. The Help menu item should be located at the right of the menu bar. If the menu bar is wider than a line, the Help menu item should be located at the bottom right. 1 about =Title About the Help Widget =Keyword about =Include programming creating create_help_widget This topic provides version information. 1 onhelp =Title Help Widget On Help =Keyword on-help =Include programming creating create_help_widget This topic provides help-on-using-help information. 1 menu_bar =Title Menu Bar Context Sensitive Help =Keyword menu 1 file_menu =Title File Menu Context Sensitive Help =Keyword file 1 edit_menu =Title Edit Menu Context Sensitive Help =Keyword edit 1 not_implemented =Title Not Yet Implemented =Keyword 1 order_menu =Title Order Menu Context Sensitive Help =Keyword order 1 order =Title Order Context Sensitive Help =Keyword order =Include programming creating create_help_widget Order menu context-sensitive help 2 burgers =Title Burgers For Us =Keyword burger 3 burgers_rare =Title Burgers Rare For Us =Keyword burger rare 3 burgers_medium =Title Burgers Medium For Us =Keyword burger medium 3 burgers_well =Title Burgers Well For Us =Keyword burger well . . . 1 options =Title Help on Custom Colors =Keyword options 1 print =Title Help on Print Order =Keyword print 1 programming =Title Programming Help =Keyword programming Programming help. 2 creating =Title Creating a Help widget =Keyword programming Creating a help widget. 3 create_help_widget =Title Creating a Help widget =Keyword programming Programming help for creating a help widget. 1 glossary =Title Help Widget Glossary =Keyword glossary =Include programming creating create_help_widget This topic provides glossary information. . . .