List Box Object

Array list boxes

In an array list box, each column must be associated with a one-dimensional 4D array; all array types can be used, with the exception of pointer arrays. The number of rows is based on the number of array elements.

By default, 4D assigns the name "ColumnX" to each column. You can change it, as well as other column properties, in the column properties. The display format for each column can also be defined using the OBJECT SET FORMAT command.

Array type list boxes can be displayed in hierarchical mode, with specific mechanisms.

With array type list box, the values entered or displayed are managed using the 4D language. You can also associate a choice list with a column in order to control data entry. The values of columns are managed using high-level List box commands (such as LISTBOX INSERT ROWS or LISTBOX DELETE ROWS) as well as array manipulation commands. For example, to initialize the contents of a column, you can use the following instruction:

ARRAY TEXT(varCol;size)

You can also use a list:

LIST TO ARRAY("ListName";varCol)

Warning: When a list box contains several columns of different sizes, only the number of items of the smallest array (column) will be displayed. You should make sure that each array has the same number of elements as the others. Also, if a list box column is empty (this occurs when the associated array was not correctly declared or sized using the language), the list box displays nothing.

Selection list boxes

In this type of list box, each column can be associated with a field (for example [Employees]LastName) or an expression. The expression can be based on one or more fields (for example, [Employees]FirstName+" "[Employees]LastName) or it may simply be a formula (for example String(Milliseconds)). The expression can also be a project method, a variable or an array item. You can use the LISTBOX SET COLUMN FORMULA and LISTBOX INSERT COLUMN FORMULA commands to modify columns programmatically.

The contents of each row is then evaluated according to a selection of records: the current selection of a table or a named selection.

In the case of a list box based on the current selection of a table, any modification done from the database side is automatically reflected in the list box, and vice versa. The current selection is therefore always the same in both places.

Collection or Entity selection list boxes

In this type of list box, each column must be associated to an expression. The contents of each row is then evaluated per collection element or per entity of the entity selection.

Each element of the collection or each entity is available as an object that can be accessed through the This keyword. A column expression can be a property path, a project method, a variable, or any formula, accessing each entity or collection element object through This, for example This.<propertyPath> (or This.value in case of a collection of scalar values). You can use the LISTBOX SET COLUMN FORMULA and LISTBOX INSERT COLUMN FORMULA commands to modify columns programmatically.

When the data source is an entity selection, any modifications made on the list box side are automatically saved in the database. On the other hand, modifications made on the database side are visible in the list box after touched entities have been reloaded.

note

When entities are deleted, their references remain in the entity selection with an undefined value, thus displaying blank rows in the list box. In this case, you can call the .clean() function to get a new entity selection but without the deleted entity references.

When the data source is a collection, any modifications made in the list box values are reflected in the collection. On the other hand, if modifications are done on the collection using for example the various functions of the Collection class, you will need to explicitely notify 4D by reassigning the collection variable to itself, so that the list box contents is refreshed. For example:

myCol:=myCol.push("new value") //display new value in list box

Supported Properties

Supported properties depend on the list box type.

Property	Array list box	Selection list box	Collection or Entity Selection list box
Alternate Background Color	X	X	X
Background Color	X	X	X
Bold	X	X	X
Background Color Expression		X	X
Border Line Style	X	X	X
Bottom	X	X	X
Class	X	X	X
Collection or entity selection		X	X
Column Auto-Resizing	X	X	X
Current item			X
Current item position			X
Data Source	X	X	X
Detail Form Name		X
Display Headers	X	X	X
Display Footers	X	X	X
Double-click on row		X
Draggable	X	X	X
Droppable	X	X	X
Focusable	X	X	X
Font	X	X	X
Font Color	X	X	X
Font Color Expression		X	X
Font Size	X	X	X
Height (list box)	X	X	X
Height (headers)	X	X	X
Height (footers)	X	X	X
Hide extra blank rows	X	X	X
Hide focus rectangle	X	X	X
Hide selection highlight	X	X	X
Hierarchical List Box	X
Highlight Set		X
Horizontal Alignment	X	X	X
Horizontal Line Color	X	X	X
Horizontal Padding	X	X	X
Horizontal Scroll Bar	X	X	X
Horizontal Sizing	X	X	X
Italic	X	X	X
Left	X	X	X
Master Table		X
Meta info expression			X
Method	X	X	X
Movable Rows	X
Named Selection		X
Number of Columns	X	X	X
Number of Locked Columns	X	X	X
Number of Static Columns	X	X	X
Object Name	X	X	X
Right	X	X	X
Row Background Color Array	X
Row Control Array	X
Row Font Color Array	X
Row Height	X
Row Height Array	X
Row Style Array	X
Selected Items			X
Selection Mode	X	X	X
Single-Click Edit	X	X	X
Sortable	X	X	X
Standard action	X
Style Expression		X	X
Top	X	X	X
Transparent	X	X	X
Type	X	X	X
Underline	X	X	X
Variable or Expression	X	X
Vertical Alignment	X	X	X
Vertical Line Color	X	X	X
Vertical Padding	X	X	X
Vertical Scroll Bar	X	X	X
Vertical Sizing	X	X	X
Visibility	X	X	X
Width	X	X	X

List box columns, headers and footers support specific properties.

Supported Form Events

Form event	Additional Properties Returned (see Form event for main properties)	Comments
On After Edit	column columnName row
On After Keystroke	column columnName row
On After Sort	column columnName headerName	Compound formulas cannot be sorted. (e.g., This.firstName + This.lastName)
On Alternative Click	column columnName row	Arrays list boxes only
On Before Data Entry	column columnName row
On Before Keystroke	column columnName row
On Begin Drag Over	column columnName row
On Clicked	column columnName row
On Close Detail	row	Current Selection & Named Selection list boxes only
On Collapse	column columnName row	Hierarchical list box only
On Column Moved	columnName newPosition oldPosition
On Column Resize	column columnName newSize oldSize
On Data Change	column columnName row
On Delete Action	row
On Display Detail	isRowSelected row
On Double Clicked	column columnName row
On Drag Over	area areaName column columnName row
On Drop	column columnName row
On Expand	column columnName row	Hierarchical list box only
On Footer Click	column columnName footerName	Arrays, Current Selection & Named Selection list boxes only
On Getting Focus	column columnName row	Additional properties returned only when editing a cell
On Header Click	column columnName headerName
On Load
On Losing Focus	column columnName row	Additional properties returned only when editing a cell has been completed
On Mouse Enter	area areaName column columnName row
On Mouse Leave
On Mouse Move	area areaName column columnName row
On Open Detail	row	Current Selection & Named Selection list boxes only
On Row Moved	newPosition oldPosition	Arrays list boxes only
On Selection Change
On Scroll	horizontalScroll verticalScroll
On Unload

Additional Properties

Form events on list box or list box column objects may return the following additional properties:

Property	Type	Description
area	text	List box object area ("header", "footer", "cell")
areaName	text	Name of the area
column	longint	Column number
columnName	text	Name of the column
footerName	text	Name of the footer
headerName	text	Name of the header
horizontalScroll	longint	Positive if scroll is towards the right, negative if towards the left
isRowSelected	boolean	True if row is selected, else False
newPosition	longint	New position of the column or row
newSize	longint	New size (in pixels) of the column or row
oldPosition	longint	Previous position of the column or row
oldSize	longint	Previous size (in pixels) of the column or row
row	longint	Row number
verticalScroll	longint	Positive if scroll is towards the bottom, negative if towards the top

If an event occurs on a "fake" column or row that doesn't exist, an empty string is typically returned.