Mouse Input and the WPF

Attached Events

It is possible to define an attached event. This is the routed-event equivalent of an attached property: an event defined by a different class than the one from which the event will be raised. This keeps the input system open to extension. If a new kind of input device is invented, it could define new events as attached events, enabling them to be raised from any UI element.

In fact, the WPF input system already works this way. The mouse, stylus, and keyboard events examined in this chapter are just wrappers for underlying attached events defined by theMouse,Keyboard, andStylus classes in theSystem.Windows.Inputnamespace. This means we could change theGrid element in Example 4-1 to use the attached events defined by theMouseclass, as shown in Example 4-6.

Example 4-6. Attached event handling

<Grid Mouse.PreviewMouseDown="PreviewMouseDownGrid"
      Mouse.MouseDown="MouseDownGrid">

This would have no effect on the behavior, because the names Example 4-1 used for these events are aliases for the attached events used in this example.

Handling attached events from code looks a little different. Normal CLR events don’t support this notion of attached events, so we can’t use the ordinary C# event syntax like we did in Example 4-4. Instead, we have to call the AddHandlermethod, passing in theRoutedEventobject representing the attached event (see Example 4-7).

Example 4-7. Explicit attached event handling

myEllipse.AddHandler(Mouse.PreviewMouseDownEvent,
    new MouseButtonEventHandler(PreviewMouseDownEllipse)); myEllipse.AddHandler(Mouse.MouseDownEvent,
    new MouseButtonEventHandler(MouseDownEllipse));

Alternatively, we can use the helper functions provided by theMouseclass. Example 4-8 uses this to perform exactly the same job as the preceding two examples.

Example 4-8. Attached event handling with helper function

Mouse.AddPreviewMouseDownHandler(myEllipse, PreviewMouseDownEllipse); Mouse.AddMouseDownHandler(myEllipse, MouseDownEllipse);

Example 4-8 is more compact than Example 4-7 because we were able to omit the explicit construction of the delegate, relying instead on C# delegate type inference. Example 4-7 cannot do this because AddHandlercan attach a handler for any kind of event, so in its function signature the second parameter is of the baseDelegate type. By convention, classes that define attached events usually provide corresponding helper methods like these to let you use this slightly neater style of code.

Mouse Input

Mouse input is directed to whichever element is directly under the mouse cursor. All user interface elements derive from the UIElement base class, which defines a number of mouse input events. These are listed in Table 4-1.

Table 4-1. Mouse input events

In addition to the mouse-related events,UIElementalso defines a pair of properties that indicate whether the mouse pointer is currently over the element:IsMouseOverandIsMouseDirectlyOver. The distinction between these two properties is that the former will be true if the cursor is over the element in question or over any of its child elements, but the latter will be true only if the cursor is over the element in question but not one of its children.

Note that the basic set of mouse events shown in Table 4-1 does not include a Clickevent. This is because clicks are a higher-level concept than basic mouse input—a button can be “clicked” with the mouse, the stylus, the keyboard, or through the Windows accessibility API. Moreover, clicking doesn’t necessarily correspond directly to a single mouse event—usually, the user has to press and release the mouse button while the mouse is over the control to register as a click. Accordingly, these higher-level events are provided by more specialized element types. TheControl class adds aPreviewMouseDoubleClickandMouseDoubleClick event pair. Likewise,ButtonBase—the base class ofButton,CheckBox, andRadioButton—goes on to add aClick event.

Mouse Input and Hit Testing

WPF always takes the shapes of your elements into account when handling mouse input. Many graphical systems just use the rectangular bounding box of elements to perform hit testing (i.e., testing to see which element the mouse input “hit”). WPF does not employ this shortcut, no matter what shapes your elements may be. For example, if you create a donut-shaped control and click on the hole in the middle, the click will be delivered to whatever was visible behind your control through the hole.

Occasionally it is useful to subvert the standard hit testing behavior. You might wish to create a donut-shaped control with a visible hole, but which doesn’t let clicks pass through it. Alternatively, you might want to create an element that is visible to the user, but transparent to the mouse. WPF lets you do both of these things.

To achieve the first trick—transparent to the eye but opaque to the mouse—you can paint an object with a transparent brush. For example, anEllipsewith itsFillset toTransparent will be invisible to the eye, but not to the mouse. Alternatively, you can use a nontransparent brush, but make the whole element transparent by setting itsOpacityproperty to0. If a donut-shaped control paints such an ellipse over the hole, this enables it to receive any clicks on the hole. As far as the mouse is concerned, an element is a valid mouse target as long as it is painted with some kind of brush. The mouse doesn’t even look at the level of transparency on the brush, so it treats a completely transparent brush in exactly the same way as a completely opaque brush.

If you want a shape with a transparent fill that does not receive mouse input, simply supply noFillat all. For example, you might want the shape to have an outline but no fill. If theFillis null, as opposed to being a completely transparent brush, the shape will not act as an input target.

WPF supports the second trick—creating a visible object that is transparent to the mouse—with theIsHitTestVisibleproperty, which can be applied to any element. Setting this to false ensures that the element will not receive mouse input; instead, input will be delivered to whatever is under the element. For example, suppose you had written code to make some sort of graphical embellishment follow the mouse around, such as a semi-transparent ellipse to act as a halo for the pointer. SettingIsHitTestVisibleto false would ensure that this visual effect had no impact on the interactive behavior.

If you are using 3D (as described in Chapter 17), hit testing can be an expensive process. If you don’t require hit testing for your 3D content, making it invisible to hit testing can offer a useful performance boost.

Mouse State

As well as defining events, the Mouse class defines some static properties and methods that you can use to discover information about the mouse or modify its state.

TheGetPosition method lets you discover the position of the mouse. As Example 4-9 shows, you must pass in a user interface element. It will return the mouse position relative to the specified element, taking into account any transformations that may be in effect.

Example 4-9. Retrieving the mouse position

Point positionRelativeToEllipse = Mouse.GetPosition(myEllipse);

TheCapturemethod allows an element to capture the mouse. Mouse capture means that all mouse input events are sent to the capturing element, even if the mouse is currently outside of that element.* Example 4-10 captures the mouse to an ellipse when a mouse button is pressed, enabling it to track the movement of the mouse even if it moves outside of the ellipse. In fact, it will continue to receiveMouseMove events even if the mouse moves outside of the window. This is useful for drag operations, as the user will expect an item being dragged to follow the mouse for as long as the mouse button is pressed. The capture is released by passing null to theCapturemethod.

Example 4-10. Mouse capture

public Window1() {
    InitializeComponent();

    myEllipse.MouseDown += myEllipse_MouseDown;
    myEllipse.MouseMove += myEllipse_MouseMove;
    myEllipse.MouseUp += myEllipse_MouseUp; }

void myEllipse_MouseDown(object sender, MouseButtonEventArgs e) {
    Mouse.Capture(myEllipse);
}

void myEllipse_MouseUp(object sender, MouseButtonEventArgs e) {
    Mouse.Capture(null);
}

void myEllipse_MouseMove(object sender, MouseEventArgs e) {
    Debug.WriteLine(Mouse.GetPosition(myEllipse));
}

TheMouseclass provides aCaptured property that returns the element that has currently captured the mouse; it returns null if the mouse is not captured. You can also discover which element in your application, if any, the mouse is currently over, by using the staticMouse.DirectlyOverproperty.

Mouse provides five properties that reflect the current button state. Each returns aMouseButtonStateenumeration value, which can be eitherPressedorReleased. Three of these properties—LeftButton,MiddleButton, andRightButton—are self-explanatory. The other two—XButton1 andXButton2 —are perhaps less obvious. These are for the extra buttons provided on some mice, typically found on the side. The locations of these so-called extended buttons are not wholly consistent—one of the authors’ mice has these two buttons on the lefthand side, and another has one on each side. This explains the somewhat abstract property names.

Mousealso provides anOverrideCursorproperty that lets you set a mouse cursor to be shown throughout your whole application, as shown in Example 4-11. This overrides any element-specific mouse cursor settings. You could use this to temporarily show an hourglass cursor when performing some slow work.

Example 4-11. Temporary mouse cursor override

private void StartSlowWork() {
    Mouse.OverrideCursor = Cursors.AppStarting;
    ...
}

private void SlowWorkCompleted() {
    Mouse.OverrideCursor = null;
}

Please check back next week for the continuation of this article.