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:

• Open a screen as a form or window.

• Execute a function.

• Invoke an operating system command.

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.

Search Path

Panther looks for the named screen in the following places in this order:

• The memory-resident screen list.

• All open libraries.

If all searches fail, Panther displays an error message and returns.

Viewport Arguments

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:

(row, col, len, width, vRow, vCol)

Note: All viewport arguments are optional. However, if you specify any one argument, you must supply all leading arguments; trailing arguments are optional.

row, col

The position of the viewport's top left corner on the physical display, where 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

If the window does not fit on the display at the specified location, Panther adjusts it as needed. Panther does not allow viewports to be positioned completely offscreen.

len, width

The viewport's dimensions in rows and columns. A value of 0 or less specifies to use the screen's actual dimensions if the physical display is large enough. Note that the border is counted as part of the screen.

vRow, vCol

The row and column of the screen to display on the viewport's first row and column.

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

The name of an installed or built-in function or a JPL procedure or module. An installed function can be one of Panther's library functions or your own. For information about function installation, refer to "Installing Functions." Built-in functions are preinstalled in Panther and begin with the prefix 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

One or more arguments to pass to parameters in 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

The control string can optionally test the return value against one or more semicolon-delimited target strings. Each target string has this syntax:

[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:

1. Calls the JPL module or procedure process.
2. Evaluates the return value from process to determine its next action:

   • If process returns -1, Panther executes cleanup. When cleanup returns, the built-in function jm_exit is called.

   • If process returns 1, Panther opens the welcome_scr screen.

Table 18-3 shows several control strings that call functions:

Using Built-in 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: