Common Properties

TITLE

Grids do not have titles

VALUE

A grid does not have a (single) value. You can set or inquire the contents of each cell using the CELL-DATA property. You can also retrieve an entire record at once with the RECORD-DATA property.

SIZE

The SIZE of a grid is the number of characters across that you want to be visible in the grid. This is measured using the grid's default font. The LINES of a grid is the number of rows you want to be visible. Note that this is not the same as the number of records in the case where a record occupies more than one row. Normally, you should ensure that the LINES setting of a grid is an even multiple of the number of rows per record.

Space is added as needed to accommodate the grid's scroll bars and any border or grid lines

COLOR

Grids will use any specified foreground or background color. If either color is omitted, that color uses a system-dependent default value. Under Microsoft Windows, the default values are determined by the settings defined by the user in the Control Panel (usually black on bright-white). Note that the grid's color is its default color. You can override this default for a specific row, column, or cell by using various special properties (see ROW-COLOR, COLUMN-COLOR, CELL-COLOR, CURSOR-COLOR, HEADING-COLOR and ROW-COLOR-PATTERN). The grid uses a priority rule for determining which color to use when several are specified for a cell (for example, a cell that has a ROW-COLOR and a different COLUMN-COLOR specified for it). This is discussed in detail in the introduction to the grid above.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme (that is, a #class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

REGISTRY-KEY

REGISTRY-KEY enables the runtime to store information in the registry about modifications to the grid via sort-column, physical-columns, and column widths. This information is loaded from the registry when a COBOL program with the same key name is run.

Ideally, the information stored is unique for each grid in an application. If the number of columns in the grid doesn't match the number of columns stored in the registry, the values in the registry are ignored.

Notes:
  • The runtime loads saved registry values when REGISTRY-KEY is set; therefore, we recommend that you set this property last.
  • For AcuToWeb these values are saved in the LocalStorage of the browser using the same key used for the registry. To check these values, start the browser development console by pressing Ctrl + Shift + i. Click the Application tab. The values are listed in the LocalStorage section on the left side.

STYLES

3-D

Displays 3-D shading around the border of the control.

ADJUSTABLE-COLUMNS

Enables grid column size to be adjusted by dragging a column header divider with the mouse.

The minimum column size is 0. When dragged to zero, the column is entirely hidden, and displays a small mark to indicate the location of the hidden column. To restore a hidden column, hover over the mark, and then click the resulting image. When a column is hidden, the runtime sends a MSG-COLUMN-SHOW event to the COBOL program.

When the user changes a column size, the program is informed via a MSG-COL-WIDTH-CHANGED message. Because grids use integer character widths for measuring columns, the grid automatically adjusts the location given by the user to the nearest character position.

The maximum column size is the visible portion of the grid. If the grid allows for horizontal scrolling, the VIRTUAL-WIDTH property changes as the user changes column sizes.

The default value of ADJUSTABLE-COLUMNS is 512.

Restrictions: The following restrictions apply to the ADJUSTABLE-COLUMNS style:
  • The grid can contain no more than one row per record
  • Single-column grids are not adjustable because the column already occupies all of the grid's display space. If ADJUSTABLE-COLUMNS is set on a single-column grid, the column might appear to be adjustable, but when the user releases the mouse after dragging to change the width, the column returns to its original width.
  • Columns may not be dragged to the left of any row headers
ADJUSTABLE-ROWS Enables you to change the height of a row by clicking and dragging a row divider. To change a row height, first declare it in the grid variable within the screen section. Once declared, hovering over a row divider changes the mouse cursor to a SIZE-NS arrow. Click and hold in this position to display a draggable divider outline that shows what the location of the row divider will be once resizing is completed. Releasing the mouse changes the row height.
Notes:
  • When the ROW-HEADINGS style is also enabled, row heights can be changed only by hovering over and dragging dividers in the row headings column.
  • When the ADJUSTABLE-COLUMNS style is also enabled, the resized row heights can be stored in the registry in the same manner as resized column widths.

MOVEABLE-COLUMNS

Enables grid columns to be moved by dragging a column header to a new position, and dropping the column when arrows appear at the desired location.

When a column is moved, the runtime sends a MSG-COLUMN-MOVED event to the COBOL program.

The default value of MOVEABLE-COLUMNS is 4096.

Restrictions: The following restrictions apply to the MOVEABLE-COLUMNS style:
  • The grid can contain no more than one row per record
  • The grid must have column headers
  • Columns may not be dragged to the left of any row headers
  • When NUM-COL-HEADINGS is > 1, this effectively turns off the MOVEABLE-COLUMNS style. For more information, see NUM-COL-HEADINGS.
BOXED Displays a border around the grid. If neither BOXED nor NO-BOX is specified, the default is machine-dependent. Under Windows, a box is displayed.
CENTERED-HEADINGS Draws column headings centered, regardless of the alignment of the rest of the column. If this is not specified, the column headings match the alignment of the corresponding column. Note that the alignment of row headings is specified as the first entry in the ALIGNMENT property, so there is no need for any special row heading alignment styles.
CENTERED-ROW-HEADINGS Vertically centers grid row headings. Set this style as part of the grid declaration in the screen section. In addition, you must also enable the ROW-HEADINGS style.
COLUMN-HEADINGS Causes the first record to be treated as column headers. See the discussion on headers above for details.
HSCROLL Specifies a horizontally scrolling grid. A grid with this style may not specify more than one row per record (for more information, see the DISPLAY-COLUMNS special property).
NO-BOX Causes the grid to display without a surrounding border. See the BOXED property.
NO-CELL-DRAG Prevents the user from dragging a cell in a grid control. You can configure NO-CELL-DRAG style to be the default setting for grid controls by setting the GRID_NO_CELL_DRAG configuration variable to 1 (on, true, yes). The default value is 0 (off, false, no) and will enable the user to drag a cell in a grid control.
PAGED Makes the grid a "paged" grid. Paged grids are typically used when the number of records in the grid is too many for a normal grid. When you set this style for a grid that contains data, records above the first visible record and records after the last visible record are deleted. See Paged Grids for a complete description of paged grids.
ROW-HEADINGS Treats the first column of each record as a row header. Note that this is typically useful only when you have one record per row. See the discussion on headers above for more details.
TILED-HEADINGS Draws the headings with some shading that causes the headings to look like tiles. This gives a light 3-D look to the grid. This style is effective only if the background color for the heading cells is low-intensity and not black. This looks best if you set the heading's background color to low-intensity white (that is, gray) and set the heading's divider color to black. Using the constants found in the COPY library acucobol.def, you can most easily specify this with:
HEADING-COLOR = BCKGRND-WHITE, 
HEADING-DIVIDER-COLOR = BLACK
USE-TAB Causes the grid to use the Tab and Backtab keys as navigation keys within the grid. Without this style, the Tab and Backtab keys move between the grid and other controls in the grid's window.
VSCROLL Specifies a vertical scroll bar for the grid. Grids without vertical scroll bars may still contain more records than seen on the screen, and the user can still reach these records using the keyboard. The usual reason for creating a grid without a vertical scroll bar is if you are going to limit the number of records to an amount that fits on the screen (see NUM-ROWS below).