dlgListView

Function

Defines a multi column list view selection field.

Syntax

dlgListView(string Headers, string array[], int &Selected[, int &Sort]) [ statement ]

Description

The dlgListView statement defines a multi column list view selection field with the contents of the given array.

Headers is the tab separated list of column headers.

Selected reflects the index of the selected list view entry in the array (the sequence in which the entries are actually displayed may be different, because the contents of a dlgListView can be sorted by the various columns). The first entry has index 0.
If no particular entry shall be initially selected, Selected should be initialized to -1.

Sort defines which column should be used to sort the list view. The leftmost column is numbered 1. The sign of this parameter defines the direction in which to sort (positive values sort in ascending order). If Sort is 0 or outside the valid number of columns, no sorting will be done. The returned value of Sort reflects the column and sort mode selected by the user by clicking on the list column headers. By default dlgListView sorts by the first column, in ascending order.

Each element of array defines the contents of one line in the list view, and must contain tab separated values. If there are fewer values in an element of array than there are entries in the Headers string the remaining fields will be empty. If there are more values in an element of array than there are entries in the Headers string the superfluous elements will be silently dropped. None of the strings in array may be empty (if there is an empty string, all strings after and including that one will be dropped).

The optional statement is executed whenever the user double clicks on an entry of the dlgListView.
Before the statement is executed, all variables that have been used with dialog objects are updated to their current values, and any changes made to these variables inside the statement will be reflected in the dialog when the statement returns.

If the initial value of Selected is outside the range of the array indexes, no entry will be selected.

If Headers is an empty string, the first element of the array is used as the header string. Consequently the index of the first entry is then 1.

The contents of a dlgListView can be sorted by any column by clicking on that column's header. Columns can also be swapped by "click&dragging" a column header. Note that none of these changes will have any effect on the contents of the array. If the contents shall be sorted alphanumerically a numeric string[] array can be used.

Example

string Colors[] = { "red\tThe color RED", "green\tThe color GREEN", "blue\tThe color BLUE" };
int Selected = 0; // initially selects "red"
dlgListView("Name\tDescription", Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);