Management of List box objects

version 2004.2 (Modified)

The commands of this theme are dedicated to handling form objects of the List box type.

List boxes are comparable to Grouped Scrollable Areas. A list box provides all the functions of grouped scrollable areas, notably the ability to represent data in the form of columns and selectable rows. However, the list box does even more than that, including the ability to enter values, sort columns, define alternating colors, etc.

You can set up a List box completely in the 4th Dimension Form editor and can also manage it through programming. For more information on creating and setting List boxes in the Form editor as well as on their use, refer to the Design Reference manual of the 4th Dimension documentation.

Programming List box objects is done in the same way as other 4th Dimension list form objects. However, specific rules must be followed, as detailed in this section.

Note: List box objects are designed for screen interfaces only. They cannot be printed.

A list box can contain one or more columns. Each column must be associated with a one-dimensional 4th Dimension array; all array types can be used, with the exception of pointer arrays. The display format for each column can be defined in the Form editor or by using the SET FORMAT command.

Using the language, the values of columns (data entry and display) are managed using high-level List box commands (such as INSERT LISTBOX ROW or DELETE LISTBOX ROW) as well as array manipulation commands.

For example, to initialize the contents of a column, you can use the following instruction:

   ARRAY TEXT(ColumnName; size)

You can also use a list:

   LIST TO ARRAY("ListName"; ColumnName)

Note: When a List box object contains several columns, each related array must have the same size (same number of items) as the others, otherwise only the number of items of the smallest array will be displayed.

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.

A List box object is composed of three separate items:

• the object itself,

• the columns,

• and the column headers.

These items can be selected individually in the Form editor. Each one has its own object and variable name and can be handled separately.

By default, columns are named Column1 to X and headers are named Header1 to X in the form, independently of the list box objects.

Each item type contains individual and shared characteristics with other items. For example, character fonts can be globally assigned to the list box object or separately to columns and headers. On the other hand, entry properties can only be defined for columns.

These rules apply to the "Object properties" theme commands that can be used with list boxes. Depending on its functionality, each command can be used with the list box, columns and/or column headers. To set the type of item on which you want to work, simply pass the name or the variable associated with it.

The following table details the scope of each command of the "Object properties" theme that can be used with list boxes:

Notes:

• All the commands of the "List Box" theme apply only to List box objects, except for the SET LISTBOX COLUMN WIDTH command (applies to object, column and header) and Get listbox column width command (applies to column and header only).

• Only the color of the text of column headers can be modified using the SET COLOR and SET RGB COLORS commands.

It is possible to add an object method to the list box object and/or to each column of the list box. Object methods are called in the following order:

1. Object method of each column

2. Object method of the list box

The column object method gets events that occur in its header.

When the SET VISIBLE command is used with a header, it is used on all List box object headers, regardless of the header set in the command. For example, the SET VISIBLE(*;"header3";False) instruction will hide all headers in the List box object to which header3 belongs and not simply this header.

The Self function ("Language" theme) can be used in the object method of a list box or a list box column. In both cases, it returns a pointer to the column variable or the header variable depending on where the click occurred.

The Focus object function ("User Interface" theme) returns a pointer to the column of the list box with the focus (i.e. to an array). The 4th Dimension pointer mechanism allows you to see the item number of the modified array. For example, supposing a user modified the 5th line of the column col2:

   $Column:=Focus object
      ` $Column contains a pointer to col2
   $Row:= $Column->   `$Row equals 5

The SCROLL LINES command ("User Interface" theme) can be used with a list box. It scrolls the list box rows so that the first selected row or a specified row is displayed.

The EDIT ITEM command ("Entry Control" theme) allows you to pass a cell of a list box object into edit mode.

Specific form events are intended to facilitate list box management, in particular concerning drag and drop and sort operations. For more information, refer to the description of the Form event command.

By default, the list box automatically handles standard column sorts when the header is clicked. A standard sort is an alphanumeric sort of column values, alternately ascending/descending with each successive click. All columns are always synchronized automatically.

You can forbid standard user sorts by deselecting the "Sortable" property of the list box.

The developer can set up custom sorts using the SORT LISTBOX COLUMNS command and/or combining the On Header Click and On After Sort form events (see the Form event command) and array management 4D commands.

Note: The "Sortable" column property only affects the standard user sorts; the SORT LISTBOX COLUMNS command does not take this property into account.

The value of the variable related to the column header allows you to manage additional information: the current sort of the column (read) and the display of the sort arrow.

• If the variable is set to 0, the column is not sorted and the sort arrow is not displayed;

• If the variable is set to 1, the column is sorted in ascending order and the sort arrow is displayed;

• If the variable is set to 2, the column is sorted in descending order and the sort arrow is displayed.

You can set the value of the variable (for example, Header2:=2) in order to "force" the sort arrow display. The column sort itself is not modified in this case; it is up to the developer to handle it.

The SELECT LISTBOX ROW command can be used to select one or more rows of the list box by programming.

The variable linked to the List box object is used to get, set or store selections of object rows.

This variable corresponds to a Boolean array that is automatically created and maintained by 4th Dimension. The size of this array is determined by the size of the list box: it contains the same number of elements as the smallest array linked to the columns.

Each element of this array contains True if the corresponding line is selected and False otherwise. 4th Dimension updates the contents of this array depending on user actions. Inversely, you can change the value of array elements to change the selection in the list box.

On the other hand, you can neither insert nor delete rows in this array; you cannot retype rows either.

Note: The Count in array command can be used to find out the number of selected lines.

For example, this method allows inverting the selection of the first row of the list box:

   ARRAY BOOLEAN(tBListBox;10)
      ` tBListBox is the name of the list box variable in the form
   If (tBListBox{1} = True)
      tBListBox{1}:= False
   Else
      tBListBox{1}:= True
   End if