Component library

ListBox

Version:

A ListBox control shows a list of items. If you bind the ListBox control to a SearchDataSource component, it displays all the items that the search retrieves.

You can specify that the ListBox control uses the name of a different field of the items than the default display name, but you must keep the following in mind: If an item does not contain the field that you specify, there is no “fall-back” mechanism, and the ListBox control displays such an item as an empty string.

Users can select items in the list, and you can specify that users can make multiple selections. The ListBox control returns the values of the selected items in the SelectedValue or SelectedValues members. If you have enabled multiple selections, SelectedValues contains a comma-separated list of values, while SelectedValue contains the value of the first (top) item the user has selected.

You can set properties of a ListBox control programmatically in different ways. We recommend you use the rebind function. It has this syntax:

rebind (items, selectedItem, selectedValue, displayFieldName, valueFieldName, selectedItems, selectedValues)

If you set two or more properties out of selectedItem, selectedValue, selectedItems and selectedValues, the order or precedence is: selectedItems > selectedValues > selectedItem > selectedValue.

Properties

Name	Description	Default
Appearance
WidthPolicy	Specify how SPEAK interprets the width of the control. You can specify: Default: the default width of the control is used. BlockLevel: the width is set relative to the width of the container. The control fills the container horizontally.	Default
Data
DisplayFieldName	Specify the name of a field to display instead of the default.
Items	Bind the control to the items that it displays.
Multiple	If true, users can select more than one item in the list at the same time.	False
SelectedItem	Get or set the selected item.	None
SelectedItems	Get or set the selected items as a comma-separated list.	None
SelectedValue	Get or set the selected item by value (ID).	None
SelectedValues	Get or set the selected items by value (ID) as a comma-separated list.	None
ValueFieldName	Specify the data field that the ListBox control uses as the option value (and returns as selectedValue(s)).	ID of the item.

Configuration

You can create a configuration item for a ListBox control by creating an item based on the ListBox Parameters template.

The configuration item has these specific fields:

Database

It inherits these fields:

IsVisible
AccessKey
Tooltip
Behaviors
Id

If you have suggestions for improving this article, let us know!