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.
myEllipse.AddHandler(Mouse.PreviewMouseDownEvent, new MouseButtonEventHandler(PreviewMouseDownEllipse)); myEllipse.AddHandler(Mouse.MouseDownEvent, new MouseButtonEventHandler(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 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
Event
Routing
Meaning
GotMouseCapture
Bubble
Element captured the mouse.
LostMouseCapture
Bubble
Element lost mouse capture.
MouseEnter
Direct
Mouse pointer moved into element.
MouseLeave
Direct
Mouse pointer moved out of element.
PreviewMouseLeftButtonDown, MouseLeftButtonDown
Tunnel, Bubble
Left mouse button pressed while pointer inside element.
PreviewMouseLeftButtonUp, MouseLeftButtonUp
Tunnel, Bubble
Left mouse button released while pointer inside element.
PreviewMouseRightButtonDown, MouseRightButtonDown
Tunnel, Bubble
Right mouse button pressed while pointer inside element.
PreviewMouseRightButtonUp, MouseRightButtonUp
Tunnel, Bubble
Right mouse button released while pointer inside element.
PreviewMouseDown, MouseDown
Tunnel, Bubble
Mouse button pressed while pointer inside element (raised for any mouse button).
PreviewMouseUp, MouseUp
Tunnel, Bubble
Mouse button released while pointer inside element (raised for any mouse button).
PreviewMouseMove, MouseMove
Tunnel, Bubble
Mouse pointer moved while pointer inside element.
PreviewMouseWheel, MouseWheel
Tunnel, Bubble
Mouse wheel moved while pointer inside element.
QueryCursor
Bubble
Mouse cursor shape to be determined while pointer inside element.
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.
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.
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.
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.
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.