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:
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
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.
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.
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.
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.
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.
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
’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 ’
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
allowselection colorback colortext fontstyle format text textalign valid value
Click Clienttoscreen Close Create Delete Deletecols Deleterows Draw Editstart Focus Hide Insertcols Insertrows New Open Paint Pointtocell Resize Screentoclient Send Set Show Trigger
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