Directives 

Formats

Where:

Note:
If you change any of the settings for month names, currency, decimal point and the thousands separator character, your grid logic must recreate the grid after the change(s) has been made.

Description

Use the GRID directive to create a grid or table of cells in columns and rows; i.e. a spreadsheet input format. The GRID control object is a two-dimensional array of multi_line input fields (default), check_boxes, buttons, drop_boxes or any combination of these control objects. Each cell can be of a different type.

Note:
PxPlus supports alpha channel transparency processing of bitmap images for grids (for console output only, not printer and PDF).

(Alpha channel support was added in PxPlus 2017.)

For some formats of the GRID directive (e.g. GOTO and FIND), both column and row coordinates are required (to act as pointers to a particular cell). For other formats, one or both of the values can be 0 (zero).

The following chart shows how PxPlus interprets the column and row values:

Note:
Referencing a setting or value using a row number of 0 (zero) and a non-zero column number references the column DEFAULT values. Columns (and only columns) can have a default setting which will apply to any cell within the column that does not have the corresponding setting/value established for the cell itself. Only columns can have default settings, not rows. Setting the column number to 0 (zero) with a non-zero row number will set the values for all cells in the row.

Grid Properties

The Apostrophe Operator can be used with the unique logical identifier (ctl_id) to dynamically read and alter a wide variety of control attributes (properties) directly from the programming language. Most cell attributes are only accessible through the implementation of properties. For example, drag and drop functionality utilizes the 'DraggedColumn, 'DraggedRow, 'DroppedOnColumn and 'DroppedOnRow properties.

See GRID Properties for the list of properties available for manipulating a grid.

Note:
To access many grid properties, cell(s) must be identified first using the 'Column and 'Row properties. See Grid Cell Access Properties.

GRID OPT= Settings

The single character parameters for OPT=char$ are listed below:

Format Definition

The FMT=def$ option allows you to define the format for cells in the grid. In the following syntax, the round and square brackets are part of the format:

FMT=[col_title](cell_type:col_name) Alignment Width

Where:

Example: 

"[Client ID](Multi_line:CST_ID$)L10 [Name](Normal:CST_NAME$)L10"

Cell Types

The following cell types can be assigned using the FMT= option in the GRID directive or via the 'CellType$ grid object property:

Horizontal Bar Charts in Grid Cells

A "BarChart" cell type in the grid can be used to display horizontal bar charts based on the contents of the 'Text$ property.

(Horizontal bar chart support in grids was added in PxPlus 2017.)

The length of the bar and fill color are defined by a series of comma-separated parameters set in the 'Text$ property. The first parameter defines the length of the bar as a percentage of the cell width. A value of 100 will result in the bar covering the complete cell, 50 will cover half of the cell, etc. If the cell is resized, the bar length will be adjusted accordingly. The second and optional third parameters define the color of the bar with the second parameter representing the color for the top of the bar and the third parameter, if present, the bottom of the bar. If the third parameter is omitted, the bottom of the bar will be automatically generated by the system to make the bar appear slightly three-dimensional.

Note:
When specifying a color using "RGB:rrr ggg bbb", you must not include the commas that are normally allowed between the red, green and blue color values.

Multiple bars may be supplied to create multiple bars within the cell with each bar specification being separated by a semi-colon. Any portion of the bars that exceeds the total width of the cell will be truncated.

Example:

For this example, let us assume that we are dealing with client information that is comparing CurrentYTDSales against PriorYTDSales with the following data:

If we want to present a simple graph in the grid, we might code something like this:

0010 begin
0020 print 'CS'
0030 let gd=10
0040 grid gd,@(5,5,66,6),fmt="[ID]10C [Name]20 [Performance]20 [Sales]10R"
0050 let gd'autoSequence=-1
0060 let gd'colno=3,gd'celltype$="BarChart"
0070 let row=0
0080 while 1
0090 read data id$,name$,CurrentSales,PriorSales,end=*break
0100 let pct=(100*CurrentSales)/PriorSales
0110 row++
0120 grid load gd,1,row,id$+sep+name$+sep+""+sep+str(CurrentSales:"$##,##0")+sep
0130 let bar$=str(pct)+",Green"
0140 let gd'colno=3,gd'row=row,gd'text$=bar$
0150 wend
0160 input *
0170 data "0001","First Client",80000,100000
0180 data "0002","Secondary Client",55000,50000
0190 data "0003","Third Client",45000,90000

This would result in a grid something like this:

If we want to include the percentage as a number following the bar, we could include the text to display in the value of the cell. In the program above, we set the cell value to "", but this could be changed to include the actual value as follows:

0120 grid load gd,1,row,id$+sep+name$+sep+str(pct)+"%"+sep+str(CurrentSales:"$##,##0")+sep

This would result in the following:

Notice that the percentage does not show on the second line because the bar completely fills the cell width. In fact, the percentage for ID 0002 is 110%. To resolve this, we need to adjust the bar display percentage to allow for both the full bar and the text. This can be done by factoring the bar percentage itself:

0130 let bar$=str(pct/1.5)+",Green"

This would result in the following:

Let us assume we want to enhance this as follows:

If the Percentage is < 70%, display the bar in Red, and for any percentage over 100%, display the bar in Yellow.

To do this, we could change line 130 and add 135 as follows:

0130 let bar$=str(min(pct,100)/1.5)+","+tbl(pct<70,"Green","Red")

0135 let bar$+=";"+str(max(pct-100,0)/1.5)+",Yellow"

This would result in the following:

Note:
Negative percentage values will be treated as 0 (zero) for both displaying and sorting.

Multiple Character Search

Drop boxes provide a multiple character search capability that makes it easier to search for an exact match in a drop box list.

Note:
Multiple character search applies to the following drop box Cell Types: "DropBox", "DropBoxHideBtn", "VarDropBox" and "VarDropBoxHideBtn".

To use this capability effectively, the characters must be entered within a ½ second of one another and must exactly match the start of an item in the drop box.

Example:

Assume that a drop box contains the following items:

C10000
C30000
C50000

Typing the character "c" followed within ½ second by the number "3" would select the "C30000" item.

Note:
In drop boxes, searching always starts from the current selection and wraps.

(Multiple character search in drop boxes was added in PxPlus 2019.)

Format 1

Create Grid 

GRID ctl_id,@(col,ln,wth,ht)[,ctrlopt]

Use this format to create your grid. The value in ctl_id is a unique identifier for your grid. This value is used to generate a CTL value whenever the grid is selected and changed.

When first creating a new grid, the height of the font declared in the FNT= option will be used to determine the default row height. If the font height exceeds 20 (the normal default row height), the system will automatically adjust the default row heights to a size large enough to accommodate the font size specified.

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

Format 2

Delete Grid

GRID REMOVE ctl_id[,ERR=stmtref]

Use this format to delete an entire grid.

Format 3

Add Row/Column

GRID ADD ctl_id,col,row[,ERR=stmtref]

Use the GRID ADD format to add a row or column of blank cells to your grid. At least one of the col,row values must be other than 0 (zero).

Format 4

Load

GRID LOAD ctl_id,col,row,contents$[,ERR=stmtref]

Use GRID LOAD to load contents$ into the grid from a string variable or expression. You must include both the column and the row for the address at which the load is to start. If column and row are both 0 (zero), then the grid is cleared first. 

PxPlus can load a number of columns and rows of data at a time. Column and row separators are mandatory. Set the column separator using the SEP= option. Set your row separator by including it as the last character in your data string. (PxPlus treats the last character in the string as your row separator.)

Adding a New (Bottom) Row

Use row=0 to add a new row to the bottom of a grid.

Example:

grid load ctl,1,0,data$+esc ! (using ESC as the row delimiter)

Format 5

Delete Col/Row

GRID DELETE ctl_id,col,row[,ERR=stmtref]

Use the GRID DELETE format to delete a column or row from your grid. You can identify a column to delete, a row to delete, or both.

Note:
If 0 (zero) is used as the value for both column and row, PxPlus interprets that as all columns and rows respectively and will delete the entire grid.

Format 6

Clear 

GRID CLEAR ctl_id,col,row[,width,height][,ERR=stmtref]

Use the GRID CLEAR format to clear or reset the contents of a range of cells to the default (empty). You can clear a column or a row or both.

Note: 
If 0 (zero) is used as the value for both column and row, PxPlus interprets that as all columns and rows respectively and will clear the entire grid.

Format 7

Disable/Enable

GRID {DISABLE | ENABLE} ctl_id[,ERR=stmtref]

Use the GRID DISABLE format to disable a grid so that it will be visible but inaccessible to users. To reactivate it, use GRID ENABLE.

Format 8

Lock/Unlock

GRID {LOCK | UNLOCK} ctl_id,col,row[,width,height][,ERR=stmtref]

Use the GRID LOCK format to allow/deny access to a range of cells in the grid. The user cannot change the cell's value; however, if the cell is a button control, the user can still click on it. Use the GRID UNLOCK format to release the locked range of cells for other processes.

Note:
If 0 (zero) is used as the value for both column and row, PxPlus interprets that as all columns and rows respectively and will lock/unlock the entire grid. You can also use a grid control object's properties to lock or unlock cells (by setting the 'Row, 'Column and 'Lock properties). Set your 'Lock value to 1 (lock) or 0 (zero to unlock).

The default background color for locked cells is LIGHT GRAY (standard button face color). Use the 'BackColor$ property to override this.

Format 9

Set Focus

GRID GOTO ctl_id[,ERR=stmtref]

Use this format of the GRID GOTO directive to set the focus on the first cell of your grid, ready for the user's next action.

Format 10

Focus on Cell Address

GRID GOTO ctl_id,col,row[,ERR=stmtref]

Use this format of the GRID GOTO directive to go to a specific cell address (other than the first cell) and set the focus on that cell, ready for the user's next action. You must include both column and row coordinates in this format of the directive (not zero values).

Format 11

Read First Cell

GRID READ ctl_id,col,row,var$,eom$[,ERR=stmtref]

Use var$ in the GRID READ format to receive the modified cell address and value of the first selected cell. If the cell does not exist, an Error #2: END-OF-FILE on read or File full on write. If there is more to read, the CTL event is re-posted. The eom$ string tells you which input sequence ended the message (e.g. $0D$ for the Enter key).

The GRID READ directive must include both column and row addresses. PxPlus returns a queue of cells that have been changed and generates an additional CTL event after a read to ensure that no events are lost. There can be a problem due to potential race conditions when the host is unable to keep up with the user input. To circumvent this, PxPlus returns Error #2: END-OF-FILE on read or File full on write if the queue is empty.

Note:
Under NOMADS, the read is automatic and should not be done by your application. The data read is placed in the standard input variable with control_name.row and control_name.column containing the associated cell information.

Format 12

Read Next

GRID READ NEXT ctl_id,col,row,var$,eom$[,ERR=stmtref]

Use the string var$ in the GRID READ NEXT format to receive the modified cell address and value of the next (not first) selected cell. If this cell does not exist, PxPlus returns an Error #2: END-OF-FILE on read or File full on write. If there is more to read, no CTL event is re-posted. The CTL value is posted when another cell is changed. The eom$ string tells you what input sequence ended the message (e.g. $0D$ for the Enter key)

Formats 13, 14, 15, 16

Select Read/Reset

Use the following formats to select ranges of cells to READ or to RESET (to remove cells from the SELECT state). GRID SELECT can be used to control cell selection. (When you SELECT a range of cells, the given cells are added to the list of selected cells.) To determine which cells are selected, use GRID SELECT READ to obtain the first selected cell, and then use GRID SELECT READ NEXT to get subsequent cells.

Note:
If 0 (zero) is used as the value for both column and row, PxPlus interprets that to mean "all cells" and will select the entire grid.

GRID SELECT ctl_id,col,row[,width,height][,ERR=stmtref]

Select Range. This format selects a range of cells from your grid.

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 *

GRID SELECT READ ctl_id,col,row[,ERR=stmtref]

Select Read. Use this to read the first selected cell. By default, the current cell is always selected; thus, this will always return a value. However, the values returned may reference a cell that does not exist as it has been deleted due to a GRID LOAD.

GRID SELECT READ NEXT ctl_id,col,row[,ERR=stmtref]

Select Read Next. Use this format to read the next (not the first) selected cell. When PxPlus encounters a GRID SELECT READ NEXT after the last selected cell is returned, it reports Error #2: END-OF-FILE on read or File full on write.

GRID SELECT RESET ctl_id[,ERR=stmtref]

Select Reset. This format removes all cells from the SELECT state. There is no way to remove cells from the selected state individually.

Format 17

Find or Retrieve

GRID FIND ctl_id,col,row,var$[,ERR=stmtref]

Use a string var$ in the GRID FIND format to return the value for a specific cell. 

Retrieve Range of Cells

GRID FIND ctl_id, 0,row, var$[,ERR=stmtref]	(Retrieve all cells in row)
GRID FIND ctl_id, col, 0, var$[,ERR=stmtref]	(Retrieve all cells in column)
GRID FIND ctl_id, 0, 0, var$[,ERR=stmtref]	(Retrieve all cells in grid)

Specifying a col or row of 0 (zero) causes PxPlus to return all columns/rows of the grid.

(The ability to retrieve a range of grid cells was added in PxPlus v7.10.)

Format 18

Write Setting

GRID WRITE ctl_id,col,row,contents$[,ERR=stmtref]

Use GRID WRITE to update your grid by writing settings to specified cells.

Note:
If 0 (zero) is used as the value for both column and row, then the value specified in contents$ will be written to each cell in the grid.

Format 19

Set Focus

GRID SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref]

Use the GRID SET_FOCUS format to have PxPlus return CTL values when focus changes to an address in the grid.

Format 20

Focus Notification

GRID AUTO ctl_id[,ERR=stmtref]

Use this format to have PxPlus return a CTL value whenever focus changes occur within your grid. You can use the values in your applications to track a user's selections. 

Format 21

Hide/Show

GRID {HIDE | SHOW} ctl_id[,ERR=stmtref]

With the GRID HIDE format, the grid remains active but is not displayed. It is still accessible programmatically. Use the SHOW format to restore the display and user access.

See Also

GRID Properties

Example

The example demonstrates how you can use a combination of GRID directives and GRID control object properties to perform various functions (formatting, loading, retrieving, etc.).

0010 ! GRIDDEMO - Grid demo program
0020 begin ; 
0020:print 'CS',"Grid Demonstration"
0030 grid 10,@(3,3,70,15)
0040 grid load 10,0,0,""
0050 for R=1 to 10
0060 let R$=""
0070 for C=1 to 10
0080 let R$+=str(C*R)+sep
0090 next
0100 grid load 10,1,0,R$
0110 next
0120 let X=10
0130 for I=1 to 10;
0130:let X'ROW=-1,X'COLUMN=I;
0130:let X'VALUE$="Col "+str(I);
0130:next
0140 for I=1 to 10;
0140:let X'ROW=I,X'COLUMN=-1;
0140:let X'VALUE$="Row "+str(I);
0140:next
0150 let X'COLUMN=-1,X'COLUMNWIDTH=6
0160 let X'COLUMN=2,X'ROW=0,X'LOCK=1
0170 let X'COLUMN=3,X'ROW=0,X'COLUMNWIDTH=7,X'CELLTYPE$="Button",X'LOCK=1
0180 let X'COLUMN=4,X'ROW=0,X'COLUMNWIDTH=7,X'CELLTYPE$="CheckMarkRecessed"
0190 let X'COLUMN=5,X'ROW=0,X'COLUMNWIDTH=7,X'CELLTYPE$="DropBox",
0190:X'TEXT$="cat/pig/dog/"
0200 let X'COLUMN=6,X'ROW=0,X'COLUMNWIDTH=7,X'CELLTYPE$="DropBoxHideBtn",
0200:X'TEXT$="cat/pig/dog/"
0210 let X'COLUMN=7,X'ROW=0,X'COLUMNWIDTH=7,X'BITMAP$="!bug"
0220 let X'COLUMN=8,X'ROW=0,X'ALIGN$="C"
0230 let X'COLUMN=9,X'ROW=0,X'ALIGN$="R"
0240 let X'COLUMN=0,X'ROW=2,X'BACKCOLOUR$="LIGHT CYAN"
0250 let X'COLUMN=0,X'ROW=3,X'BACKCOLOUR$="LIGHT YELLOW"
0260 let X'ROW=8;
0260:for I=1 to 10;
0260:let X'COLUMN=I;
0260:let X'BACKCOLOUR$="RGB:"+str(rnd(200)+55)+" "+str(rnd(200)+55)+
0260:" "+str(rnd(200)+55);
0260:next
0270 let X'ROW=9;
0270:for I=1 to 10;
0270:let X'COLUMN=I;
0270:let X'TEXTCOLOUR$="RGB:"+str(rnd(200)+55)+" "+str(rnd(200)+55)+
0270:" "+str(rnd(200)+55);
0270:next
0280 for I=1 to 10;
0280:let X'COLUMN=I,X'ROW=I,X'FONT$="Arial,1,BI";
0280:next
0290 input X$;
0290:if ctl=4
0290:then stop
0300 if ctl<>10
0300:then print "Recv'd CTL=",ctl;
0300:goto 0290
0310 grid read 10,C,R,ZZ$,E$
0320 print @(0,20),'CL',"Col=",C," Row=",R," Dta=",ZZ$," Eom=$",hta(E$),"$",
0330 goto 0290