Application Development

Manipulating widgets at runtime requires that you be able to uniquely identify each widget. In order to identify widgets, it is recommended that you name each widget.

This chapter describes how to identify each widget on the screen, how to identify each occurrence of a widget, and how to determine the contents of a group and of an ActiveX control.

Functions described in this section are documented in the Programming Guide; refer to that manual for the syntax and specific behavior of each function.

Widget Types

You can create widgets in the editor by choosing the widget type on the Create menu or on the Create toolbar. Table 14-1 lists the widget types, their availability and their description in the Using the Editors; that manual also contains instructions for setting property values in the Properties window.

Widget Identifiers

JPL and most runtime functions let you identify widgets by object ID, name, or number. Panther provides three widget identity properties, accessible through JPL or the library function sm_prop_get. All three properties are read-only. In JPL, these properties are:

• id—Set to the integer identifier that Panther assigns to each widget at runtime.

• name—Set to the name that the developer assigns to this widget in the screen editor.

• fldnum—Set to the widget's base field number.

In JPL, you can identify the current widget (the widget that has focus) with statements that use the @current object identifier as follows:

@widget("@current")->widgetProperty

For example, the following statement sets variable cur_widget to the current widget's id property:

cur_widget = @widget("@current")->id

You can also get a widget's id property by calling sm_prop_id, as in this statement:

cur_widget = sm_prop_id(@widget("@current"))

For more information on referencing widgets in JPL, refer to "Setting Properties Using the Property API."

Object IDs

At runtime, Panther assigns each widget a unique object ID, which provides the most reliable way to reference and manipulate that widget. Widget and screen IDs are set when a screen initially opens and remain valid as long as the screen remains on the window stack. All object ID assignments during an application's life span are unique; IDs that are no longer valid are not reused.

You can get a widget's ID through its id property or by calling sm_prop_id.

Widget Names

Each widget can be assigned a name through its Name property in the screen editor. Widgets that are created as the result of importing database tables are automatically named—corresponding to the database column. A widget name can be up to 31 characters and can start with an alphabetic character, an underscore, a dollar sign, or a period. Names are case-sensitive; thus, city and City are two distinct names.

Names must be unique within a screen. Widgets on different screens can share the same name, but they should use the same name only when they share data through an LDB entry or inherit the same properties.

A widget must be named when one of these conditions is true:

• Its contents are shared with other screens through a local data block (LDB).

• It inherits its properties from a repository entry of the same name.

For more information about mapping database columns to widgets, refer to Chapter 29, "Reading Information from the Database."

Field Numbers

Widgets that allow data entry all have internally assigned field numbers. Field numbers are assigned automatically when you add a widget to a screen, and are reassigned whenever the widget position changes. Panther numbers widgets as follows:

• Widgets are numbered sequentially from left to right, and top to bottom—as Field #1, Field #2, and so on.

• Each onscreen occurrence, or element, of an array has a unique field number. The number of the first element in an array, or the array's base field, is the number by which the widget as a whole is identified.

  Notes: Elements in an array might not be numbered contiguously, depending on whether other widgets are positioned on the array's right side. Refer to the next section on arrays for more information about element numbering.

If you rely upon field numbers, be aware of two potential drawbacks:

• Because a widget's position determines its number, changing design considerations and runtime repositioning make referencing widgets by number problematic.

• Widgets that do not contain data, such as static labels, boxes, lines, and grid widgets, are not numbered and so have no fldnum property that you can use to reference them.

In general, names and object IDs are more reliable handles for identifying widgets and controlling their behavior at runtime; named widgets are also easier to identify in your code.

Arrays

Panther identifies an array as any widget that can contain one or more occurrences of data. In this sense, any Panther widget type that can contain data can be regarded as an array. Typically, however, there are three widget types regarded as arrays: single line text, multiline text, and list box. In all three cases, you can modify the Geometry properties of these widgets to allow more occurrences than are visible onscreen. Widgets thus defined are scrolling arrays.

An array consists of elements and occurrences:

• The number of elements in an array is determined either by its array_size property or, if within a grid widget, by the grid widget's onscreen_rows property. All elements in an array are visible whether or not they contain data.

• Occurrences are the data that populate an array, visible via the array elements. Occurrences are numbered independently of elements, between 1 and the number of occurrences that currently populate the array—obtained through the runtime property num_occurrences.

Panther allocates memory only for occurrences that have data; trailing occurrences that are empty are discarded. Information is maintained about the number of occurrences allocated for an array and the offset of occurrences within an array's elements.

Non-Scrolling and Scrolling Arrays

If an array is non-scrolling—its scrolling property is set to PV_NO—it can only have as many occurrences as elements. For example, if a non-scrolling array's array_size property is set to 3, the array can contain a maximum of three occurrences of data.

In a scrolling array— scrolling is set to PV_YES—occurrences can outnumber elements if its max_occurrences property is greater than its array_size property. A scrolling array can contain up to max_occurrences occurrences; if this property is set to NULL, the array can contain an unlimited number of occurrences.

Synchronized Scrolling Arrays

Scrolling arrays can be synchronized so that they scroll together. This helps manage related information in table-like screens.

Panther automatically synchronizes arrays when they meet either of the following conditions:

• The widgets are grid members within a grid widget.

• They are database-derived widgets that belong to the same table view or to different table views that are joined by a server link.

You can manually synchronize arrays that do not meet the above conditions by making the widgets members of a synchronized scrolling group.

Refer to "Synchronizing Scrolling Arrays" in Using the Editors for instructions on creating synchronized arrays.

Element and Occurrence Numbering

At runtime, Panther numbers all occurrences between 1and n, where n has the value of the array's runtime property num_occurrences. In a non-scrolling array, the first occurrence—referenced in JPL as array-spec[1]—is always visible in the array's first element—in JPL, array-spec[[1]]; the second occurrence is in the second element; and so on.

In a scrolling array, the first occurrence and first element coincide when the first occurrence is visible in the first element; if the first occurrence scrolls out of view, the occurrence that is visible in the array's first element can be any number up to and including array-spec->num_occurrences. For example, Figure 14-1 shows scrolling array pid in which the first occurrence—pid[1]—is visible in the array's first element—pid[[1]]:

Figure 14-1 The first occurrence is displayed in the array's first element.

Figure 14-2 shows the same array; however, the data has scrolled up one occurrence so the first occurrence pid[1] is out of view; the first element pid[[1]] now contains the second occurrence pid[2]:

Figure 14-2 The first occurrence is scrolled offscreen; the second occurrence is therefore displayed in the array's first element.

You can obtain the current occurrence in an array's first element through the array's first_occurrence property. For example, given array pid's state in the first figure, its first_occurrence property is set to 1; in the second figure, first_occurrence is set to 2. You can also use this property to programmatically scroll an array's occurrences. For example, the following JPL statement resets a scrolling array so that its first element displays the first occurrence of data:

pid->first_occurrence=1

If an array is referenced in a JPL procedure without an occurrence being specified, Panther uses the default occurrence. When executing a field entry, field exit, or validation function, the default occurrence is the occurrence currently being processed. Otherwise, the default occurrence is 1.

Groups

You can group widgets of the same or different types together. This allows you to perform such tasks as allowing synchronized scrolling among several arrays or allowing selection among radio buttons or check boxes. Widgets within each group retain their separate identities; however, Panther also recognizes groups as unique components that can be named, and identifies their constituent widgets by their relative offset within the group. All group properties are accessible at runtime through JPL and by Panther library functions sm_prop_get and sm_prop_set.

If a widget is a member of a group, the following runtime properties return the group's object ID:

• group— the widget is a member of a selection group.

• sync_group—the widget is a member of a synchronized scrolling group.

If a widget is not a member of that type of group, these properties return an empty string.

Two library functions let you identify groups and their widgets:

• sm_i_gtof converts a group name and group occurrence into a field number and occurrence. This function lets you use other Panther library functions to manipulate group widgets by converting group references into widget references. For example, to access text from a specific widget within a group, use sm_i_gtof to get the field and occurrence number, then call sm_o_getfield to retrieve the text.

• sm_ftog converts field references to group references. It returns the name of the group that contains the referenced widget and the widget's offset within the group.

For information on traversing members of a group, refer to "Traversing Widgets."

Table views are also considered group widgets. Refer to "Identifying a Widget's Table View" for information on identifying the table view at runtime.

ActiveX Controls

Active X controls, available for Windows and Web applications, are considered separately since the ActiveX control itself is not a Panther' widget, only the ActiveX container is. The Active X container's CLSID property (clsid) determines which ActiveX control is located inside the container. If the ActiveX control specified in that CLSID property is registered on your system, the control will be displayed in the editor and the Properties window's ActiveX category will display the control's property names and settings.

For more information on ActiveX controls, refer to Chapter 18, "ActiveX Controls," in Using the Editors.