.NET 4.0+

WPF Selection Controls - CheckBox

by Richard Carr, published at http://www.blackwasp.co.uk/WPFCheckBox.aspx

The sixty-eighth part of the Windows Presentation Foundation Fundamentals tutorial begins a look at the selection controls provided by WPF. The first of the selection control articles describes the CheckBox.

CheckBox

The CheckBox control is one of the five selection controls that are supplied as part of Windows Presentation Foundation (WPF). A CheckBox is a standard windows control that is familiar to most users. Normally it appears as a small square or box alongside an option, which is usually described with plain text. If the box contains a tick or a cross, the option is enabled. If the option is disabled, the square is empty. In some cases a third, indeterminate state is possible. This is usually represented by a shaded box. To switch between states the user clicks the square or its related content, or focuses the control before pressing the space bar.

To demonstrate the CheckBox control we need a sample solution. Create a new WPF Application project in Visual Studio, using the name, "CheckBoxDemo". Once the solution is ready, replace the XAML in the main window with the following code:

<Window x:Class="CheckBoxDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="CheckBox Demo"
        Height="100"
        Width="300">
    <StackPanel>
        <CheckBox Margin="5">Please send me emails about your products</CheckBox>
        <CheckBox Margin="5">Please sell my details to third parties</CheckBox>
    </StackPanel>
</Window>

The XAML generates a window containing two CheckBoxes, as pictured below:

Run the program to see the results. Note that the CheckBoxes can be toggled by clicking the small squares or the text. The CheckBox class is derived from ContentControl, allowing any content to be included, not just text. However, some child controls will prevent the state from being changed. For example, if you use a Button for the content, this can capture the mouse click, preventing the CheckBox from updating.

Reading and Setting the CheckBox State

The most important property of a CheckBox is IsChecked. This allows you to determine the current state of the CheckBox, to initialise it in the XAML, or to set it from code. The property returns a nullable Boolean value that is true when the CheckBox is checked, false when unchecked, and null if the state is indeterminate.

Let's set the initial IsChecked states for the two CheckBoxes in the XAML. The following code checks the first control and sets the second to indeterminate. Note the syntax for specifying null, "{x:Null}".

<CheckBox Margin="5"
          IsChecked="True">Please send me emails about your products</CheckBox>
<CheckBox Margin="5"
          IsChecked="{x:Null}">Please sell my details to third parties</CheckBox>

Try running the program to see the results. Note that when you click a CheckBox it is not possible to return it to the indeterminate state.

Three State CheckBoxes

As we've seen, CheckBoxes always have three states and any state can be selected in the XAML or programmatically. However, by default, it is not possible for the user to select the indeterminate option. To enable this you simply set the IsThreeState property to true.

<CheckBox Margin="5"
          IsChecked="True"
          IsThreeState="True">Please send me emails about your products</CheckBox>
<CheckBox Margin="5"
          IsChecked="{x:Null}"
          IsThreeState="True">Please sell my details to third parties</CheckBox>

Update the XAML for the two CheckBoxes as shown above and run the program again. Clicking the CheckBoxes will now cycle through the three available values.

CheckBox State Change Events

As with most interactive controls, the CheckBox class defines events that are raised in response to user actions. There are three key events that are triggered when the IsChecked value changes. The event raised is determined by the state of the CheckBox after the change. Accordingly, they are named Checked, Unchecked and Indeterminate.

To show the use of the events, register all three for both CheckBoxes, as shown below:

<CheckBox Margin="5"
          IsChecked="True"
          IsThreeState="True"
          Checked="CheckBox_Checked"
          Unchecked="CheckBox_Unchecked"
          Indeterminate="CheckBox_Indeterminate">
          Please send me emails about your products</CheckBox>
<CheckBox Margin="5"
          IsChecked="{x:Null}"
          IsThreeState="True"
          Checked="CheckBox_Checked"
          Unchecked="CheckBox_Unchecked"
          Indeterminate="CheckBox_Indeterminate">
          Please sell my details to third parties</CheckBox>

We'll now add code that changes the colour of the text within the CheckBox's content, depending upon the status. Add the following code behind the window:

private void CheckBox_Checked(object sender, RoutedEventArgs e)
{
    ((CheckBox)sender).Foreground = Brushes.Green;
}

private void CheckBox_Unchecked(object sender, RoutedEventArgs e)
{
    ((CheckBox)sender).Foreground = Brushes.Red;
}

private void CheckBox_Indeterminate(object sender, RoutedEventArgs e)
{
    ((CheckBox)sender).Foreground = Brushes.Black;
}

Run the program for the final time and cycle through the various states to see the effect.