List Property - ListBox
Gets or sets the items in the list portion of a list box.
object.List(index) = [string]
Where object is an object expression that evaluates to one of the controls in the Applies To list, and string can be either a literal string array, an SQL query or an expression, depending on how this property is being set.
Client support
Newlook Smartclient
Newlook Server
Setting an initial list
The easiest way of specifying the control's list is to set the List property within Designer. This can be done by entering a literal string or an expression which will be evaluated at run-time.
The list item string may be an array of value and descriptions, or values only. Each individual list item must be separated by a semi-colon (i.e. Item1;Item2;Item3;).
|
List with values and descriptions If you wish to display both values and descriptions in
the drop down list then the string must include the value and description
separated by an equals (=) character. For
example: The value and the description will then be shown in separate columns in the list. When an item is selected in a Combo box, the value is entered into the Text box portion of the control. |
|
List with values only If you wish to display only a list of values, without a
description, then the string will consist of semi-colon delimited values.
For example: The values will be displayed in the drop down list. |
The list property may also be an expression by preceding the string with an equals (=) sign. The expression will be evaluated when the form is initialized at run-time, and the property set to the result of the evaluation.
|
As an example, let's assume the following SetValue macro is called on startup: SetValue (WeekdaysList,"M=Mon;T=Tues;W=Wed;Th=Thurs;F=Fri") To populate our combo box control with the weekdays list above we would set the List property to: =WeekdaysList |
TIP:
To add a list option that contains a Newlook reserved character (for instance the '=' character) the entire string must be enclosed in quotation marks. Let's look at an example. If you wanted to display 1 Name = 'XX' as one of the list items (where 1 is the value and Name = 'XX' is the description) then you would specify the option as 1="Name = 'XX'";.
Appending items to a list at run-time
At run-time, the list property is converted into an array. Individual items in the list array can be accessed via their index or alternatively, the full list string can be returned or set.
It is also possible to dynamically append item to the control's initial list using the Macro Editor, by using a SetValue action to set the List with an index of -1.
For example, the following macro will append the item G4 to the existing list:
SetValue (App.ActiveForm.lboOptions.List(-1), "G4")
To dynamically add an item to the list using the Script Editor, use the AddItem method. Using this method gives you more flexibility over the position of the added item.
TIP:
Regardless of the method used to append an item to the list, if the Sorted
property for the control is set to True, then the item will be
inserted in alphabetical order within the list and its index will be set according to its corresponding position in the list. If the Sorted property
is set to False and you are using the SetValue action in the Macro Editor, then the item will be appended to the end of the
list and its index will be the next available index. If you are using the AddItem method the index will be the one specified in the Index argument. The index of any new item can be determined via the NewIndex
property of the control.
Removing items from the list at run-time
To dynamically remove an item from the list using the Macro Editor, use the SetValue action to set the nth item to Null.
For example, the following macro will remove the 2nd item from the list (the list array uses a zero-based index):
SetValue (App.ActiveForm.lboOptions.List(1), Null)
To dynamically remove an item from the list using the Script Editor, use the RemoveItem method. Any subsequent items will be re-indexed.
Clearing the list at run-time
To clear the list property using the Macro Editor, use the SetValue action to set it to an empty string.
For example, the following macro will clear the list completely:
SetValue (App.ActiveForm.lboOptions.List, "")
To clear the list using the Script Editor, use the Clear method.
TIP!
If you have set the List property of an automatically generated combo box to an empty string and you want to get the host generated list back, position your cursor in the List property and click the default (
) button.
Setting item data
The ItemData property is an array of items that correspond to the List array. It can be used to store an additional field for each List array item. The most common way of using this property is to store the value (an employee ID for example) in the ItemData array and the related description (such as employee name) in the List array. By separating them into the ItemData and List arrays respectively you can restrict the display to the description only (in this case the Employee names) and have more control over both values. A List item's corresponding ItemData element can be returned by specifying its index. The ListIndex property is used to determine a selected item's index - this index can then be used to determine the appropriate ItemData element to return. Any re-indexing of the control's list array items will result in a synchronized re-indexing of the item data array, for example, setting the Sorted property to True will result in the List property array being re-indexed to the correct sort order. The ItemData array will be re-indexed so that corresponding values in the two properties have the same index.
See Also
IntegralHeight property | ItemData property | ListCount property | ListIndex property | NewIndex property | Sorted property
Applies To
© 2004-2021 looksoftware. All rights reserved.