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 Base Classes - Thumb

The thirty-seventh part of the Windows Presentation Foundation Fundamentals tutorial looks at another WPF control base type. This time it is the Thumb class, which defines functionality that is used by controls that the user can drag.

Thumb

The Thumb class is another base class that is subclassed by WPF layout controls and visual controls. It defines methods, properties and events for controls that can be dragged by the user, using a mouse or similar pointing device. The dragging is usually undertaken to resize or move controls. For example, GridSplitter is derived from Thumb and allows the user to resize columns or rows in a Grid. Thumbs are also used in other WPF controls, such as scroll bars.

In this article we'll look at several members of the Thumb class, demonstrating their use with a GridSplitter. To follow the examples, create a new WPF application project in Visual Studio. Name the project, "ThumbDemo". Once the solution is ready, replace the XAML of the main window with the code shown below. This defines a Grid with two columns that can be resized using a GridSplitter.

<Window x:Class="ThumbDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Thumb Demo"
        Width="250"
        Height="150">
    <Grid>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="1*"/>
            <ColumnDefinition Width="2*"/>
        </Grid.ColumnDefinitions>

    <TextBlock Name="LeftText"/>
    <TextBlock Name="RightText" Grid.Column="1"/>

    <GridSplitter Name="MyGridSplitter"
                  Background="Gray"
                  Width="5"
                  HorizontalAlignment="Right"
                  VerticalAlignment="Stretch" />
    </Grid>
</Window>

The window appears as follows when you run the program:

WPF Thumb Demo Window

Drag Events

The purpose of the Thumb class is to provide functionality related to dragging, so let's look at the dragging events first. There are three such events. The first two that we will consider are DragStarted and DragCompleted. As the names might suggest, DragStarted is raised when the user starts dragging a Thumb-based control. DragCompleted is raised when the user stops dragging and releases the mouse button.

DragStarted provides event arguments as a DragStartedEventArgs object. This includes properties that describe the start of the drag operation. Two key properties are HorizontalOffset and VerticalOffset. These return double-precision floating-point numbers that allow you to determine the position of the mouse pointer, relative to the co-ordinates of the control. For example, if the VerticalOffset is zero, the user positioned the mouse pointer at the very top of the control when they commenced dragging.

DragCompleted provides a DragCompletedEventArgs object. This includes several useful properties. HorizontalChange returns the distance that the control was dragged in the horizontal direction and VerticalChange gives a similar value for the vertical movement.

We can see this by adding the two events to our GridSplitter. Modify the XAML for the control as follows:

<GridSplitter Name="MyGridSplitter"
              Background="Gray"
              Width="5"
              HorizontalAlignment="Right"
              VerticalAlignment="Stretch"
              DragStarted="MyGridSplitter_DragStarted"
              DragCompleted="MyGridSplitter_DragCompleted"/>

Next, add the following code behind the Window.

private void MyGridSplitter_DragStarted(
    object sender, System.Windows.Controls.Primitives.DragStartedEventArgs e)
{
    LeftText.Text = "Dragging Started";
    MyGridSplitter.Background = Brushes.Red;
}

private void MyGridSplitter_DragCompleted(
    object sender, System.Windows.Controls.Primitives.DragCompletedEventArgs e)
{
    LeftText.Text = string.Format("Dragging Completed, moving {0}", e.HorizontalChange);
    MyGridSplitter.Background = Brushes.Gray;
}

Run the program and drag the GridSplitter to see the results. When you start dragging, the text in the left column will indicate that the DragStarted event was raised. When you release the mouse button the text will be updated to show the amount that the GridSplitter moved. Both events also update the colour of the GridSplitter so that it appears red whilst dragging.

23 November 2013