Pointer events fire for UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary 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.
| 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 | Yes | |
| PointerLeaveEvent | Sent when the pointer leaves a visual element and all of its descendants. | Yes | 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: The 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: The azimuthAngle contains the angle of the stylus relative x-axis, in radians. A value of 0 indicates that the stylus points along the x-axis of the device.
button: The button property returns 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: The clickCount property contains the number of times the button is pressed.
deltaPosition: The deltaPosition property contains the difference between the pointer’s position during the previous mouse event and its position during the current mouse event.
deltaTime: The deltaTime property contains the amount of time that has passed since the last recorded change in pointer values, in seconds.
localPosition: The localPosition property returns the pointer position relative to the target visual element.
modifiers: The modifiers property returns the modifier key currently held down. Some examples of modifiers are the Shift, Ctrl, or Alt keys. For more information, see the Modifier keys section of the MDN documentation.
pointerId: The pointerId property returns an integer that identifies the pointer that sends the event.
pointerType: The pointerType property returns a string that defines the type of pointer that creates the event.
position: The position property returns the pointer position in the screen or world coordinate system.
pressedButtons: The pressedButton property returns an integer that identifies which combination of mouse buttons are currently pressed.
The number is the sum of the individual buttons’ integer value (see table below). For example, holding the right mouse button and the middle mouse button pressed at the same time will result in pressedButton having a value of 6.
| Integer | Button |
|---|---|
| 1 | Left button |
| 2 | Right button |
| 4 | Middle button |
pressure: The pressure property 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: The radius property 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: The radiusVariance property value 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: The tangentialPressure property returns a float value representing the pressure applied to an additional pressure-sensitive control on the stylus.
twist: The twist property 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, see 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 will receive this event when the pointer is no longer over either the parent or the child. The parent element won’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 will receive 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}");
}
}