BlackWaspTM

This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

Windows Presentation Foundation
.NET 4.0+

WPF Layout Controls - GridSplitter

The seventh part of the Windows Presentation Foundation Fundamentals tutorial takes a look at another WPF layout control. This article explains the use of the GridSplitter, which allows Grid columns and rows to be resized using the mouse or keyboard.

Adding a Row Splitter

Let's add a horizontal splitter to our example to see the difference in its configuration. To make a splitter resize rows instead of columns we can align it to the top or bottom of the cell, whilst setting the horizontal alignment to be stretched. We could also specify the ResizeDirection as Rows.

The XAML below creates a grid with two columns and two rows. In the first column I've added a TextBlock that spans two rows, filling an area that is the entire height of the grid. The right column retains two separate cells, each with a message.

The first GridSplitter separates the two columns and allows them to be resized. It is placed at the right side of the first grid cell and spans two rows so that the vertical bar fills the table height. You don't have to add the row spanning. If you omitted this property the vertical splitter would extend to just the height of the top cell. However, dragging the splitter would still resize the entire column.

The second splitter appears at the bottom of the cell at the top-right of the grid and is stretched to the cell width. This means that we don't have to specify the resize direction. Note that the Height property must be used rather than the Width for horizontal GridSplitters.

<Grid>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="1*"/>
        <ColumnDefinition Width="2*"/>
    </Grid.ColumnDefinitions>
    <Grid.RowDefinitions>
        <RowDefinition/>
        <RowDefinition/>
    </Grid.RowDefinitions>

    <TextBlock Grid.Column="0"
               Text="This text is on the left."
               TextWrapping="Wrap"
               Background="LightYellow"
               Grid.RowSpan="2"/>
    <TextBlock Grid.Column="1"
               Text="This text is at the top right."
               TextWrapping="Wrap"
               Background="AliceBlue"/>
    <TextBlock Grid.Column="1"
               Grid.Row="1"
               Text="This text is at the bottom right."
               TextWrapping="Wrap"
               Background="AliceBlue"/>

    <GridSplitter Width="5"
                  Grid.Column="0"
                  Grid.RowSpan="2"
                  HorizontalAlignment="Right"
                  VerticalAlignment="Stretch"
                  Background="Red"/>
    <GridSplitter Height="5"
                  Grid.Column="1"
                  HorizontalAlignment="Stretch"
                  VerticalAlignment="Bottom"
                  Background="Green"/>
</Grid>

Running the program gives results similar to those shown below. Try resizing the columns and rows using the mouse or the four arrow keys.

WPF GridSplitter with Split Columns and Rows

Previews

In the default configuration, during a resize of a pair of columns or rows, the content of the modified cells is re-rendered as you resize. This allows the user to immediately see the results of the change. However, it can cause problems. If the content of the cells is particularly complex, or if the information is being viewed via a slow remote connection you may see flickering or excessive, slow refreshing.

To stop this type of issue you can switch the GridSplitter's preview mode using the ShowsPreview property. The default value for this Boolean property is false, indicating that the contents of cells should be updated as their size changes. When changed to false, a shadow of the splitter moves when you resize columns or rows. The original GridSplitter position is still displayed and the contents of the cells remain the same. When you release the mouse button to end the drag operation the cells resize and redraw just once.

To see this in action try modifying the first GridSplitter's XAML to that shown below:

<GridSplitter Width="5"
              Grid.Column="0"
              Grid.RowSpan="2"
              HorizontalAlignment="Right"
              VerticalAlignment="Stretch"
              Background="Red"
              ShowsPreview="True"/>

The image below shows a grey bar, or shadow, representing the new position of the columns, which will resize when the mouse button is released.

WPF GridSplitter with ShowsPreview set to True

Sizing Increments

So far our examples have included GridSplitters that can be moved smoothly, allowing pixel-perfect positioning. In some cases you might not want this behaviour, instead preferring that the GridSplitter position be "stepped", with a fixed number of pixels between each possible location. You can control this with two properties. DragIncrement can be set to the size of each step when dragging the splitter using the mouse. To change the size of the steps when resizing with the keyboard, set the KeyboardIncrement property.

For the final example modify the horizontal GridSplitter's XAML element to add these two properties, as follows. When you execute the program you should find that the splitter can only be moved in steps of ten pixels.

<GridSplitter Height="5"
              Grid.Column="1"
              HorizontalAlignment="Stretch"
              VerticalAlignment="Bottom"
              Background="Green"
              DragIncrement="10"
              KeyboardIncrement="10"/>
20 March 2013