APLX Help : System Classes : List of Classes : Grid
Grid
Introduction
The Grid object allows the display, optionally with editing, of two-dimensional data in a form similar to that of a spreadsheet. By placing Grid objects on a Page object within a tabbed Selector, you can add further dimensions to the data.
The Grid is made up of a rectangular array of cells, which can contain either text or numeric data. At the top and left of the grid you can optionally have header (non-scrolling) cells.
In this example, we create a grid with 4 rows and 3 columns of scrolling (data) cells, and one row and column of header cells:
W←'⎕' ⎕NEW 'Window' ⋄ W.caption←'Grid example'
W.Grid.New 'Grid' ⋄ W.Grid.align←¯1 ⋄ W.Grid.rows←4 ⋄ W.Grid.cols←3
W.Grid.text (¯1) (⍳3) ('Jan' 'Feb' 'Mar')
W.Grid.text (⍳4) (¯1) ('Europe' 'N. America' 'S. America' 'Asia')
DATA←4 3⍴17.3 14.4 19.2 12.2 12.9 14.2 7.4 7.1 7.9 2.3 3 2.8
W.Grid.value (⍳4) (⍳3) DATA
This produces the following effect:
Cell Properties
As well as ordinary properties, a Grid object has properties which are associated with individual cells, known as cell properties. In the example above, we have used the text cell property to set the text within the header cells. We have also used the value cell property to set the contents of the data (scrolling) cells, in this case to be numbers. Cell properties are set with the special dot-notation syntax (rather as though they were methods):
WindowRef.ControlName.PropertyName Rows Cols Array
where Rows is a scalar or vector of the row indices you want to change, Cols is a scalar or vector of the column indices you want to change, and Array is an array of the data you want to assign to the cells. As with normal APL indexed assignment, the shape of Array must match the number of rows and columns specified, or be a scalar (in which case the data is assigned to all the cells specified). If either Rows or Cols has only one element, a vector can be used for Array instead of a one-row or one-column matrix.
If you are using the older ⎕WI syntax, the equivalent is:
'WindowName.ControlName' ⎕WI 'PropertyName' Rows Cols Array
The syntax for reading back cell properties is similar, simply omitting the Array parameter:
R←WindowRef.ControlName.PropertyName Rows Cols
or the equivalent
R←'WindowName.ControlName' ⎕WI 'PropertyName' Rows Cols
The result will be an array of shape (⍴Rows) (⍴Cols)
Rows and columns in the data (scrolling) region are numbered starting from 1. Rows and columns in the header (non-scrolling)
region are numbered ¯1,
¯2 etc, where ¯1
means the row or column nearest to the data area. In some cases, you can specify a row or column of 0, which means
'apply to the whole row/column'.
Using our example above:
W.Grid.text (1 2) (¯1)
Europe
N. America
⎕DISPLAY W.Grid.text (1 2) (¯1)
┌→─────────────┐
↓ ┌→─────┐ │
│ │Europe│ │
│ └──────┘ │
│ ┌→─────────┐ │
│ │N. America│ │
│ └──────────┘ │
└∊─────────────┘
W.Grid.value (1 2) (1 3)
17.3 19.2
12.2 14.2
or, using ⎕WI syntax, something like this (assuming Win is the name of the window):
'Win.Grid' ⎕WI 'text' (1 2) (¯1)
Europe
N. America
'Win.Grid' ⎕WI 'value' (1 2) (1 3)
17.3 19.2
12.2 14.2
Numeric versus Text cells
Each cell can be of type Text or Numeric. Text cells contain simply character vectors; when you read either the text or value property of the cell, you get the text shown in the cell, possibly edited by the user, as a character vector.
Numeric cells contain numbers. If you read the value property of a Numeric cell, you get a numeric scalar, which is the current value of the cell. If the cell does not currently contain a valid number (because the user has edited it), you get a special numeric value to indicate an invalid number (by default this is a very large negative number; you can change it using the conversionerrorvalue property). If you read the text property of the cell, you get the actual text shown in the cell, which is usually the text representation of the cell∇s value, but may be different if it has been edited by the user and is not a valid value. You can also read the valid cell property, which tells you whether the cell contains a valid value.
With our example above:
W.Grid.valid (1 2) (1 3)
1 1
1 1
⎕DISPLAY W.Grid.value (1 2) (1 3)
┌→────────┐
↓17.3 19.2│
│12.2 14.2│
└~────────┘
⎕DISPLAY W.Grid.text (1 2) (1 3)
┌→──────────────┐
↓ ┌→───┐ ┌→───┐ │
│ │17.3│ │19.2│ │
│ └────┘ └────┘ │
│ ┌→───┐ ┌→───┐ │
│ │12.2│ │14.2│ │
│ └────┘ └────┘ │
└∊──────────────┘
In this example, the text property returns a 2 by 2 nested array of character vectors, but the value property returns a 2 by 2 numeric matrix.
Initially, all cells default to type Text. A cell becomes of type Numeric if you write a numeric value to its value property, or if you write a format string to its format property, which determines how it is formatted in the cell.
Properties of the Grid object
style: (Integer) The style property is the sum of a set of flags which determine how the Grid behaves:
1 If set, user can select a range of cells (Default: Off)
To allow the mouse to be used to select the range,
you should also set autoeditstart to 0.
2 If set, a whole row is selected together (Default: Off)
4 If set, user can use the Tab key to move between cells (Default: On)
8 Reserved
16 If set, vertical scroll bar is shown if the Grid's contents will not
fit between the top and bottom of the visible area (Default: On)
32 Reserved
64 If set, horizontal scrollbar is shown if the Grid's contents will not
fit between the left and right of the visible area (Default: On)
128 If set, user can re-size rows (Default: Off)
256 If set, user can re-size columns (Default: On)
512 If set, user can move rows to re-arrange their order (Default: Off)
1024 If set, user can move columns to re-arrange their order (Default: Off)
2048 If set, the contents of the grid update as the scroll-bar is moved
(Default: Off. Under MacOS, this flag is ignored since the grid
always updates immediately).
4096 If set, unnecessary scroll bars are disabled instead of being
hidden (MacOS only)
borderstyle: (Integer) The borderstyle property is the sum of a set of flags which determine the appearance of the Grid (the defaults are all On):
1 Header cells have separator horizontal line
2 Header cells have separator vertical line
4 Data cells have separator horizontal line
8 Data cells have separator vertical line
16 Use 3D effect (Windows and MacOS only, ignored under Linux)
autoeditstart: (Integer) Determines whether the data in the Grid can be edited, and if so how the edit process starts. It can be one of:
0 Editing of a cell is possible only when the program calls Editstart
1 Editing is automatically enabled when the cell is selected; the user
can immediately type
2 The user must press Enter (or, under Windows and Linux, F2) to start
editing a cell
The default is 1.
color or colour: (1, 2, 3 or 6 element numeric) The color or colour property for a Grid is set in the same way as for other controls. The foreground color you set determines the default color of the text shown in the Grid (you can change this for individual cells using the colortext cell property). The background color is used as the background for the data part of the Grid (you can change this for individual cells using the colorback cell property).
colorhead or colourhead:
(1 or 3 element numeric) The colorhead or colourhead
property for a Grid can be set as either a single RGB encoded integer (256 ⊥ Blue Green Red) or
as three Red Green Blue values, each 0 to 255. It determines the background color used for header cells. The special value ¯1 means use the Grid control's foreground
color. The special value ¯2 means use the
default (light gray).
font: (Character vector or nested vector) The font for a Grid is set in the same way as for other controls. It determines the default font for the text shown in the Grid. You can change the font style for individual cells using the fontstyle cell property.
conversionerrorvalue: (Floating-point number) Value to return if a numeric cell cannot be converted to valid number. The default is a large negative number.
gridlines: (Boolean) Determines whether the grid lines within the data area are visible. (Default 1)
headcols: (Integer) The number of heading (fixed) columns (Default 1). You typically set this property when you create the grid (before setting the cols property).
headrows: (Integer) The number of heading (fixed) rows (Default 1). You typically set this property when you create the grid (before setting the rows property).
cols: (Integer) The number of data (scrolling) columns. You typically set this property when you create the Grid to fit the size of the data you want to display.
rows: (Integer) The number of data (scrolling) rows. You typically set this property when you create the Grid to fit the size of the data you want to display.
col: (Integer) The Column number (in index origin 1) of the currently-active cell. You can write to this property to change the current cell.
row: (Integer) The Row number (in index origin 1) of the currently-active cell. You can write to this property to change the current cell.
activecell: (2-element integer vector) The Row and Column of the currently-active cell. You can write to this property to change the current cell.
text: (Character vector) Although text is a cell property for a Grid object, as a convenience you can read (but not write to) text as a simple property of the Grid object. It returns the text of the currently-active cell.
value: (Character vector or numeric scalar) Although value is a cell property, as a convenience you can read (but not write to) value as a simple property of the Grid object. It returns the value of the currently-active cell. If the cell is a text cell, it will return a character vector. If it is a numeric cell, it will return the numeric value of the cell, or (if the cell is invalid) the current conversionerrorvalue.
selection: (4-element integer vector) The Row and Column of the top-left of the selected cell range, followed by the number of rows selected and the number of columns selected. If the style property is set so that only single-selection is possible (which is the default), the last two elements will both be one. You can write to this property to change the selection under program control.
view: (4-element integer vector) Determines the visible portion of the grid. The four elements are the First visible row, First visible column, Number of visible Rows, Number of visible columns. You can write to this property to scroll the grid under program control (only the first two elements are required).
firstvisible: (2-element integer vector) Determines the top-left position of the visible portion of the Grid. It is the same as the first two elements of the view property.
imagesize: (Read-only, 2-element numeric vector) Returns the total height and width, in the control∇s current scale, of all the cells in the Grid. This may be smaller than or larger than the height and width of the visible Grid control itself.
Cell properties of the Grid object
These are all set using the syntax:
WindowRef.ControlName.PropertyName Rows Cols Array
and read using the syntax:
R←WindowRef.ControlName.PropertyName Rows Cols
value: (Each cell element is a character vector or numeric scalar) Read or set cell values.
When you read this cell property for a Grid object, it returns a character vector for each Text cell and a numeric scalar for each Numeric cell, for each cell in the list of rows and columns specified. If a Numeric cell is invalid, it will return the current conversionerrorvalue. If you read a set of cells some of which are Numeric and some Text, it will return a nested array containing a mixture of character vectors and numeric scalars. If you read a set of cells all of which are Numeric, it will return a simple numeric array.
When you write to this cell property for a Grid object, it sets the value for each cell in the list of rows and columns specified. If you supply a number for a cell, that cell becomes a Numeric cell. If you supply a character vector or scalar, it becomes a Text cell. Writing to a cell also causes its valid property to be set to 1.
text: (Each cell element is a character vector) Read or set cell text.
When you read this property, it returns a character vector containing the text displayed in the cell, irrespective of the cell∇s type, for each cell in the list of rows and columns specified. For multiple cells, it will therefore return a nested array of character vectors.
When you write to this property, the text displayed in the cell is set to the text you supply. To set multiple cells in one operation, provide a nested array of character vectors. The type of the cell, and the cell∇s valid property, are not changed. If the cell is Numeric, it will remain so, and its value will not change.
Note: The text in the cell can contain embedded carriage-return (⎕R) characters, which results in the text being displayed on multiple lines. In this case, you may need to increase the row height.
valid: (Each cell element is a Boolean scalar, read-only) Returns 1 if the cell is valid, and 0 if it is invalid. Text cells are always valid. Numeric cells may be invalid if the user has edited the text.
allowselection: (Each cell element is a Boolean scalar) If this is set to 1 (default), the cell can be selected. If it is set to 0, the cell cannot be selected.
textalign: (Each cell element is an integer scalar) Determines how the text is aligned within the cell. The value is the sum of two numbers. The horizontal alignment is 1 for left, 2 for right, or for 4 center. The vertical alignment is 8 for top, 16 for bottom, or 32 for center. The default value depends on the type of the cell. Header cells default to centered in both directions (4 + 32 = 36). Text cells in the data area default to top, left (1 + 8 = 9). Numeric cells default to top, right (2 + 8 = 10).
colortext or colourtext: (Each cell element
is an integer scalar) Determines the
color of text in the cell. The value is
a color expressed as a numeric scalar (256 ⊥
Blue Green Red). The special value of ¯1
means use the Grid foreground color for this cell; this is the default.
colorback or colourback: (Each cell element
is an integer scalar) Determines the
background color for the cell (when it is not selected). The value is a color expressed as a numeric
scalar (256 ⊥
Blue Green Red). The special value of ¯1 means use the Grid background color for this cell; this is the default.
fontstyle: (Each cell element is an integer scalar) Determines the style of the text within the cell. The value is the sum of:
0 Plain
1 Bold
2 Italic
4 Underlined
8 Hollow (supported under MacOS only)
16 Strikeout (not supported under MacOS)
The special value of ¯1 means use the default font style of the Grid.
format: (Each cell element is a character vector) Determines the format used to display numeric values. You can specify separate formats for positive, negative and zero numbers. See the description of the format cell property for details of the format strings.
Setting this value automatically sets the cell type to Numeric.
Row and Column sizes
You can set the size of the rows and columns using the rowsize and colsize properties, as follows:
WindowRef.ControlName.rowsize Rows Sizes
WindowRef.ControlName.colsize Cols Sizes
or:
'WindowName.ControlName' ⎕WI 'rowsize' Rows Sizes
'WindowName.ControlName' ⎕WI 'colsize' Cols Sizes
where Rows or Cols is a scalar or vector list of row/column numbers, and Sizes is a matching vector (or scalar) of the row/column sizes in pixels. A row or column number of 0 sets the default size for all rows or columns which are not explicitly set. Note: At least one of Rows/Cols and Sizes parameters must be a vector, otherwise the statement will be interpreted as an attempt to read back the current sizes.
You can read back the current sizes using the syntax:
R ← WindowRef.ControlName.rowsize Rows
R ← WindowRef.ControlName.colsize Cols
or:
R ← 'WindowName.ControlName' ⎕WI 'rowsize' Rows
R ← 'WindowName.ControlName' ⎕WI 'colsize' Cols
Note that, depending on the flags you have set in the style property, the user may be able to resize rows and columns.
Methods for the Grid object
EditStart: This method takes no arguments. It initiates an editing session on the currently-active cell. It is useful mainly if you have set the autoeditstart property to 0. For example, you might initiate an edit session for certain cells only (in response to an onSelChange event).
DeleteCols and DeleteRows: These methods take an argument which is a vector of rows or columns to be deleted. After they have been deleted, the remaining rows or columns are re-numbered to form an integer sequence starting at 1.
InsertCols and InsertRows: These methods take an argument which is a vector of positions at which you wish to insert new rows or columns. You can specify integers (for example 5 means 'insert before the current row/column 5'), or non-integers (for example 4.5 means 'insert between the current row/column 4 and 5'). After the insertion, the rows or columns are re-numbered to form an integer sequence starting at 1. Thus, if you insert at 5 and 6, the new rows/columns become numbers 5 and 7. To insert three new rows/columns before the current second one, specify 2 2 2.
Pointtocell: Converts a point on the visible Grid control to cell row/column.
Callbacks for the Grid object:
onChange: This event is triggered when the user has
edited the contents of a cell. The
event-specific parameters in ⎕EV
are (in index origin 1):
⎕EV[6] Row number of the edited cell
⎕EV[7] Column number of the edited cell
⎕EV[8] Flag to indicate whether the contents were valid
onColMoved: This event is triggered when the user has
moved a column by dragging it to a different position in the grid. (This is possible only if the style property
includes the flag 1024, column moving allowed). The event-specific parameters in ⎕EV are (in index origin 1):
⎕EV[6] Column number before the move
⎕EV[7] The position of the column after the move
onRowMoved: This event is triggered when the user has
moved a row by dragging it to a different position in the grid. (This is possible only if the style property
includes the flag 512, row moving allowed). The event-specific parameters in ⎕EV are (in index origin 1):
⎕EV[6] Row number before the move
⎕EV[7] The position of the row after the move
onColSized: (MacOS only) This event is triggered when the user has
resized a column. (This is possible only if the style property
includes the flag 256, column re-sizing allowed). The event-specific parameters in ⎕EV are (in index origin 1):
⎕EV[6] Column number
onRowSized: (MacOS only) This event is triggered when the user has
resized a row. (This is possible only if the style property
includes the flag 128, row re-sizing allowed). The event-specific parameters in ⎕EV are (in index origin 1):
⎕EV[6] Row number
onScroll: This event is triggered when the user has scrolled the Grid control.
onSelChange: This event is triggered when the user
selects a new cell. The
event-specific parameters in ⎕EV
are (in index origin 1):
⎕EV[6] Row number of the newly-selected cell
⎕EV[7] Column number of the newly-selected cell
Example
∇DEMO_Grid;DATA;SIZE;Demo
[1] ⍝ Sample function demonstrating use of the Grid object
[2] ⍝
[3] ⍝ Create basic Grid control, without automatic edit
[4] Demo←'⎕' ⎕NEW 'Window' ⋄ Demo.caption←'Grid example' ⋄ Demo.scale←5
[5] Demo.Grid.New 'Grid' ⋄ Demo.Grid.align←¯1 ⋄ Demo.Grid.autoeditstart←2
[6] Demo.Grid.rows←4 ⋄ Demo.Grid.cols←3
[7] ⍝
[8] ⍝ Add headings (text cell properties)
[9] Demo.Grid.text (¯1) (¯1) ('Profit')
[10] Demo.Grid.text (¯1) (⍳3) ('Jan' 'Feb' 'Mar')
[11] Demo.Grid.text (⍳4) (¯1) ('Europe' 'N. America' 'S. America' 'Asia')
[12] ⍝
[13] ⍝ Insert data (numeric cell properties)
[14] DATA←4 3⍴17.33 14.41 19.21 12.2 12.94 14.23 7.4 7.17 7.92 ¯2.32 ¯3.03 ¯2.85
[15] Demo.Grid.value (⍳4) (⍳3) DATA
[16] ⍝
[17] ⍝ Add format strings for the numbers, different for positive/negative
[18] Demo.Grid.format (⍳4) (⍳3) (⊂'$#.00M;($#.00M)')
[19] ⍝
[20] ⍝ Set some foreground colors for cells
[21] Demo.Grid.colortext (4) (⍳3) 255
[22] ⍝
[23] ⍝ Set header text styles
[24] Demo.Grid.fontstyle (¯1) (¯1) 1
[25] Demo.Grid.fontstyle (¯1) (⍳3) 2
[26] ⍝
[27] ⍝ Make the window fit snugly around the Grid control, with a small margin
[28] SIZE←Demo.Grid.imagesize
[29] Demo.size←(SIZE+4)
[30] ⍝
[31] ⍝ Wait for the user to close the window
[32] 0 0⍴⎕WE Demo
∇
Properties
activecell align anchors aquaadjust autodraw autoeditstart borderstyle caption children class col color colorhead cols colsize conversionerrorvalue data doublebuffered dragsource droptarget enabled events extent firstvisible font gridlines handle headcols headrows maxsize methods minsize name opened order pointer properties row rows rowsize scale self size sourceformats style tabstop targetformats tie tooltip units view visible where winptr
Cell Properties
allowselection colorback colortext fontstyle format text textalign valid value
Methods
Click Clienttoscreen Close Create Delete Deletecols Deleterows Draw Editstart Focus Hide Insertcols Insertrows New Open Paint Pointtocell Resize Screentoclient Send Set Show Trigger
Callbacks
onChange onClick onClose onColMoved onDblClick onDestroy onDragDrop onDragEnd onDragEnter onDragLeave onDragOver onDragStart onFocus onHide onKeyDown onKeyPress onKeyUp onMouseDown onMouseMove onMouseUp onOpen onRowMoved onScroll onSelChange onSend onShow onUnFocus
APLX Help : System Classes : List of Classes : Grid