GridList

(System Library)

Description: This module draws a list in the style of a spreadsheet.

Returns: Nothing

Usage: Steady State

Format: \System\GridList(Titles, Data, DataFormat, ColWidthsParm, NumDataRowsParm, NumDataColsParm, GridListBGndParm, GridColorParm, GridLineWidthParm, GridStyleParm, RowHeightParm, TitleHeightParm, HCellPaddingParm, VCellPaddingParm, HScrollPosParm, VScrollPosParm, DisableVScroll, DisableHScroll, DisableColumnSizing, DisableSorting, DisableSelectedCell, DisableVGridLines, DisableHGridLines [, LockFirstColumn , Sort, SelectedRow, SelectedColumn, GridFontParm])

Parameters: Titles { text array } { required } { no default }

The array of the titles you wish to use for the grid column headings. The title bar for a grid can be disabled by setting the Titles array to Invalid, or by setting TitleHeightParm to 0.

Data { array - varies } { required } { no default }

The array of data with which to populate the grid.

DataFormat { text array } { required } { no default }

The array of the data formats corresponding to the data specified in the Data array. There must be one entry per column of data.

ColWidthsParm { numeric array } { required } { no default }

The array of the widths of the columns in pixels.

NumDataRowsParm { numeric } { required } { no default }

Specifies the number of data rows to display.

NumDataColsParm { numeric } { required } { no default }

Specifies the number of data columns to display.

GridListBGndParm { numeric } { required } { no default }

Indicates the background color for the cells in the grid.

GridColorParm { numeric } { required } { no default }

Indicates the color of the grid lines.

GridLineWidthParm { numeric } { required } { no default }

Indicates the width of the grid lines.

GridStyleParm { numeric } { required } { no default }

Indicates the style of the grid lines.

RowHeightParm { numeric } { required } { no default }

Indicates the height of the rows in the grid.

TitleHeightParm { numeric } { required } { no default }

Indicates the height of the column headings row above the grid. The title bar for a grid can be disabled by setting TitleHeightParm to 0, or by setting the Title array to Invalid.

HCellPaddingParm { numeric } { required } { no default }

Indicates the horizontal cell padding for the grid.

VCellPaddingParm { numeric } { required } { no default }

Indicates the vertical cell padding for the grid.

HScrollPosParm { numeric } { required } { no default }

Indicates the horizontal scroll bar position.

VScrollPosParm { numeric } { required } { no default }

Indicates the vertical scroll bar position.

DisableVScroll { Boolean } { required } { no default }

A flag that may be set to TRUE (non-zero) to disable vertical scrolling, or FALSE (0) to enable vertical scrolling.

DisableHScroll { Boolean } { required } { no default }

A flag that may be set to TRUE (non-zero) to disable horizontal scrolling, or FALSE (0) to enable horizontal scrolling.

DisableColumnSizing { Boolean } { required } { no default }

A flag that may be set to TRUE (non-zero) to disable column resizing, or FALSE (0) to enable column resizing.

DisableSorting { Boolean } { required } { no default }

A flag that may be set to TRUE (non-zero) to disable sorting by clicking the column headings, or FALSE (0) to enable sorting by clicking the column headings.

DisableSelectedCell { Boolean } { required } { no default }

A flag that may be set to TRUE (non-zero) to disable selected cell highlighting, or FALSE (0) to enable selected cell highlighting.

DisableVGridLines { Boolean } { required } { no default }

A flag that may be set to TRUE (non-zero) to disable vertical grid lines, or FALSE (0) to enable vertical grid lines.

DisableHGridLines { Boolean } { required } { no default }

A flag that may be set to TRUE (non-zero) to disable horizontal grid lines, or FALSE (0) to enable horizontal grid lines.

LockFirstColumn { Boolean } { optional } { default: false }

An optional flag that may be set TRUE (non-zero) to lock the first column from horizontal scrolling (e.g. the first column contains row titles). The default value if Invalid or not supplied is FALSE.

Sort { numeric } { optional } { default: no sorting }

An optional parameter that specifies the column on which the GridList is to be sorted. The parameter is 1-based (i.e. a value of 1 refers to the first column). If negative, the sort order is descending. If Invalid or not supplied, no column sorting will be applied. If the user clicks a column title to sort the GridList, then the parameter is set to the appropriate value.

SelectedRow { numeric } { optional } { default: no cell selected }

An optional parameter that specifies the row of the selected cell. The parameter is 0-based (i.e. a value of 0 refers to the first row). If Invalid or not supplied, no cell is selected. If the user clicks in a cell, then the parameter is set to the index of the selected row.

SelectedColumn { numeric } { optional } { default: no cell selected }

An optional parameter that specifies the column of the selected cell. The parameter is 0-based (i.e. a value of 0 refers to the first column). If Invalid or not supplied, no cell is selected. If the user clicks in a cell, then the parameter is set to the index of the selected column.

GridFontParm { Font } { optional } { no default }

An optional parameter that specifies the font to be used for Titles and Grid elements. The selected font will affect all items in the GridList. If using callbacks, it will allow the user to use the same font in their callbacks or have a separate title font and use their own font in their callbacks. Note: Nothing in a GridList is sized based on font size; the caller must ensure that the row and title heights are large enough to accommodate the font.

Comments: GridList is a member of the VTS System Library, and must therefore be prefaced by "\System\", as shown in the "Format" section above. If the application you are developing is a script application, the System variable must be declared in APPMOD.SRC and need not be prefaced by a backslash in the function call.

Using GridList, you may enable such functionality as column resizing, sorting when clicking on column headings, selection of cells, using the keyboard to move around the grid, and adding scroll bars.

GridList also afford the ability to define a callback function to draw in a cell:

Data[I][1] = <Object Value Where module exists>

DataF[1] = "<Module name to call>"

Note: GridList has been configured to clip text on the right and display a tooltip if there is not enough room to show the entire text string in a cell.

Example:

{initialize the data array}

Titles[0] = "Name";

Titles[1] = "Area";

Titles[2] = "Description";

Titles[3] = "I/O Device";

Titles[4] = "Address";

Data[0][0] = "Tag1";

Data[1][0] = "Tag2";

Data[2][0] = "Tag3";

Data[0][1] = "Area1";

Data[1][1] = "Area1";

Data[2][2] = "I'm a tag";

Data[1][3] = "PollDrvr1";

Data[0][4] = "40001";

DataForm = "%s";

GUITransform(50, 500, 350, 50 { Reference rectangle },

1 { Scale Left },

1 { Scale Bottom },

1 { Scale Right },

1 { Scale Top },

1 { No overall scaling },

0, 0, 1, 0 { No movement; visible; res },

0, 0, 0 { Not selectable },

\System\GridList(Titles { Titles array },

Data { Data array },

DataForm { Cell format array },

60 { Column widths array },

3 { # Data rows },

5 { # Data cols },

15, 8 { Grid BGnd, Grid color },

1, 1 { Grid line width, line style},

30, 30 { Row/Title height },

0, 0 { Horiz/Vert cell padding },

0, 0 { Horiz/Vert Scroll position },

1, 1 { Disable V/H scroll bars },

1 { Disable column sizing },

1 { Disable Sorting },

1 { Disable selected cell },

0, 0 { Disable V/H grid lines },

1 { LockFirstColumn },

Invalid { Sort },

0 { SelectedRow },

0 { SelectedColumn },

\_DialogFont { GridFontParm }));

This code example will create a Grid List that looks like the following: