List Property - ComboBox control
Gets or sets the collection of list items to display in the drop down list of a combo box control.
object.List(index) as [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
How is a combo box list derived?
A combo box's drop down list is generated from the control's underlying list array at runtime. This array is derived in the following way (see sub-sections below this list for more detail):
- Any identified field choice values (or value-description pairs) for the host field become the default items in the List property for the control. Note that this is not applicable in the case of inserted controls as there is no underlying host field.)
- The contents of the List property are evaluated (this can include a literal string array, SQL query or an expression that modifies or replaces existing the items in the default list array)
- The initial value of the Text property is added to the list array (this ensures that the current value of the control is added to the drop down list if it is not already present in the list array).
- Any macro or script that dynamically modifies the list array at runtime is applied (this can include a macro or script that completely resets the list by assigning a value to the List property or logic that modifies the list array)
It's important to note that the value in the List property at design-time may not be the same as the drop down's physical list at runtime.
Identified field choice values
When a combo box is automatically generated from a host field, the control's underlying list array is populated with an array of values that have been recognized as valid field choice values (or field choice values and field choice description pairs) for the field. This array becomes the default List property.
In the examples below, the host entry field is followed by a series of characters that the recognition engine has recognized as valid field choice values for this field. These values will automatically become the default list items for the generated combo box. The List property will be populated with a semi-colon delimited string array containing the four recognized field choice values.
|
g |
|
List Property = ;I;A;R |
In the case of inserted combo box controls, the default list array is empty and must be set, at either design-time or run-time.
Setting the List property
If the combo box control is generated from a host field, then the List property will default to an array of identified field choice values, however it is possible to override this default array by replacing the List property with a different literal string array, SQL query or an expression that evaluations to a literal string array. It is also possible to append items to the default list by using an append expression (see example below).
TIP!
If you have modified the List property of an host-generated combo box and you want to get the default list back, position your cursor in the List property and click the default (
) button.
If the combo box is an inserted control, then the List property can be set either at design-time or at run-time.
Specifying a literal string array in the List property
The simplest method of setting the List property is to enter a literal string array, or an expression which evaluates to a string array at run-time.
The string can be a semi-colon delimited array of either values and descriptions, or values only.
|
List with values and descriptions If you wish to display a custom list containing both values and descriptions in
the drop down 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 from the combo box drop down, the selected value is entered into the text box portion of the control and becomes the current Text property of the control. |
|
List with values only If you wish to display only a list of values, without
descriptions, then the string will consist of semi-colon delimited values.
For example: The values will be displayed in a single column in the drop down list. |
TIP:
To include a list option that contains a Newlook reserved character (for instance the '=' character) the entire string must be enclosed in quotation marks. For 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'".
To set this property via an expression in Designer, you will need to precede the List property string with an equals (=) sign. The expression will be evaluated when the form is initialized, and the property set to the result of the evaluation.
|
List generated from an expression To set the List property via an expression, use the following syntax =<variable> where variable is a Newlook variable containing a semi-colon delimited string array of items that you wish to populate the List property with at run-time. In the example on the left, the following macro has been called at startup (the macro sets the variable WeekdaysList to a string array of weekday values and descriptions): SetValue (WeekdaysList,"M=Mon;T=Tues;W=Wed;Th=Thurs;F=Fri") To populate the combo box's list with the contents of WeekdaysList the List property of the control would be set to |
Appending items to the default list via using an expression in the List property
It is possible to append items to the default list array (irrespective of whether it is blank or has been automatically generated from host field choice values) by setting the List property to an expression that is preceded with a plus (+) sign.
|
Appending items to an automatically generated list. To append an item to a combo box's generated list array, use the following syntax in the List property: +<variable> where variable is a Newlook variable containing a semi-colon delimited string array of items that you wish to append to the list at run-time. In the example on the left, the values to the right of the entry field represent the recognized field choice values for the field. The items "T" and "B" have been added to the list by initializing the variable |
Specifying an SQL query in the List property
If you have Openlook installed on your IBM i, it is possible to use the SQL builder (
) to return the results of a query on a host file to the control's List property. This tool calls a web service provided by Openlook which allows you to run an SQL query on your host file which will return the results as an expression to the List property. While the SQL builder only returns basic SELECT statements, it is possible to modify the resulting expression in the list property to add additional clauses to your query. For example, the values in the example below will return the expression =SQL("HOST", "SELECT * FROM LOOKOADEMO/STOCKLVL") to the List property.
While it is possible to include all columns in your SQL statement, only the first two columns of the returned data source will be used in the list. If these columns are not the columns of data you want to display in your list, you will need to explicitly select the columns you wish to return, in the desired order.
The contents of the Text property
If the control's Text value is not one of the items in the list array, it will be added to the array. This is particularly relevant for host generated fields where any value that is sent through from the host will be automatically added to the control's list array, even if it has not been identified as a valid field choice value by the recognition engine.
BE AWARE THAT:
If you have manually overridden the Text property in Designer, then the overridden value will display in the text portion of the control and added to the list array rather than any value sent through from the host.
BE AWARE THAT:
If a control is bound to a data source via the DataField and DataSource properties then any value specified in the Text property at Design-time will be ignored.
Dynamically modifying the list at run-time
At run-time, individual items in the list array can be accessed via their index and the total count (of items in the array) is available via the ListCount property. It is possible to modify the final list array at run-time via a script or macro.
Appending items to the list
Using a Script
To dynamically add an item to the list using a script, use the AddItem method. Using this method gives you more flexibility over the position of the added item as its index can be specified.
For example, the following Jscript will append the item G4 to the top of the existing list:
App.Activeform.cbComboBox.AddItem ("G4",0);
Using a Macro
To dynamically add an item to the list at runtime using a macro, use a SetValue action to set the List property with an index of -1.
For example, the following macro will append the item G4 to the existing list:
SetValue (App.ActiveForm.cbComboBox.List(-1), "G4")
TIP:
With either method, 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
Using a Script
To dynamically remove an item from the list using a script, use the RemoveItem method. Any subsequent items will be re-indexed.
For example, the following Jscript will remove the item with an index of 0 in the existing list:
App.Activeform.cbComboBox.RemoveItem (0);
Using a Macro
To dynamically remove an item from the list using a macro, 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.cbComboBox.List(1), Null)
Recreating the list at run-time
Using a Script
To dynamically recreate the list at run-time using a script, assign the List property a literal string array.
For example, the following Jscript will replace any existing list array with the new array of A, B, C:
App.Activeform.cbComboBox.List = "A;B;C";
Using a Macro
To dynamically recreate the list at run-time using a macro, use the SetValue action to set the List property to a literal string array.
For example, the following macro will replace any existing list array with the new array of A, B, C:
SetValue (App.ActiveForm.cbComboBox.List, "A;B;C")
Clearing the list at run-time
Using a Script
To dynamically clear the list using a script, use the Clear method.
For example, the following script will clear all items from the existing list:
App.Activeform.cbComboBox.Clear;
Using a Macro
To dynamically clear the list at runtime using a macro, use the SetValue action to set the List property to an empty string.
For example, the following macro will clear the list completely:
SetValue (App.ActiveForm.cbComboBox.List, "")
See Also
ItemData property | ListCount property | ListIndex property | NewIndex property | Sorted property | ListIndex property | ShowDropDownListValues property
Applies To
© 2004-2021 looksoftware. All rights reserved.