Export (0) Print
Expand All

ListItem Class

Represents a data item in a data-bound list control. This class cannot be inherited.

System.Object
  System.Web.UI.WebControls.ListItem

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

[TypeConverterAttribute(typeof(ExpandableObjectConverter))]
public sealed class ListItem : IStateManager, 
	IParserAccessor, IAttributeAccessor

The ListItem type exposes the following members.

  NameDescription
Public methodListItem()Initializes a new instance of the ListItem class.
Public methodListItem(String)Initializes a new instance of the ListItem class with the specified text data.
Public methodListItem(String, String)Initializes a new instance of the ListItem class with the specified text and value data.
Public methodListItem(String, String, Boolean)Initializes a new instance of the ListItem class with the specified text, value, and enabled data.
Top

  NameDescription
Public propertyAttributesGets a collection of attribute name and value pairs for the ListItem that are not directly supported by the class.
Public propertyEnabledGets or sets a value indicating whether the list item is enabled.
Public propertySelectedGets or sets a value indicating whether the item is selected.
Public propertyTextGets or sets the text displayed in a list control for the item represented by the ListItem.
Public propertyValueGets or sets the value associated with the ListItem.
Top

  NameDescription
Public methodEqualsDetermines whether the specified object has the same value and text as the current list item. (Overrides Object.Equals(Object).)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodStatic memberFromStringCreates a ListItem from the specified text.
Public methodGetHashCodeServes as a hash function for a particular type, and is suitable for use in hashing algorithms and data structures like a hash table. (Overrides Object.GetHashCode().)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringReturns a string that represents the current object. (Overrides Object.ToString().)
Top

  NameDescription
Explicit interface implemetationPrivate methodIAttributeAccessor.GetAttributeInfrastructure. Returns the attribute value of the list item control having the specified attribute name.
Explicit interface implemetationPrivate methodIAttributeAccessor.SetAttributeInfrastructure. Sets an attribute of the list item control with the specified name and value.
Explicit interface implemetationPrivate methodIParserAccessor.AddParsedSubObjectInfrastructure. Allows the Text property to be persisted as inner content.
Explicit interface implemetationPrivate propertyIStateManager.IsTrackingViewStateInfrastructure. For a description of this member, see IStateManager.IsTrackingViewState.
Explicit interface implemetationPrivate methodIStateManager.LoadViewStateInfrastructure. For a description of this member, see IStateManager.LoadViewState.
Explicit interface implemetationPrivate methodIStateManager.SaveViewStateInfrastructure. For a description of this member, see IStateManager.SaveViewState.
Explicit interface implemetationPrivate methodIStateManager.TrackViewStateInfrastructure. For a description of this member, see IStateManager.TrackViewState.
Top

A ListItem control represents an individual data item within a data-bound list control, such as a ListBox or a RadioButtonList control.

There are several ways to specify the text displayed for an item in the list control. The most common method is by placing text in the inner HTML content. The inner HTML content is the text between the opening and closing tags of the ListItem control. You can also use the Text property to specify the text displayed in the list control for the item.

The Value property allows you to associate a value with the item in the list control, in addition to the text displayed in the control. For example, you can display text for an item in the list control, such as "Item 1", and use the Value property to specify a value for that item, such as "$1.99".

You can have any combination of the inner HTML content, Text, or Value properties set. The resulting HTML output for the ListItem control depends on the combination of these three properties that are set. For example, if all three properties are set as follows:

<asp:ListItem Value="Value 1" Text="Item 1">Inner 1</asp:ListItem>

The inner HTML content is used for rendered inner HTML content and the Value property is used for the Value attribute. The resulting HTML rendering output is:

<option value="Value 1">Inner 1</option>

The following table lists the combination of set properties and the corresponding property used for the rendered inner HTML content and Value attribute. The three columns on the left list the combination of set properties. The two columns on the right list which property value is used for the corresponding attribute.

Inner HTML content

Text property

Value property

Rendered Inner HTML content

Rendered Value attribute

Set

Set

Set

Inner HTML content

Value property

Set

Set

Not set

Inner HTML content

Inner HTML content

Set

Not set

Set

Inner HTML content

Value property

Set

Not set

Not set

Inner HTML content

Inner HTML text

Not set

Set

Set

Text property

Value property

Not set

Set

Not set

Text property

Text property

Not set

Not set

Set

Value property

Value property

Not set

Not set

Not set

Not set

Not set

NoteNote

Because the Text and Value properties each have a default value of an empty string, it is possible to have empty list items in the list control.

When a list control is displayed, any ListItem control with its Selected property set to true appears highlighted in the control.

The ListItem control provides the Enabled property to allow you to specify whether a ListItem control is enabled or disabled. A ListItem control that is disabled is dimmed to indicate that it cannot be selected. Use this property to disable a ListItem control in either a RadioButtonList control or a CheckBoxList control.

NoteNote

You cannot use this property to disable a ListItem control in a DropDownList control or ListBox control.

For a list of initial property values for an instance of ListItem, see the ListItem constructor.

Caution noteCaution

This control can be used to display user input, which might include malicious client script. Check any information that is sent from a client for executable script, SQL statements, or other code before displaying it in your application. You can use validation controls to verify user input before displaying the input text in a control. ASP.NET provides an input request validation feature to block script and HTML in user input. For more information, see Securing Standard ControlsHow to: Protect Against Script Exploits in a Web Application by Applying HTML Encoding to Strings, and Validating User Input in ASP.NET Web Pages.

TopicLocation
How to: Determine the Selection in List Web Server ControlsBuilding ASP .NET Web Applications
How to: Set Web Server Control Properties in CollectionsBuilding ASP .NET Web Applications
How to: Add Items in List Web Server ControlsBuilding ASP .NET Web Applications
How to: Determine the Selection in List Web Server ControlsBuilding ASP .NET Web Applications
How to: Set Web Server Control Properties in CollectionsBuilding ASP .NET Web Applications
How to: Add Items in List Web Server ControlsBuilding ASP .NET Web Applications
How to: Add Items in List Web Server Controls (Visual Studio)Building ASP .NET Web Applications in Visual Studio

The following example illustrates the use of ListItem controls within a ListBox control.

NoteNote

The following code samples use the single-file code model and may not work correctly if copied directly into a code-behind file. Each code sample must be copied into an empty text file that has an .aspx extension. For more information on the Web Forms code model, see ASP.NET Web Page Code Model.


<%@ 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 xmlns="http://www.w3.org/1999/xhtml" >
 <head>
    <title>ListBox Example</title>
<script language="C#" runat="server">

         void SubmitBtn_Click(Object Sender, EventArgs e) {
             if (ListBox1.SelectedIndex > -1) {
                 Label1.Text="You chose: " + ListBox1.SelectedItem.Text;
                 Label1.Text+="<br /> with value: " + ListBox1.SelectedItem.Value;
             }
         }

     </script>

 </head>
 <body>

     <h3>ListBox Example</h3>
     <br />

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

         <asp:ListBox id="ListBox1" Width="100px" runat="server">
             <asp:ListItem>Item 1</asp:ListItem>
             <asp:ListItem>Item 2</asp:ListItem>
             <asp:ListItem>Item 3</asp:ListItem>
             <asp:ListItem Value="Value 4">Item 4</asp:ListItem>
             <asp:ListItem Text="Item 5" Value="Value 5" Selected="True"/>
             <asp:ListItem>Item 6</asp:ListItem>
         </asp:ListBox>

         <asp:button Text="Submit" OnClick="SubmitBtn_Click" runat="server" />

         <br />

         <asp:Label id="Label1" font-names="Verdana" font-size="10pt" runat="server"/>

     </form>

 </body>
 </html>
          



<!-- This example demonstrates how to select multiple items from a DataList and add the 
selected items to a DataGrid. The example uses a foreach loop to iterate through 
the ListItem objects in the ListItemCollection of ListBox1. -->



...


<%@ Page language="c#" AutoEventWireup="true"%>
<%@ Import Namespace="System.Data" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script language="C#" runat="server">
            // Global Variables.
            private DataView dv;
            private DataTable dt = new DataTable();

            private void Page_Load(object sender, System.EventArgs e)
            {
                // Set the number of rows displayed in the ListBox to be
                // the number of items in the ListBoxCollection.
                ListBox1.Rows = ListBox1.Items.Count;

                // If the DataTable is already stored in the Web form's default
                // HttpSessionState variable, then don't recreate the DataTable.
                if (Session["data"] == null)
                {
                    // Add columns to the DataTable.
                    dt.Columns.Add(new DataColumn("Item"));
                    dt.Columns.Add(new DataColumn("Price"));
            // Store the DataTable in the Session variable so it can 
                    // be accessed again later.
                    Session["data"] = dt;

                    // Use the table to create a DataView, because the DataGrid
                    // can only bind to a data source that implements IEnumerable.
                    dv = new DataView(dt);

                    // Set the DataView as the data source, and bind it to the DataGrid.
                    DataGrid1.DataSource = dv;
                    DataGrid1.DataBind();
                }
            }

            private void addButton_Click(object sender, System.EventArgs e)
            {
                // Add the items selected in ListBox1 to DataGrid1.
                foreach (ListItem item in ListBox1.Items)
                {
                    if (item.Selected)
                    {
                        // Add the item to the DataGrid.
                        // First, get the DataTable from the Session variable.
                        dt = (DataTable)Session["data"];

                        if (dt != null)
                        { 
                            // Create a new DataRow in the DataTable.
                            DataRow dr = dt.NewRow();
                            // Add the item to the new DataRow.
                            dr["Item"] = item.Text;
                            // Add the item's value to the DataRow.
                            dr["Price"] = item.Value;
                            // Add the DataRow to the DataTable.
                            dt.Rows.Add(dr);

                            // Rebind the data to DataGrid1.
                            dv = new DataView(dt);
                            DataGrid1.DataSource = dv;
                            DataGrid1.DataBind();
                        }
                    }
                }
            }
        </script>
<html xmlns="http://www.w3.org/1999/xhtml" >
    <head>
    <title> ListItemCollection Example </title>
</head>

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

            <h3> ListItemCollection Example </h3>

            <table cellpadding="6" border="0">
                <tr>
                    <td valign="top">
                        <asp:ListBox id="ListBox1" runat="server" SelectionMode="Multiple">
                            <asp:ListItem Value=".89">apples</asp:ListItem>
                            <asp:ListItem Value=".49">bananas</asp:ListItem>
                            <asp:ListItem Value="2.99">cherries</asp:ListItem>
                            <asp:ListItem Value="1.49">grapes</asp:ListItem>
                            <asp:ListItem Value="2.00">mangos</asp:ListItem>
                            <asp:ListItem Value="1.09">oranges</asp:ListItem>
                        </asp:ListBox>
                    </td>

                    <td valign="top">
                        <asp:Button id="addButton" runat="server" Text="Add -->"
                            Width="100px" OnClick="addButton_Click"></asp:Button>
                    </td>

                    <td valign="top">
                        <asp:DataGrid Runat="server" ID="DataGrid1" CellPadding="4">
                        </asp:DataGrid>
                    </td>
                </tr>
            </table>        
        </form>
    </body>
</html>


.NET Framework

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

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

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

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

Community Additions

ADD
Show:
© 2014 Microsoft