Using object arrays in columns (4D View Pro)

List box columns can work with object arrays. Since object arrays can contain different kinds of data, this powerful feature allows you to enter and display various types of values in the rows of a single column, and use various widgets as well. For example, you could insert a text input in the first row, a check box in the second, and a drop-down list in the third. Object arrays also provide access to new kinds of widgets, such as buttons or color pickers.

The following list box was designed using an object array:

About 4D View Pro: The ability to use object arrays in list boxes is a "4D View Pro" function, which means that its use requires you to have a valid 4D View license. 4D View Pro is a new tool being developed which includes a set of features related to arrays and list presentations. It is intended to progressively replace the 4D View plug-in. For more information, please refer to the 4D Web site. 

To assign an object array to a list box column, you just need to set the object array name in either the Property list ("Variable Name" field), or using the LISTBOX INSERT COLUMN command, like with any array-based column. In the Property list, you can select Object as a "Variable Type" for the column:

Standard properties related to coordinates, size, and style are available for object columns. You can define them using the Property list, or by programming the style, font color, background color and visibility for each row of an object-type list box column. These types of columns can also be hidden.

However, the Data Source theme is not available for object-type list box columns. In fact, the contents of each column cell are based on attributes found in the corresponding element of the object array. Each array element can define:

• the value type (mandatory): text, color, event, etc.
• the value itself (optional): used for input/output.
• the cell content display (optional): button, list, etc.
• additional settings (optional): depend on the value type

To define these properties, you need to set the appropriate attributes in the object (available attributes are listed below). For example, you can write "Hello World!" in an object column using this simple code:

Note: Display format and entry filters cannot be set for an object column. They automatically depend on the value type.

When a list box column is associated with an object array, the way a cell is displayed, entered, or edited, is based on the valueType attribute of the array element. Supported valueType values are:

• "text": for a text value
• "real": for a numeric value that can include separators like a <space>, <.>, or <,>
• "integer": for an integer value
• "boolean": for a True/False value
• "color": to define a background color
• "event": to display a button with a label.

4D uses default widgets with regards to the "valueType" value (i.e., a "text" is displayed as a text input widget, a "boolean" as a check box), but alternate displays are also available through options (e.g., a real can also be represented as a drop-down menu). The following table shows the default display as well as alternatives for each type of value:

You set the cell display and options using specific attributes in each object (see below).

You cannot set display formats or entry filters for columns of object-type list boxes. They are automatically defined according to the value type. These are listed in the following table:

Each element of the object array is an object that can contain one or more attributes that will define the cell contents and data display (see example above).

The only mandatory attribute is "valueType" and its supported values are "text", "real", "integer", "boolean", "color", and "event". The following table lists all the attributes supported in list box object arrays, depending on the "valueType" value (any other attributes are ignored). Display formats are detailed and examples are provided below.

Cell values are stored in the "value" attribute. This attribute is used for input as well as output. It can also be used to define default values when using lists (see below).

Example:

Note: Null values are supported and result in an empty cell.

When the "valueType" is "real" or "integer", the object also accepts min and max attributes with appropriate values (values must be of the same type as the valueType). 

These attributes can be used to control the range of input values. When a cell is validated (when it loses the focus), if the input value is lower than the min value or greater than the max value, then it is rejected. In this case, the previous value is maintained and a tip displays an explanation.

Example:

The behavior attribute provides variations to the regular representation of values. In the current version of 4D, a single variation is proposed:

Example:

When a "choiceList" or a "requiredList" attribute is present inside the object, the text input is replaced by a drop-down list or a combo box, depending of the attribute:

• If the attribute is "choiceList", the cell is displayed as a combo box. This means that the user can select or type a value.
• If the attribute is "requiredList" then the cell is displayed as a drop-down list and the user can only select one of the values provided in the list.

In both cases, a "value" attribute can be used to preselect a value in the widget.

Note: The widget values are defined through an array. If you want to assign an existing 4D list to the widget, you need to use the "requiredListReference", "requiredListName", "choiceListReference", or "choiceListName" attributes.

Examples:

• You want to display a drop-down list with only two options: "Open" or "Closed". "Closed" must be preselected:
  
   ARRAY TEXT($RequiredList;0)
 APPEND TO ARRAY($RequiredList;"Open")
 APPEND TO ARRAY($RequiredList;"Closed")
 C_OBJECT($ob)
 OB SET($ob;"valueType";"text")
 OB SET($ob;"value";"Closed")
 OB SET ARRAY($ob;"requiredList";$RequiredList)
  
  

• You want to accept any integer value, but display a combo box to suggest the most common values:
  
   ARRAY LONGINT($ChoiceList;0)
 APPEND TO ARRAY($ChoiceList;5)
 APPEND TO ARRAY($ChoiceList;10)
 APPEND TO ARRAY($ChoiceList;20)
 APPEND TO ARRAY($ChoiceList;50)
 APPEND TO ARRAY($ChoiceList;100)
 C_OBJECT($ob)
 OB SET($ob;"valueType";"integer")
 OB SET($ob;"value";10) //10 as default value
 OB SET ARRAY($ob;"choiceList";$ChoiceList)
  
  

The "requiredListName" and "requiredListReference" attributes allow you to use, in a list box cell, a list defined in 4D either in Design mode (in the Lists editor of the Tool box) or by programming (using the New list command). The cell will then be displayed as a drop-down list. This means that the user can only select one of the values provided in the list.

Use "requiredListName" or "requiredListReference" depending on the origin of the list: if the list comes from the Tool box, you pass a name; otherwise, if the list has been defined by programming, you pass a reference. In both cases, a "value" attribute can be used to preselect a value in the widget.

Note: If you want to define these values through a simple array, you need to use the "requiredList" attribute.

In this case, the "saveAs" attribute will define whether the selected item must be saved as a "value" or as a "reference".

• If "saveAs" = "reference" then it will be saved as a reference and the "valueType" must be real or integer.
• If "saveAs" = "value" then the value is saved. In this case, the "valueType" must be the same type as the values of the list, usually "text" or "integer"; otherwise 4D will try to convert the value of the list into the "valueType" of the object (see examples below).

For more information about the "save as" option, please refer to the Save as Value or Reference section in the Design Reference manual.

Note: If the list contains text items representing real values, the decimal separator must be a period ("."), regardless of the local settings, e.g.: "17.6" "1234.456".

Examples:

• You want to display a drop-down list based on a "colors" list defined in the Tool box (containing the values "blue", "yellow", and "green"), save it as a value and display "blue" by default:
  
  
   C_OBJECT($ob)
 OB SET($ob;"valueType";"text")
 OB SET($ob;"saveAs";"value")
 OB SET($ob;"value";"blue")
 OB SET($ob;"requiredListName";"colors")
  
  

• You want to display a drop-down list based on a list defined by programming and save it as a reference:
  
   <>List:=New list
 APPEND TO LIST(<>List;"Paris";1)
 APPEND TO LIST(<>List;"London";2)
 APPEND TO LIST(<>List;"Berlin";3)
 APPEND TO LIST(<>List;"Madrid";4)
 C_OBJECT($ob)
 OB SET($ob;"valueType";"integer")
 OB SET($ob;"saveAs";"reference")
 OB SET($ob;"value";2) //displays London by default
 OB SET($ob;"requiredListReference";<>List)
  
  

The "choiceListName" and "choiceListReference" attributes allow you to use, in a list box cell, a list defined in 4D either in Design mode (in the Tool box) or by programming (using the New list command). The cell is then displayed as a combo box, which means that the user can select or type a value.

Use "choiceListName" or "choiceListReference" depending on the origin of the list: if the list comes from the Tool box, you pass a name; otherwise, if the list has been defined by programming, you pass a reference. In both cases, a "value" attribute can be used to preselect a value in the widget.

Note: If you want to define these values through a simple array, you need to use the "choiceList" attribute.

The "saveAs" attribute cannot be used in this case because selected items are automatically saved as a "value" (cf. for more information).

Note: If the list contains text items representing real values, the decimal separator must be a period ("."), regardless of the local settings, e.g.: "17.6" "1234.456".

Example:

You want to display a combo box based on a "colors" list defined in the Tool box (containing the values "blue", "yellow", and "green") and display "green" by default:

You can use specific attributes to add units associated with cell values (e.g.: "10 cm", "20 pixels", etc.). To define the unit list, you can use one of the following attributes:

• "unitsList": an array containing the x elements used to define the available units (e.g.: "cm", "inches", "km", "miles", etc.). Use this attribute to define units within the object.
• "unitsListReference": a reference to a 4D list containing available units. Use this attribute to define units with a 4D list created with the New list command.
• "unitsListName": a name of a design-based 4D list that contains available units. Use this attribute to define units with a 4D list created in the Tool box.

Regardless of the way the unit list is defined, it can be associated with the following attribute:

• "unitReference": a single value that contains the index (from 1 to x) of the selected item in the "unitList", "unitsListReference" or "unitsListName" values list.

The current unit is displayed as a button that cycles through the "unitList", "unitsListReference" or "unitsListName" values each time it is clicked (e.g., "pixels" -> "rows" -> "cm" -> "pixels" -> etc.)

Example: We want to set up a numeric input followed by two possible units: "rows" or "pixels". The current value is "2" + "lines". We use values defined directly in the object ("unitsList" attribute):

If you want to add an ellipsis button [...] to a cell, you just need to pass the "alternateButton" with the True value in the object. The button will be displayed in the cell automatically.

When this button is clicked by a user, an On Alternate Click event will be generated, and you will be able to handle it however you want (see the "Event management" section below for more information).

Example:

The "color" valueType allows you to display either a color or a text.

• If the value is a number, a colored rectangle is drawn inside the cell. Example:
  
   C_OBJECT($ob4)
 OB SET($ob4;"valueType";"color")
 OB SET($ob4;"value";0x00FF0000)
  
  
• If the value is a text, then the text is displayed (e.g.: "value";"Automatic").

The "event" valueType displays a simple button that generates an On Clicked event when clicked. No data or value can be passed or returned.

Optionally, you can pass a "label" attribute. 

Example:

Several events can be handled while using an object list box array:

• On Data Change: An On Data Change event is triggered when any value has been modified either:
  
  • in a text input zone
  • in a drop-down list
  • in a combo box area
  • in a unit button (switch from value x to value x+1)
  • in a check box (switch between checked/unchecked)

• On Clicked: When the user clicks on a button installed using the "event" valueType attribute, an On Clicked event will be generated. This event is managed by the programmer.

• On Alternative Click: When the user clicks on an ellipsis button ("alternateButton" attribute), an On Alternative Click event will be generated. This event is managed by the programmer.

Compatibility note (4D v15): On Alternative Click is the new name of the On Arrow Click event that was available in previous versions of 4D. This event has been renamed since its scope has been extended.