ListBox Web Server Control Overview

Article
12/04/2014

The ListBox Web server control enables users to select one or more items from a predefined list.

This topic contains:

Scenarios
Features
Background
Code Examples
Class Reference

Scenarios

Use the ListBox Web server control when you want to display multiple items at once and to enable users to select one or more items from a predefined list. The ListBox control differs from a DropDownList control in that it can display multiple items at once and that it optionally enables the user to select multiple items.

Features

You can use the ListBox control to:

Set the control to display a specific number of items.
Set the size of the control in pixels.
Use data-binding to specify the list of items to display.
Determine which item or items are selected.
Specify the selected item or items programmatically.

Background

The ListBox control is typically used to display more than one item at once. You can control the look of the list in these ways:

Number of rows displayed. You can set the control to display a specific number of items. If the control contains more items than that, it displays a vertical scroll bar.
Height and width. You can set the size of the control using pixels. In that case, the control ignores the number of rows you have set and displays as many as will fit into the height of the control. Some browsers do not support setting the height and width in pixels and will use the row count setting.

As with other Web server controls, you can use style objects to specify the appearance of the control. For details, see ASP.NET Web Server Controls and CSS Styles.

List Items

The ListBox control is a container for one or more list items. Each list item is an object of type ListItem with its own properties. These properties are described in the following table.

Property	Description
Text	Specifies the text that is displayed in the list.
Value	Contains the value that is associated with an item. Setting this property enables you to associate a value with a specific item without displaying it. For example, you can set the Text property to the name of a color and the Value property to its hexadecimal representation.
Selected	Indicates whether the item is currently selected.

To work with items programmatically, you work with the Items collection of the ListBox control. The Items collection is a standard collection, and you can add item objects to it, delete items, clear the collection, and so on.

The currently selected item is available in the ListBox control's SelectedItem property. If the control is set to single-selection mode, this property returns the one selected item. If the control is set to multi-selection mode, you get the selected items by looping through the entire Items collection and examining the Selected property of each item.

Single versus Multiple Selection

Users can normally select a single item in the list by clicking it. If you set the ListBox control to enable multiple selections, users can hold down the CTRL or SHIFT key while clicking to select multiple items.

Binding Data to the Control

You can use a ListBox Web server control to list options that are made available to the page using a data source control. Each item in the ListBox control corresponds to an item in the data source, typically an individual data record.

The control displays one field from the source. Optionally, you can bind the control to a second field to set the value of an item, which is not displayed.

As with other server controls, you can bind any control properties, such as the color or size of the control, to data. For details, see How to: Populate List Web Server Controls from a Data Source.

ListBox Events

The ListBox control raises the SelectedIndexChanged event when users select an item. By default, this event does not cause the page to be posted to the server, but you can cause the control to force an immediate postback by setting the AutoPostBack property to true.

Note

The auto-postback capability requires that the browser support ECMAScript (JScript, or JavaScript) and that scripting be enabled on the user's browser.