You can respond to mouse input in your Windows Store apps built for Windows using C++, C#, or Visual Basic by handling the same events that you use for touch and pen input.
These events enable you to implement basic input functionality without having to write separate code for each input device. However, you can also take advantage of the special capabilities of each device if you choose to. For example, you can respond to mouse wheel events.
This topic assumes you have a basic understanding of events as described in the Events and routed events overview.
Sample: For example code that demonstrates the events described in this topic, see the Input sample.
Roadmap: How does this topic relate to others? See:
User experience guidelines (best practices)
This topic covers the mouse, touch, and stylus input events, but there are a number of user experience guidelines you should keep in mind for specific scenarios. These guidelines are primarily focused on touch input, but there is also some relevance for mouse and stylus input. See below for details:
- Guidelines for user interaction
- Guidelines for optical zoom and resizing
- Guidelines for panning
- Guidelines for rotation
- Guidelines for semantic zoom
Input events
Windows Store apps using C++, C#, or Visual Basic can implement support for mouse, touch, and stylus input by using a variety of UIElement events. These events come in three different varieties: gesture, pointer, and manipulation events.
Gesture events
The following events correspond to high-level gestures. These events occur in addition to the lower-level events that occur for the same user actions. For example, the Tapped event occurs after the PointerPressed and PointerReleased events occur. In general, you should use one of the higher level events unless you need to respond to a specific portion of the gesture. For example, you might need to perform different actions for press and release.
| Event | Description |
|---|---|
| Tapped | Occurs when an element is clicked or tapped, unless its IsTapEnabled property is set to false. |
| RightTapped | Occurs when an element is right-clicked, or after a Holding event, unless the element's IsRightTapEnabled property is set to false. |
| DoubleTapped | Occurs when an element is clicked or tapped twice in succession, unless its IsDoubleTapEnabled property is set to false. |
| Holding | Occurs when the pointer is pressed and held on an element, unless the element's IsHoldingEnabled property is set to false. This event does not occur for mouse input. For equivalent mouse input, use RightTapped instead. |
Each of these events has its own event arguments type, but they all share some common members. In a handler for one of these events, you can determine whether the input came from mouse, touch, or pen by checking the PointerDeviceType property of the event argument. You can also determine the coordinates of the event relative to the screen or to a specified element by calling the GetPosition method of the event argument.
Pointer events
The following events correspond to lower-level gestures. Events at this level are similar to traditional mouse input events, but provide more information about the user input gesture and device.
| Event | Description |
|---|---|
| PointerCaptureLost | Occurs when an element loses contact with the pointer. |
| PointerEntered | Occurs after the pointer enters the bounds of an element. |
| PointerExited | Occurs after the pointer leaves the bounds of an element. |
| PointerMoved | Occurs when the pointer moves within the bounds of an element. |
| PointerPressed | Occurs when a press gesture occurs within the bounds of an element. |
| PointerReleased | Occurs when a release gesture occurs within the bounds of an element. |
| PointerWheelChanged | Occurs when the user changes the position of the mouse wheel. |
Using PointerRoutedEventArgs
All pointer events use PointerRoutedEventArgs for event data. In addition to the familiar Handled and OriginalSource properties, this class provides the following members:
| Member | Description |
|---|---|
| Pointer property | Gets a Pointer object that identifies the input device and device type. |
| GetCurrentPoint method | Gets a PointerPoint object that provides extensive info about the pointer location and device state at the time of the event. |
| GetIntermediatePoints method | Gets a list of PointerPoint objects that represent the locations and device states of the pointer between the current and previous input events. This is useful for determining whether a series of pointer actions represents a more complex gesture. |
| KeyModifiers property | Indicates whether a modifier key such as Control or Shift is pressed at the same time as the pointer event. |
Pointer capture
In some cases, you want an element to continue to receive PointerMoved events even when the pointer is no longer above the element. This is called pointer capture. It is useful, for example, when the user performs a drag operation that should not be interrupted simply because the user momentarily moves the pointer outside the bounds of an element. When an element has pointer capture, the PointerMoved event does not occur for any other elements that the pointer moves over.
You can use the CapturePointer, ReleasePointerCapture, and ReleasePointerCaptures methods to enable or disable pointer capture. This works even with multiple input devices or touch points. While pointer capture is in effect, you can use the PointerCaptures property to retrieve Pointer objects that represent each captured pointer.
Pointer capture requires that the left mouse button, finger, or stylus button remain pressed for the duration of the movement. As soon as the button is released or the finger lifted, pointer capture is lost, and the PointerCaptureLost event occurs.
Manipulation events
The following events correspond to even lower-level gestures. Events at this level provide the most information about the user input gesture.
| Event | Description |
|---|---|
| ManipulationStarting | Occurs when the manipulation processor is first created. |
| ManipulationStarted | Occurs when an input device begins a manipulation on the UIElement. |
| ManipulationDelta | Occurs when the input device changes position during a manipulation. |
| ManipulationInertiaStarting | Occurs when the input device loses contact with the UIElement object during a manipulation and inertia begins. |
| ManipulationCompleted | Occurs when a manipulation and inertia on the UIElement are complete. |
As their names imply, these events are suitable for using mouse, touch, and pen input to manipulate elements in your UI. For example, you can use these events to enable users to drag elements around the screen, and to provide realistic inertial effects. The various event argument classes provide detailed info on pointer position, change, and velocity, in addition to common properties such as PointerDeviceType, Handled, and OriginalSource.
For a simple example using the manipulation events, see Quickstart: Touch input.
Hit testing
When a user input gesture occurs over a UIElement, the corresponding events occur for that element only if it is visible to the input. Otherwise, the gesture passes through the element to any underlying elements or parent elements in the visual tree.
Determining whether an element is visible to mouse, touch, and stylus input is called hit testing. There are several factors that affect hit testing, but you can determine whether a given element can raise input events by checking its IsHitTestVisible property. This property returns true only if the element meets the following criteria:
- Its Visibility property value is Visible.
- Its Background or Fill property value is not null (Nothing in Visual Basic), which results in transparency and hit test invisibility. To make an element transparent and hit testable, be sure the relevant property is set to Transparent instead null.
- If the element is a control, its IsEnabled property value is true.
Some controls have special rules for hit testing. For example, TextBlock and related controls have no Background property, but they are still hit testable within the entire region of their layout slot. Image and MediaElement controls are hit testable over their defined rectangle, regardless of transparent content. Also, most Panel classes are not hit testable, but can still handle user input events routed from elements that they contain.
You can determine which elements are located at the same position as a user input event, regardless of whether the elements are hit testable. To do this, call the FindElementsInHostCoordinates method. As the name implies, this method finds the elements at a location relative to a specified host element. However, you should be aware that applied transforms and layout changes can affect the coordinate system of an element, and therefore affect which elements are found at a given location.
Related topics
- Roadmaps
- Roadmap for creating apps using C#, C++, or VB
- Roadmap for Windows Store apps using C++
- Samples
- Input sample
- Reference
- UIElement
- FindElementsInHostCoordinates
- Concepts
- Events and routed events overview
- Quickstart: Touch input
- Responding to keyboard input
Build date: 11/29/2012
