UIElement.PointerExited Event

  • Reference

Definition

Namespace:
Windows.UI.Xaml
Edit

Occurs when a pointer leaves the hit test area of this element.

public:
 virtual event PointerEventHandler ^ PointerExited;
// Register
event_token PointerExited(PointerEventHandler const& handler) const;

// Revoke with event_token
void PointerExited(event_token const* cookie) const;

// Revoke with event_revoker
UIElement::PointerExited_revoker PointerExited(auto_revoke_t, PointerEventHandler const& handler) const;
public event PointerEventHandler PointerExited;
function onPointerExited(eventArgs) { /* Your code */ }
uIElement.addEventListener("pointerexited", onPointerExited);
uIElement.removeEventListener("pointerexited", onPointerExited);
- or -
uIElement.onpointerexited = onPointerExited;
Public Custom Event PointerExited As PointerEventHandler 
<uiElement PointerExited="eventhandler"/>

Event Type

PointerEventHandler

Remarks

The PointerExited event fires in response to a pointer that was initially in the element's bounding area leaving that 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 PointerExited event. For more info, see Handle pointer input and the other remarks in this topic.

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.

PointerExited 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 PointerExited input event. If so, the control probably has an override for the method OnPointerExited. Typically the event is not marked handled by the class handler, so the PointerExited 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.

If another element has captured the pointer, PointerExited won't fire even if the captured pointer leaves an element's bounds. For more info on pointer capture, see CapturePointer or Mouse interactions.

PointerExited 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. 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 PointerExited events in slightly different cases than touch events do. For more info, see Mouse interactions. A PointerExited event fires after the last PointerMoved event for the element fires.

PointerExited for touch input

A touch point is only detectable if a finger is touching the surface. Whenever a touch action results in a PointerReleased event, that event is immediately followed by a PointerExited 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 PointerExited if that pointer remains in constant contact with the surface as it moves, was over the element initially, and then exits 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 PointerExited

PointerExited is a routed event. For more info on the routed event concept, see Events and routed events overview. You can define multiple PointerExited 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 PointerExited event will first occur for the child when the pointer moves out of the child, and then for the parent when the pointer moves completely out of that parent. The PointerExited event doesn't typically bubble to the parent when the child element fires it, because it would be confusing for the input system to route the PointerExited event occurrence to the parent too. Typically you don't want PointerExited 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 PointerExited 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 exited, and gives the event info as reported by how the child element fired the event.

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. Use OnPointerExited to call GoToState to load a state other than the "PointerOver" state, for example "Normal". 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.

Applies to

See also