## 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

Topic: APLX Help : System Classes : List of Classes : Grid

[ Previous | Next | Contents | Index ]