This documentation is archived and is not being maintained.

ListControl Class

Serves as the abstract base class that defines the properties, methods, and events common for all list-type controls.

Namespace:  System.Web.UI.WebControls
Assembly:  System.Web (in System.Web.dll)

[AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal)]
public abstract class ListControl : DataBoundControl, 
	IEditableTextControl, ITextControl
<asp:ListControl />

An instance of the ListControl abstract class cannot be created directly. Instead, this class is inherited by other classes, such as the CheckBoxList, DropDownList, ListBox, and RadioButtonList classes, to provide common basic functionality.

The properties of the ListControl class allow you to specify the source of the data to populate the list control. Use the DataSource property to specify the data source to bind to the list control. If the data source contains more than one table, use the DataMember property to specify the table to use. You can bind different fields in the data source to the ListItem.Text and ListItem.Value properties of the items in the list control by setting the DataTextField and DataValueField properties, respectively. The text displayed for each item in the list control can by formatted by setting the DataTextFormatString property.

All items displayed in the list control are stored in the Items collection. You can programmatically specify or determine the index of a selected item in the list control by using the SelectedIndex property. The properties of the selected item can be accessed by using the SelectedItem property.

The ListControl class provides the SelectedIndexChanged event, which is raised when the selection in the list control changes between posts to the server. This allows you to provide a custom handler for this event. For more information about handling events, see Consuming Events.

The ListControl class implements the IEditableTextControl interface so that derived list-type controls can be used in the template mode of other controls.

The following code example demonstrates how to select items in a ListBox control. If the item is found in the text box, the item is selected and a message is displayed stating the name of the selected item. If the item is not found, no item is selected and a message is displayed stating that the item was not found.

Security noteSecurity Note:

This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.

<%@ Page Language="C#" AutoEventWireup="True" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
<html xmlns="" > 

<head runat="server">
    <title> ListControl SelectedValue Example </title>
<script runat="server">

      void Button_Click(Object sender, EventArgs e)

         // Perform this operation in a try-catch block in case the item is not found. 
            List.SelectedValue = ItemTextBox.Text;
            MessageLabel.Text = "You selected " + List.SelectedValue + ".";
         catch (Exception ex)
            List.SelectedValue = null;
            MessageLabel.Text = "Item not found in ListBox control.";





   <form id="form1" runat="server">

      <h3> ListControl SelectedValue Example </h3>

      <asp:ListBox ID="List"

         <asp:ListItem>Item 1</asp:ListItem>
         <asp:ListItem>Item 2</asp:ListItem>
         <asp:ListItem>Item 3</asp:ListItem>
         <asp:ListItem>Item 4</asp:ListItem>


      <hr />

      Enter the value of the item to select: <br />
      <asp:TextBox ID="ItemTextBox"
           Text="Item 1"


      <asp:Button ID="SelectButton"
           Text="Select Item"

      <br /><br />

      <asp:Label ID="MessageLabel"



Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0