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}");
}
}
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.