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.

Detecting the Left and Right Mouse Buttons

The concept of left and right when applied to mouse buttons is somewhat misleading. Ideally, you should think of a primary button, which is usually the left button, and a secondary button, which is usually on the right of the mouse. However, these roles are often reversed for left-handed users using configuration options in the Control Panel. Unfortunately, the left and right naming convention is used for two pairs of events that detect the primary and secondary button clicks. The four events are LeftMouseButtonDown and LeftMouseButtonUp for the primary button, RightMouseButtonDown and RightMouseButtonUp for the secondary button.

The events use a similar syntax to MouseUp and MouseDown, with the same type of event arguments. The key difference is that the "Left" events only fire when the primary button is used and the "Right" events are raised for the secondary button. No button-specific events are available for the middle button or any extended buttons.

To add the four events to the StackPanel, modify its opening XAML tag:

<StackPanel Margin="20"
            Background="BlueViolet"
            MouseDown="StackPanel_MouseDown"
            MouseUp="StackPanel_MouseUp"
            MouseLeftButtonDown="StackPanel_MouseLeftButtonDown"
            MouseLeftButtonUp="StackPanel_MouseLeftButtonUp"
            MouseRightButtonDown="StackPanel_MouseRightButtonDown"
            MouseRightButtonUp="StackPanel_MouseRightButtonUp">

Now add code for the events:

private void StackPanel_MouseLeftButtonDown(object sender, MouseButtonEventArgs e)
{
    Debug.WriteLine("Left Button Down");
}

private void StackPanel_MouseLeftButtonUp(object sender, MouseButtonEventArgs e)
{
    Debug.WriteLine("Left Button Up");
}

private void StackPanel_MouseRightButtonDown(object sender, MouseButtonEventArgs e)
{
    Debug.WriteLine("Right Button Down");
}

private void StackPanel_MouseRightButtonUp(object sender, MouseButtonEventArgs e)
{
    Debug.WriteLine("Right Button Up");
}

Try running the program and clicking the left and right buttons. If you click the primary button once, followed by the secondary button once, you'll see the following output. This shows that all six of the events that we've added operate together.

Left Button Down
Mouse Down
Left Button Up
Mouse Up
Right Button Down
Mouse Down
Right Button Up
Mouse Up

MouseEnter and MouseLeave

There's much more to mouse interaction than clicking. You can also detect movement. One common task is detecting when the mouse pointer moves into or out of a control, with or without a mouse button being clicked. These actions can be identified using the MouseEnter and MouseLeave events. MouseEnter executes when the mouse pointer moves into a non-transparent area of the control and MouseLeave runs when the pointer moves away from the control.

To add the events to the XAML, modify the StackPanel opening tag, as follows:

<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">

For the code let's add more debug messages:

private void StackPanel_MouseEnter(object sender, MouseEventArgs e)
{
    Debug.WriteLine("Enter");
}

private void StackPanel_MouseLeave(object sender, MouseEventArgs e)
{
    Debug.WriteLine("Leave");
}

Now start the project and try moving the mouse pointer over the StackPanel to see the output.

Detecting Mouse Movement

Aside from detecting when the mouse pointer enters or leaves a control, you can also track any movement within a control's area, using the MouseMove event. This event is raised every time the moves over a control by any distance. It is not raised if the mouse is stationary.

To demonstrate, first register the event in the StackPanel's XAML:

<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">

For the moment we'll output a message indicating that movement has taken place each time the event fires:

private void StackPanel_MouseMove(object sender, MouseEventArgs e)
{
    Debug.WriteLine("Move");
}

Run the program again and move the mouse within the control's area. You will see that the Move event is raised repeatedly whilst the pointer is in motion within the StackPanel's area.

4 August 2013