SelectionList Control

Article
09/14/2006

The SelectionList control basically provides UI selection capability for a list. Although they are both lists, a SelectionList control differs in capabilities and scope from a List control. Whether you choose to use a SelectionList or List control depends on the following criteria:

Do you intend to include a Command control for submission of the form to the server? A choice selected from a SelectionList control does not generate a server event.
Do you intend to maintain one or more selected items? A SelectionList control allows multiple items to be selected.
Do you intend to render only a small list? Do you intend not to support device templates, or internal or custom pagination? A SelectionList control manages only small lists and does not offer pagination.
Do you want to use drop-down lists or combo boxes? A SelectionList control supports these capabilities.

For more detailed information about choosing a SelectionList control versus a List control, see the SelectionList class.

Mobile Controls Syntax

Required properties, defaults, and code-featured elements are noted in bold type.

<mobile:SelectionList
   runat="server"
   id="id"
   Font-Name="fontName"
   Font-Size="{NotSet|Normal|Small|Large}"
   Font-Bold="{NotSet|False|True}"
   Font-Italic=""{NotSet|False|True}"
   ForeColor="foregroundColor"
   BackColor="backgroundColor"
   Alignment="{NotSet|Left|Center|Right}"
   StyleReference="styleReference"
   Wrapping="{NotSet|Wrap|NoWrap}"

   DataMember="dataMember"
   DataTextField="DataTextField"
   DataValueField="DataValueField"
   OnItemDataBind="itemDataBindHandler"
   OnSelectedIndexChanged="selectedIndexChangedHandler"
   Rows="rows"
   SelectType="{DropDown|ListBox|Radio|MultiSelectListBox|CheckBox}"
   Title="Text">

Place DeviceSpecific/Choice construct here. (optional)
      <Choice Add choice here>
      </Choice>
   </DeviceSpecific>

      <Choice Add choice here>
      </Choice>
   </DeviceSpecific>

Place statically declared list items here. (optional)
   <Item Text="Text" Value="Value" />
</mobile:SelectionList>

Containment Rules

The following controls can contain a SelectionList control.

Control	Comments
System.Web.UI.MobileControls.Form	Can contain any number of SelectionList controls.
System.Web.UI.MobileControls.Panel	Can contain any number of SelectionList controls.

The SelectionList control can contain the following controls.

Control	Comments
System.Web.UI.MobileControls.Item	Any number of Item controls can be contained in an SelectionList control.

Device Templates

The SelectionList control does not support device templates.

Device-Specific Behavior

Device language	Description of behavior
HTML	The SelectionList control is rendered as a combo box, a list box, a group of radio buttons, or a group of check boxes, depending on the SelectType control. The Title property is ignored.
WML	The SelectionList control is rendered as a <select> construct, allowing the user to use numeric keys to click or select items. Other UI elements on the card are not merged into this select block. The text in the Title property is displayed.

SelectionList Control Example

The following example shows how to create a selection list for stereo components. When the user chooses a component, a second page displays the component name and its price.

<%@ Page Inherits="System.Web.UI.MobileControls.MobilePage"
   Language="VB" %>
<%@ Register TagPrefix="mobile"
    Namespace="System.Web.UI.MobileControls"
    Assembly="System.Web.Mobile" %>

<script language="vb" runat="server">
Public Sub PriceHandler(source As Object, e As EventArgs)
   Dim selectedStereoComponent As String
   selectedStereoComponent = StereoComponents.Selection.Value
   Price.Text = StereoComponents.Selection.Text _
      + " at " + selectedStereoComponent
   ActiveForm = PricePage
End Sub
</script>

<mobile:Form runat="server">
   <mobile:Label>For pricing, select a component:</mobile:Label><br><br>
   <mobile:SelectionList id="StereoComponents" runat="server">
      <item Text="Amplifier" Value="$500.00"/>
      <item Text="Compact Disc" Value="$600.00"/>
      <item Text="Receiver" Value="$1000.00"/>
      <item Text="Speakers" Value="$800.00"/><br>
   </mobile:SelectionList>
   <mobile:Command runat="server" OnClick="PriceHandler">
   Get the price!</mobile:Command>
</mobile:Form>
<mobile:Form runat="server" id="PricePage">
   <mobile:Label runat="server" id="PriceMessage" />
      Stereo Component Price Request</mobile:Label><br>
  <mobile:Label runat="server" id="Price" />
</mobile:Form>
[C#]
<%@ Page Inherits="System.Web.UI.MobileControls.MobilePage"
   Language="c#" %>
<%@ Register TagPrefix="mobile"
    Namespace="System.Web.UI.MobileControls"
    Assembly="System.Web.Mobile" %>

<script language="c#" runat="server">
public void PriceHandler(Object source, EventArgs e)
{
   String selectedStereoComponent = StereoComponents.Selection.Value;
   Price.Text = StereoComponents.Selection.Text
      + " at " + selectedStereoComponent;
   ActiveForm = PricePage;
}
</script>

<mobile:Form runat="server">
   <mobile:Label>For pricing, select a component:</mobile:Label><br><br>
   <mobile:SelectionList id="StereoComponents" runat="server">
      <item Text="Amplifier" Value="$500.00"/>
      <item Text="Compact Disc" Value="$600.00"/>
      <item Text="Receiver" Value="$1000.00"/>
      <item Text="Speakers" Value="$800.00"/><br>
   </mobile:SelectionList>
   <mobile:Command runat="server" OnClick="PriceHandler">
   Get the price!</mobile:Command>
</mobile:Form>
<mobile:Form runat="server" id="PricePage">
   <mobile:Label runat="server" id="PriceMessage" />
      Stereo Component Price Request</mobile:Label><br>
  <mobile:Label runat="server" id="Price" />
</mobile:Form>

Share via