GRID Create/Control Grid

Property

Description

Auto

When set, the control will generate a 'Change' event whenever its value changes as opposed to the default Off state where the control will only generate the change event when losing focus.

Possible values are:

AutoColSize

This property is used to control the automatic adjustment of column sizes so that the total space occupied by the columns will fill the control width.

When this property is set to 1, the system will adjust all columns in the control so that the sum of the column widths will completely fill the control width exclusive of any scrollbars that may be present. Once set, any resizing of the control will again re-apply the automatic columns sizing logic. (Default: 0 - No automatic column resizing)

When adjusting the column sizes, the system will compute the new size based on percentages.

Example:

Consider the following - Control has three columns:

• Column 1 is 40 pixels wide.
• Column 2 is 10 pixels wide.
• Column 3 is 50 pixels wide.

If this control had AutoColSize enabled, it would determine that column 1 was 40% of the total column width, column 2 was 10%, and column 3 was 50%. These columns would each be adjusted based on the total width of the control to retain the same percentages. Therefore, if the control itself was 150 pixels wide, column 1 would become 150*40%=60 pixels, column 2 would become 150*10%=15 pixels, and column 3 would become 150*50%=75 pixels.

AutoSequence

This property assigns a column number that will contain the automatic row sequence number. (Default: 0 - No column will be used to show automatic row sequence)

PxPlus automatically fills in values of the cells with the appropriate row number. When rows are changed, the column containing the sequence number is automatically updated. Changing this property forces full redraw of the grid.

AutoTrack

This property is used to control the automatic tracking of the contents of a grid relative to movement of the scrollbars (vertical/horizontal). By default, when a scrollbar position is changed by dragging the "thumb", the grid will not follow the movement until the thumb is released. This reduces the screen re-draw overhead within the system but does not allow the user to view the data during the scroll operation.

The 'AutoTrack property can be used to control whether the grid is to be updated while the thumb is being moved -- in effect, having the grid contents track the thumb position. The value in 'AutoTrack determines which, if any, scrollbars will be tracked.

Possible values are:

BackHilight1$

Background color, alternating lines: Background color for every second line. (Default: "DEFAULT")

If set to other than the value "DEFAULT", the color set in this property will be used as the background color on every second line in a list. For information on valid color names and color specifications, see Color Properties.

BackHilight2$

Background color, alternating three lines: Background color for every third line. (Default: "DEFAULT")

If set to other than the value "DEFAULT", the color set in this property will be used as the background color on every third line in a list. For information on valid color names and color specifications, see Color Properties.

Border

Add border: 1 - Border; 0 - No border (Default: 1)

Note:
Applicable only when using Windows XP or Windows 7 style controls.

BringToTop

This property, when set to any value, will cause the control to be moved to the top of the display order. Once at the top of the display order, the control will appear visually on top of any other control on the window. (Default: Not Applicable - Always returns 0)

ButtonColor$

Background color for system-generated buttons in a grid, including Drop Box buttons and Query buttons. For information on valid color names and color specifications, see Color Properties.

This property will also be applied to cells with the 'Lock property set to 1 only when creating a "Button" cell type, providing that the BackColor$ property has not been set specifically for that cell.

(The ButtonColor$ property was added in PxPlus 2020.)

CellHiLight

Cell selection highlight. Possible values are:

CellLeft

Cell left position: Relative X position for cell.

CellTop

Cell top position: Relative Y position for cell.

CellTypeList$

List of supported cell types. See CellType$ property. For a list of available cell type values, see Cell Types as described in the GRID directive.

Col

Screen position (column) of control.

Colno

Column number of grid. This property is fundamentally the same as referring to the 'Column property, however, is included to allow a numeric column number to be specified as a string with accessing the properties.

If the application references 'Column$ in a grid, it will receive the logical column name as opposed to its number. Referencing 'Colno$ will return the column number as a string.

Cols

Width of control in column units.

Column

Currently referenced column number of grid. This property does not contain the current column number of the control, but rather the column number being referenced when used in conjunction with other properties.

For instance, in a grid, setting 'Column to 2 and 'Row to 3 will allow the application to reference the 'Text$ value for the cell in column 2, row 3. It will not change the current position within the grid.

Column$

Grid column name.

ColumnNames$

Comma-separated list of grid column names.

ColumnsWide

Number of columns.

CtlName$

Control type ("GRID"). See GRID directive.

CurrentCellColor$
CurrentCellColour$

Background color for current cell. For information on valid color names and color specifications, see Color Properties.

CurrentCellTextColor$

Text color for current cell. For information on valid color names and color specifications, see Color Properties.

(The CurrentCellTextColor$ property was added in PxPlus 2024.)

CurrentColno

Current column number with focus: This property contains the same information as 'CurrentColumn; however, regardless of whether referenced as a string or numeric property, only the column number is reflected. (The 'CurrentColumn property reflects the column name when referenced as a string). It is recommended that this property be used when accessing the control using Pseudo Properties.

CurrentColumn$

Current column with focus: When this property is referenced as a numeric ('CurrentColumn), it returns the column number. When referenced as a string ('CurrentColumn$), it will return the logical column name.

CurrentRow

Current row with focus. (Default: 1)

CurrentValue$

This property is used to access the value of the current cell within a grid. Using the CurrentValue$ property avoids the application from having to set the 'Row and 'Colno properties for a grid prior to reading the value in the grid.

DraggedColumn$
DraggedColno

Column number dragged from. This property indicates the column number (cell) where dragging started. See Drag and Drop. (Default: 0)

DraggedRow

This property indicates the row number (cell) where dragging started. See Drag and Drop. (Default: 0)

DroppedOnColumn$
DroppedOnColno

This property indicates the column number (cell) where the mouse was released/items dropped. See Drag and Drop.

DroppedOnRow

This property indicates the row number (cell) where the mouse is released/items dropped. See Drag and Drop.

Enabled

Enabled indicator: 1 = True; 0 = False (Default: 1)

EnterMode

This property is used to define how the ENTER key will be processed with the control. For the grid, possible values are:

(Default for Grid: The default setting is 0.)

Note:
In the grid, if the SHIFT key is pressed, these key modes reverses the direction. In addition, if the Tab/Enter '+E' mnemonic has been set, this property will be ignored and the settings in the TabMode property will be used.

Eom$

Last change terminator. See also GRID directive.

ExcelStyle

This property is used to control the display of grid lines in either the grid or the report view controls.

Possible values are:

Note:
Prior to PxPlus v8.11 (build 9182), this property was only available on the grid and only accepted a value of 0 or 1. As of PxPlus v8.11, PxPlus supported the property in the report view and options 2/3.

FillColor$
FillColour$

This property defines the color to be used to fill in the empty regions of a grid (blank space to the right and below the grid). Any valid PxPlus color or RGB specification can be used. For information on valid color names and color specifications, see Color Properties.

A value of DEFAULT indicates that the system is to use the default 'Windows' background color as selected by the user.

FindColNo

This property is used to control which column the 'FindItemText will search. If not set, the search encompasses all rows/columns within the grid. See FindItemText$ property and FindOptions$ property. (Default: 0 - No column specified; searches all columns)

FindItemText$

This property, when set, causes the system to search the list box or grid for the text supplied. If the text is found, the system will set the 'Column and 'Item (or 'Row) property for the control to the entry where the match was found. If no match is found, the 'Column and 'Item ('Row for the grid) property is set to zero.

A typical use of this property would be to locate a value in the list box and then change or delete it. It can also be used to validate that an entry exists in the list box. This property is generally only written to. Reading this value will return the same as reading the 'ItemText$ property.

Controlling the Search (List View/Grid Only): The search is controlled by the settings found in 'FindOptions$. These options are provided as a series of characters in 'FindOptions$:

Search Range (List View/Grid Only): When searching, if the "W"rap option is not specified, the search will start from the beginning of the data in the control and proceed through the end. If the "R"everse option is set, the search starts at the end and proceeds to the beginning. If the "W"rap option is set, the search will start from the position immediately after that specified in the 'Item ('Row for Grid) and 'Column and search through all the data wrapping around the end/start back to the starting point.

If the property 'FindColNo (or 'Column for Grid) is set, only data in that column will be searched. If the "S"ort option is specified, only the column specified in the 'Sort property will be checked and its setting (Ascending/Descending) will be used to determine the assumed sort sequence. If 'Sort is not set, the system will assume that the column specified in 'FindColNo has been pre-sorted in Ascending order. If 'FindColNo is not set, then the system will assume the first column is to be used and is in ascending sequence.

If both "W"rap and "S"ort options are specified, the system will use the starting point set in 'Item ('Row on Grid) and 'Column and determine the search direction based on the value at the starting point. If the value at the start point matches that of the search value, the "R" option will determine the search direction.

See 'FindColNo and 'FindOptions$ properties.

Note:
Prior to PxPlus v11, this property and functionality was not available on the grid. In addition, the 'Column was not set nor were the 'FindOptions$ and 'FindColNo (list view only) supported.

Example 1: Changing item text in a list box

To change the value of the list box entry of "CAT" to "DOG" for list box "LIST1", you could do the following:

     List1'FindItemText$="CAT" ! Locate the item
     List1'ItemText$ = "DOG" ! Change the value

Example 2: Locate and delete an item from a list box

To locate and delete a value from a list box:

     List1'FindItemText$="CAT" ! Locate the item to delete
     LIST_BOX LOAD List1, List1'Item, *

Example 3: Validate the existence of an item in a list

To search a list box to find a specific value, set the FindItemText$ to the desired search value then read 'Item. If zero, the item does not exist.

     List1'FindItemText$=X$ ! Locate the item
     IF List1'Item=0 THEN MSGBOX X$+" is not found"

FindOptions$

This property is used to control how the 'FindItemText will search the data in the grid. It can have one of the following characters specified in its value:

(Default value is "" - no options specified.)

See 'FindItemText$ and 'FindColNo properties.

Fmt$

Control format definition. Refer to the FMT= option as described in the GRID directive.

Focus

Focus indicator: 1 = Control has focus (Default: 0)

ForegroundButtonColor$

Foreground text color for system-generated buttons in a grid, including drop box buttons and query buttons. For information on valid color names and color specifications, see Color Properties.

(The ForegroundButtonColor$ property was added in PxPlus 2024.)

HdrBackColor$
HdrBackColour$

This property sets the background color for the top row only of the grid (Row -1) and does not affect the leading left column (Colno -1). For information on valid color names and color specifications, see Color Properties.

(The HdrBackColor$ (or HdrBackColour$) property was added for Grids in PxPlus 2018.)

HdrFont$

This property defines the font for the top row only of the grid (Row -1) and does not affect the leading left column (Colno -1).

(The HdrFont$ property was added for Grids in PxPlus 2018.)

HdrHeight

This property can be used to control the height of the header in the grid in pixels.

Setting this property to -1 restores the height to its default size. Setting this property to 0 results in no header.

(The HdrHeight property was added in PxPlus 2020.)

HdrTextColor$
HdrTextColour$

This property sets the color of the text for the top row only of the grid (Row -1) and does not affect the leading left column (Colno -1). For information on valid color names and color specifications, see Color Properties.

(The HdrTextColor$ (or HdrTextColour$) property was added for Grids in PxPlus 2018.)

Height

Height of control in pixels.

HideButtons

This property hides query buttons or drop box icons associated with grid cells if there is a bitmap (thus, the bitmap is all that shows on a transparent background).

The StdGridHideButtons option (in the 'OPTION' mnemonic or SETDEV directive) can be used to set the default 'HideButtons property for all subsequent grids.

(The HideButtons property was added in PxPlus 2020.)

hWnd

Windows handle for control.

ImpliedDecimal

Controls implied decimal input.

InsDelEnabled

Cell editing keys: 0 = Off; 1 = On. (Default: 0) This enables use of Insert to begin cell editing and Delete for clearing the contents of a cell.

Key$

Hot key to jump to control.

Left

Left margin for control in pixels.

Line

Screen position of control.

LineColor$
LineColour$

This property contains the color of the lines drawn between rows and columns when the 'ExcelStyle property is set. For information on valid color names and color specifications, see Color Properties. (Default: DEFAULT (normally BLACK))

(The LineColor$ (or LineColour$) property was added in PxPlus 2020.)

Lines

Height of control in number of lines.

LoadIOList$

This property contains the list of columns that will be returned in 'RowData in compiled IOList format. See Loading/Accessing by Row and the 'LoadList$ property.

By default, the list of columns will contain the column names starting from the first column (far left) through the end of the grid. It can be altered by setting either the 'LoadList$ or 'LoadIOList$ property.

LoadList$

This property contains the list of columns that will be returned in 'RowData as a string of column names separated by a delimiter (last character of string). See Loading/Accessing by Row.

By default, the list of columns will contain the column names starting from the first column (far left) through the end of the grid. It can be altered by setting either the 'LoadList$ or 'LoadIOList$ property.

LockBottom

Number of rows at the bottom of the grid to exclude from sorting. See LockTop property.

LockColumns

This property is used to set the number of leftmost columns that will remain fixed and will not be resized when the display is scrolled horizontally.

LockRows

Number of rows to lock into position, starting from row 1.

LockTop

Number of rows at the top of the grid to exclude from sorting. See LockBottom property.

(The LockTop property was added in PxPlus 2019.)

LookAndFeel

Defines how a control will look. Possible values are:

MaxListItems

This property is used to control the number of lines that will appear in a drop down list in the grid. This property affects all cells in the grid.

By default, this property will be set to zero where the drop down list size is determined by the height of the grid and the number of options in the list.

Setting this property to a positive non-zero value defines the maximum number of options to show in the drop down list in the grid.

Setting this property to a negative value will result in an Error #60: Invalid control argument value.

Note:
Due to the nature of the browsers, this property is unable to be supported in iNomads; however, the property is defined for compatibility purposes. Any value assigned to this property in iNomads will be ignored.

(The MaxListItems property was added in PxPlus 2020.)

MenuColumn$
MenuColno

This property indicates the column number of a selected cell on a right-click of the mouse.

MenuCtl

This property reports/sets the CTL value to generate when an object is selected on a right-click of the mouse.

MenuRow

This property indicates the row number of a selected cell on a right-click of the mouse.

Msg$

Message line text for the control.

MultiSelect

Select multiple cells: 1 = On; 0 = Off (Default: 1)

ObjectID

User object method. (Default: 0 - No object specified)

The 'ObjectID property allows applications to intercept property values and add methods to controls. When set to a valid Object ID by the application, you can add methods and add/override property logic for any control in the system. When set in the system, it allows the application to logically request methods against the control that, in turn, will be performed by the related Object ID. It will also first check the object for any property requests and if the property is defined in the object set or get that property instead of the controls.

To allow the specified object to get true access to the control, while executing within the object identified by the 'ObjectID property, the system will direct any property requests directly to the control.

Sample used to add a GetValue$ and SetValue method to a grid

Grid Object definition (GRID.PVC):

     0010 DEF CLASS "grid"
     0020 LOCAL _CTLNO
     0030 FUNCTION GETVALUE$(COL,ROW)
     0040 ENTER C,R
     0050 LET _CTLNO'COLUMN=C
     0060 LET _CTLNO'ROW=R
     0070 RETURN _CTLNO'VALUE$
     0080 FUNCTION SETVALUE(COL,ROW,VALUE$)
     0090 ENTER C,R,V$
     0100 LET _CTLNO'COLUMN=C
     0110 LET _CTLNO'ROW=R
     0120 LET _CTLNO'VALUE$=V$
     0130 RETURN 1
     0140 END DEF
     0150 ON_CREATE:
     0160 ENTER CTLNO
     0170 LET _CTLNO=CTLNO
     0180 LET _CTLNO'OBJECTID=_OBJ
     0190 RETURN

Test program to create the grid and assign the Object to the grid control:

     0010 GRID 10,@(30,2,40,15)
     0020 GRID ADD 10,10,10
     0030 LET X=10
     0040 LET O=NEW("grid",X)
     0050 FOR I=1 TO 3
     0060 X'SETVALUE(I,I,"Hi there")
     0070 NEXT
     0080 PRINT X'GETVALUE$(2,2)
     0090 ESCAPE

Note:
When a control is deleted from the system, any object identified by an 'ObjectID property will be automatically dropped.

OnFocusCtl

On Focus CTL event. 0 is returned if no On Focus CTL value is set up for the control.

OnLoadCtl

This property, when set to a non-zero value, causes the system to generate an internal CTL event following any changes to a grid. It can be used to monitor changes to a list style control so that external action (such as updating screen or files) can be performed. If the value of this property is non-zero, the system will use its value as a CTL event to generate. If zero (default state), no event will be generated.

To avoid multiple signals being generated, the system will defer the generation for approximately 1/2 second following the last update. This means that when multiple rows/cells are being updated, the event will generally only occur once the updating is complete.

OnTipCtl

This property controls the CTL event that will be fired prior to the system displaying the Tip for any control. If the value of this property is non-zero, the system will use its value of a CTL event to fire and will defer the display of the tip until the application changes the value in 'Tip$. If the value in 'Tip$ is not changed, no tip will be displayed.

Setting this to zero (Default) disables the event from being sent and the current 'Tip$ will be displayed.

OverlapEnabled

Allow cells to overlap: 1 = Yes; 0 = No (Default: 1)

Parent

Parent window handle.

PasteFilter

Strip non-printing characters from pasted data. When this property is set to On, the filter strips leading/trailing non-printing characters, such as line feeds or tabs, from data that is copied/pasted into a grid control and replaces any internal sequence of non-printing characters with a single space. (Default: 1 = On)

Example:

Data that is copied as …

123 Main Street
Markham
Ontario

… will be pasted as:

123 Main Street Markham Ontario

The Clipboard will reflect the actual data pasted in case the user wants to paste the data elsewhere.

(The PasteFilter property was added in PxPlus 2020 Update 1.)

Resizable

Enable grid resize by user. Possible values are:

Row

Grid row reference.

RowHeaderBackColor$

Sets the background color for the leading left column only of the grid (Colno -1) and does not affect the grid top row (Row -1). For information on valid color names and color specifications, see Color Properties.

(The RowHeaderBackColor$ property was added in PxPlus 2024.)

RowHeaderTextColor$

Sets the text color for the leading left column only of the grid (Colno -1) and does not affect the grid top row (Row -1). For information on valid color names and color specifications, see Color Properties.

(The RowHeaderTextColor$ property was added in PxPlus 2024.)

RowHiLight

Row selection highlight: 1 = Row highlight; 0 = Cell highlight. This enables selection of a full row rather than limited to cells. Only locked cells are highlighted. One side effect is that when the cells are locked, the grid becomes a fancy list view.

The SelectCount property returns the number of selected cells; however, when the RowHiLight property is set, SelectCount returns the number of rows:

Example:

   0010 BEGIN
   0020 LET G=10
   0030 GRID G,@(20,10,50,12)
   0040 GRID ADD G,5,9
   0050 LET G'ROWHILIGHT=1
   0060 GRID SELECT G,0,0
   0070 PRINT G'SELECTCOUNT
   0080 INPUT *

RowsHigh

Number of rows defined in the grid.

ScrollWheel

Set scroll wheel increment. This property is used to define how many lines each click of the scroll wheel will move a list box or grid.

Possible values are:

SelectColumn$
SelectColno

(Read Only) Column number of selected cell. See Multiple Selections.

SelectCount

Number of items/cells selected. See Multiple Selections.

This property returns the number of selected cells; however, when the RowHiLight property is set, SelectCount returns the number of rows:

Example:

   0010 BEGIN
   0020 LET G=10
   0030 GRID G,@(20,10,50,12)
   0040 GRID ADD G,5,9
   0050 LET G'ROWHILIGHT=1
   0060 GRID SELECT G,0,0
   0070 PRINT G'SELECTCOUNT
   0080 INPUT *

Set the SelectCount property to zero to deselect all items.

SelectIndex

Index to 'SelectItem: Set this property to point to a selected element; e.g. 1 points to the first item selected, 2 points to the second item selected, etc. See Multiple Selections.

SelectRow

(Read Only) Row number of selected cell. See Multiple Selections.

SelectText$

Text contained within the highlight: This allows for cut, copy and paste within a graphical user interface input region. See Multiple Selections.

SelectValue$

Value within selected field. See Multiple Selections.

Sep$

Separator character between each field, column or data point.

SepLoad$

Separator character for each row or data set.

ShowLocked

This property applies to the entire grid and controls the color of locked cells.

When set to 1 (Default), locked cells are shown with a gray background. Setting this property to 0 (zero) does not change the color of locked cells. This allows background colors to be set on alternating lines in a grid (see BackHilight1$ and BackHilight2$), regardless if cells are locked.

(The ShowLocked property was added in PxPlus 2019.)

SignalOnExit

This property controls whether a 'Change' signal will be generated when the control (or region of a grid control) is exited regardless of whether the control's value changes. Normally, controls only signal changes when the control loses focus and the contents have changed. Setting 'SignalOnExit allows a change signal to also be generated whenever focus leaves the control (or region for grid).

SkipLockedCells

Skip over locked cells. Possible values are:

Sort

Column sorting: Sorts the contents of the control. In grids, this property sets the number of the column on which the data is to be sorted. Positive integers indicate normal ascending sort order; negative integers indicate descending order. (Default for Grid: 0)

When using the grid sort on numeric data, the currency sign, thousands separator, and decimal point are ignored. The values used to represent these characters are established when the grid is first created.

Sort$

Sort by column name: This sets a column name (inside quotes) by which to sort. A minus sign indicates descending order.

Example:

x'Sort$ = "- col_name" (Locked rows are included in the sort.)

SortCaseSensitive

This property is used to control whether the case of the data will be ignored when sorting data within the grid.

If this property is On (Default: 1), then values will be sorted as such that uppercase data will be placed before lowercase data. If this property is Off (0), then the case of the data will be ignored. (Default: 1 - Data is sorted with uppercase before lowercase.)

Important Note:
This property has been deprecated as of PxPlus v11 by the 'SortOrder property, which allows for control not only of sort case but also accented characters and supports a system wide default.

SortGrouping

This property is used to control the sorting of a grid by defining the number of lines that make up a logical group within the grid. (Default: 1 - Each line is independent.)

Example:

     If each logical entry in the grid contained two lines, you would set 'SortGrouping to 2. This will cause the sort to keep each pair of lines together when sorting.

In terms of the values being sorted, only the data in sort column from the first line are considered when sorting. The contents of the secondary lines within the group will not be considered.

SortNullLast

This property is used to control how null entries will be sorting within the grid.

f this property is set to Off (Default: 0), then null values will be sorted first. If this property is set to On (1), then null values will be placed at the end of the sorted data. (Default: 0 - Null values occur first in the sort sequence.)

SortOrder$

Sorting control settings. This property is used to control how column data will be sorted in the grid. It can have one of the following values or be set to Null, which indicates the sort order is defined by the system StdSortOrder setting using the SETDEV SET directive or the 'OPTION' mnemonic.

(Default: Null - Data is sorted using the StdSortOrder setting.)

Alternatively, this property can be accessed as a string comprising the characters C, A or N. An empty string is used to indicate all settings are Off.

Important Note:
The 'SortCaseSensitive property for the grid control has been deprecated as of PxPlus v11 by the 'SortOrder$ property, which allows for control not only of sort case but also accented characters and supports a system-wide default.

SortStyle

Sort without nulls: Determines if cells with null values are to be included in the sort.

SortStyle values indicate the following:

SuppressHdr

Suppress grid headers. Possible values are:

Suppression is done by setting the header height/width to 0. When not suppressed, the height/width will return to the last value.

(The SuppressHdr property was added in PxPlus 2020.)

SwapEnabled

Column swap enabled: 1 = Yes; 0 = No (Default: 0)

TabMode

This property is used to define how the TAB key will be processed with the grid control. Possible values are:

TickPerUnit

This property sets the number of ruler-style "ticks" between numbers (units) displayed in the header cells (row and column) of the grid. Ruler numbers begin at 0 (zero) and count upwards by whole numbers but will be reset to 0 (zero) again if the header cell contains a 'Value$ greater than null. (Default: 0)

Example:

'TickPerUnit=8 will display a number every 8 ticks on the ruler and cause median points (at 'TickPerUnit/2) to appear slightly larger.

TickPixels

This property sets the space in pixels between ruler-style "ticks" (marker lines) displayed in the header cells of the grid.

Tip$

Tip message for control.

TipColno

Column number for the cell that is requesting its tip. In response to an OnTipCtl event, the program can read this property and set the appropriate cell tip value. See 'TipRow property.

TipRow

Row number for the cell that is requesting its tip. In response to an OnTipCtl event, the program can read this property and set the appropriate cell tip value. See 'TipColno property.

Top

Top of control in pixels.

TopVisibleRow

This property is used to access the row number that is currently displayed at the top of the grid. It can be used to determine/control vertical scrolling of the data. (Default: Not Applicable)

If set, it must be set to a value between 1 and the number of rows in the grid. Setting this property to a row near the bottom of the grid contents does not always guarantee that the row identified will be the first row on the grid. The system will attempt to leave the bottom few rows visible; however, it will assure that the row indicated is visible.

TrackColor$
TrackColour$

Cell tracking color. Header cells corresponding to a cell that currently has focus are switched to the color set by this property as the user moves around the grid. This provides a visual cue to the user for which column and row they are on currently.

Only header cells that use their default color will change to the tracking color. For information on valid color names and color specifications, see Color Properties.

(Default: "DEFAULT")

Visible

Control visible flag: 1 = Yes; 0 = No (Default: 1)

Width

Width of control in pixels.

_PropList$

Controls the list of properties to be returned in '_PropValues$. Each value is separated by the value in '_PropSep$.

This property can be used to speed up the processing of multiple property accesses but reducing the number of interactions with the control. See Multi-Property Access.

_PropSep$

Controls the separator used between each of the values of the properties returned in '_PropValues$ as defined by '_PropList$.

This property can be used to speed up the processing of multiple property accesses but reducing the number of interactions with the control. See Multi-Property Access.

_PropValues$

Accesses the values of the properties defined in '_PropList$. Each value is separated by the value in '_PropSep$.

This property can be used to speed up the processing of multiple property accesses but reducing the number of interactions with the control. See Multi-Property Access.

Property

Description

Align$

Text alignment of the data in a grid cell. Possible values are:

(The alignment values "MC", "ML" and "MR" were added in PxPlus 2014 FP1 Update 0001.)

AutoCompName$

Name of a defined Auto Complete entry. Auto Complete entries are assigned to individual cells and are used to show text suggestions when a user types a partial entry. See Assigning Auto Complete Entries.

AutoValue$

List of entries to load into Auto Complete drop box. See 'CellAutoCtl property.

BackColor$
BackColour$

Background color. For information on valid color names and color specifications, see Color Properties. (Default: "DEFAULT")

Bitmap$

Bitmap to appear in a grid cell.

Example:

     !Stop (embedded bitmap)
     C:\windows\clouds.bmp (external bitmap)

BottomBorder

Bottom border of cell (thickness): 0 to 3 pixels (Default: 0)

BottomLeftTick$

When set to a color, this property displays a tick in the bottom left corner of the cell. For information on valid color names and color specifications, see Color Properties. (Default: "DEFAULT")

CellAutoCtl

Generates ctl_id to signal Auto Complete: ctl_id to signal that the list of entries for the Auto Complete drop box is to be loaded via the AutoValue$ property.

CellBlankWhenZero

When this property is set and cell contents are displayed, if the cell contains no non-zero numeric characters (1-9), the cell will be displayed as if null although the actual contents will be preserved.

(The CellBlankWhenZero property was added in PxPlus 2020.)

CellDClick

Cell double click. Possible values are:

CellFormat$

Cell format mask. See FMT= option in the MULTI_LINE directive. (Default: Null)

Note:
The grid will not format data over 1024 bytes long. (as of PxPlus 2017)

CellHlp$

Help reference for a grid cell.

CellImpliedDecimal

Controls implied decimal input on cell-by-cell basis.

CelliNomadsClass

Apply an iNomads class to a grid cell: The iNomads class contains class attribute references used when defining the control in the HTML code generated in iNomads.

An iNomads class reference must start with an alpha character (A-Z or a-z), followed by any combination of A-Z, a-z, 0-9, underscore or dash. Multiple references may be entered, separated by a space. For a list of pre-defined classes, see iNomads Classes.

Note:
The CelliNomadsClass property can also be set in the Grid Presets Definition when using the NOMADS Panel Designer; however, it will only be applicable when the panel is run in iNomads.

The CelliNomadsClass property was added in PxPlus 2018.

CellIsNumeric

When set, this property forces a cell to only accept numeric data. When exiting the cell after it is edited, if the cell contains no numbers (0-9), it will be set to "0".

(The CellIsNumeric property was added in PxPlus 2020.)

CellTag$

This property provides the ability to place an application defined "Tag" on a specific cell. The contents of the tag string is application dependent and not used by the system. It can be used to store any cell related information required by the application.

CellTbl$

Translation table for cell: This property controls the translation of the values selected in the cell and how the value will be passed to/from the application. Generally, it contains a table of single-character values representing selections from the controls with each character representing each of values in the control in sequence. The size of each entry can be changed using the 'CellTblWidth property.

CellTblWidth

Translation table width for cell: This property can be used to set the length of each of the items in the 'CellTbl$ property. It can be set to any positive value (Default: 1). Setting 'CellTblWidth to zero indicates that 'CellTbl$ contains a delimited string, with the last character of the string being the delimiter character.

CellTip$

Tip for cell: Tip message.

CellType $

Grid cell type. (Default: "Normal")

For a list of available cell type values, see Cell Types as described in the GRID directive.

Class

Apply a data class to a grid cell: The Class property can also be set in Grid Presets Definition when using the NOMADS Panel Designer. See Data Classes.

Font$

This property is used to reference the font for a cell. It will contain (or can be set to) a string containing 3 comma-separated fields of the font name, size and attributes.

Example:

     To set the font to Arial, 1.5 times normal size, and Bold, the format would be xxx'Font$="Arial,1.5,B".

When setting the 'Font$ property on a grid for all columns/rows ('Column=0 and 'Row=0), the system will check that the current default Row Height is large enough to accommodate the font selected. If the default row height is too small, the system will automatically adjust the default and all existing row heights to a size large enough to accommodate the font size.

See 'FONT' mnemonic.

(Support for the automatic adjustment of row height was added in PxPlus 2019.)

JoinColumns

Merge two or more columns (left to right): Set this property in the column that starts the join (leftmost) to the total number of joined columns - that number of columns will be merged into one. For columns belonging to an existing join, this property returns a negative integer indicating the column's current position within the join.

JoinRows

Merge two or more rows (downward): Set this property in the row that starts the join (uppermost) to the total number of joined rows - that number of rows will be merged into one. For rows belonging to an existing join, this property returns a negative integer indicating the row's current position within the join.

LeftBorder

Left border of cell (thickness): 0 to 3 pixels (Default: 0)

Len

Input length of cell.

Lock

Lock status: Possible values are:

(The Lock status of 2 was added in PxPlus 2019.)

LockBackColor$

Background color when the grid cell is locked. For information on valid color names and color specifications, see Color Properties.

(The LockBackColor$ property was added in PxPlus 2024.)

LockTextColor$

Foreground text color when the grid cell is locked. For information on valid color names and color specifications, see Color Properties.

(The LockTextColor$ property was added in PxPlus 2024.)

Nul$

String text to display when the value of the grid cell is empty: If a numeric format string has been assigned, then the text is displayed when the value is 0 (zero).

PriorValue$

This property contains the value last returned when the grid cell was read.

(The PriorValue$ property was added in PxPlus 2018.)

Query

Assign a query to a grid cell. The expression should include the query definition name and library in the following format: "QueryName,Library".

When defined, the grid cell will display a lookup button with a bitmap, if a bitmap has been set; otherwise, the lookup button will display a ? (question mark) by default.

The Query property can also be set in Grid Presets Definition when using the NOMADS Panel Designer.

RightBorder

Right border of cell (thickness): 0 to 3 pixels.

SpellCheck

Enable spell checking. For a multi-line and grid cell, set this property to non-zero to enable spell checking on the input field. Reading this property will determine whether spell checking is enabled. (Default: 0)

(The SpellCheck property was added in PxPlus 2019.)

Text$

Text of item or label. In a grid, this property applies to the following cell types: "BarChart", "Button", "DropBox" and ""DropBoxHideBtn", "UseTextEllipsis", "UseTextNormal" and "UseTextSingleLine", "VarDropBox" and VarDropBoxHideBtn".

See Cell Types as described in the GRID directive.

TextColor$
TextColour$

Foreground text color. See Color Properties for a list of valid color names. (Default: "DEFAULT")

TopBorder

Top border of cell (thickness): 0 to 3 pixels. (Default: 0)

TopLeftTick$

When set to a color, this property displays a tick in the top left corner of the cell. For information on valid color names and color specifications, see Color Properties.

(Default: "DEFAULT")

Uppercase

Force text to uppercase: 1 = On; 0 = Off. (Default: 0)

Value$

Current grid cell value.

Property

Description

AutoFit

This property, when set to any value, forces the associated grid to resize the column currently selected by the 'Colno or 'Column property to the width required to fit its contents.

If the currently selected column is set to zero, all columns in the grid will be resized.

The value set in 'AutoFit indicates how many rows to check, with zero indicating all rows and the column header. Any value other than zero specifies the number of rows (starting at the first row) to take into account in computing the new column width. A non-zero setting may be used to minimize the time it might take to scan all the rows in a large grid.

Reading this property returns zero, as the value of the property itself has no meaning, and simply the act of setting it causes the grid to be updated.

Note:
If a column has the ColumnSizeLock property set to On or a ColumnWidth of zero (hidden), the width will not be adjusted unless the column number is explicitly set to that column (i.e. 'Colno is not zero.)

(The AutoFit property was added in PxPlus 2017.)

ColumnPixels

Width of column in pixels.

ColumnSizeLock

This property controls the ability of the user to resize the width of a column by dragging the column header.

If set to 0, the column may not be resized. If set to 1, the column is resizable. (Default: 0 (fixed size)

When used with the grid, this property is only valid when the grid itself is deemed resizable (the Resizable property > 0).

ColumnWidth

Width of column in column units.

SortColFmt$

This property is used to control the sorting of grid columns when a sort by date is required. (Default: Default value is "" - no sorting definition).

Normally, when the grid sorts columns, it does so by either a numeric value comparison or a string compare. If the column contains a date, you need to tell the system the format of the date being provided so it can determine which value is the year, month or day respectively.

The SortColFmt$ property is used to control the sorting of date columns. This property can be set from one to three characters long where each character can be a '#', 'S', 'Y', 'M' or 'D' as follows:

• If set to '#', the column will be sorted based on the assumption that all data in the column is numeric.
• If set to 'S', the assumption is that all data in the column are strings and will be sorted based on string values.
• If set to 'Y', 'M' or 'D', the letters will be used to indicate the order of the data in the column. (Lowercase 's', 'y', 'm' or 'd' is also supported.)

Example:

If the date is of the form day, month, then year, the 'SortColFmt$ property should be set to "DMY".

Note:
For a date sort to work properly, the dates in the column must have a divider, such as a dash ( - ), separating the date components.

Example:

     01-01-2016

A date such as 01012016 does not sort.

If this field is not set, the column will be pre-scanned to determine if all values are numeric. If all the column data is numeric, then a numeric sort will be performed; otherwise, a string sort will be used.

The 'SortColFmt property works in conjunction with the 'Column or 'Colno property to identify the column to which the sort format will be applied.

Note:
When forcibly sorting numerically, mixing numeric and non-numeric data will result in an incorrect and somewhat random sort sequence based on the original input sequence.

SortOnHdrClick

This property is used to control the sorting of grid columns based on the user clicking the column header.

For the grid, the property exists both for the complete grid and on each column. To reference the grid settings, set 'Column to zero prior accessing to the property. To reference a column, set the 'Column property to the desired column prior to access.

Possible values are:

(Default for Grid: 0 - Column sorting is disabled on the grid and all columns.)

When setting the property for a specific column, you can specify a value of -1, which forces the column to adhere to the current grid default setting.

Property

Description

RowData$

Row data based on cell columns identified in the 'LoadList$ or 'LoadIOList$ property. Each value will be separated by the column separator as defined for the grid. Reading this property will return the contents cells within the row identified in the 'Row property. Writing it will update the cells.

See Loading/Accessing by Row, 'LoadList$ property and 'LoadIOList$ property.

RowHeight

Height of current row in lines.

RowPixels

Height of row in pixels.