Application Development

The client side of a Panther application is largely composed of screens: client screens that users open as forms or windows and screens that are saved as repository entries or that are used to merge data into other screens or widgets as LDBs.

In two-tier applications, client screens contain both the application logic and the presentation interface. In three-tier applications, client screens are primarily concerned with the presentation interface and send service requests to the application server for processing.

This chapter discusses:

• How to open and close screens

• How a screen can be opened as a dialog box

• The size and position of screens

• The scope of screen processing

• Screens' runtime properties

Other chapters in this manual discuss:

• How to move data between screens (Chapter 25)

• How the stack of screens is maintained (Chapter 24)

• How to display messages in a window, on the status line, or as a dialog (Chapter 26)

Creating Screens

You can build screens with the screen wizard or from scratch in the editor. Once the screen is created, save it in the appropriate library.

For information on creating screens and saving them in libraries, refer to Chapter 6, "Defining Screen Properties," in Using the Editors. For instructions on using the screen wizard, refer to Chapter 4, "Screen Wizard," in Using the Editors.

Creating Dialog Boxes

A screen that has its Dialog (dialog) property set to Yes:

• Cannot be resized, maximized, or minimized at runtime. These options are not available on the screen's system menu, and the border (specifically in GUIs) has no maximize/minimize buttons. However, it can be moved.

• Is modal at runtime, the user is forced to enter data, respond to, or acknowledge the dialog box before proceeding with the application. The menu bar and controls strings outside of the dialog box cannot be accessed while the modal dialog box is active.

Any stacked or sibling windows that are invoked from a dialog box are also opened as modal dialog boxes.

To prevent users from closing a dialog box from the system menu, set the screen's Close Item (close_item) property to No.

For an example of a dialog box using tab widgets, refer to "Creating a Tab Dialog Screen" in Using the Editors.

Understanding Screen Scope

A screen provides a namespace for widgets, JPL procedures and Panther variables.

For widgets, this means that all widgets on a screen must be uniquely named, even though a widget with the same name can appear on other screens.

For variables and JPL procedures, this means that Panther searches the current screen for the variable or procedure before going to public modules.

A screen is also one of the levels for menu scope. Setting the screen's Menu Name (menu_name) property overrides the application-level menu.

Opening Screens

Applications typically let users open screens by pressing a key, choosing a menu item, or a selection-type widget or push button. You specify the screen to open through the control string property of the screen, menu item, or widget; the control string specifies which screen to display and whether to open it as a form or window. For example:

For information about the form stack and the window stack, refer to Chapter 24, "Setting the Screen Sequence."

You can also use Panther runtime functions to open a screen and give it focus:

• sm_jform opens the specified screen as a form. It first closes all open screens—that is, the previous top form and any windows in the window stack.

• sm_jwindow and sm_r_window open the specified screen as a window.

  Notes: Avoid calling sm_jform in a screen entry or exit function. Doing so can yield unpredictable results. To open a form at screen entry, use the built-in function jm_keys; pass as its argument a function key with a control string that brings up the desired window. You can call sm_jwindow and sm_r_window in screen entry and exit functions if you close the window before the function returns.

For information about screen entry events, refer to "Screen Entry."

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.

Screen Display Defaults

Unless otherwise specified, Panther tries to display the entire screen. If a screen is opened as a form, Panther displays it at the physical display's upper-left corner; in GUIs, this excludes the menu bar, which remains visible. If a screen is opened as a window, Panther tries to leave the calling screen's last cursor position visible. In GUI environments, the displayed form always leaves the menu bar visible.

Displaying Screens in Viewports

Panther automatically handles screens whose size exceeds the actual dimensions of the viewing area—for example, the screen is larger than the physical display. When a screen's dimensions exceed its display area, Panther displays the screen in a viewport with vertical and horizontal scroll bars, so users can scroll out-of-view data into view. By default, the viewport's upper-left corner (1,1) initially displays the screen's upper-left contents, unless this prevents display of the cursor. Panther always ensures that the cursor's initial position in a viewport—usually the first field—is visible. If necessary, it adjusts the screen offset within the viewport accordingly.

The viewport itself can only be as large as the system's physical or virtual display. In character mode, the two are identical; thus, a viewport can only be as large as the screen. In contrast, under some GUIs—for example, Motif—a viewport can be larger than the physical display. The offscreen portions of the viewport can be brought into view either by the user or programmatically.

Overriding Display Defaults

The control string that you use to open a screen can specify the screen's position and dimensions. If the specified dimensions are unable to display the entire screen, you can also specify the offset of the screen within the viewport. The full control string syntax is as follows:

[lead-char] (row, col, height, width, vrow, vcol) screen-name

If you omit lead-char, 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. If you use ampersands (& or &&) to open a screen as a window, they must precede the viewport arguments. Parentheses must enclose all viewport arguments.

For example, the following control string specifies the PF1 key to open the new_customer screen at the upper left corner of the physical display:

PF1 = (1,1)new_customer

For more information, refer to Chapter 18, "Programming Control Strings."

Specifying Viewports at Runtime

The runtime functions sm_jform, sm_r_window, and sm_jwindow can specify viewport parameters. For example, the following calls to sm_jwindow and sm_r_window are equivalent: each opens myscreen as a stacked window at coordinates 4,4 on the physical display:

ret = sm_jwindow("&(4,4)myscreen");
ret = sm_r_window("myscreen", 4, 4 );

In a Windows application, screens are implemented inside an MDI (multiple document interface) frame. MDI allows several windows to be opened inside a main application window.

Your Windows initialization file contains several settings controlling the use of the MDI frame. For more information, refer to Chapter 3, "Windows Initialization File," in Configuration Guide.

The following library functions deal specifically with MDI frames:

• sm_mw_get_client_wnd gets a handle to the client section of an MDI frame.

• sm_mw_get_frame_wnd gets a handle to the MDI frame of an application.

• sm_mw_PrintScreen sends either the current Panther screen or all the screens in the MDI frame to the printer.

Specifying the Window Style

As of Panther 4.5, there are new options for opening windows under the Windows operating system. The new options are implemented by the properties Keep in Frame and Topmost. These are screen-level properties and are found under the Identity section in the Properties window.

Previously, windows could either be opened as MDI windows or as dialogs. An MDI window cannot be moved outside the MDI frame. A dialog can be moved outside the MDI frame, but blocks access to the MDI frame – when a dialog is opened, focus cannot be given to any MDI windows, nor can the MDI menu bar be accessed until the dialog is closed.

With the new options, a screen can open as a non-MDI window, moving outside the MDI frame, but not blocking access to the MDI windows or to the MDI menu bar. You can also specify this screen to be the topmost window.

For more information, refer to "Specifying Styles under Windows" in Using the Editors.

Closing Screens

You can close a screen with jm_exit and sm_jclose. The two functions are equivalent; jm_exit is a built-in function, while sm_jclose is an installed library function.

By default, the EXIT logical key calls jm_exit and causes the current screen, whether a window or form, to close. If you leave EXIT unassociated with any control string, you can make it available to users to exit the current screen—for example, by pressing its physical key (Esc on most terminals) or by attaching it to a menu item or push button.

For information about screen exit events, refer to "Screen Exit."

Setting Screen Properties

By setting properties in the Properties window, you can define the appearance of the screen in your application. For more information, refer to Chapter 6, "Defining Screen Properties," in Using the Editors.

When you create a screen, Panther initializes its properties according to internally set defaults. You can set a screen to inherit properties from a repository entry through the screen's Inherit From property. When you do this, Panther writes the entry's properties to the target screen. You can subsequently turn inheritance on and off for individual properties, or turn off inheritance for the entire screen by emptying its Inherit From property.

Some screen properties listed in the editor are accessible at runtime. In addition, there are runtime-only properties for screens. There are also runtime properties for screens; For a list of all runtime screen properties, refer to "Screen and Frameset Properties" in Quick Reference.

Using JPL to Set Screen Properties

You can get and set all screen properties at runtime through JPL, which contains two screen objects:

For example, this statement gets the title property for screen vidlist.scr:

cur_title = @screen("vidlist.scr")->title

The following example sets the title property:

@screen("vidlist.scr")->title = "Current Title List"

For more information about accessing properties at runtime, refer to "Setting Properties Using the Property API."

Runtime Properties for Screens

In addition to the properties listed for screens in the Properties window, there are screen properties that are only available at runtime. The screen will also be affected by the application's runtime properties.

numflds

Returns the number of fields on the current screen.

numgrps

Returns the number of groups on the current screen.

sibling

Set the screen as a sibling window. Refer to "Sibling Windows" for the discussion of sibling windows.