Export (0) Print
Expand All

ListItem Class

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

For a list of all members of this type, see ListItem Members.

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

[Visual Basic]
NotInheritable Public Class ListItem
   Implements IStateManager, IParserAccessor, IAttributeAccessor
[C#]
public sealed class ListItem : IStateManager, IParserAccessor,
   IAttributeAccessor
[C++]
public __gc __sealed class ListItem : public IStateManager,
   IParserAccessor, IAttributeAccessor
[JScript]
public class ListItem implements IStateManager, IParserAccessor,
   IAttributeAccessor

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.

Remarks

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
Note   Since the Text and Value properties 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.

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

Example

[Visual Basic, C#, JScript] The following example illustrates the use of ListItem controls within a ListBox control.

[Visual Basic] 
<%@ Page Language="VB" AutoEventWireup="True" %>
<html>
 <head>
 
     <script language="VB" runat="server">
 
         Sub SubmitBtn_Click(Sender As Object, e As EventArgs)
             If ListBox1.SelectedIndex > -1 Then
                 Label1.Text = "You chose: " & ListBox1.SelectedItem.Text
                 Label1.Text &= "<br> with value: " & ListBox1.SelectedItem.Value
             End If
         End Sub
 
     </script>
 
 </head>
 <body>
 
     <h3>ListBox Example</h3>
     <p>
 
     <form 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" />
         
         <p>
         
         <asp:Label id=Label1 font-name="Verdana" font-size="10pt" runat="server"/>
         
     </form>
 
 </body>
 </html>
          

[C#] 
<%@ Page Language="C#" AutoEventWireup="True" %>
<html>
 <head>
 
     <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>
     <p>
 
     <form 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" />
         
         <p>
         
         <asp:Label id=Label1 font-name="Verdana" font-size="10pt" runat="server"/>
         
     </form>
 
 </body>
 </html>
          

[JScript] 
<%@ Page Language="JScript" AutoEventWireup="True" %>
<html>
 <head>
 
     <script language="JSCRIPT" runat="server">
 
         function SubmitBtn_Click(Sender : Object, e : EventArgs){
             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>
     <p>
 
     <form 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" />
         
         <p>
         
         <asp:Label id=Label1 font-name="Verdana" font-size="10pt" runat="server"/>
         
     </form>
 
 </body>
 </html>
          

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

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

<HTML>
    <HEAD>
        
        <SCRIPT runat="server">
            ' Global Variables.
            Private dv As DataView
            Private dt As New DataTable()

            Private Sub Page_Load(sender As Object, e As System.EventArgs)
                ' 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") Is Nothing Then
                    ' 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()
                End If
            End Sub

            Private Sub addButton_Click(sender As Object, e As System.EventArgs)
                ' Add the items selected in ListBox1 to DataGrid1.
                Dim item As ListItem
                For Each item In ListBox1.Items
                    If item.Selected Then
                        ' Add the item to the DataGrid.
                        ' First, get the DataTable from the Session variable.
                        dt = CType(Session("data"), DataTable)
            
                        If  Not (dt Is Nothing) Then
                            ' Create a new DataRow in the DataTable.
                            Dim dr As 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()
                        End If
                    End If
                Next item
            End Sub
        </SCRIPT>

    </HEAD>
    
    <BODY>
        <form 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>

[C#] 
<!-- 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" %>

<HTML>
    <HEAD>
        
        <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>

    </HEAD>
    
    <BODY>
        <form 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>

[C++] No example is available for C++. To view a Visual Basic, C#, or JScript example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Web.UI.WebControls

Platforms: Windows 2000, Windows XP Professional, Windows Server 2003 family

Assembly: System.Web (in System.Web.dll)

See Also

ListItem Members | System.Web.UI.WebControls Namespace | ListControl | RadioButtonList | ListBox | DropDownList | CheckBoxList

Show:
© 2014 Microsoft