CheckBox Overview

The CheckBox class represents a check box that users can select and clear. This topic introduces you to the CheckBox control in Windows Presentation Foundation (WPF) and describes how to create CheckBox elements in Extensible Application Markup Language (XAML) and C#, set event handlers in C#, create CheckBox controls that contain rich content such as images, and use styling to change the control's appearance.

This topic contains the following sections.

• CheckBox Control
• Creating CheckBoxes
• Check Boxes Containing Rich Content
• CheckBox Styling
• Related Topics

CheckBox Control

The CheckBox control enables users to select and clear options in an application's user interface (UI). A CheckBox control is a ContentControl, which means it can contain content such as text, images, or panels. CheckBox controls inherit from the ToggleButton class, which in turn inherits from ButtonBase. Because CheckBox controls inherit from ToggleButton, they enable a user to toggle between selections. The user's selection is indicated by a check mark, and when a user clicks a CheckBox, its appearance and state change. The following graphic shows two different states of a CheckBox, checked and unchecked.

CheckBox buttons in different states

In addition to the checked and unchecked states CheckBox controls can have a third state, indeterminate. If the IsThreeState property is set to true the IsChecked property can be set to null (indeterminate).

The following graphics illustrate the three states of a CheckBox. The graphics show a dialog that shows the properties of files in an application called accesstext. The attributes of the files are indicated with a CheckBox. In the first graphic the file is Read-only (CheckBox is checked) and the second is Read\Write (CheckBox is unchecked). In the first two graphics the information concerns only one file Pane1 but the third graphic concerns all the files in the accesstext application. Some of the files are Read-only and some are Read\Write the attributes for the entire application cannot be determined (CheckBox is null).

CheckBox - Checked

CheckBox - Unchecked

CheckBox - Indeterminate

Creating CheckBoxes

The following examples show how to create CheckBox controls and add event handlers. In the first example when a user clicks the CheckBox, the text of the control changes. The CheckBox is created using XAML.

<CheckBox Margin="10, 10, 3, 3" Grid.Column="0" Grid.Row="2" Name="cb1" FontSize="12" 
Checked="HandleChange">Check Box</CheckBox>

After creating a CheckBox, you can add an event handler to handle check change events. Event handlers must be written in a procedural programming language such as C# or Microsoft Visual Basic. The following event handler is written in C#.

private void HandleChange(object sender, RoutedEventArgs e)
{
    cb1.Content = "You clicked the check box";
}

For the complete sample see CheckBox Sample

The following example also generates a CheckBox (cb), with a label, and then adds the CheckBox as a child of a canvas (cv3).

cb = new CheckBox();
cb.Content = "CheckBox";
spanel2.Children.Add(cb);

For the complete sample see Creating Controls Sample

Check Boxes Containing Rich Content

CheckBox controls can contain rich content such as text, images, and panels. The following example shows how to generate a CheckBox that contains an image.

<CheckBox Name="cb6" Checked="HandleChange1"><Image Source="data\flower.jpg" Height="30" Width="30"/>
</CheckBox>

For the complete sample see CheckBox Sample

CheckBox Styling

With control styling, you can dramatically change the appearance and behavior of CheckBox controls without having to write a custom control. In addition to setting visual properties, you can also apply styles to individual parts of a control, change the behavior of parts of the control through properties, or add additional parts or change the layout of a control. The following examples demonstrate several ways to add styles to CheckBox controls.

The first sample defines a style called SystemResStyle that shows how to use the current system settings in your style. The code assigns the color of the ControlDarkBrush as the Background color of the CheckBox and the ControlDarkDarkBrush as the Foreground color of the CheckBox.

<Style x:Key="SystemResStyle" TargetType="{x:Type CheckBox}">
    <Setter Property = "Background" Value= "{DynamicResource {x:Static SystemColors.ControlDarkBrushKey}}"/>
    <Setter Property = "Foreground" Value= "{DynamicResource {x:Static SystemColors.ControlDarkDarkBrushKey}}"/>
</Style>

This sample uses Trigger elements that enable you to change the appearance of a CheckBox in response to events raised on the control. When you click the CheckBox, the Foreground color changes; when you move the mouse over the CheckBox, the Background changes.

<Style x:Key="Triggers" TargetType="{x:Type CheckBox}">
<Style.Triggers>
    <Trigger Property="CheckBox.IsPressed" Value="true">
       <Setter Property = "Foreground" Value="Green"/>
    </Trigger>
    <Trigger Property="CheckBox.IsMouseOver" Value="true">
       <Setter Property = "Background" Value="Red"/>
    </Trigger>
</Style.Triggers>
</Style>

The final example uses various properties to customize the CheckBox.

<Style x:Key="Properties" TargetType="{x:Type CheckBox}">
    <Setter Property = "Background" Value= "Purple"/>
    <Setter Property = "Foreground" Value= "Green"/>
    <Setter Property = "BorderBrush" Value= "Black"/>
    <Setter Property = "BorderThickness" Value= "5"/>
</Style>

For the complete sample see CheckBox Styles Sample.

See Also

Reference

CheckBox
ToggleButton
ButtonBase

Concepts

CheckBox ControlTemplate Example

Other Resources

CheckBox
WPF Controls Gallery Sample