ui.Dialog.setArrayAttributes

Define cell decoration attributes array for the specified list (singular or multiple dialogs).

Syntax

setArrayAttributes(
   name STRING,
   attributes dynamic-array-type )
  1. name is the name of the screen record, see Identifying screen-arrays in dialog methods.
  2. attributes is a program array defining the cell attributes.
  3. 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 WITH DIMENSION 2 OF STRING (to define attributes in dynamic dialog when the row structure is defined at runtime)
    • A DYNAMIC ARRAY OF STRING (to define attributes for complete lines instead of individual cells)

Usage

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

The setArrayAttributes() is typically used in a DIALOG block where several screen arrays are defined. The method takes the name of the screen array as first parameter, to identify the list to be decorated with colors. An equivalent method called setCellAttributes() can be used, for dialogs where only one screen array is defined.

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
Then, attach the array to the dialog with the setArrayAttributes() method, in a BEFORE DIALOG, BEFORE INPUT or BEFORE DISPLAY block:
BEFORE DIALOG
   CALL DIALOG.setArrayAttributes( "sr", 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