Using the Editors

A grid widget is a two-dimensional array, displayed as columns and rows, that allows users to scroll data both vertically and horizontally. It can be particularly useful for displaying data in a spreadsheet fashion and for displaying database query results in a tabular arrangement.

With a grid widget, you can display an unlimited number of rows associated with a specified set of columns.

Creating and Editing a Grid Widget

A default grid widget consists of a frame, numeric row designators, alphabetic column titles (visible once a widget is added to the grid), and horizontal and vertical scroll bars. By default, all members of the grid are synchronized to scroll together. Grid widget properties define the grid as a whole and, to some extent, the widgets that are contained within the frame.

How to Create and Populate a Grid Widget

1. Choose CreateGrid Frame or choose the grid frame icon from the Create toolbar.
2. On your application screen, click once to create a default-sized widget or drag out the grid widget to the desired dimension (which you can change later).

   The default grid allows for the display of five rows (Onscreen Rows property) and up to 999 occurrences (Max Occurrences property).

3. (Optional) Under Identity, assign a name to the grid widget in the Name property.

Panther numbers grid widgets sequentially from left to right, and top to bottom—as Grid #1, Grid #2, and so on. These numbers are for the Editor's use only and cannot be used to access the grid widget itself at runtime.

4. Add widgets (dynamic labels, single line text, or list boxes) to the grid widget by doing any of the following:

   • Drag an existing widget or widgets to fall within the grid widget border. Widgets can be copied from within the current screen, from another screen, or from an open repository entry.

   • Choose the widget from the Create menu or select the icon from the Create toolbar and click within the grid widget border.

   • Select a widget on the screen and under Identity, specify the name of the grid in the Grid property (this property is available only when a grid widget is on the same screen as the selected widget).

     Each widget is added as the last (rightmost) array, or column, in the grid. The column acquires its number of onscreen rows and number of occurrences from the grid widget itself. Panther internally numbers each column with a field number. Default titles are assigned to the columns, alphabetic identifiers starting with the letter A and going from left to right.

---

Manipulating a Grid Widget and Grid Members

Rubberband a portion of the grid widget, or

• In Motif, click on an area of the grid widget, not on a member of the grid.

• In Windows, click anywhere on the grid, except on a row or column title.

• Select it using the Widget List.

When you move, copy, or delete a grid widget, the members of the grid are moved, copied, or deleted as well.

How to Resize a Grid Widget

Select the grid widget. Do either of the following:

• Drag it by a resize handle to the desired size.

• Under Geometry, set the Onscreen Rows and Onscreen Columns properties to the desired number of rows and columns.

How to Select One or More Grid Members

Do any of the following:

• Under Motif, click on the desired grid member; Shift+click to select more than one grid member.

• Under Windows, click on the desired grid member's column title; Shift+click to select more than one grid member.

• Select the desired grid member (Shift+click to select more than one widget) from the Widget List.

• Select the grid widget, and then choose EditGroupSelect Members to select all members of the grid.

How to Remove a Grid Member from the Grid

Do any of the following:

• Select the grid member. Under Identity, set the Grid Property to None.

• In Windows, click on the grid member's title to select the column and drag the selected widget beyond the border of the grid widget.

• In Motif, select the grid member by clicking on one of its row separators (the mouse pointer appears as a right-left arrow indicator), and drag the widget beyond the border of the grid widget.

How to Delete the Grid Widget, but not the Widgets within the Grid

1. Do either of the following:

   • Select the grid members. Under Identity, set their Grid property to None.

   • Select a grid member, and drag it outside of the grid border.

2. When all grid members have been moved from the grid widget, select the grid widget and choose EditDelete or Cut (or the Cut button from the toolbar).

---

Grid Widget Features

Grid widgets consist of columns and rows. The columns are created by dragging one or more of any combination of the following widget types into the grid widget border:

• Dynamic label

• Single line text

• List box

You determine how many columns are visible on the screen. However, this does not define how much data the grid widget as a whole can contain. Therefore, you can define both onscreen dimensions and offscreen specifications. The background color of the stripe row is defined by the Color Control Panel and corresponds to the highlight color.

Specifying Grid Fonts

You can assign a font for the grid widget by setting the Font Name property under the Font heading. This specification applies to the column titles and row titles if they are used. The font also affects all members of the grid, unless the individual grid member has its own font specification.

Note: Under Motif, the grid members always acquire the font specification from the grid widget itself. In other words, the font specification on individual grid members is ignored.

Displaying Columns

If the grid as a whole contains more columns than can be displayed at one time, you can use a horizontal scroll bar to allow users to shift the columns from left to right and vice versa. In addition, you can include columns that are wider than the grid widget itself. At runtime, the user can expand such fields by using the ZOOM logical key.

How to Control the Onscreen Width of the Grid Widget

1. Create a grid widget and add the widgets that will make up the grid.
2. Select the grid widget.
3. Under Geometry, in the Onscreen Columns property, enter the number of columns that you want to display. This number defines how many columns are fully visible in the grid widget when it is fully shifted to the left.

   In the screen editor, the grid widget adjusts to the correct size to show the specified number of columns exactly (assuming the screen can accommodate the total width of the columns).

   If the Onscreen Columns property is blank, partial columns or blank space can display on the right side of the grid widget when it is fully shifted to the left.

When you add a widget to a grid widget, it is automatically positioned to the right of all other columns. Select the grid member that you want repositioned, and do either of the following:

• Under Identity, enter the desired position by number in the Grid Column subproperty.

  Note: If the grid's Rows Title property is set to First Column, entering 1 in the Grid Columns property defines the selected column as the rows' titles.

• Drag the column right or left beyond the adjacent column.

  Note: If you drag the column beyond the grid widget border, the widget is removed from the grid and becomes a screen widget.

How to Control How the Grid Can Be Shifted from Left to Right to Display Offscreen Columns

1. Select the grid widget.
2. Under Geometry, set the Horizontal Scroll Bar to the desired setting:

   • Yes—(default) Provides a horizontal scroll bar whereby the user can click on the scroll bar to shift the display of columns from left to right and vice versa. You can use the scroll bar while you are in Edit mode.

     Shifting by column shifts in such a way to allow for whole columns to display.

   • No—No scroll bar is displayed. The column display can be shifted by using the right and left arrow keys or Tab.

Each column of the grid, by default, is displayed with an alphabetic column title, starting with the letter A. The column title displays at the top of the grid and remains fixed above the rows of data that scroll below them.

How to Define Column Titles

1. Select the grid widget.
2. Under Format/Display, specify the source/type of column heading in the Column Titles property:

   • Auto Number—Each column is automatically numbered sequentially from left to right beginning with 1.

   • Auto Letter—(default) Each column is automatically assigned an alphabetic heading, beginning with A...Z, AA...AZ, BA...BZ, ..., ZA...ZZ.

   • Per Column—Uses the name designated in the individual widget's Column Title property (under Identity). Widgets derived from database columns automatically derive their Column Title property setting from the Name property.

   • None—No titles appear over the columns.

When a grid widget contains a large amount of data, sometimes shifting the columns from left to right causes vital information to be shifted outside the grid's viewport. You can define how many columns should be stationary when the user tabs or shifts the columns horizontally.

How to Define Stationary Columns

1. Select the grid widget.
2. Under Format/Display, enter the number of columns that should be stationary in the Frozen Columns property.

   The default is 0.

Columns are frozen from the left. So, if you enter 2, the first two columns in the grid are stationary. The remaining columns can be shifted.

The user can enter data into columns that are frozen.

If only frozen columns are visible, the other columns will not be accessible. Therefore, you will need to resize the grid to display at least one nonfrozen column.

Defining Column Separators

Grid widgets display with vertical and horizontal lines to provide definition to each grid cell. You can display columns of data with or without these separators.

How to Define the Display of Column Separators

1. Select the grid widget.
2. Under Format/Display, set the Column Separators property accordingly:

   • Yes (default)—Displays vertical lines between each grid member column.

   • No—Causes the grid to display with no vertical lines.

The number of onscreen rows determines the height of the grid widget and how many rows, or records, are displayed at a time. If there are more rows than can be displayed within the grid widget, use a vertical scroll bar to allow users to scroll the data from top to bottom and vice versa.

How to Define the Number of Rows that Should Be Displayed at Runtime

1. Create a default-size grid widget or drag it out to an approximate size that will allow the desired number of rows to display. Doing this in Windows may cause problems since that grid widget works best when no partial rows are displayed.
2. Add the widgets that will make up the grid.
3. (Optional) Under Geometry, enter the desired number of rows that you want to display in the Onscreen Rows property. This value overrides any array-specific properties you may have previously set on individual grid members.
4. Under Geometry, enter the total number of occurrences in the Max Occurrences property.

   This value overrides any value that you have previously set for individual widgets that are now members of the grid. A blank value returns an unlimited number of rows (default is 1000 as set by max_fetches).

5. Under Geometry, set the Vertical Scroll Bar property to the desired setting:

   • Yes—(default) Allows the user to use the scroll bar to display data in offscreen rows.

   • No—The user can scroll data by using arrow keys or Page Up/Page Down keys to display offscreen rows.

     This value overrides any scrolling-specific property settings that you have previously set for individual widgets that are now members of the grid.

6. (Optional) Under Geometry in the Scroll Increment property, enter the number of occurrences by which the rows should scroll when the user presses the Page Down key and Page Up key.
7. (Optional) Under Geometry in the Circular property, specify the desired behavior:

   • Yes—Causes the first row to redisplay after the last element in the grid is reached, and vice versa when the user arrows or pages up/down to scroll the rows.

   • No—(default) If the user uses the arrow keys to move the cursor to the last/first row, the cursor moves to the next or previous field. If the user presses Page Down/Up to scroll the rows, Panther displays the message "No more data" when the first/last row is reached.

Each row of the grid, by default, is displayed with a numeric row designator that corresponds to the setting of the Onscreen Rows property under Geometry. You can display a more useful row indicator by defining the grid's row titles.

How to Display Titles for Rows of the Grid

1. Select the grid widget.
2. Under Format/Display in the Row Titles property, specify the title source/type:

   • Auto Number—(default) Displays the number corresponding to the row number beginning with 1 (one). As the data is scrolled, the numbers increment appropriately until the last row is reached.

   • First Column—The first data column is used as the row titles. The data is used from this column, but all other display attributes are ignored. In addition, the column can no longer receive focus in Edit mode (use the Widget List to gain access to the widget's properties) or at runtime. All other columns in the grid adjust accordingly; the leftmost column in the grid is considered to be the second column in the grid.

   • None—No row titles are displayed.

By default, all members of the grid widgets scroll synchronously. The assumption is that a row in the grid corresponds to a record in the database, or at least, each element of the row has related information. You can allow a user to click on a single item to select just the one cell or click on a single item to select the entire row. When an item is selected, it is displayed in reverse video or is highlighted.

How to Control What a User Selects in a Grid

1. Select the grid widget.
2. Under Format/Display, set the Stripe Current Row property to the desired value:

   • Yes—(default for grid created with the screen wizard) At runtime, the user can select a row by clicking on any one item in any column and, as a result, the entire row is highlighted. The Up and Down arrow keys will also move the stripe up and down the arrays.

   • No—(default) Individual occurrences, or cells, can be selected. There is no highlight bar.

Grid widgets display with vertical and horizontal lines to provide definition to each grid cell. You can display rows of data with or without these separators.

How to Define the Display of Row Separators

1. Select the grid widget.
2. Under Format/Display, set the Row Separators property accordingly:

   • Yes (default)—Displays horizontal lines between each grid member row.

   • No—Causes the grid to display with no horizontal lines.

The height of a grid row is scaled in relation to the font size. You can change the height of a row by adjusting the space, or the margin, between the text and the row dividers.

The default row margin is dependent on the grid widget's Row Separator property:

• With row separators, the default is 2 pixels.

• Without row separators, the default is 0 pixels.

How to Adjust The Row Margin

• For a single grid widget, under Geometry, enter a value for the Row Margin property. The default unit of measurement is character units. Refer to Table 9-1 for a list of valid units of measurement.

• For all grid widgets, set the application property default_row_margin. The default units for this application property are pixels.

  Note: Applications written in previous versions of JAM, Panther, and Panther can preserve the original row height behavior by setting the application property default_row_margin to 6 in Windows or 5 in Motif.

Defining Column Click Behavior

You can define the behavior that occurs when a user clicks on the column header. The Column Click Action property can be defined for any widget in a grid.

Note: Change the Column Click Action property on widgets in the repository to allow the application's widgets to inherit the new value.

Sorting Items

To specify the column sort order:

1. Select the column. Under Format/Display, set the Column Click Action property to Sort.
2. Set the Sort Order property as desired:

   • Lexicographic —An alphanumeric sort order which allows for better sorting of international font sets.

   • Numeric—The Data Formatting property, under Format/Display, must also be set to Numeric.

   • Date/Time—The Data Formatting property, under Format/Display, must also be set to Date/Time.

   • Custom—If the Sort Order property is set to Custom, a Sort Order Function property subheading will appear. Enter the name of your custom function.

In Windows and in character mode applications, the field used to sort the grid rows will be indicated by a small arrow in that field's column heading. The direction of the arrow indicates the direction of the sort—an up arrow for an ascending sort, a down arrow for a descending sort.

Note: The sort function was not compatible with the transaction manager before Panther 4.60.

Writing a Custom Sort Function

The Sort Order Function property, under Format/Display, is the name of a JPL procedure or installed C function that you have written to compare two elements in the sort. After evaluating the two string arguments according to their positions, the function must return one of the following:

• COMPARE_LESS—the first argument is less than the second one.

• COMPARE_GREATER—the first argument is greater than the second one.

• COMPARE_EQUAL—the two arguments are equal.

• COMPARE_ERROR

Since the arguments to this function will be strings, to implement numeric sorts, you will have to convert the strings to appropriate numeric values.

Specifying a Function

Alternatively, you can specify your own function to define the behavior that occurs when the user clicks on the column heading.

How to Define a Custom Click Function

1. Select the column.
2. Under Format/Display, set the Column Click Action property to Custom. The Column Click Function property will appear.
3. Enter the name of your custom function.

The Custom Click Function is passed a single parameter, which is the object ID of the field whose column heading was clicked. The value it returns is ignored. The function can be written in JPL or can be an installed C function.

As an example, to do a normal colums sort and then perform other operations, sm_obj_sort_auto can be called to do the sort and the other operations can then be performed.

Moving and Resizing Grid Columns at Runtime

The grid widget's dimensions determine the overall size of the frame and how many rows and columns can be displayed. You can make grid members very small or very large; however, the data within the cells of the column might not be completely visible. You can allow users to both move and resize individual columns horizontally in the grid as well as horizontally expand individual cells to see the contents.

How to Allow Users To Move and Resize Grid Members

1. Select the grid widget.
2. Under Geometry, set the Column Move Resize property accordingly:

   • Yes (default)

     The user can move a column:

     • - In Windows, by clicking on the column's title and dragging it either left or right in the grid.

     • - In Motif, by clicking on the column's row separator (the mouse pointer appears as a right-left arrow indicator) and dragging the column either left or right in the grid.

       Note: To ensure that Windows users can, in fact, move grid members, the grid's Column Titles property must be set to Auto Number, Auto Letter, or Per Column.

       The user can resize a column horizontally by dragging on the column's right column separator (the mouse pointer appears as a right-left arrow indicator).

   • No—The grid columns cannot be move or resized at runtime.

1. Click in the desired cell
2. Choose the ZOOM logical key.

   A zoom window opens where the user can view, edit, or enter data (if applicable).

---

Grid Focus Properties

The following Focus properties can be set for grid widgets:

Entry and Exit Function Properties

The grid's entry function is executed when the cursor first enters a field the grid. The order of function calls is: grid entry, group entry, grid row entry, and field (widget) entry.

The grid's exit function is executed in the reverse order. The grid exit function is called when the cursor leaves the grid.

Grid entry and exit functions are passed an occurrence number, which is always zero.

Focus Protection Property

Focus protection set on a grid prevents the cursor from moving into the grid, regardless of how individual members have focus protection set. However, if the grid widget is not protected (Focus Protection is set to No), then the focus protection setting for individual columns is honored.

Row Entry Function Property

The row entry function is executed after the grid entry function and any group entry function, but before the field entry function.

Row Exit Function Property

The row exit function is executed in reverse order of the row entry function. The row exit function is called after field exit functions, and before any group exit function or the grid exit function.