UIElement.PointerEntered Event
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Occurs when a pointer enters the hit test area of this element.
public:
virtual event PointerEventHandler ^ PointerEntered;// Register
event_token PointerEntered(PointerEventHandler const& handler) const;
// Revoke with event_token
void PointerEntered(event_token const* cookie) const;
// Revoke with event_revoker
UIElement::PointerEntered_revoker PointerEntered(auto_revoke_t, PointerEventHandler const& handler) const;public event PointerEventHandler PointerEntered;function onPointerEntered(eventArgs) { /* Your code */ }
uIElement.addEventListener("pointerentered", onPointerEntered);
uIElement.removeEventListener("pointerentered", onPointerEntered);
- or -
uIElement.onpointerentered = onPointerEntered;Public Custom Event PointerEntered As PointerEventHandler <uiElement PointerEntered="eventhandler"/>
Event Type
Remarks
The PointerEntered event fires in response to a pointer moving into the element's bounding area. Touch, mouse, and pen/stylus interactions are received, processed, and managed as pointer input in UWP app. Any of these devices and their interactions can produce a PointerEntered event. For more info, see Handle pointer input and also the other remarks in this topic.
PointerEntered is a routed event. For more info on the routed event concept, see Events and routed events overview.
Use a handler based on PointerEventHandler to handle this event.
For touch actions and also for interaction-specific or manipulation events that are consequences of a touch action, an element must be hit-test visible in order to be the event source and fire the event that is associated with the action. UIElement.Visibility must be Visible. Other properties of derived types also affect hit-test visibility. For more info, see Events and routed events overview.
PointerEntered supports the ability to attach event handlers to the route that will be invoked even if the event data for the event is marked Handled. See AddHandler.
Specific Windows Runtime controls may have class-based handling for the PointerEntered input event. If so, the control probably has an override for the method OnPointerEntered. Typically the event is not marked handled by the class handler, so the PointerEntered event can still be handled by your user code for the control in your UI. For more info on how class-based handling for events works, see Events and routed events overview.
PointerEntered for mouse and pen/stylus input
A mouse input device has an onscreen cursor that is visible whenever the mouse moves, even if no mouse button is pressed at the time. A PointerEntered event will precede the first PointerMoved event fired by the element. Similar behavior is available for pen device input, where the input devices can detect that the stylus is hovering just over the input device surface (IsInRange) but not touching it. Mouse and pen device input will thus fire PointerEntered events in slightly different cases than touch events do. For more info, see Mouse interactions.
PointerEntered for touch input
A touch point is only detectable if a finger is touching the surface. Whenever a touch action results in a PointerPressed event, that event is immediately preceded by a PointerEntered event, with all the event data being the same information for the two events (same pointer ID, same position, and so on.) In other words the pointer is considered to enter the element at the moment and position that the element is touched by a touch point.
Alternatively, a touch point will generate PointerEntered if a pointer remains in constant contact with the surface as it moves, and enters the hit testing bounds of an element. For these kinds of touch actions it's also possible that the action could be processed as a manipulation, or as a gesture, rather than a pointer event. For more info, see Handle pointer input.
Routed event behavior for PointerEntered
PointerEntered is a routed event. For more info on the routed event concept, see Events and routed events overview. You can define multiple PointerEntered events for elements in a XAML UI, including for elements that are in a parent-child relationship. In a typical UI composition, the child elements are somewhere within a parent element's bounds, so the PointerEntered event will first occur for the parent when the pointer moves into the parent, and then for the child when the pointer moves there. The PointerEntered event doesn't typically bubble to the parent when the child element fires it, because conceptually the pointer is already within the parent bounds and it would be confusing for the input system to route the PointerEntered event occurrence to the parent too. Typically you don't want PointerEntered events to route anyways, you only want to process them from the sender. You can explicitly prevent event routing by setting Handled to true in your handler.
In rare cases it's possible to see a PointerEntered event bubble to the parent. For example, if you've used a RenderTransform to offset a child element outside the bounds of its parent, the event bubbles to the parent when the child element is entered, and gives the event info as reported by how the child element fired the event.
Pointer capture
If another element has captured the pointer, PointerEntered won't fire even if the captured pointer enters an element's bounds. However, if pointer capture is released while the pointer is over the element, PointerEntered will then fire, even thought the pointer might have remained stationary in this case. The value of GetCurrentPoint from event data might be a point somewhere in the middle of an element rather than a point along its edges because the pointer was already over the element when capture was released. For more info on pointer capture, see CapturePointer or Mouse interactions.
PointerOver visual states for controls
Controls that have control templates can apply visual states that are active only when a pointer is over the bounds of the control. You don't always need to handle PointerEntered or PointerExited to get or change this behavior. You may need to re-template the control. If you are deriving from an existing control that already has the low-level input handling that invokes visual states, you should provide a visual state named "PointerOver" in the "CommonStates" VisualStateGroup, and the built-in control logic will load that visual state whenever a pointer is over the control. A visual state for pointer-over is often present on controls that can be invoked or selected, like a Button or ListViewItem. If you're deriving from a base class like Control that doesn't have built-in input event handling that invokes visual states, you may need to override OnPointerEntered and OnPointerExited yourself to get this behavior. For more info, see Storyboarded animations for visual states.
Windows 8 behavior
For Windows 8, generally the PointerEntered event won't fire if the onscreen cursor (or stylus or touchpoint) did not actually move. For example, PointerEntered doesn't fire if the mouse and its onscreen cursor remains stationary, and an object with a PointerEntered handler has its position translated or otherwise adjusted to move underneath the onscreen cursor. Or, PointerEntered doesn't fire if an element like a popup or flyout disappears and the pointer is now over a new element (but pointer hasn't moved yet). Related to this is the PointerExited behavior. For example, if a popup is dismissed programmatically, it won't fire PointerExited if the pointer didn't move as the cause of dismissing it. You would still get a PointerEntered event if the pointer moves while over the newly revealed element, but that's up to the user whether that will happen, and it happens at the time of movement, not the moment of dismissal. In short, trying to use the last element that fired PointerEntered for pointer state determination in the app UI isn't comprehensive in Windows 8, and there are many scenarios where PointerEntered and PointerExited won't pair up. This impacts the visual states for controls that use PointerEntered and PointerExited as triggers also.
Starting with Windows 8.1, PointerExited is fired for any case where the pointer had at one time fired a PointerEntered event, but some UI state change happens where the pointer is no longer within that element. This includes cases where the whole element disappears. And if the pointer is now over a different element because a previous element disappeared, that element fires PointerEntered, even if the pointer never moves. Elements that set their Visibility to Collapsed programmatically is one way that elements might disappear from UI, and the Windows 8.1 behavior accounts for this and will fire PointerExited for the Collapsed element and PointerEntered for the newly revealed element.
If you migrate your app code from Windows 8 to Windows 8.1 you may want to account for this behavior change, because it results in PointerExited and PointerEntered being fired in cases where they wouldn't have fired before.
Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.