Using the Editors


Chapter 15 . Grid Widgets

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.

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

Manipulating a Grid Widget and Grid Members

How to Select a Grid Widget

Rubberband a portion of the grid widget, or

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:

How to Select One or More Grid Members

Do any of the following:

How to Remove a Grid Member from the Grid

Do any of the following:

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

  1. Do either of the following:
  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:

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

Defining the Grid's Width

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.

How to Change the Column Order

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:

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:

Displaying Column Titles

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:

Defining Stationary 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:

Displaying Rows

Defining the Number of Rows

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

Displaying Row Titles

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:

Selecting Rows of Data

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:

Defining Row Separators

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:

Changing Row Height

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:

How to Adjust The Row Margin

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:

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:

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.

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:

How to Expand a Single Grid Cell to Its Maximum Length

  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.