OpenEdge Development: Progress 4GL Handbook

Providing Help for OpenEdge Applications

Online help provides users with immediate access to information as they work with a software application. OpenEdge™ provides multiple ways to supply online help to applications.

This chapter explains how you can implement:

Field-level help — Short strings of text that describe the functions of the field-level objects in your application’s user interface. Field-level help includes status area messages and ToolTips.
A complete online help system — A help file that can provide large amounts of information about your entire application.

You can use both of these help delivery mechanisms or just one, depending on the kind of information you want to provide your users.

This chapter includes the following sections:

Field-level online help
Online help systems

Field-level online help

OpenEdge supports two techniques for implementing field-level help for the user interface of your application: status messages and ToolTips.

Status messages

A status message is a string of text that appears in the status area of a window and describes the function of the field-level object that has input focus.

Notes: The status area is an optional feature of an OpenEdge application window. It displays one line of message text at the bottom of the window. Its appearance is controlled by the STATUS-AREA attribute. Thus, if the STATUS-AREA is disabled on a window, no help message appears. While a dialog box does not have a status area, help strings defined for fields on a dialog box are displayed in the status area of its parent window.

Also, when you use the HELP attribute to display help text for a widget, Progress overwrites any status text (defined with the STATUS statement) with the HELP text.

Status messages are a good way to provide cursory information about a database field or a field-level object in your application. You define status messages for database fields in the field schema (using the Data Dictionary) and for field-level objects in the appropriate property sheet (using the AppBuilder), or in 4GL code written in the Procedure Editor.

OpenEdge provides the ability to associate status messages with database fields and those field-level objects that can receive input focus. These messages are easy to implement and produce a preliminary level of help for your application. When the user tabs through certain field-level objects (fill-in fields, buttons, combo boxes, selection lists, editors, toggle boxes, radio sets, and sliders) that are enabled for input on an application interface, OpenEdge displays help text in the status area of the current window, as shown in Figure 10–1.

Figure 10–1: Status bar message for a field-level object

There are three methods for creating help text in the status area:

Defining help text for database fields in the schema definition.
Creating help text for field-level widgets with 4GL statements and the HELP attribute.
Creating help text for field-level widgets in the Advanced Properties dialog box in the AppBuilder.

The next three sections discuss these methods for creating help text.

Associating help text with database fields

By default, a data representation object associated with a database field displays the help text defined for that database field. You can define and store a default help string as part of the schema definition of a database field using the Data Dictionary. Creating help strings in the database schema provides a centralized location for help strings and makes them easy to maintain.

To define help text in a database field’s schema definition:

Connect to your application database, for example, sports2000.
In the Data Dictionary, select a database table (for example, Customer) then choose the Fields button .
Double-click a database field, for example, Name. The Field Properties dialog box appears:



In the Help Text field, type the text string you want to associate with the database field, then choose OK.

You can then run a test program to view the message in the status area. For example, you can open the Procedure Editor and run the following program:

FOR EACH customer FIELDS (name):    UPDATE name WITH 1 DOWN. END.

You can then see your help text shown in the status area of the running window, as shown in Figure 10–2.

Figure 10–2: Sample database field help text in the status area of a window

Note: Make sure that the test program involves an update to the database field. A program that just displays the field does not show the help message in the status area.

Specifying help text with the Progress 4GL

The alternative to associating help strings with database fields is to define help strings as a part of field-level objects that contain the data. To attach a help string to a field-level object, use the HELP option of the Format phrase specified with the following 4GL statements: CHOOSE, DEFINE TEMP-TABLE, DEFINE BROWSE, DEFINE FRAME, ENABLE, FORM, PROMPT-FOR, SET, or UPDATE. The following code shows an example using the DEFINE FRAME statement:

DEFINE FRAME FRAME-A    BUTTON-1 AT ROW 4 COL 12       HELP "Choose to cancel the operation and exit."    WITH 1 DOWN NO-BOX OVERLAY SIDE-LABELS       AT COL 1 ROW 1       SIZE 74 BY 11.

You can also use the HELP attribute to define help strings for field-level objects. For example, after the DEFINE FRAME statement, you can use the following code to change the help text for the button:

BUTTON-1:HELP = "This button cancels the operation and exits the window."

In Progress, the Format phrase HELP option and the HELP attribute let you define help strings for widgets not associated with database fields. Help strings defined with these options override any help strings specified for associated database fields in the Data Dictionary. For more information, see the Format Phrase and the HELP attribute reference entries in OpenEdge Development: Progress 4GL Reference.

Defining help text with the AppBuilder

Within the AppBuilder, you can specify a help string for a field-level object in its Advanced Properties dialog box.

To define help text for a field-level object in the AppBuilder:

Open your window (.w) file in the AppBuilder.
Note: Make sure that the status area of your window is enabled. To check this option, select the design window’s title bar then choose the Object Properties button from the AppBuilder toolbar. The property sheet for the window appears. Verify the Status-Area option is checked.
Double-click on a field-level object, such as a button. The property sheet for the object appears.
Choose the Advanced button in the property sheet. The Advanced Properties dialog box appears.
Type a help message in the Help field. For example, for a Cancel button message you could type: Cancel the operation and exit:



Choose OK to close the Advanced Properties dialog box.
Choose OK again to close the property sheet.
Save the window. The help string that you typed in the Advanced Properties dialog box becomes part of a HELP option of a FORMAT phrase in the DEFINE FRAME statement generated by the AppBuilder.
Run the window and select the object (in this example, the Cancel button). The help text appears in the status area of the window:

ToolTips

A ToolTip is a short string that appears in an enclosing rectangle when the user pauses the mouse pointer over a field-level widget. ToolTips are widely used in Windows applications. For example, ToolTips are often used to provide labels for toolbar buttons, as shown in Figure 10–3.

Figure 10–3: ToolTip example

You can assign a ToolTip to any field-level object such as a button, combo box, editor, fill-in field, image, radio set, selection list, slider, text, and toggle box.

Implementing ToolTips with the Progress 4GL

To implement ToolTips, you specify the ToolTip text in the TOOLTIP attribute of the associated object and set the TOOLTIPS attribute of the SESSION system handle to TRUE.

TOOLTIP attribute

Each object for which the TOOLTIP option is implemented has a run-time attribute, called TOOLTIP, established with read/write capabilities. If the TOOLTIP attribute is set to "" or the unknown value (?), then no ToolTip is displayed for that object. The default is to not have a ToolTip. You can add a ToolTip to an object at any time.

Here is the syntax is for the TOOLTIP option:

SYNTAX

[ TOOLTIP tooltip ]

tooltip

A quoted string containing the text that displays when the user pauses the mouse pointer over the object.

The following code example shows how to specify the ToolTip attribute at run time:

Btn_OK:TOOLTIP = "Select this button to accept the information."

You can use the TOOLTIP option with the following 4GL elements:

DEFINE BROWSE statement
DEFINE BUTTON statement
DEFINE IMAGE statement
DEFINE RECTANGLE statement
VIEW-AS phrase for combo box, editor, fill-in, radio set, selection list, slider, text, and toggle box objects

TOOLTIPS attribute

There is a session attribute called TOOLTIPS. The session default setting for TOOLTIPS is on (TRUE). To turn TOOLTIPS off for the session, set the TOOLTIPS session attribute to FALSE, for example:

SESSION:TOOLTIPS=FALSE

Implementing ToolTips with the AppBuilder

The OpenEdge AppBuilder tool allows you to define ToolTips by entering ToolTip text in an object’s property sheet.

To define ToolTips using the AppBuilder tool:

Open a design window in the AppBuilder.
Select a field-level object (such as a button) in the design window, then choose the Object Properties button to open its property sheet.
Type some help text in the Tooltip fill-in field:



Note: The Help ID field is not related to ToolTips. It is for specifying an identifier for the help topic associated with this object.
Choose OK, then Save the window.
Run the window and pass the mouse cursor over the object. The ToolTip appears in a rectangular box:

Online help systems

While field-level help in the form of status messages and ToolTips offers a first level of information for end users, the information it provides is limited. A help system can provide much larger amounts of information to the end user with a much more sophisticated delivery mechanism.

From the end user’s perspective, there are two general ways to access information in a help system:

Context sensitivity — Context-sensitive help is information that is primarily accessed “on demand.” Typically, the end user clicks a help button in a dialog box, presses a help key (usually F1), or clicks the question mark icon to access a help topic that explains the current status or user interface of an application.
Navigation — A help file can be opened in such a way that the end user is not immediately presented with a specific help topic. For example, the Help Topics item on the Help menu of an application window opens a help viewer that allows the end user to access help topics in several different ways.
Help topics containing conceptual information or reference information are typically accessible only through navigation.
Individual help topics can also contain links to other topics that provide related information in the form of definitions and other help topics. Also, help viewer windows usually implement features that allow end users to navigate among help topics in various ways.

In a help system, help information is stored in a help file that is external to the application’s source code. A help author creates the help file, which is divided into chunks of information called help topics. An application programmer uses the SYSTEM-HELP statement to direct Windows to either display a specific help topic in a help viewer window, or allow the end user to navigate through the help topics via the help file’s table of contents or search program.

While a help system should appear to end users as a seamless part of an OpenEdge application, the Progress 4GL’s SYSTEM-HELP statement actually calls a separate Windows application. For Microsoft HTML help (.chm) files it calls hh.exe, which launches the Microsoft HTML Help Viewer.

For information about what you need to create and run Microsoft help applications, go to the Microsoft Developer’s Network Web site (msdn.microsoft.com) and search for HTML help.

Because help information is stored in an external help file or files, a help system requires a coordinated effort of information design and application programming. The help author codes, compiles, and tests the help files, and the application programmer adds the appropriate Progress 4GL code to the application to invoke the help viewer and display the appropriate help topic when the end user requests help.

A help system consists of three elements:

Help information — Text that assists users so that they can understand and use an application. The help information for an application resides in one or more help files and is displayed in chunks or units of information called help topics. Each help topic contains information about a single subject. For example, a help topic might describe a dialog box in your application, define a term, give instructions on how to perform a task, or describe a 4GL language element. Each help topic is associated with a unique identifier, called a topic ID.
Both types of help files are generated by compiling a set of help source files. The HTML Help (.chm) files are compiled HTML files. The Windows Help files (.hlp) are compiled binary files.
For more information on how to organize and write help information, go to the Microsoft Developer’s Network Web site (msdn.microsoft.com).
Help engine — The executable file (hh.exe for HTML help or winhelp32.exe for Windows Help) displays help topics in a help viewer that allows the user to navigate among help topics in a help file.
For more information about the help engines, go to the Microsoft Developer’s Network Web site (msdn.microsoft.com).
Help calling interface — The code in an application that allows users to access help information. It calls the help viewer and determines which help topic to display. Users can request and receive help information using a help keystroke, a help button, or a help menu.

The following sections describe in detail how to create a help calling interface for an OpenEdge application.

The SYSTEM-HELP statement

An OpenEdge application executes the Windows help engine (hh.exe or Winhlp32.exe) using the SYSTEM-HELP statement. Here is the syntax for the SYSTEM-HELP statement:

Syntax

SYSTEM-HELP file-string [ WINDOW-NAME window-name ] {   CONTENTS     | CONTEXT int-expr     | HELP-TOPIC string     | KEY string     | ALTERNATE-KEY string     | POSITION X x Y y WIDTH dx HEIGHT dy | POSITION MAXIMIZE     | QUIT     | SET-CONTENTS int-expr     | CONTEXT-POPUP int-expr     | PARTIAL-KEY string | MULTIPLE-KEY char TEXT string     | COMMAND string     | FINDER     | FORCE-FILE | HELP }

file-string

The file-string parameter is a character expression that specifies the pathname of a help file. If the file has a .chm extension (the extension for compiled Microsoft HTML Help files), the Microsoft HTML Help viewer is launched. If the file has a .hlp file extension, the Microsoft Windows Help viewer is launched.

WINDOW-NAME window-name

This option is supported for Windows Help (.hlp files) only.

The window-name parameter is a character expression that evaluates to the primary or secondary window name as defined in the [WINDOWS] section of the help project file. If the window name is omitted, or if “main” is specified, the primary help window is used.

CONTENTS

This option is supported for backward compatibility only.

For HTML Help, this option displays the Microsoft HTML Help viewer with the default topic in the content pane. Use the HELP-TOPIC option to specify the topic to display.

For Windows Help, this option displays the help topic defined as the contents in the [OPTIONS] section of the help project file.

CONTEXT int-expr

Displays the help topic that the context number identifies. You define context numbers in the [MAP] section of the help project file.

The int-expr parameter is the context number for the help topic.

HELP-TOPIC string

This option is supported for HTML Help (.chm files) only.

Displays a help topic in the content pane of the Microsoft HTML Help viewer.

The string parameter is a character expression that indicates the topic (.htm/.html file) within the compiled Microsoft HTML Help (.chm) file to display.

KEY string

For HTML Help, this option displays the topic matching the string found in the keyword index. Use semicolons in the string parameter to delimit multiple keywords. If no match is found, Microsoft HTML Help displays the help viewer with the Index tab on top.

For Windows Help, this option displays the help topic matching the string found in the index keyword list. If there is more than one match, it displays the first topic containing the keyword. If there is no match or the string is omitted, a message is displayed indicating that the keyword is invalid. The string parameter is a character expression that evaluates to a keyword for the desired help topic.

ALTERNATE-KEY string

This option is supported for HTML Help (.chm files) only. For Windows Help (.hlp files), see the MULTIPLE–KEY option.

Displays a help topic matching the string found in the alternate keyword (Alink) index. The string parameter is a character expression that evaluates to a keyword in the alternate keyword index.

POSITION X x Y y WIDTH dx HEIGHT dy

Positions an existing (already opened) help window as specified.

The x parameter is an integer expression that specifies the x coordinate for the help window.

The y parameter is an integer expression that specifies the y coordinate for the help window.

The dx parameter is an integer expression that specifies the width of the help window.

The dy parameter is an integer expression that specifies the height of the help window.

POSITION MAXIMIZE

Maximizes an existing (already opened) help window.

QUIT

Informs the help application that help is no longer required. If no other applications are using help, the operating system closes the help application.

SET-CONTENTS int-expr

This option is supported for Windows Help (.hlp files) only. This option is supported for backward compatibility only.

Dynamically remaps the contents help topic from what is defined in the [OPTIONS] section of the help project file. When a CONTENTS call is made, the new contents help topic is displayed.

The int-expr parameter is the context number for the new contents help topic.

CONTEXT-POPUP int-expr

This option is supported for Windows Help (.hlp files) only.

Displays the help topic in a pop-up window that the context number identifies. You define context numbers in the [MAP] section of the help project file. If a nonscrolling region exists in a help topic, only that region displays when you use the CONTEXT-POPUP option to display the topic.

The int-expr parameter is the context number for the help topic.

PARTIAL-KEY string

This option is supported for Windows Help (.hlp files) only.

Displays the help topic matching the string found in the keyword list. On Windows, if there is more than one match, no match, or if the string is omitted, it displays the Help Topics: Window Help Topics dialog box with the Index tab on top.

The string parameter is a character expression that evaluates to a partial key for the desired help topic.

MULTIPLE-KEY char TEXT string

This option is supported for Windows Help (.hlp files) only. For HTML Help, see the ALTERNATE-KEY option.

Displays the help topic matching a keyword from an alternate keyword table.

The char parameter is a character expression that evaluates to the single character keyword table identifier for the required table.

The string parameter is a character expression that evaluates to the keyword that is located in the keyword table.

COMMAND string

This option is supported for Windows Help (.hlp files) only.

Executes a help macro.

The string parameter is a character expression that evaluates to the help macro to execute.

FINDER

This option is supported for Windows Help (.hlp files) only.

Displays the Help Topics: Windows Help Topics dialog box, which contains an Index tab, a Find tab, and optionally a Contents tab, with the most recently used tab displayed on top.

If a Contents tab file (.cnt file) is present when you initially call the Help Topics: Windows Help dialog box, then the Contents tab displays on top. However, if a.cnt file is not present, then the dialog box displays with the Index tab on top; the Contents tab is not available.

FORCE-FILE

This option is supported for Windows Help (.hlp files) only.

Ensures that the correct help file is open and displayed.

HELP

This option is supported for Windows Help (.hlp files) only.

Displays the contents of the Progress Help-on-Help file. On Windows, HELP displays the Help Topics: Windows Help Topics dialog box.

Coding the help calling interface

This section explains some SYSTEM-HELP statement calls that are commonly used in the help calling interfaces of OpenEdge applications. For more information on the Progress language elements described in the following sections, see OpenEdge Development: Progress 4GL Reference.

You can run the sample procedure, r-syshlpchm.p, to execute the help calls explained in this section. This procedure demonstrates several features of the SYSTEM-HELP statement with the Procedure Editor help file (editeng.chm). The user can select a button to demonstrate each of the following SYSTEM-HELP options:

CONTEXT
KEY
ALTERNATE-KEY
POSITION
POSITION-MAXIMIZE
QUIT

The source code example r-syshlpchm.p, is in the library, prodoc.pl, in \Program Files\Progress\OpenEdge\src. Follow the directions in the Preface for extracting files from libraries.

To execute r-syshlpchm.p:

Copy editeng.chm from \Program Files\Progress\OpenEdge\prohelp to your OpenEdge working directory (by default, C:\OpenEdge\WRK).
Open r-syshlpchm.p in the Procedure Editor.
Press F2 to run the file.
When you click the buttons on the sample interface, r-syshlpchm.p calls the Procedure Editor help file, editeng.chm:

r-syshlpchm.p

/* r-syshlpchm.p */ DEFINE VAR helpfile as CHAR. DEFINE BUTTON b_context LABEL "CONTEXT Call". DEFINE BUTTON b_blank LABEL "KEY Call-''". DEFINE BUTTON b_single LABEL "KEY Call-'Tools'". DEFINE BUTTON b_full LABEL "KEY Call- Tools;Menu". DEFINE BUTTON b_max LABEL "POSITION MAXIMIZE Call". DEFINE BUTTON b_pos LABEL "POSITION Call". DEFINE BUTTON b_alt LABEL "ALTERNATE-KEY Call". DEFINE BUTTON b_quit LABEL "QUIT Call". FORM skip(1) space(1) b_context space(1) skip(1) space(1) b_blank space(1) skip(1) space(1) b_single space(1) skip(1) space(1) b_full space(1) skip(1) space(1) b_max space(1) skip(1) space(1) b_pos space(1) skip(1) space(1) b_alt space(1) skip(1) space(1) b_quit space(1) skip(1) WITH FRAME x. ENABLE ALL WITH FRAME x. helpfile = "editeng.chm". /* The CONTEXT call displays the help topic associated with the specified context number of a help topic (in this case, 49256, for the Using Editor Buffers topic). */ ON CHOOSE OF b_context IN FRAME x DO: SYSTEM-HELP helpfile CONTEXT 49256. END. /* The KEY call brings up the topic matching the string found in the keyword index. If the string parameter is empty or is omitted altogether, the help viewer displays with the Index tab on top.*/ ON CHOOSE OF b_blank IN FRAME x DO: SYSTEM-HELP helpfile KEY "". END.

/* In a KEY call where the string parameter does not exactly match an index keyword of any help topic, the fill-in at the top of the Index tab is populated with the string that is passed in, and the default help topic is displayed. */ ON CHOOSE OF b_single IN FRAME x DO: SYSTEM-HELP helpfile KEY "Tools". END. /* In a KEY call where the string parameter exactly matches a unique index keyword of a help topic, the help engine automatically launches a help viewer window and displays the matching topic. Use semicolons to delimit multiple keywords.*/ ON CHOOSE OF b_full IN FRAME x DO: SYSTEM-HELP helpfile KEY "Tools;Menu". END. /* In an ALTERNATE-KEY call works like the KEY call but it uses the alternate keyword (Alink) index, if one is provided. */ ON CHOOSE OF b_alt IN FRAME x DO: SYSTEM-HELP helpfile ALTERNATE-KEY "Tools Menu". END. /* The POSITION X x Y y WIDTH dx HEIGHT dy call positions the open help window as specified */ ON CHOOSE OF b_pos IN FRAME x DO: SYSTEM-HELP helpfile POSITION X 2 Y 2 WIDTH 450 HEIGHT 450. END. /* The POSITION MAXIMIZE call maximizes the open help window as specified*/ ON CHOOSE OF b_max IN FRAME x DO: SYSTEM-HELP helpfile POSITION MAXIMIZE. END. /* The QUIT call causes the help engine to terminate, unless another application is using help. */ ON CHOOSE OF b_quit IN FRAME x DO: SYSTEM-HELP helpfile QUIT. RETURN. END. WAIT-FOR GO OF FRAME x.

Accessing online help from the menu bar

A common method of requesting help from an application is by selecting help items from the application menu bar. The menu bar usually includes a help pull-down menu and contains menu items such as:

Help Topics — Instructs the help engine to display the HTML Help Viewer for the specified help file.
About or Version — Provides application copyright and version number information.

The CHOOSE event occurs when a user chooses an option from a menu. In the Progress 4GL, you use a CHOOSE event to code a trigger for menu items.

The following code example demonstrates a help trigger that executes when the user selects a menu item from the application’s menu bar to access the help engine:

ON CHOOSE OF MENU-ITEM menu_help_contents DO: SYSTEM-HELP myhelp.chm CONTENTS. END.

Calling the Help Viewer

Using the CONTENTS option of the SYSTEM-HELP statement displays the HTML Help Viewer for the specified help file. You frequently use this for a Help Topics call from the help menu. The following code example demonstrates a Help Topics call:

ON CHOOSE OF MENU-ITEM Help_Topics: DO: SYSTEM-HELP myhelp.chm CONTENTS. END.

For example, when the user chooses the Help Topics from the Help menu in the Procedure Editor’s main window, the Help Viewer appears, as shown in Figure 10–4.

Figure 10–4: HTML Help Viewer showing Procedure Editor help

Calling the Index function of the Help Viewer

Like the Help Topics call, it is common to call the Index function of the Help Viewer from the Help menu. The following pseudocode calls the Help Viewer with the Index tab on top:

ON CHOOSE OF Button_Search IN FRAME frame_1 DO: SYSTEM-HELP myhelp.chm KEY "". END.

Figure 10–5 shows the Help Viewer for the Procedure Editor help file with the Index tab on top.

Figure 10–5: Help Viewer with Index tab on top

Calling online help with a help button

Your application should provide context-sensitive help when a user wants to learn about the purpose of a particular window, dialog box, or widget. You can code the OpenEdge application to display a Help button, as shown in Figure 10–6. When the user chooses the button, the Help Viewer displays the help topic for the current window or dialog box.

Figure 10–6: Dialog box with a Help button

For example, when the user chooses the Help button in the Procedure Editor Buffer Information dialog box, the user sees context-specific help for that dialog box, as shown in Figure 10–7.

Figure 10–7: Context-sensitive help for the Buffer Information dialog box

As with menu items, you attach triggers to buttons with the CHOOSE event. In this example, a help trigger is attached to the Help button. In the following code example, a help trigger executes when the user chooses a Help button to access help information from an application window or dialog box:

ON CHOOSE OF b_help IN FRAME x DO: SYSTEM-HELP myhelp.hlp CONTEXT 49154. END.

You can write a help trigger for a field-level widget, a frame, a dialog box, a window, or an application. The following code example demonstrates a help trigger that executes when the current application window has input focus and the user presses HELP:

ON HELP OF WINDOW-1: DO: SYSTEM-HELP myhelp.hlp CONTEXT 49154. END.

Accessing online help with the help key

When a user presses the designated help key (usually F1 in Windows applications), a HELP event goes to the field-level widget with input focus in the current frame. If there is no trigger on the field-level widget, the HELP event goes to the current frame. The HELP event continues to move to the next level in the widget hierarchy, as shown in Figure 10–8. If the help event does not find an associated widget, it runs applhelp.p, the OpenEdge help calling interface. This procedure, applhelp.p, in <install-dir>\src\, displays the message, “No application help is available.”

Figure 10–8 depicts the behavior of the Progress HELP event.

Figure 10–8: HELP Event Hierarchy

Quitting help when exiting the application

You can terminate the help viewer with the QUIT parameter. As a matter of sound programming practice, the OpenEdge application should execute the following line of code when it terminates:

SYSTEM-HELP myhelp.hlp QUIT.

If the help engine is running when the user terminates the OpenEdge application, then the Help Viewer also terminates.