Controls are visual by definition. For that reason, several properties can be shared as a baseline implementation for anything visual and potentially interactive. The appearance-related properties for control are shown in table 10.1.

The Background property is used to hold the background brush of the control. This can be a simple color or a complex gradient. Similarly, the BorderBrush property does the same for the brush used to paint the border. The BorderThickness is a size to be used to control the pen weight or thickness of the border for the control. The Foreground brush should be used when displaying text or other content for which the user hasn't provided a specific color. The last three—Padding, HorizontalContentAlignment, and VerticalContentAlignment—all control how the content will be displayed.

It's important to know that no specific user interface is implied by these properties. The control author (or person creating the style/template) is required to apply these properties to specific elements in the template. Common sense would say that a BorderBrush should control the color of the outline of the control, but nothing enforces that.

Two other common traits that controls share is the ability to be navigated to via mouse and keyboard and set as either enabled or disabled.

Silverlight controls also support Tab-key navigation as well as manual focusing via the mouse or API. The properties and methods that support that are shown in table 10.2.

IsEnabled controls the enabled state for the control. The expected behavior is that, if IsEnabled is false, the control won't accept any keyboard, mouse, or other human input and isn't considered a tab stop. It should also display itself using a faded or grayed-out look to convey this state.

The Focus method may be used to attempt to manually set focus to a control via code. If the control can't receive focus (for example, IsEnabled is False), the method will return false.

Three properties control tab navigation for the control. The first—IsTabStop—controls whether the Tab key can be used to access the control. The TabIndex controls the order within the container that the Tab key will navigate between controls. Lower-numbered controls come earlier in the tabbing sequence. Finally, the TabNavigation property controls how tabbing works for elements hosted inside this control. The possible values and their meanings are listed in table 10.3.

If you were to create a composite control, such as the LockableListBox at the end of this chapter, Local tab navigation would be the expected behavior. But, if you created a ListBox-like control, you'd expect the Once behavior because you'd use the arrow keys to navigate between the individual items.

The next key area of support in the Control type is templating. Templates give Silverlight controls their appearance and user experience.

One key feature that the controls add over the base type is the ability to template the control. As we'll learn in section 23.3, a template is a definition for the visual representation of the control. By default, controls in Silverlight are defined by their model and functionality. The user interface elements can be completely replaced; they're considered lookless controls. Table 10.4 shows the properties and methods that support templating.

The Template property enables this flexible control templating. The DefaultStyleKey property is used by control authors to wire up the control to a default style and template, something which may be overridden by consumers of the control. The ApplyTemplate method is used to rebuild the visual tree for the control, using the supplied template.

Control also supports the FontFamily, FontSize, FontStretch, FontStyle, and FontWeight properties we covered in the chapter on text. For more detail, please refer back to section 9.2.

It's rare that you'll create new controls that derive directly from UIElement or FrameworkElement. Instead, you'll usually derive from Control or one of its descendents such as ContentControl. ContentControl provides functionality above and beyond Control by enabling the containment and templating of arbitrary content.

The ContentPresenter is a descendent FrameworkElement that exists primarily to support the display of content in a ContentControl. Rather than require you to put a TextBlock, Image, or other strongly typed content presentation element into your control template, you can use a ContentPresenter to bind to and display the content from the Content property.

Table 10.7 shows the properties of the ContentPresenter element.

Without the ContentPresenter, the ContentControl can't do much of anything exciting. The ContentPresenter holds the logic to try and render the object passed into it. In fact, in a typical control template, the ContentPresenter simply is assigned values from the ContentControl via template binding, as seen here:

<ContentPresenter
  Content="{TemplateBinding Content}"
  Margin="{TemplateBinding Padding}"
  HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
  VerticalAlignment="{TemplateBinding VerticalContentAlignment}" />

We'll cover TemplateBinding in chapter 23 when we work with control templates. For now, understand that TemplateBinding is used to bind an element in XAML to a dependency property in the control's implementation. For example, the Content property of the ContentPresenter in the preceding code is bound to the Content property of the containing ContentControl.

Together, Controls, ContentControls, and the associated ContentPresenter make up the core of the control tree in Silverlight. One other type of control, the ItemsControl, is equally as important. But before we look at the various types of ItemsControls, let's look at some concrete implementations of ContentControls—specifically, those based on Button.

The traditional Button is a simple ContentControl that a user can click to perform an action. This control is defined by the Button class, which derives directly from the ButtonBase class. The Button automatically exposes the Click event. The thing that makes the Button class special is the default appearance it creates around the Content. This appearance and the syntax of a Button are shown in listing 10.1.

Example 10.1. The syntax for a button

As you can see, the buttons in table 10.6 are slightly more complex than the one shown in this example, but it's intended to show only the basic syntax and look of a Button. This appearance includes a small container that makes a Silverlight Button look similar to the buttons seen in other technologies. This container is designed to hold a Button element's Content. Occasionally, you may want this Content to behave more like a hyperlink. For these situations, you should look to the HyperlinkButton.

The HyperlinkButton control is designed to create a button that looks and behaves like a hyperlink. This behavior is provided through two publicly visible properties called NavigateUri and TargetName, which are shown here:

<HyperlinkButton x:Name="myHyperlinkButton"
  Content="Search in a New Window"
  NavigateUri="http://www.live.com"
  TargetName="_blank" />

The HyperlinkButton control uses the NavigateUri property to determine which page to load. By default, this Uri will be loaded in the current window, forcing your Silverlight application to unload. As you can imagine, this side effect may not be desirable. But, you can take control of this behavior with the TargetName property.

The TargetName property is a string that represents the name of the frame or window to load the NavigateUri within. By default, the TargetName value will be an empty string. You can use any of the values in table 10.9 to create the intended experience.

This table describes the values that can be assigned to the TargetName property. If you happen to assign an unrecognized value to the TargetName property, one of two things will happen. If the value has one or more whitespace characters, an InvalidOperationException will be thrown. Alternatively, if the TargetName doesn't have any whitespace characters, the NavigateUri will load in a new window. It's important to remember that, despite its behavior as a hyperlink, the HyperlinkButton is still a type of button.

The HyperlinkButton class derives from the ButtonBase class; it still acts like a button and supports the Click event. In the case of a HyperlinkButton, the Click event will fire before the NavigateUri is evaluated so you can dynamically change the location of the NavigateUri just before it gets loaded. In addition, this event can be useful for performing cleanup operations if you're redirecting the user away from your Silverlight application.

A RadioButton represents a choice within a group of options. For instance, imagine having to choose your favorite pizza topping or flavor of ice cream. Each of these situations requires one and only one choice to be selected. To properly deliver this kind of functionality, you need to familiarize yourself with the selection and grouping behaviors of the RadioButton.

RADIOBUTTON SELECTION

A RadioButton is a kind of ToggleButton. A ToggleButton represents a button that can change states. For a RadioButton, this state can change between a checked state and the default unchecked state. The state can be set at design time through the Boolean-based IsChecked property, the value of which affects both behavior and appearance, as shown in listing 10.2.

Example 10.2. The default appearances of a checked and unchecked RadioButton

This example shows four answers for a single question, one of which is disabled. You can see that the first option is selected by default when the application starts. Note also that it's chocolate. If it's not chocolate, it's not a dessert.

Once a RadioButton has been selected, it can't be unselected by clicking it again. A RadioButton can only be unselected by using one of two approaches: set the IsChecked property to false at runtime using code or selecting a different RadioButton within the same group.

RADIOBUTTON GROUPING

A grouping of RadioButton items represents the choices available for a single situation. In the previous listing, you saw a StackPanel that grouped together a couple of ice cream flavor choices. These choices were grouped because the StackPanel was the immediate parent of both of the RadioButton items. A problem begins to emerge if you add unrelated RadioButton items to the scenario. For these situations, you use the GroupName property.

The GroupName property allows you to control how RadioButton elements are grouped together. By default, this string-typed property is set as an empty string, indicating there's no group. Because of this, all RadioButton elements with a direct parent will belong to the same group. By explicitly setting this property, you can control the groupings. You can even do this for RadioButton elements that share the same parent, as shown in listing 10.3.

Example 10.3. Manually controlling RadioButton grouping

The listing shows how the GroupName property can be used to force RadioButtons to work together. A close relative of the radio button, but one that doesn't handle mutually exclusive choices and, therefore, needs no grouping, is the CheckBox.

The CheckBox control enables a user to select whether an option is chosen. Unlike the RadioButton, the CheckBox control allows you to select multiple elements that belong to the same grouping so you could do something like select multiple pizza toppings (see listing 10.4).

Example 10.4. A basic CheckBox setup

Selecting multiple CheckBox elements at the same time is possible because the CheckBox isn't bound to a specific group. In fact, the CheckBox does little more than extend the ToggleButton class. Because the CheckBox does extend the ToggleButton class, you can use three-state checkboxes by switching the IsThreeState bool property to true. What happens to the IsChecked property? Well, this property is actually a nullable type so it also supports three states. These states and the look of a three-state CheckBox are shown in listing 10.5.

Example 10.5. Using three-state mode with the CheckBox control

Listing 10.5 shows the look and syntax of a three-state CheckBox. The fact that the CheckBox can support three different states demonstrates one way in which Silverlight is an improvement over HTML. Another improvement is found in the flexibility of the ContentControl class in general. This class was discussed at the beginning of section 10.2 and can be used in the CheckBox, RadioButton, HyperlinkButton, and Button controls. In addition, the flexibility of the ContentControl can be used with Silverlight's item controls.

In this section, we discussed the controls derived from the ButtonBase class that represent buttons available within Silverlight. Often, these controls are used to trigger an action. Occasionally, you may need to provide to present a list of items rather than a single item. This type of functionality can be delivered through an ItemsControl.

The ListBox is one of the most commonly used items controls. Though much of its functionality is directly inherited from ItemsControl, it adds the important distinctions of exposing a selected item and including scrolling in its default template. This control enables you to show multiple items from a collection of items at the same time. If there are more items than the space allowed for the control, the ListBox will display scrollbars to allow scrolling through the content. An example of this scrolling feature as well as the syntax of a ListBox is shown in listing 10.6.

Example 10.6. A ListBox that displays the days of the week

This ListBox uses the Items property to load options at design time. You also have the option of binding to a data source to make this list of items more dynamic. Binding to a data source will be covered in the next chapter. Regardless of whether you're binding to a data source or defining items at design time, each item in the control is a ListBoxItem. A ListBoxItem is a type of ContentControl so you can use any visual tree you want for an item, as shown in listing 10.7.

Example 10.7. Using a ListBoxItem as a ContentControl

This listing shows a ListBox control with much richer ListBoxItem elements than those shown in listing 10.6. Ultimately, one of the main reasons for using a ListBox is to enable your users to select an item from it. Luckily, the ListBox exposes some properties for this.

The ListBox exposes two properties and an event—SelectedIndex, SelectedItem, and SelectionChanged, respectively—all of which help you handle item selection. The SelectedIndex is a zero-based int that reflects the index of the currently selected item in the ListBox. If no item is selected, this property will return –1. Even more informative is the SelectedItem property, which returns the current selection in object form. This property type is a powerful improvement over the value/text property of items in HTML. Regardless, whenever an item is selected, whether by the user or programmatically, the SelectionChanged event will fire. This event, as well as the SelectedItem and SelectedIndex properties, is also available on the ComboBox.

The ComboBox gives users the ability to select a single option from a list of choices. These choices are visible to a user as long as the ComboBox is in an open state, which is set when a user interacts with a ComboBox. Alternatively, this state can be set programmatically through the IsDropDownOpen property. This bool property is by default set to false so a ComboBox starts in a compacted, closed state, as shown in listing 10.8.

Example 10.8. A ComboBox that has been used to select an item

Listing 10.8 shows the appearance of a closed ComboBox. As you can see, this control delivers a compact approach for displaying a list of items. In fact, this control resembles the DropDownList found in ASP.NET and the select element used in HTML. But, unlike those controls, each item in the ComboBox can have a fully customized appearance; each item is a ComboBoxItem, which happens to be a kind of ContentControl. This fact enables you to recreate the list shown in listing 10.7 in the more compact form of a ComboBox.

The ComboBox also provides three members that make it unique from the other list controls. The first member is a double property called MaxDropDownHeight that allows you to customize the maximum height of the drop-down list. The second member is an event named DropDownOpened that fires when the drop-down list is shown. The third member is an event that triggers when the drop-down list closes. This event is called DropDownClosed. Collectively, these three members make the ComboBox special—they won't be found on the third and final type of ItemsControl, the TabControl.

The TabControl is another ItemsControl available within Silverlight. This ItemsControl is designed to show multiple content items in the same physical space on the screen using a tab metaphor to switch between them. Each of these pieces of content is defined within a TabItem, which happens to be a ContentControl. Because of this, you can define the complete visual tree for each TabItem. Before you can do this, you must reference the System.Windows.Controls assembly. The tab-related controls are extended controls like the GridSplitter mentioned in chapter 7, so the sdk prefix will be used once again throughout this section, as shown in listing 10.9.

Example 10.9. The basic syntax of a TabControl

This listing shows an entire page, which includes a basic TabControl. Because TabControl is an extended control and is part of the System.Windows.Controls.dll, we've shown the entire page's XAML to demonstrate the use of the ext namespace. Now that you can use a TabControl, it's important to understand the behavior of the headers.

Each of the tab headers in listing 10.9 is hardly visible because each header is set by a TabItem property called Header. This property represents the object used when rendering the Header, so you should consider using some UIElement such as a Panel for the Header. Listing 10.10 shows a TextBlock used for one Header and a StackPanel for the other.

Example 10.10. Customizing the header of a TabItem

This shows a TabControl with two TabItem elements. Each element has a Header. Note that, if a TabItem has its Header property set, the HasHeader property of the TabItem will change to true. This bool property defaults to false and is useful in the event you need to check whether a TabItem has a header at runtime. For situations where you want to change the location of the tabs, there's another property.

The TabStripPlacement property determines how the tabs align in relation to the tab content area. This property represents an enumeration that can be set to Bottom, Left, Right, or Top. By default, this property value is set to Top on a TabControl.

The TabControl, ComboBox, and ListBox represent three ItemsControl elements available in Silverlight. ItemsControl elements give you the flexibility to allow a user to select from any kind of content. ItemsControls are the key type of control to use whenever you need to display lists of content: menus, list boxes, tab strips, carousels, and more.

Together with the content controls such as Buttons, the ItemsControls help make up the majority of the user interface elements you'll use in Silverlight. Chances are, if you create your own custom control, it'll derive from one of those core types.

Creating your own custom controls is a deep topic, and one that will need to wait for the discussion of styling, templating, binding, and the Visual State Manager—all covered in later chapters. But there's one type of control you can create that doesn't require all this additional complexity. In fact, it was designed for simple reuse and UI composition of existing controls such as those we've discussed in this chapter. That type of control is the UserControl.

Defining the appearance of a UserControl involves creating the XAML for the user interface. This process is the same as defining the UI for a page in Silverlight because every page in Silverlight is a UserControl. The XAML for the UserControl (LockableTextBox) is shown in listing 10.12.

Example 10.12. The user interface for the LockableTextBox UserControl

This listing shows the XAML that makes up the default appearance of the LockableTextBox. This UI defines a TextBox and an Image within a StackPanel. The StackPanel is important because, as we discussed, each UserControl can have only one UIElement as a child, so you'll almost always use one of the Panel elements discussed in chapter 7 as the content of a UserControl.

Also note that, in order to make the control truly reusable, we've put it into a separate Silverlight class library project named MyClassLibrary. This project is referenced from our main Silverlight application.

Setting the Content of a UserControl is an important first step in creating a reusable control. This step defines the static parts of the UI, but the real value in creating a reusable control is to provide some kind of new functionality. This functionality is generally delivered when you define the behavior of a control.

The functionality of a reusable control is also known as the control's behavior. This behavior is defined in the code-behind file of the XAML file, which will contain a class that derives from the UserControl class. It's your responsibility to make sure this class provides the events, methods, and properties that detail the behavior of the control. Look at the code for the LockableTextBox control shown in listing 10.13. This listing uses a DependencyProperty, which was covered in chapter 2.

Example 10.13. The LockableTextBox class definition (C#)

This class includes the call to InitializeComponent inside the constructor. If left out, our control references (to the textbox and the image, for example) would be null at runtime.

The class also includes the creation of a DependencyProperty for IsLocked. We introduced dependency properties in chapter 2, but let's dive a bit deeper into what's required to create them in your own class.

REGISTERING DEPENDENCY PROPERTIES

To register a property as a DependencyProperty, you must call the statically visible DependencyProperty.Register method. This method requires the name of the CLR wrapper, the type of the property value, and the type of the object that owns the property. Listing 10.14 shows how to register the IsLocked property.

Example 10.14. Registering a DependencyProperty with the property system

This listing shows how to register a property as a DependencyProperty. Note the name of the DependencyProperty itself. This name can be anything, but it generally follows a naming template of [CLR Wrapper Name]Property. This DependencyProperty serves as a key in the property dictionary used by the GetValue and SetValue methods of a CLR property wrapper. Also note the fourth parameter, which allows you to define behavioral aspects and automatically respond to property value changes.

While the rest of the runtime uses the dependency properties directly, the CLR property wrapper is required because it's used by direct property assignments in XAML or from your own code. Note that, unlike a normal CLR property, you'll assign the value to and read it from the dependency property system. In addition, you won't perform any other logic in the setter; you'll do that inside the changed callback instead.

private static void OnIsLockedChanged(DependencyObject o,
    DependencyPropertyChangedEventArgs e)
{
    LockableTextBox textBox = (LockableTextBox)(o);
    textBox.UpdateUI();
 }

To include a UserControl in your application, you must do two things. First, you must add an XML namespace that references the location of the UserControl. Then, you must add an instance of that control within your XAML. These two steps are the same for any UserControl. Listing 10.15 shows how to reference the LockableTextBox control built over the past two sections.

Example 10.15. Using the LockableTextBox

This snippet shows how to add the LockableTextBox to a basic Silverlight page. The my namespace is used to tell Silverlight where to look for the LockableTextBox definition. This definition is used to build the control, which is referenced later. That's all there is to it.

Creating a reusable control in Silverlight is as simple as defining a UserControl that consists of an appearance and a behavior. These two items generally represent a small component within a Silverlight application. Alternatively, a UserControl can represent a component as large as an entire page. This fact is important because it can affect how you decide to share your content.

UserControls are intended for simple reuse. They're great for those times when you need to compose a number of existing elements and reuse them within your application. But they're generally not the best approach for creating controls for broader reuse, which often require binding support and styling flexibility. In those instances, you need to create a custom control, which we'll cover in chapter 24—once we get binding, styling, and visual state management under our belts.