Using the Editors


Chapter 12 . Providing Help Facilities

To provide assistance to users of your application, you can include:


Determining the Level of Help Requests

When a user requests help (by choosing Help) on a field that has focus, Panther proceeds as follows:

  1. Determines if the External Help property has a context identifier. If it does, that help engine is invoked and the external help screen is displayed.
  2. If there is no External Help property setting, Panther determines if the Help Screen property names an internal help screen. If it does, the help screen is displayed.
  3. If there is no Help Screen property setting, Panther determines if the Selection Screen property names a selection screen. If it does, the selection screen is displayed.
  4. If there no selection screen associated with the field, screen-level help is displayed.

If you do not define field-level help, you can include screen-level help. When a field has focus and no help is defined for it, Panther checks for screen-level help as follows:

  1. Determines if the External Help property has a context identifier. If it does, that help engine is invoked and the external help screen is displayed.
  2. If there is no External Help property setting, Panther determines if the Help Screen property names a help screen. If it does, the help screen is displayed.

Providing Status Line Text

You can assign status text to screens and to any widgets that can get focus at runtime. Field-level status text is displayed when the cursor is in a field that has status text attached to it; status text associated with a screen is displayed as long as the cursor is not in a field that has its own status text.

You can embed code sequences in the status text that:

These embedded codes are interpreted at runtime.

To define status text for a selected widget or screen, enter the text and any desired code sequences directly in the Status Line Text property under Help in the Properties window

The codes are described briefly below; for a more complete explanation, refer to the JPL msg command in Programming Guide).

Adding Display Attributes to Status Text

To apply a display attribute to status text, include the string %Annnn anywhere in the status text. nnnn is a four-digit hexadecimal number; the corresponding display attribute is then applied to the remainder of the text, or until another %A is encountered. To combine attributes, add the numbers together in hexadecimal. The possible values for nnnn and the corresponding attributes are shown in Tables 52 and 53.

Table 12-1 Status text attribute codes

Attribute Hex Code Attribute Hex Code

Non-display

0008

Blink

0040

Reverse

0010

Highlight

0080

Underline

0020

Dim (low intensity)

1000

Table 12-2 Status text color codes

Foreground Color Hex Code Background Color Hex Code

Black

0000

Black

0000

Blue

0001

Blue

0100

Green

0002

Green

0200

Cyan

0003

Cyan

0300

Red

0004

Red

0400

Magenta

0005

Magenta

0500

Yellow

0006

Yellow

0600

White

0007

White

0700

Displaying Key Names on the Status Line

By embedding key names in your application's status text, you can provide keystroke instructions to the user. To display a physical key name or Panther logical key name in the status text, include the string %Kkkkk anywhere in the status text. kkkk is the short name of a Panther logical key (such as XMIT, EXIT, PF1).

For a list of Panther logical keys, refer to Table 6-1 in Configuration Guide.

If the specified key has a keytop defined in the key translation file used at runtime, the appropriate key label replaces the embedded code. For example, %KEXIT might be replaced with Esc when using the Panther-distributed key translation file for the IBM PC. If there is no keytop in the key translation file, the %K is stripped out, and the Panther logical name remains in the text.

Sounding a Message Bell

To alert the user to a status line message, precede the status text with %B. This notation causes Panther to issue a beep on the terminal. The Status Line Text property setting might look like %BDon't forget to check return/due date.


Using Panther Help Screens

A Panther help screen, or internal help, can be associated with any screen in your application as well as with any widget or menu item that can get focus. By using Panther internal help screens, you can ensure that your application help is environment- and platform-independent.

A Panther help screen can provide users with information about a field and its contents, a menu item, or the screen as a whole. A help screen that is attached to a widget can also be used to enter or change that widget's data.

Help is invoked at runtime when the user chooses Help or if you have specified that the help screen opens automatically on entry to a widget. Refer to "Determining the Level of Help Requests" for the order of precedence that Panther uses to display help.

Creating Internal Help Screens

Use the editor to create help screens as with any other screen in your application. There are several ways in which help screens can function and look. With Panther, you can create help screens that:

In general, you want to make help screens distinctly different from your application screens. You might consider the following approaches and property settings:

Display-Only Help Screen

A help screen can be used for display-only data, such as information about the widget, menu item, or screen. A display-only help screen can contain any widget that conforms to these conditions:

You can populate a help screen's data in several ways:

To exit a Panther display-only help screen, the user can press any key or mouse click anywhere on the screen.

Data Entry Help Screen

Users can enter data via a help screen that is invoked from a widget. You can do this by creating a help screen that contains one single line text widget, which is available for data entry.

When a widget opens a help screen, Panther copies the widget's value into the help screen's single line text widget. The user can then edit this widget's value. When the user chooses XMIT on the help screen with XMIT, Panther copies the content of the help screen widget back to the calling widget, then closes the help screen. If the user exits the help screen in any other way—for example, through EXIT—none of the data is copied and the calling widget remains unchanged.

Note: The control string jm_keys XMIT when attached to a push button causes an infinite loop. This occurs because the act of pressing XMIT actually activates a push button.

Panther's help function provides for the automatic passing of data whenever the help screen contains exactly one widget that is unprotected; that is, all protection properties (Input Protect and Focus Protect) are set to No. All other widgets on the help screen must be protected from input and focus.

Note: Scrolling widgets, like multiline text, can be scrolled even if they are protected.

The data entry widget on the help screen is usually defined to be the same length as the calling widget. If the help screen widget is too short, it is automatically made shiftable, and its length then matches the maximum length of the calling widget. If it is too long, then it is shortened—allowing only the number of characters that are defined for the calling widget.

Almost all properties that define the calling widget's input and format are adopted (not inherited) by the data entry widget on the help screen. For example, the following properties are adopted over any specifications for the help screen's widget:

Colors are not adopted; therefore, you can assign different colors to the calling widget and help screen widget.

Multilevel Help System

A help screen can contain widgets that can access another level of help, somewhat like help-on-help. You can define up to five levels of help screens; the user can traverse the help system, moving from one help screen to another. The help screens maintain a separate stack from application screens. You attach help screens to other help screens by naming the subscreen in either a screen's or a widget's Help Screen property.

When the user requests additional information by choosing Help or when you set the Auto Help property to Yes, the lower level help screen opens.

You can provide multilevel help for:

Attaching Panther Help Screens

How to Assign a Panther Help Screen to a Widget or a Screen

  1. Select the object (screen or widget).
  2. Under Help, enter the help screen name or choose More to select the screen from the Select Library Member dialog box. Optionally, you can specify the position of the screen in the Help Screen property. Choose OK. If you attach help to a widget, the Auto Help property is displayed.
  3. In the widget's Auto Help subproperty, define the desired behavior:

To assign a Panther help screen to a menu item, enter the screen name in the item's Panther Help property (refer to Help Screen).

Positioning Help Screens

You can control where and what appears when help is invoked by specifying the position and size of the help screen or selection screen directly in the Help Screen property or Selection Screen property, respectively. The full format of the position and size specification is:

(row,col,height,width,vrow,vcol)

If you do not specify a position, Panther attempts to display the entire help screen without hiding the field.

If you do not specify height and/or width, the help screen displays in the size specified in its Height and Width properties.

row
The row of the physical display at which to position the upper left corner of the help window's viewport. If row starts with a + or -, then row is the row offset, relative to the top left corner of the current screen, at which to position the upper left corner of the help window's viewport.

col
The column of the physical display at which to position the upper left corner of the help window's viewport. If col starts with a + or -, then col is the column offset, relative to the top left corner of the current screen, at which to position the upper left corner of the help window's viewport.

height
The size of the viewport in rows.

width
The size of the viewport in columns.

vrow
The row of the help window to be initially displayed in the upper left corner of the viewport.

vcol
The column of the help window to be initially displayed in the upper left corner of the viewport.

Using Selection Screens

A selection screen, as well as a help screen, can be attached to any single line widget or multiline text widget (whose Word Wrap property is set to No). It is displayed under the following conditions:

When the selection screen is displayed at runtime, the user can make a selection and it is automatically copied back to the associated widget on the calling screen. Cancelling the selection or pressing EXIT leaves the field unchanged.

Assigning a selection screen to a widget does not restrict data entry into the field, it only provides a list of possible choices. To restrict the choices to the entries in the selection screen, specify the same selection screen name in the Table Lookup property (under Input) as well. Refer to "Using Table Lookup Screens" for more information.

Creating a Selection Screen

Use the screen editor to create selection screens, just as you would create any other screen in your application.

  1. Use any widget that allows the user to make a selection; for example, a list box (set the Listbox Type property under Identity to Action) or an array of push buttons works well on selection screens.

    The length of the widget on the selection screen need not be the same as the length of the associated text widget on the underlying screen. However, the length of text widget determines how much data does display. Therefore, if the selection widget length is greater than the calling text widget, the data might be truncated if the Max Data Length property is not sufficient. However, by limiting the size of the widget, you can include additional information on the selection screen entry that will not be able to display in the calling text widget. Figure 12-1 illustrates an example of this type of selection screen.

    If the underlying text widget has a format of right justified output (Justification property is set to Right) and has a Max Data Length of 4, for example, then only the rightmost part, or the first 4 characters, of the selection screen field is displayed in the underlying widget.

    Figure 12-1 Only the first four characters are returned to the field on the underlying screen. The remaining data serves as additional help.

  2. Determine the source of the data that will populate the selection screen.

At runtime, you can shrink the screen to fit the number of selections by calling the library function sm_shrink_to_fit.

Note: In a three-tier architecture, you must create a selection service component for every selection screen. A selection service component is identical to its corresponding selection screen, except that it does not have push buttons or a title bar. It facilitates the transfer of data from the server to the selection screen on the client side of the application.

Attaching a Selection Screen

How to Assign a Selection Screen

  1. Select the text widget.
  2. Under Help in the Selection Screen property, enter the name of the screen that holds the valid choices or choose More to select the screen from the Select Library Member dialog box. Choose OK. The Auto Item subproperty is displayed.

    You can control the selection screen's position by specifying the parameters in the property setting. For example, to display the screen cc_code.itm at row 5, column 25, enter (5,25)cc_code.itm as the property setting. For more information on positioning screens, refer to "Positioning Help Screens."

  3. Specify whether the selection screen should display in the Auto Item property:
  4. (Optional) To provide a means of validating the input data to the text widget, enter the name of a lookup screen in the Table Lookup property under Input in the Properties window. Refer to the next section for details on using lookup screens.

Using Table Lookup Screens

A table lookup screen is similar to a selection screen, except that it doesn't display at runtime. Instead, its contents are used to validate the entry in the field. You can assign a table lookup screen to any data entry widget: single line text, multiline text, and combo box.

For single line and multiline text widgets, it is common to specify the same screen in the Table Lookup property under Input as is indicated in the Selection Screen property under Help in the Properties window. This ensures that the list of entries on the selection screen, which does display at runtime, provides only valid choices.

At runtime, the table lookup screen binary is read, and screen entry and exit functions are called in the same way that other screens are processed.

Creating and Attaching Table Lookup

Use the editor to create lookup screens just as you would create any other screen in your application. The screen can consist of any widget type that can display or accept data—data that is used to validate the contents of the widget on the underlying screen. This widget must not be focus protected; that is, the Focus Protection property (under Focus) must be set to No.

The data can be:

How to Attach a Lookup Screen to a Data Entry Widget

  1. Select the widget.
  2. Under Input, enter the name of the lookup screen in the Table Lookup property or choose More to select the screen from the Select Library Member dialog box. Choose OK.
  3. (Optional) If the widget is a single line text widget, you can also attach a displayable selection screen by naming it in the Selection Screen property under Help.

    This selection screen provides the user with a list from which to choose. Refer to "Using Selection Screens" for more information.


Using External Help Sources

Panther provides support for external help engines (WinHelp, etc.). You provide Panther with the following information:

Attaching Help from Another Source

How to Attach an External Help to an Application Object

  1. Select the widget or screen.

    At runtime, screen-level help is invoked only if the widget that has focus has no help of its own (including internal help).

  2. Specify the context identifier in the External Help Tag property under Help.

The identifier indicates to Panther that there is an external help engine. Assuming that the external help processing hook function is installed, Panther passes the identifier to the hook function when the user chooses Help, and the hook function displays the appropriate help topic.

If the hook function fails, either because it is not installed or the external help file is not found, Panther attempts to access Panther help. Refer to "Determining the Level of Help Requests" for details on the order of precedence Panther uses to display help.


Using Tooltips

You can implement tooltips for widgets in Panther Windows and Motif applications. A tooltip is a popup containing a text message that appears next to a widget in response to a mouse hover event. A mouse hover event occurs when the mouse pointer remains over a widget for approximately one-and-a-half seconds.

For each platform, there are widgets for which tooltips cannot be defined. For Windows, the exceptions are lines, boxes, grid frames and tab decks. For Motif, the exceptions are lines, boxes, tab decks, and grid frames (including widgets within a grid frame).

Adding Tooltips in the Editor

The property Tooltip Text is found in the Help category in the Properties window in the editor. This is a string valued property that simply holds the text to be shown in the tooltip for a widget. If no tooltip text is specified for a widget, it will not display a tooltip at runtime. It is not possible to have a widget display an empty tooltip.

Tooltip Text is not a multi-valued property on the editor. All the occurrences of an array will show the same tooltip at runtime. However, starting in Panther 5.10, occurrence tooltips are supported at runtime.

The Tooltip Text property can be changed at runtime. Its value in C is PR_TOOLTIP_TEXT and its JPL mnemonic is tooltip_text.

Controlling Tooltip Appearance

Tooltip appearance is, in general, determined by platform settings in the Windows desktop or in Motif. In the Windows desktop however, there is a property called tooltip_style (PR_TOOLTIP_STYLE in C) that can be used to get and set the Windows tooltip style bits.

The tooltip_style property is of application scope. It applies to the tooltips associated with all widgets and to the tooltips associated with the toolbar.

The following table lists the bits that can be set with the tooltip_style property, the Windows bits they correspond to, and the values so defined.

Panther bit Wndows bit Value

PV_TOOLTIP_ALWAYS

TTS_ALWAYSTIP

0x01

PV_TOOLTIP_NOPREFIX

TTS_NOPREFIX

0x02

PV_TOOLTIP_NOANIMATE

TTS_NOANIMATE

0x10

PV_TOOLTIP_NOFADE

TTS_NOFADE

0x20

PV_TOOLTIP_BALLOON

TTS_BALLOON

0x40

Some of these bits are relevant only to the latest versions of the Windows operating system. Other bits are undefined, but may be defined in future releases of Windows.

PV_TOOLTIP_ALWAYS is set by default. This means that the tooltip will be displayed even when the Panther application is not active. Clearing this bit will prevent tooltips from being displayed when the Panther application is inactive. However, tooltips will always display on an inactive form within an active Panther application.

PV_TOOLTIP_NOPREFIX is off by default and is irrelevant to Panther applications.

PV_TOOLTIP_NOANIMATE and PV_TOOLTIP_NOFADE are off by default. They are used to override Windows desktop settings. If a user's desktop is set up with the tooltip animation and fading features enabled tooltips will display those behaviors. Setting these bits will override the desktop preferences and turn off animation or fading, respectively, for tooltips in the Panther application.

PV_TOOLTIP_BALLOON is off by default. Setting this bit will cause tooltips to be displayed in a "balloon," like the voice balloon used in comic strips, rather than the usual plain rectangle.

Examples

This JPL code will turn off the TOOLTIP_ALWAYS bit and prevent tooltips from being displayed for Panther widgets when the Panther application is not active:

@app()->tooltip_style = @app()->tooltip_style & ~ PV_TOOLTIP_ALWAYS

This will set both the BALLOON bit and the NOANIMATE bit:

@app()->tooltip_style = @app()->tooltip_style | \
PV_TOOLTIP_BALLOON | PV_TOOLTIP_NOANIMATE