Pointer events fire for UI interactions with a pointing device. Similar to mouse events, pointer events provide additional information about the used input device, such as pen pressure or tilt angle.
Pointer events always precede mouse events in UI Toolkit.
Pointer events don’t have a persistent position. They also don’t have a set position when they’re released from the touch device.
Some pointer events, such as PointerStationaryEvent and PointerCancelEvent events, have conditions triggered by the operating system (OS) of the input device.
The base class for all pointer events is PointerEventBase.
The following table describes the pointer events and their propagation phases:
| Event | Description | Trickles down | Bubbles up | Cancellable |
|---|---|---|---|---|
| PointerDownEvent | Sent when you press a pointer. | Yes | Yes | Yes |
| PointerUpEvent | Sent when you release a pointer. | Yes | Yes | Yes |
| PointerMoveEvent | Sent when the pointer changes state. | Yes | Yes | Yes |
| PointerEnterEvent | Sent when the pointer enters a visual elementA node of a visual tree that instantiates or derives from the C# VisualElement class. You can style the look, define the behaviour, and display it on screen as part of the UI. More infoSee in Glossary, or one of its descendants. |
Yes | No | Yes |
| PointerLeaveEvent | Sent when the pointer leaves a visual element and all of its descendants. | Yes | No | Yes |
| PointerOverEvent | Sent when the pointer enters a visual element. | Yes | Yes | Yes |
| PointerOutEvent | Sent when the pointer leaves a visual element. | Yes | Yes | Yes |
| PointerStationaryEvent | Sent when a pointer type (like a stylus or finger) doesn’t change for a set amount of time determined by the operating system. | Yes | Yes | Yes |
| PointerCancelEvent | Sent when a pointer action is cancelled by the operating system. | Yes | Yes | Yes |
altitudeAngle: Contains the angle of the stylus relative to the surface, in radians. A value of 0 indicates that the stylus is parallel to the surface. A value of pi/2 indicates that it’s perpendicular to the surface.
azimuthAngle: Contains the angle of the stylus relative to the x-axis, in radians. A value of 0 indicates that the stylus points along the x-axis of the device.
button: Contains an integer that identifies the mouse button pressed to trigger the event. The following table lists the integer and associated mouse button:
| Integer | Button |
|---|---|
| 0 | Left button |
| 1 | Right button |
| 2 | Middle button |
clickCount: Contains the number of times the button is pressed.
deltaPosition: Contains the difference between the pointer’s position during the previous mouse event and its position during the current mouse event.
deltaTime: Contains the amount of time that has passed because of the last recorded change in pointer values, in seconds.
localPosition: Returns the pointer position relative to the target visual element.
modifiers: Returns the modifier key currently held down. Some examples of modifiers are the Shift, Ctrl, or Alt keys. For more information, refer to the Modifier keys section of the MDN documentation.
pointerId: Returns an integer that identifies the pointer that sends the event.
pointerType: Returns a string that defines the type of pointer that creates the event.
position: Returns the pointer position in the screen or world coordinate system.
pressedButtons: Returns an integer that identifies which combination of mouse buttons are currently pressed.
The number is the sum of the individual buttons’ integer value (refer to the table below). For example, holding the right mouse button and the middle mouse button pressed at the same time will result in pressedButtons having a value of 6.
| Integer | Button |
|---|---|
| 1 | Left button |
| 2 | Right button |
| 4 | Middle button |
pressure: Returns the amount of pressure currently applied by a touch. If the device doesn’t report pressure, the value of this property is 1.0f.
radius: Returns an estimate of the radius of a touch. Add radiusVariance to get the maximum touch radius, subtract it to get the minimum touch radius.
radiusVariance: Determines the accuracy of the touch radius. Add this value to the radius to get the maximum touch radius, subtract it to get the minimum touch radius.
tangentialPressure: Returns a float value representing the pressure applied to an additional pressure-sensitive control on the stylus.
twist: Returns the rotation of the stylus around its axis, in radians.
The following list provides the name, description, and target of each event in the event family. For more information on the event, refer to the UI Toolkit API.
The PointerDownEvent is sent when you press a pointer inside a visual element.
target: The visual element that receives the pointer capture. Otherwise, it’s the topmost selectable element under the cursor.
A PointerUpEvent triggers when you release a pointer within a visual element.
When the PointerUpEvent event triggers, it also removes the pointer coordinates. It also clears the cache of the pointer, so there’s no record of the pointer location.
target: The visual element that receives the pointer capture. Otherwise, it’s the topmost selectable element under the cursor.
The PointerMoveEvent occurs when the pointer changes state.
target: The visual element that receives the pointer capture. Otherwise, it’s the topmost selectable element under the cursor.
The PointerEnterEvent is sent when the pointer enters a visual element, or one of its descendants.
target: The visual element (or one of its descendants) that the pointer exits.
A PointerLeaveEvent is sent when the pointer leaves a visual element and all its descendants. For example if a visual element contains a child, then the parent element receives this event when the pointer is no longer over either the parent or the child. The parent element doesn’t receive the PointerLeaveEvent while the pointer is still over one of its child elements, even if it’s no longer the topmost element underneath the pointer. It receives the PointerOverEvent instead.
target: The visual element (or one of its descendants) that the pointer exits.
The PointerOverEvent is sent when the pointer enters a visual element.
target: The visual element under the pointer.
The PointerOutEvent is sent when the pointer leaves a visual element.
target: The visual element that the pointer exits.
The PointerStationaryEvent is sent when a pointer type (like a stylus or finger) doesn’t change for a set amount of time determined by the operating system.
target: The visual element that captures the pointer, or the topmost selectable element under the pointer.
The PointerCancelEvent is sent when a pointer action is cancelled by the operating system.
target: The visual element that captures the pointer, or the topmost selectable element under the pointer.
The following code sample creates an Editor window with a red box containing a yellow box. It prints messages to the console when the pointer leaves a visual element or its child. It demonstrates the behavior of the PointerOutEvent and the PointerLeaveEvent.
To see the example in action, do the following:
<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance" engine="UnityEngine.UIElements" editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
<ui:VisualElement style="flex-grow: 1; justify-content: center; align-items: center;">
<ui:VisualElement name="Red_Box" style="background-color: rgb(183, 34, 46); width: 50%; height: 50%; align-items: center; justify-content: center;">
<ui:VisualElement name="Yellow_Box" style="width: 175%; height: 50%; background-color: rgb(197, 163, 0);" />
</ui:VisualElement>
</ui:VisualElement>
</ui:UXML>
using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;
using UnityEditor.UIElements;
public class PointerEventsTestWindow : EditorWindow
{
[MenuItem("Window/UI Toolkit/Pointer Events Test Window")]
public static void ShowExample()
{
PointerEventsTestWindow wnd = GetWindow<PointerEventsTestWindow>();
wnd.titleContent = new GUIContent("Pointer Events Test Window");
}
public void CreateGUI()
{
// Import UXML
VisualTreeAsset visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("Assets/Scripts/Editor/PointerEventsTestWindow.uxml");
visualTree.CloneTree(rootVisualElement);
// Get the red box and register pointer event callbacks
VisualElement redBox = rootVisualElement.Q("Red_Box");
redBox.RegisterCallback<PointerOutEvent>(OnPointerOutEvent, TrickleDown.TrickleDown);
redBox.RegisterCallback<PointerLeaveEvent>(OnPointerLeaveEvent, TrickleDown.TrickleDown);
}
private void OnPointerLeaveEvent(PointerLeaveEvent evt)
{
Debug.Log($"Pointer LEAVE Event. Target: {(evt.target as VisualElement).name}");
}
private void OnPointerOutEvent(PointerOutEvent evt)
{
Debug.Log($"Pointer OUT Event. Target: {(evt.target as VisualElement).name}");
}
}