.NET 4.0+

WPF Layout Controls - GroupBox

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

The fifteenth part of the Windows Presentation Foundation Fundamentals tutorial looks at another WPF layout control. In this instalment it's the GroupBox control, which allows related controls to be arranged into a group with a common header.

The GroupBox

The GroupBox is a built-in control that allows you to group together a number of other controls. When you use the default styling for a GroupBox, the child controls are surrounded by a border that includes a caption. There is no need to explicitly define a Border. This control arrangement is used extensively within the Microsoft Windows operating system, its tools and applications.

Configuring a GroupBox is similar to setting up an Expander. Both controls inherit from the same base class and include the same properties for controlling the header area and content. The key difference is that a GroupBox does not add the user interaction that permits the content to be expanded and collapsed.

As with the Expander control, GroupBoxes must have a single child control, which may be another layout control. The header can be configured with plain text or you can use property element syntax in your XAML to use embed any other control in place of the caption.

GroupBox Example

To demonstrate the use of GroupBoxes, create a new WPF application project in Visual Studio. Name the project, "GroupBoxDemo". Once the project is initialised, replace the XAML of the automatically created window with that shown below.

The sample XAML defines two GroupBox controls in a window layout that might be used to configure the operation of the mouse. The first GroupBox contains radio buttons to allow the user to specify that they are either left or right-handed. The second contains a Slider to set the speed of double clicks.

<Window x:Class="GroupBoxDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="GroupBox Demo"
        Width="250"
        Height="180">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition Height="Auto"/>
        </Grid.RowDefinitions>

        <GroupBox Header="Mouse Handedness">
            <StackPanel>
                <RadioButton Content="Left-Handed" Margin="5"/>
                <RadioButton Content="Right-Handed" Margin="5" IsChecked="True"/>
            </StackPanel>
        </GroupBox>

        <GroupBox Grid.Row="1" Header="Double Click Speed">
            <Slider Margin="5" />
        </GroupBox>
    </Grid>
</Window>

Execute the program to see the results, which should be similar to that shown below. Note the thin border around each group and the positioning of the header captions.

Header Property

As mentioned above, you can replace the caption in a GroupBox with any WPF control using property element syntax. This can include layout controls, such as Grids or StackPanels, or interactive controls, such as buttons. To demonstrate, replace the XAML of the first GroupBox with that shown below. This replaces the header text with a StackPanel. The StackPanel contains two Labels. The first label uses the Wingdings font to display an icon that represents a mouse. In a real application you might decide to use a vector or bitmap image in place of the Wingdings character.

<GroupBox>
    <GroupBox.Header>
    <StackPanel Orientation="Horizontal">
        <Label FontFamily="Wingdings" FontSize="17">8</Label>
        <Label>Mouse Handedness</Label>
    </StackPanel>
    </GroupBox.Header>

    <StackPanel>
        <RadioButton Content="Left-Handed" Margin="5"/>
        <RadioButton Content="Right-Handed" Margin="5" IsChecked="True"/>
    </StackPanel>
</GroupBox>

Executing the updated program gives the following results. You can see the mouse icon within the GroupBox caption.