ListControl Class (System.Web.UI.WebControls)

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Class Library

ListControl Class

Updated: November 2007

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)

Syntax

Visual Basic (Declaration)

<ControlValuePropertyAttribute("SelectedValue")> _
<AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
Public MustInherit Class ListControl _
    Inherits DataBoundControl _
    Implements IEditableTextControl, ITextControl

Visual Basic (Usage)

Dim instance As ListControl

[ControlValuePropertyAttribute("SelectedValue")]
[AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal)]
public abstract class ListControl : DataBoundControl, 
    IEditableTextControl, ITextControl

Visual C++

[ControlValuePropertyAttribute(L"SelectedValue")]
[AspNetHostingPermissionAttribute(SecurityAction::InheritanceDemand, Level = AspNetHostingPermissionLevel::Minimal)]
[AspNetHostingPermissionAttribute(SecurityAction::LinkDemand, Level = AspNetHostingPermissionLevel::Minimal)]
public ref class ListControl abstract : public DataBoundControl, 
    IEditableTextControl, ITextControl

/** @attribute ControlValuePropertyAttribute("SelectedValue") */
/** @attribute AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level = AspNetHostingPermissionLevel.Minimal) */
/** @attribute AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal) */
public abstract class ListControl extends DataBoundControl implements IEditableTextControl, 
    ITextControl

JScript

public abstract class ListControl extends DataBoundControl implements IEditableTextControl, ITextControl

ASP.NET

<asp:ListControl />

Remarks

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.

Examples

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 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.

Visual Basic

<%@ Page Language="VB" AutoEventWireup="True" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html  > 

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

      Sub Button_Click(sender As Object, e As EventArgs)

         ' Perform this operation in a try-catch block in case the item is not found.
         Try

            List.SelectedValue = ItemTextBox.Text
            MessageLabel.Text = "You selected " & List.SelectedValue + "."

         Catch ex As Exception

            List.SelectedValue = Nothing         
            MessageLabel.Text = "Item not found in ListBox control."

         End Try

      End Sub

   </script>

</head>

<body>

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

      <h3> ListControl SelectedValue Example </h3>

      <asp:ListBox ID="List"
           runat="server">

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

      </asp:ListBox>

      <hr />

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

      &nbsp;&nbsp;

      <asp:Button ID="SelectButton"
           Text="Select Item"
           OnClick="Button_Click"
           runat="server"/>

      <br /><br />

      <asp:Label ID="MessageLabel"
           runat="server"/>     

   </form>

</body>
</html>

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html  > 

<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.
         try
         {
            List.SelectedValue = ItemTextBox.Text;
            MessageLabel.Text = "You selected " + List.SelectedValue + ".";
         }
         catch (Exception ex)
         {
            List.SelectedValue = null;
            MessageLabel.Text = "Item not found in ListBox control.";
         }

      }

   </script>

</head>

<body>

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

      <h3> ListControl SelectedValue Example </h3>

      <asp:ListBox ID="List"
           runat="server">

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

      </asp:ListBox>

      <hr />

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

      &nbsp;&nbsp;

      <asp:Button ID="SelectButton"
           Text="Select Item"
           OnClick="Button_Click"
           runat="server"/>

      <br /><br />

      <asp:Label ID="MessageLabel"
           runat="server"/>     

   </form>

</body>
</html>

Permissions

AspNetHostingPermission
for operating in a hosted environment. Demand value: LinkDemand; Permission value: Minimal.
AspNetHostingPermission
for operating in a hosted environment. Demand value: InheritanceDemand; Permission value: Minimal.

Inheritance Hierarchy

Thread Safety

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

Platforms

Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, 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.

Version Information