| Using the Editors | |
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:
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:
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).
To apply a display attribute to status text, include the string
Non-display
Blink
Reverse
Highlight
Underline
Dim (low intensity)
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 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, To alert the user to a status line message, precede the status text with Adding Display Attributes to Status Text
%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
0008
0040
0010
0080
0020
1000
Displaying Key Names on the Status Line
%Kkkkk anywhere in the status text. kkkk is the short name of a Panther logical key (such as XMIT, EXIT, PF1).
%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
%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.
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:
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:
Display-Only Help Screen
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.
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
Note:
The control string 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:
Data Entry Help Screen
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.
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.
Colors are not adopted; therefore, you can assign different colors to the calling widget and help screen widget.
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:
Multilevel Help System
Attaching Panther Help Screens
How to Assign a Panther Help Screen to a Widget or a Screen
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).
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
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
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
width
vrow
vcol
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 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.
Use the screen editor to create selection screens, just as you would create any other screen in your application.
EXIT leaves the field unchanged.
Creating a Selection Screen
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.
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.
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."
Note:
At runtime, Auto Item causes the selection screen to open automatically unless the widget has been validated. In this case, the user must choose the ITSEL logical key to invoke the selection screen.
ITSEL logical key.
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.
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
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
At runtime, screen-level help is invoked only if the widget that has focus has no help of its own (including internal 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).
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.
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.
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.
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