Windows Phone 7 : The Silverlight Controls (part 4) - Interactive Controls - TextBox Controls, ListBox Controls, ComboBox Controls

2. Interactive Controls

The controls that we will look at for the purposes of allowing user interaction and data entry are the TextBox, ListBox, ComboBox, CheckBox, RadioButton, Button, and ApplicationBar.

2.1. TextBox Controls

Silverlight's TextBox control provides a field within which the user can enter text, just like the TextBox control used in WinForms projects.

When the TextBox receives focus in a running application, Windows Phone will automatically display the onscreen keyboard (unless a hardware keyboard is currently open, in which case it will expect that to be used instead). If the onscreen keyboard would normally obscure the text box, the page will scroll to bring the text box back into view. Once focus is lost, the keyboard will disappear again.

Several properties are available to control the behavior of the control. Its font can be set using the same properties as for the TextBlock. The control can be locked to prevent text edits by setting the IsReadOnly property. The maximum number of characters that can be entered is controlled by the MaxLength property, defaulting to 0 for unlimited text.

The control can also support multiline text. If the AcceptsReturn property is set to True, pressing Enter on the keyboard will insert a line break. This can also be used with the TextWrapping property that will wrap text that is too long to fit on one line. The TextBox also offers properties named HorizontalScrollbar and VerticalScrollbar, which on the desktop implementation of Silverlight allow the displays of the field's scrollbars to be controlled, but unfortunately they have no effect on Windows Phone 7.

Useful events include GotFocus and LostFocus, KeyDown and KeyUp, and TextChanged.

2.2. ListBox Controls

ListBox controls in Silverlight are also very similar to their WinForms equivalent. They contain an Items collection into which any type of object can be added; the text displayed within the list will be obtained by calling the ToString method on each object. If the number of items exceeds the space available for them to be displayed, the user can scroll the items by dragging them up and down.

Additional functionality can be obtained, however, by adding ListBoxItem objects to the list instead of other objects. Each ListBoxItem offers a Content property (into which a text string can be placed or any other type of object just as if the object were being added directly to the ListBox). In addition, it also offers properties to allow the Background and Foreground colors to be changed, offers a selection of font properties, the IsEnabled property to allow individual items to be enabled or disabled, and HorizontalAlignment and Visible properties, among others. These properties allow for very flexible control over the items within the list.

ListBoxItem objects can be added to the list either by entering them manually into the XAML as the content for the list or by clicking the ellipsis button against the ListBox's Items property in the Properties window.

Listing 6 shows a simple ListBox with some configuration applied to a few of the items.

Example 6. Setting up a ListBox and its items

<ListBox Height="300" Width="300" BorderBrush="Gray" BorderThickness="1">
            <ListBoxItem Content="Item1" />
            <ListBoxItem Content="Item2" />
            <ListBoxItem Background="Navy" Content="Item3" />
            <ListBoxItem Content="Item4" />
            <ListBoxItem Content="Item5" IsEnabled="False" />
        </ListBox>

The resulting ListBox is shown in Figure 8.

Figure 8. The resulting ListBox control

List items need not be limited just to displaying text strings, however. Other UI elements can be placed inside the list in order to create a very rich display of information. List items can therefore be formed from images, text boxes, and even other list boxes! Only a single control element can be placed inside each list item, but by using a Grid or StackPanel control (both of which we'll look at shortly), it is possible to nest multiple controls inside. By crafting your UI carefully, it is possible to create all sorts of ListBox display configurations, such as those used to display messages in the Windows Phone 7 e-mail application.

It is also possible to select multiple items within a ListBox. This feature can be activated by setting the SelectionMode property to Multiple. Once this has been done, tapping an item will toggle its selected state rather than deselecting the other items.

To track changes to the ListBox selection in your code, add a handler for the SelectionChanged event. Your event handler can use the ListBox's SelectedItem, SelectedItems (for multiselection) and SelectedIndex properties to query the items that are selected, but it can also use the handy AddedItems and RemovedItems collections provided by the event's SelectionChangedEventArgs property. This will contain the details of all items that were added to or removed from the SelectedItems collection as part of that event.

2.3. ComboBox Controls

You might have noticed the conspicuous absence of one of the most useful controls in the Toolbox: the ComboBox control. Unfortunately, official support for this control didn't make it into Silverlight for Windows Phone 7.

Although you can still use it, it must be created manually within the XAML rather than dragged from the Toolbox. There are also some severe presentational limitations that will make it appear different to your other controls, which is why the control is not properly supported.

The ComboBox will always appear with a shaded white background when closed and a similar background on the drop-down-list when it is opened by the user. Its default text color is also white, making the items virtually invisible. The background color cannot be changed (setting the ComboBox's Background property has no effect) but fortunately the Foreground property does work. Changing it to black (or some other color that shows up on a white background) will give you a usable control, even though it doesn't really fit in with the other controls around it.

Adding items to the ComboBox is very similar to the ListBox, except that ComboBoxItem objects are used in place of ListBoxItem objects. Once again, these item objects can be given a simple text value for their Content, or other UI elements can be used.

Listing 7 shows a simple ComboBox containing several items.

Example 7. Setting up a ComboBox and its items

<ComboBox Width="200" Height="40" Foreground="Black" Background="Blue">
            <ComboBoxItem Content="Easy" />
            <ComboBoxItem Content="Medium" IsSelected="True" />
            <ComboBoxItem Content="Hard" />
        </ComboBox>

The ComboBox created from this XAML can be seen in Figure 9. The image on the left shows the combo in its closed state; on the right, it is dropped open.

Figure 9. The resulting ComboBox control

Useful events for the ComboBox include the DropDownClosed and DropDownOpen events, as well as the SelectionChanged event. This latter event offers the AddedItems and RemovedItems collections just as are provided to the ListBox, but because there is no multiselection option in the ComboBox, these collections will always simply identify the previously selected item (if there was one) and the newly selected item. The ComboBox's SelectedItem and SelectedIndex properties are also available for interrogating the selection within the control.