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 - UIElement - Mouse Events

The twenty-third instalment of the Windows Presentation Foundation Fundamentals tutorial continues the examination of the UIElement class, which is a superclass of all WPF layout controls, as well as other WPF controls. This article is about mouse events.

Capturing Mouse Wheel Scrolling

The last type of mouse operation that we'll consider is the use of the mouse wheel. This has various uses depending upon the type of application that you are developing. Often moving the mouse wheel forwards, away from you, will scroll a scroll box or zoom in to some information. Moving the wheel towards you might scroll downwards or zoom out. However, there are many other ways in which you might utilise the wheel once you have access to the raw data via the MouseWheel event.

Let's begin by simply detecting that the wheel has been moved. Amend the XAML first:

<StackPanel Margin="20"
            Background="BlueViolet"
            MouseDown="StackPanel_MouseDown"
            MouseUp="StackPanel_MouseUp"
            MouseLeftButtonDown="StackPanel_MouseLeftButtonDown"
            MouseLeftButtonUp="StackPanel_MouseLeftButtonUp"
            MouseRightButtonDown="StackPanel_MouseRightButtonDown"
            MouseRightButtonUp="StackPanel_MouseRightButtonUp"
            MouseEnter="StackPanel_MouseEnter"
            MouseLeave="StackPanel_MouseLeave"
            MouseMove="StackPanel_MouseMove"
            MouseWheel="StackPanel_MouseWheel">

Now we can add the C# event code:

private void StackPanel_MouseWheel(object sender, MouseWheelEventArgs e)
{
    Debug.WriteLine("Wheel");
}

Run the program to see the results. You will see that the MouseWheel event is raised repeatedly during wheel movement if the mouse pointer is within the StackPanel's rectangle.

This isn't particularly useful. You normally need to understand the direction of travel of the wheel in order to decide upon the action that should be taken. You also need to know how quickly the wheel was moved if your application responds differently to rapid and slow movements. This information can be obtained from the event arguments.

MouseWheel includes an event arguments object of the MouseWheelEventArgs type. Within the object is the Delta property. This holds an integer value indicating the direction and distance that the wheel moved. If the wheel was rotated upwards, or away from the user, the value is positive. For movements towards the user, the value is negative. The larger the absolute value, the greater distance the wheel was moved.

Let's show the Delta value within the debug messages. Amend the event's method as follows and run the program again to see the results.

private void StackPanel_MouseWheel(object sender, MouseWheelEventArgs e)
{
    Debug.WriteLine("Wheel: {0}", e.Delta);
}

NB: The size of the value is related both to the speed of wheel rotation and the configuration of the mouse. Larger numbers may indicate that the wheel is being moved quickly or has a high sensitivity. Faster movement may cause larger numbers or repeated raising of events with lower absolute Deltas.

MouseEventArgs

All of the events described above include an event arguments parameter. Most use the MouseEventArgs class directly. Several of the events provide an object of either the MouseButtonEventArgs or MouseWheelEventArgs types, both of which are subclasses of MouseEventArgs. This means that for all of the mentioned events we can obtain additional information about the mouse pointer or the user's action using the same set of properties and methods. We'll examine just a few of these members in the remainder of this article.

Identifying Button Usage

We've seen that there are two specific events for detecting that the pressing or release of the left or right mouse buttons. There's also a pair of events that are raised when any button is used but we didn't see how to determine which button.

We can identify the states of five buttons using five properties. These are LeftButton, RightButton, MiddleButton, XButton1 and XButton2. The meanings of the first three properties should be self-explanatory. XButton1 and XButton2 are the extended buttons. As these are not present on all devices, you should ensure that any functionality you provide for these buttons is also available by some other means.

The five button properties return a value from the MouseButtonState enumeration. This includes two named values. Pressed indicates that the button was pressed at the time that the event was raised. Released means that the button was not pressed. It is possible for more than one button to be in the Pressed state during a mouse event.

To demonstrate, let's show the mouse button states when the MouseDown event is triggered by modifying the method as follows:

private void StackPanel_MouseDown(object sender, MouseButtonEventArgs e)
{
    Debug.WriteLine("Mouse Down");
    Debug.WriteLine("* Left: {0}", e.LeftButton);
    Debug.WriteLine("* Middle: {0}", e.MiddleButton);
    Debug.WriteLine("* Right: {0}", e.RightButton);
    Debug.WriteLine("* X1: {0}", e.XButton1);
    Debug.WriteLine("* X2: {0}", e.XButton2);
}

Run the program and click the StackPanel with various buttons to see the results. Also try holding one button whilst clicking another to see that you can have multiple button properties returning Pressed for a single invocation.

NB: The five properties are available within any mouse event. This means you can check the state of the buttons during, for example, mouse movement or operation of the mouse wheel.

4 August 2013