Application Development |
User interaction with an application generally consists of entering data and making choices with function keys and menus, and with action widgets such as push buttons. You associate actions with these application objects through control strings.
Control strings can perform these tasks:
For a table for user-initiated events, refer to Table 17-2.
Associating Control Strings with the Application |
A Panther application has various hooks from which it can execute control strings. You can associate control strings with push buttons, list boxes, and menu items through their Control String property. Some widget types can be double-clicked on; their Double Click property also takes a control string: dynamic labels, single- and multiline text widgets, list boxes, and combo boxes. For example, a push button widget specifies to exit the current screen when it is pressed if its Control Strings property is set to execute the built-in function jm_exit
:
^jm_exit
You can also attach control strings to function keys. Each screen has its own Control Strings property, which lets you list Panther logical keys and a corresponding control string. For example, the following control string list lets users open two screens as windows through the logical keys PF1 and PF2, and leave the current screen through EXIT
:
PF1 = &custInfo
PF2 = &orderDetail
EXIT = ^jm_exit
You can globally associate control strings with function keys at application startup through the setup variable SMINICTRL
. For example, the following statement in your setup file globally associates the EXIT
key with your own exit routine:
SMINICTRL = EXIT = ^myExit
Panther uses the leading character of a control string to determine what type of action to perform—whether to open a screen, execute a function, or invoke a system command. Table 18-1 summarizes these leading characters and actions.
The following sections explain each type in detail.
Displaying Screens |
A control string can open a client screen as a form, as a stacked window, or as a sibling window. Control strings that open screens have the following syntax:
*[leadChar
] [(viewportArgs
)]screenName
If you omit leadChar
, Panther opens the screen as a form. A single ampersand (&
) opens the screen as a stacked window, while a double ampersand (&&
) opens it as a sibling window.
Refer to Chapter 13, "Developing Client Screens," and Chapter 24, "Setting the Screen Sequence," for more information about how Panther manages screens as forms and windows.
Panther looks for the named screen in the following places in this order:
If all searches fail, Panther displays an error message and returns.
You can optionally specify arguments for the screen's viewport—that is, the window in which the screen is displayed. Viewport arguments determine the screen's position on the physical display, the viewport's dimensions, and the offset of the screen's contents within its viewport as follows:
Note:
All viewport arguments are optional. However, if you specify any one argument, you must supply all leading arguments; trailing arguments are optional.
Viewport Arguments
(
row
, col
, len
, width
, vRow
, vCol
)
row, col
row
and col
are one-based offsets from the physical display's top left corner. The physical display excludes any area already used either by the screen manager, such as a base window border, or by the application's menu bar. Thus, arguments of 1,1 start the screen at the first line and leftmost column that are available.
Signed integer values (negative or positive) specify the viewport's position relative to the previously active screen. For example, the following control string invokes newWindow.scr as a sibling window whose viewport is two rows higher and two rows left of the current screen's viewport:
&&(-2,-2)newWindow.scr
len, width
vRow, vCol
If you specify vRow
or vCol
, the cursor appears in the upper-left corner of the viewport, whether or not a field is there. The cursor responds to the cursor keys until it encounters an unprotected field, or the TAB
key is pressed. When it is in a field, the cursor uses the normal tabbing order among fields.
Table 18-2 contains several examples of control strings that open screens.
Executing Functions |
A control string that executes a function has the following syntax:
^ [(targetString
[; targetString]
)]funcName
[(arglist
)]
funcName
jm_
. For descriptions of built-in functions, refer to Table 18-4 or Chapter 3, "Built-in Control Functions," in Programming Guide.
Panther looks first among the installed functions for funcName
, then among the JPL procedures modules. For detailed information about this search algorithm, refer to "Precedence of Called Objects."
The function must return an integer. If the integer corresponds to the value of a Panther logical key, then that key is processed. For example, if a function returns PF4, then Panther behaves as if PF4 had been pressed by the user. The function should return 0 if there is no key to process.
arglist
funcName
. Arguments for installed functions—Panther library functions and your own—must be enclosed in parentheses and delimited by commas or spaces. Arguments supplied to the built-in function jm_keys
should not be enclosed in parentheses.
targetString
[testValue
=]controlString
Panther compares funcName
's return value to each testValue
, reading from left to right. If it finds a match, it processes the specified control string. If you omit a test value, Panther processes the control string unconditionally. The control string can itself contain a JPL call with its own target strings; you can thereby nest multiple control strings with recursive calls.
For example, given this control string:
^(-1=^(^jm_exit)cleanup; 1=&welcome_scr)process
Panther processes the string as follows:
process
.process
to determine its next action:
Table 18-3 shows several control strings that call functions:
Table 18-4 lists a summary of the built-in functions. For detailed information on each function, refer to Chapter 3, "Built-in Control Functions," in Programming Guide.
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.
Invoking Operating System Commands |
A control string that starts with an exclamation point (!) temporarily passes control to the operating system. At runtime, Panther passes the string after the exclamation point to the operating system for execution. After program execution is complete, control returns to the application.
Note: In character-mode, Panther displays a message that the user must acknowledge before control returns to the application.
If you include variables in the control string, they must be prefixed by a colon(:). Panther's colon preprocessor expands colon-prefixed variables to their literal values before passing the string to the operating system.
Table 18-5 shows several operating system control strings: