The ListControl Class

I l @ ve RuBoard

The `ListControl` Class

All ASP.NET list controls inherit from ListControl in the System.Web. UI.WebControls namespace. Inheritance is the foundation of OOP design and is the means by which one class acquires all the behavior and attributes of its parent class. The new class indicates only how it is different from its parent by overriding or adding to the properties, methods, and events of the parent class. Table 6.1 shows a summary of the properties, methods , and events of the ListControl class. Each of the four controls discussed in this chapter shares these common attributes, so please take a moment to review them before the first example.

Table 6.1. Properties, Methods, and Events of the `ListControl` Class

Name	Item	Description
`AutoPostBack`	Property	Gets or sets whether the control automatically posts back to the server when the list selection is changed
`ClearSelection`	Method	Clears the current list selection
`DataSource`	Property	Gets or sets the data source that populates the items in the list control
`DataTextField`	Property	Gets or sets the data source field that provides the text for items in the list
`DataValueField`	Property	Gets or sets the data source field that provides the value for items in the list
`Items`	Property	Gets the collections of items in the list
`SelectedIndex`	Property	Gets the ordinal for the first selected item in the list
`SelectedIndexChanged`	Event	Raised on the server whenever the list selection is changed
`SelectedItem`	Property	Gets the first selected item in the list

Because ListControl is an abstract base class and therefore cannot be instantiated , we must work with the derived list controls to provide examples of the attributes listed in Table 6.1. We'll cover each of these common properties, methods, and events when we introduce each of the four list controls in this chapter. Just keep in mind that items in Table 6.1 may be discussed in the context of an individual control, but they are common to all the list controls in this chapter. When we introduce each control, attributes unique to that control will be so noted.

Because the DropDownList control is perhaps the most straightforward and no doubt will be the most commonly used in your ASP.NET applications, let's take a look at it first.

Working with `DropDownList`

You can add a DropDownList control to the form in the same way as the intrinsic controls covered in the previous chapter, as shown in Listing 6.1.

Listing 6.1 Declaring the `DropDownList` control.

 <asp:DropDownList id="StatusList" runat="server">     <asp:ListItem value="100">Pending</asp:ListItem>     <asp:ListItem value="200" Selected="True">In Transit</asp:ListItem> </asp:DropDownList>

As this code snippet illustrates, you simply add a DropDownList tag using the ASP: namespace, as you do for all Web controls. You then set the id property and set runat="server" so that you can reference the control programmatically. Next , you need to add some options to the list control. You do this by adding ListItem tags inside the list control. In the preceding example, we set the values of the list items by setting the value property. We have also set the second list item as the initially selected item in the control by setting its Selected property to True . We set the text to be displayed by each list item with the text between the opening and closing tags of the list item. You could also explicitly set the Text property in this fashion:

 <asp:ListItem value="100" Text="Pending" />

Please note that this declaration does not require a closing tag, so you can use the XML shorthand method by including a forward slash in the opening <asp:ListItem> tag.

Getting the `SelectedItem`

In the example shown in Listing 6.2, we allow the user to update the status of an order and display the status code below the selection when the button is clicked.

Listing 6.2 Using the `SelectedItem` property of the `DropDownList` control (06ddl01.aspx).

 <%@ Page language="vb" autoeventwireup="false" codebehind=""%> <html> <head> <title>Chapter 6: ASP.NET List Controls</title> <script language="VB" runat="server">     Sub UpdateButton_Click(sender As Object, e As EventArgs)         StatusLabel.Text = StatusLabel.Text & _              StatusLabel.Text = "Order status at " & FormatDateTime(Now(), 3) _              & StatusList.SelectedItem.Value & "<br>"     End Sub </script> </head> <body>     <form runat="server">         <h3>Using DropDownList</h3>         Please update the order status:         <asp:DropDownList id="StatusList" runat="server">             <asp:ListItem value="100">Pending</asp:ListItem>             <asp:ListItem value="200">In Transit</asp:ListItem>             <asp:ListItem value="300">Delivered</asp:ListItem>             <asp:ListItem value="400">Backorder</asp:ListItem>             <asp:ListItem value="500">Cancelled</asp:ListItem>         </asp:DropDownList>         <asp:button             text="Update"             OnClick="UpdateButton_Click"             runat="server"             ID="UpdateButton"/>         <p>         <asp:Label id="StatusLabel" runat="server"/>         </p>     </form> </body> </html>

The output for Listing 6.2 is shown in Figure 6.1.

Figure 6.1. The numeric status code corresponds to the chosen list item.

Using the `SelectedIndexChanged` Event

Note that in the previous example, we logged the time and the status every time the Update button is clicked. Although we are only printing the output to the screen in this basic example, we could easily update a database or some other data source. If instead you wanted to log only status changes, you simply respond to the SelectedIndexChanged event by setting up the event handler as shown in Listing 6.3.

Listing 6.3 Declaring the event handler for the `SelectedIndexChanged` event.

 Sub StatusList_SelectedIndexChanged(sender As Object, e As EventArgs)     StatusLabel.Text = StatusLabel.Text & _          StatusLabel.Text = "Order status at " & FormatDateTime(Now(), 3) _          & StatusList.SelectedItem.Value & "<br>" End Sub

Next, we need to specify the event handler by setting the onSelectedIndexChanged attribute for the DropDownList tag:

 <asp:DropDownList id="StatusList" runat="server" onSelectedIndexChanged="StatusList_SelectedIndexChanged">

So now the full example looks like Listing 6.4.

Listing 6.4 Handling the `SelectedIndexChanged` event of the `DropDownList` control (06ddl02.aspx).

 <%@ Page language="vb" autoeventwireup="false" codebehind=""%> <html> <head> <script language="VB" runat="server">    <h3>Using DropDownList</h3>     Please update the order status:     Sub StatusList_SelectedIndexChanged(sender As Object, e As EventArgs)         StatusLabel.Text = StatusLabel.Text &              StatusLabel.Text = "Order status at " & FormatDateTime(Now(), 3)              & StatusList.SelectedItem.Value & "<br>"     End Sub </script> </head> <body>     <form runat="server">         <asp:DropDownList id="StatusList" runat="server"              onSelectedIndexChanged="StatusList_SelectedIndexChanged">             <asp:ListItem value="100">Pending</asp:ListItem>             <asp:ListItem value="200">In Transit</asp:ListItem>             <asp:ListItem value="300">Delivered</asp:ListItem>             <asp:ListItem value="400">Backorder</asp:ListItem>             <asp:ListItem value="500">Cancelled</asp:ListItem>         </asp:DropDownList>         <asp:button text="Update" runat="server" ID="UpdateButton"/>         <p>         <asp:Label id="StatusLabel" runat="server"/>         </p>     </form> </body> </html>

`AutoPostBack` : When You Just Can't Wait

In the preceding example, although the list now fires the SelectedIndexChanged event only when the list selection changes, the event also does not get handled until the user performs an explicit post-back to the server by clicking the Update button. You can automatically perform this post-back simply by setting the autopostback property to True :

 <asp:DropDownList id="StatusList" runat="server"      onSelectedIndexChanged="StatusList_SelectedIndexChanged"      autopostback="True">

Go ahead and try the example again and notice how the form performs the post-back only when the value is changed, not just when the list control is clicked.

Using `ListBox`

Now that you've seen how to read list control selection values, let's take a look at some of the other list control characteristics. For the next set of examples, we'll keep it interesting by introducing the ListBox control. This control is a close relative of the DropDownList control. In fact, both controls are rendered with the HTML <SELECT> tag. The DropDownList control displays only one item at a time and provides a drop-down list to view all items. However, the ListBox control displays a set number of items and provides scroll bars to view the rest of the choices. We add a ListBox to the form as shown in Listing 6.5.

Listing 6.5 Declaring the `ListBox` control.

 <asp:ListBox id="UserList" runat="server" Rows="4">     <asp:ListItem>Paula</asp:ListItem>     <asp:ListItem>Chris</asp:ListItem>     <asp:ListItem Selected="True">Eric</asp:ListItem>     <asp:ListItem>Wynn</asp:ListItem> </asp:ListBox>

This ListBox will display a list of users to choose from. The Rows property determines how many items in the list will be displayed. If the control contains more items than this value, scrollbars will be displayed to scroll the list. Much in the same way we did for the DropDownList control, we've set the third list item in the control to be the default selection.

Using `SelectedIndex`

Listing 6.6 shows you how to use the SelectedIndex method of one ListBox control to set the selection for another ListBox control. Figure 6.2 shows you the output of this listing.

Figure 6.2. The selection of the second list control is updated based on the first list control.

Listing 6.6 Using the `SelectedItem` property of the `ListBox` control (06lstb01.aspx).

 <%@ Page language="vb" autoeventwireup="false" codebehind=""%> <html> <head> <script language="VB" runat="server" ID=Script1>     Sub UpdateButton_Click(sender As Object, e As EventArgs)         GroupList.SelectedIndex = UserList.SelectedIndex     End Sub </script> </head> <body> <form runat="server" ID=Form1>         <h3>Using ListBox</h3>         Please update the order status:     <TABLE WIDTH="300" BORDER="0" CELLSPACING="1" CELLPADDING="1">         <TR>             <TD NOWRAP>Users:</TD>             <TD NOWRAP></TD>             <TD NOWRAP></TD>         </TR>         <TR>             <TD NOWRAP>                 <asp:ListBox id="UserList" runat="server" Rows="4">                     <asp:ListItem>Paula</asp:ListItem>                     <asp:ListItem>Chris</asp:ListItem>                     <asp:ListItem selected="True">Eric</asp:ListItem>                     <asp:ListItem>Wynn</asp:ListItem>                </asp:ListBox>             </TD>             <TD NOWRAP>                 <asp:button text="Update ->" runat="server"                  ID="UpdateButton" onclick="UpdateButton_Click"/>             </TD>             <TD NOWRAP>                 <asp:ListBox id="GroupList" runat="server" Rows="4">                     <asp:ListItem>Paula</asp:ListItem>                     <asp:ListItem>Chris</asp:ListItem>                     <asp:ListItem>Eric</asp:ListItem>                     <asp:ListItem>Wynn</asp:ListItem>                 </asp:ListBox>             </TD>         </TR>     </TABLE> </form> </body> </html>

Note how in the event handler, we merely set the SelectedIndex property of the second control equal to the same property on the first control, and voil ! The selection of the second list control changes.

Selecting Multiple Items with `SelectionMode`

You probably noticed that in the ListBox example, you could only select one list item at a time. This is because the ListBox control has a SelectionMode property that determines how many list items can be selected at one time. This property defaults to Single , so in order to allow multiple selections, simply set the SelectionMode property to Multiple , like this:

 <asp:ListBox id="GroupList" runat="server" Rows="4" SelectionMode="Multiple">

After making this change, run your form again. You will notice that, although you may select multiple users from the list control, only the first selection is copied over to the second list. This is because the SelectedIndex property returns only the index for the first item in the selection. To work with multiple selections, you must work with a new property ”the Items collection.

I l @ ve RuBoard