Grid Control System Functions

This section discusses the system functions you can use to affect how the grid control works during runtime.

Grid system functions enable you to manipulate the appearance of the grid and what goes into or comes out of it during runtime. In the latter case, the system applies the command either to the model version of the grid or to the display version. The model version of the grid contains all rows and columns, whereas the display version might have hidden rows or columns. This is an important distinction to make when you are performing actions based on row or column number. For example, assume a grid contains three rows, but the second one is hidden. If you insert a row beneath row number two in the model grid, the insert row becomes row three, and row three becomes row four. However, if you insert a row beneath row number two in the display grid, the row is inserted at the bottom of the grid, because the actual row number two is hidden.

Another distinction to make is whether the system function expects the first grid row number to be zero or one. All system function descriptions where these factors might be an issue include whether they affect the model or display version of the grid and whether they are zero- or one-based.

Similar to the Table View grid format, the List View grid format supports all the grid control system functions, except the Set Grid Font system function. (Release 9.2.0.5)

Some grid-related system functions enable you to alter the appearance of the grid. Use Set Grid Color to change the background color of a cell, row, column, or the entire control. Use Set Grid Font to change the type, style, size, effects, and color of the font in a cell, row, column, or the entire control. Alternatively you can use Set Grid Row Format to use HTML formatting commands to control the appearance of the grid, not only for color and font, but for other factors as well. Use Set Grid Cell Icon within a client-side, icon-setting NER to set an icon for a grid cell. Use Set Grid Cell Icon Visibility within normal form-based ER to control an icon's visibility dynamically.

To enable or prevent a user from customizing the grid, use Display Customize Grid Option.

Use Hide Grid Column and Show Grid Column to hide and display columns in the grid. Although a user cannot affect a hidden column, you can still work with and change values in it programmatically.

If the column is based on a DD item, use Set Data Dictionary Overrides to change the DD attributes of the column, or Set Data Dictionary Item to substitute another DD item altogether. To change the heading for the column, use Set Grid Column Heading.

Use Hide Grid Row and Show Grid Row to hide and display rows in the grid. As with columns, you can still affect hidden grid rows programmatically.

You can also control the bitmap icon that appears next to a given row with Set Grid Row Bitmap.

You can enable or prevent users from changing an existing cell, row, column, or the entire control. Use Enable Grid to enable user edits (assuming that the current mode permits such actions) and Disable Grid to prevent them. Although users cannot alter a disabled grid object, you can change it programmatically.

You can enable or prevent users from importing from Excel or from importing or exporting to Excel or Word with Display Import from Excel Option, Display Export to Excel Option, and Display Export to Word Option.

You can determine if a grid cell has been updated since the last check with Was Grid Cell Value Entered.

Use Get Max Grid Rows to count the number of rows currently loaded into the grid control. Use Get Selected Grid Row Count to count the number of rows in the current selection. The selected area need not consist of contiguous rows.

Use Set QBE Column Compare Style to set the comparison value (=, >, <=, and so forth) for a QBE column. Clear QBE Column clears an entry in a QBE column.

Runtime always fetches all records for all columns defined by the BV. However, you can impact how runtime builds the WHERE and ORDER BY clauses of the SQL SELECT statement it executes to perform a fetch. (Use the various Hide system functions to filter what the user sees even more, if necessary.) Use Set Selection to input the specific values you want to use in the WHERE clause. For example, assume that you want a list of accounts that are greater than 1000 USD. The SQL WHERE statement might look like this (literal values are used to simplify the examples):

WHERE F0902.GBAN01 > 1000

The Set Selection statement that builds this code would look like this:

Set Selection(FC Grid, F0902, GBAN01, <Greater Than>, '1000', <None>)

That is: (grid control, table, alias, comparison type, comparison value, and/or).

The values you input with Set Selection persist until form close. Consequently, subsequent calls to Set Selection enable you to build a complex WHERE clause. For example, say you wanted a list of document types for Foundation. In the F0005 table, system code and object type are in two different columns, so you must call Set Selection twice. First:

Set Selection(FC Grid, F0005, DRSY, <Equal To>, '00', <None>)

Then:

Set Selection(FC Grid, F0005, DRRT, <Equal To>, 'DT', <AND>)

By setting the and/or parameter to <AND>, the system knows to append the WHERE clause with the values from a subsequent call to Set Selection with an AND. Therefore, runtime will build this WHERE clause:

WHERE F0005.DRSY = '00' AND F0005.DRRT = 'DT'

Use Set Selection Append Flag to indicate whether the criteria from the Set Selection system function should replace the criteria from existing filter fields and QBE or be appended to it.

You can alter the sort order of the returned values by using Set Sequencing. Set Sequencing builds the ORDER BY clause of the SQL statement. The Set Sequencing parameters are: Set Sequencing (grid control, table, alias, sort order), so if we wanted to sort the preceding example by the document type code (DRKY) in ascending order, you would code:

Set Selection(FC Grid, F0005, DRKY, <ASCENDING>)

If you need to build a WHERE clause and do not want to use values that may already exist because of previous uses of Set Selection, use Clear Selection to delete all existing selection (but not sequencing) values from memory. To remove sequencing values, use Clear Sequencing.

When you fetch data, you can populate GB and then use system functions to write GB values to the grid control. You can also write from the grid control to the GB and manipulate the GB and grid data in other ways.

To write from the GB to the grid, use either Insert Grid Buffer Row or Update Grid Buffer Row, depending on whether you want to add a new row to the grid (insert) or overwrite an existing row (update). In either case, when you write a new row, you have a variety of configuration options. You can make the new row selectable, editable, updatable, and deletable, assuming that the current conditions permit such actions. You can also clear the GB automatically after insert so that you do not need to make repeated calls to Clear Grid Buffer, which is the system function that removes all values from the GB.

Insert Grid Buffer Row and Update Grid Buffer Row both require a row number that is based on the model grid as input so that runtime knows where to place the new row. One way to determine a grid row number is with the system function, Get Selected Grid Row Number.

To activate a specific grid row during an event, use Get Grid Row. After identifying a row with Get Grid Row, all subsequent ER that normally references GCs will reference the identified row instead. The alternate reference lasts for the duration of the event.

To prevent a row from being written to the grid during the runtime fetch, use Suppress Grid Line.

To copy or populate a grid row to the GB, use Copy Grid Row to Grid Buffer. To remove a grid row from the grid control, use Delete Grid Row.

You can set or clear an error on a cell, row, column, or the entire control. Use Set Grid Cell Error to set errors and Clear Grid Cell Error to clear them.