ui.Dialog.setCellAttributes

Define cell decoration attributes array for the specified list (singular dialog only).

Syntax

setCellAttributes(
   attributes dynamic-array-type )
  1. attributes is a program array defining the cell attributes.
  2. dynamic-array-type is a DYNAMIC ARRAY OF ... type, which can be:
    • A DYNAMIC ARRAY OF RECORD ... END RECORD (with the same structure as the data array)
    • A DYNAMIC ARRAY OF STRING (to define attributes for complete lines instead of individual cells)
    • A DYNAMIC ARRAY WITH DIMENSION 2 OF STRING (to define attributes in dynamic dialog when the row structure is defined at runtime)

Usage

In an INPUT ARRAY or DISPLAY ARRAY dialog, the setCellAttributes() method can be used to specify display attributes for each cell, or for the complete row.

The setCellAttributes() method is designed for dialog programming, where only one screen array is used (for example, in a singular DISPLAY ARRAY dialog). An equivalent method called setArrayAttributes() can be used, when several screen arrays are defined in a multiple dialog, to be able to identify the list by the name of the screen array.

Possible values for cell attributes are a combination of the following:

  • The bold attribute
  • The reverse attribute
  • The blink attribute
  • The underline attribute
  • One of the supported color names, or an #RRGGBB value.

The cell attributes must be specified in lowercase characters and separated by a blank, for example:

  • "lightRed reverse"
  • "blue underline"
  • "blink"
  • "red bold reverse"
The structure of the dynamic array containing the cell attributes can be:
  • A DYNAMIC ARRAY OF RECORD, with the same structure as the data array
  • A DYNAMIC ARRAY WITH DIMENSION 2 OF STRING, to define a flexible set of cell attributes (for dynamic dialogs)
  • A DYNAMIC ARRAY OF STRING, to define attributes for complete lines
The following example defines a dynamic array with the same structure as the data array. Note however that the members of the attributes array use the STRING data type:
DEFINE data DYNAMIC ARRAY OF RECORD
         pkey INTEGER,
         name VARCHAR(50)
       END RECORD
DEFINE attributes DYNAMIC ARRAY OF RECORD
         pkey STRING,
         name STRING
       END RECORD
Similarly, the cell attributes array can be defined with a two-dimensional dynamic array of strings:
DEFINE attributes DYNAMIC ARRAY WITH DIMENSION 2 OF STRING

The advantage of a two-dimensional array is the flexibility, as it can define an unlimited number of cells for each row. This solution is typically used when implementing a dynamic dialog.

Finally, if you want to decorate complete lines instead of individual cells, use a simple dynamic array of strings:
DEFINE attributes DYNAMIC ARRAY OF STRING
Fill the display attributes array with color and video attributes:
FOR i=1 TO data.getLength()  -- length from data array!
    LET attributes[i].name = "blue reverse"
END FOR
Fill the display attributes array with color and video attributes:
FOR i=1 TO data.getLength()  -- length from data array!
    LET attributes[i].name = "blue reverse"
END FOR
Then, attach the array to the dialog with the setCellAttributes() method, in a BEFORE INPUT or BEFORE DISPLAY block:
BEFORE DISPLAY
   CALL DIALOG.setCellAttributes( attributes )
Like data values, if you change the cell attributes during the dialog, these are not displayed automatically unless the UNBUFFERED mode is used.
ON ACTION modify_cell_attribute 
   LET attributes[arr_curr()].name = "red reverse"
If you set NULL to an element, the default TTY attributes will be reset:
ON ACTION clean_cell_attribute 
   LET attributes[arr_curr()].name = NULL