.NET 4.0+

WPF Base Classes - UIElement - Mouse Events

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

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.

UIElement

The UIElement class is a standard base class for WPF controls, including all of the layout controls that we've looked at so far in this tutorial. UIElement provides a great deal of functionality to controls, so much so that it requires several articles to examine the key methods, properties and events. In an earlier article we looked at the UIElement Keyboard events, which allow you to identify when a key is pressed or released. We followed this with an article about the UIElement visibility and status properties.

In this article we'll look at the mouse events. These allow you to identify user interactions via mouse movements, clicks and wheel operations. To demonstrate, we'll need a sample project. Start Visual Studio and create a new WPF application project, naming it "UIElementMouseDemo". Replace the XAML of the initial window with that shown below. This places a StackPanel within the window, with a margin so that you can easily see the control's boundaries.

<Window x:Class="UIElementMouseDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="UIElement Demo"
        Width="250"
        Height="200">
    <StackPanel Margin="20" Background="BlueViolet">
    </StackPanel>
</Window>

The resultant window should appear as shown below:

MouseUp and MouseDown

In the article describing the UIElement's keyboard operations we looked at the KeyDown and KeyUp events. These allow you to identify when a key has been pressed or released and which key was used. A pair of similar events exists for detecting when a mouse button is pressed. These are MouseUp and MouseDown.

To show the use of MouseDown and MouseUp, let's just see the events being raised. Later in this article we'll look at the event arguments, which allow you to find out more information about these, and other, mouse events.

Let's add the events to the StackPanel control. To do so, modify the StackPanel's opening XAML tag as follows:

<StackPanel Margin="20"
            Background="BlueViolet"
            MouseDown="StackPanel_MouseDown"
            MouseUp="StackPanel_MouseUp">

We need some code to execute when a mouse button is pressed or released. We'll simply write the details of the event as a debug message. Add the following two methods to the code behind the window.

private void StackPanel_MouseDown(object sender, MouseButtonEventArgs e)
{
    Debug.WriteLine("Mouse Down");
}

private void StackPanel_MouseUp(object sender, MouseButtonEventArgs e)
{
    Debug.WriteLine("Mouse Up");
}

The Debug class is found in the System.Diagnostics namespace, so ensure that you include the following using directive:

using System.Diagnostics;

To see the events in action, run the program in the debugger. Make sure that you can see the output window. If you cannot, open the Debug menu, choose "Windows" and select "Output". Once the window is visible, try clicking the StackPanel control. You should see that both events are fired for each click. If you click and hold a mouse button, you'll see only the "Mouse Down" message.

Note that pressing the mouse button within the StackPanel but releasing it elsewhere shows only the "Mouse Down" and not the "Mouse Up" message. You can see the reverse of this by pressing a button within the white margin around the StackPanel and moving the mouse pointer into the StackPanel's rectangle before releasing the button.

You can use the events to detect clicks for controls that do not have a true click event. To follow the expected click behaviour of Microsoft Windows you need to ensure that you detect both events within the confines of a single control. If the user presses but does not release the button within the control, this should not usually represent a click.

The MouseDown and MouseUp events are triggered when the user presses any mouse button. We'll later see how to identify which buttons were manipulated.