Events in UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary Toolkit are similar to HTML events. When an event occurs, it’s sent to the target 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 info
See in Glossary and to all elements within the propagation path in the visual element tree.
The event handling sequence is as follows:
ExecuteDefaultActionAtTarget()
on the event target.ExecuteDefaultAction()
on the event target.As an event moves along the propagation path, the Event.currentTarget
property updates to the element currently handling the event. Within an event callback function:
Event.currentTarget
is the visual element that the callback registers on.Event.target
is the visual element where the original event occurs.For more information, see Dispatching events.
You can register an event callback to customize the behavior of an individual instance of an existing class, such as reacting to a mouse click on a text label.
Each element along the propagation path (except the target) can receive an event twice:
By default, a registered callback executes during the target phase and the bubble-up phase. This default behavior ensures that a parent element reacts after its child element.
On the other hand, if you want a parent element to react before its child, register your callback with the TrickleDown.TrickleDown
option:
using UnityEngine;
using UnityEngine.UIElements;
...
VisualElement myElement = new VisualElement();
// Register a callback for the trickle-down phase.
myElement.RegisterCallback<MouseDownEvent>(MyCallback, TrickleDown.TrickleDown);
...
This informs the dispatcher to execute the callback at the target phase and the trickle-down phase.
To add a custom behavior to a specific visual element, register an event callback on that element.
The following example registers a callback for the MouseDownEvent
:
// Register a callback on a mouse down event
myElement.RegisterCallback<MouseDownEvent>(MyCallback);
The signature for the callback function looks like this:
void MyCallback(MouseDownEvent evt) { /* ... */ }
You can register multiple callbacks for an event. However, you can only register the same callback function on the same event and propagation phase once.
To remove a callback from a VisualElement
, call the myElement.UnregisterCallback()
method.
You can send custom data along with the callback to an event. To attach custom data, you must extend the call to register the callback.
The following example registers a callback for the MouseDownEvent
and sends custom data to the callback function:
// Send user data along to the callback
myElement.RegisterCallback<MouseDownEvent, MyType>(MyCallbackWithData, myData);
The signature for the callback function looks like this:
void MyCallbackWithData(MouseDownEvent evt, MyType data) { /* ... */ }
UI controls can use the value
property to hold data for their internal state. For example:
Toggle
holds a Boolean value that changes when the Toggle
is turned on or off.IntegerField
holds an integer that holds the field’s value.You can get the value of the control by the following:
Get the value from the control directly: int val = myIntegerField.value;
.
Listen to a ChangeEvent
sent by the control and process the change when it happens. You must register your callback to the event like this:
//RegisterValueChangedCallback is a shortcut for RegisterCallback<ChangeEvent>.
//It constrains the right type of T for any VisualElement that implements an
//INotifyValueChange interface.
myIntegerField.RegisterValueChangedCallback(OnIntegerFieldChange);
The signature for the callback function looks like this:
void OnIntegerFieldChange(ChangeEvent<int> evt) { /* ... */ }
You can change the value of a control by the following:
value
variable: myControl.value = myNewValue;
. This will trigger a new ChangeEvent
.myControl.SetValueWithoutNotify(myNewValue);
. This won’t trigger a new ChangeEvent
.For more information, see Change events
When you handle pointer input, you might want the control to capture a pointer. When a visual element captures a pointer, Unity sends all the events associated with the pointer to the visual element regardless of whether the pointer hovers over the visual element. For example, if you create a control that receives drag events and captures the pointer, the control still receives drag events regardless of the pointer location.
To capture a pointer, use capture events. See Create a drag-and-drop UI inside a custom Editor window for an example.
If you’re implementing custom controls, you can respond to UI Toolkit events in two ways:
How you choose to respond to events depends on the situation.
The differences between callbacks and default actions are:
A default action applies to all instances of the class. A class that implements default actions can also have callbacks registered on its instances.
When a class implements a default action, it must derive a new subclass of VisualElement
and implement either the ExecuteDefaultActionAtTarget()
method, the ExecuteDefaultAction()
method, or both.
Default actions execute on each instance of a visual element sub-class when that instance receives an event. To customize default actions, you can override ExecuteDefaultActionAtTarget()
and ExecuteDefaultAction()
, as shown in the example below:
override void ExecuteDefaultActionAtTarget(EventBase evt)
{
// Call the base function.
base.ExecuteDefaultActionAtTarget(evt);
if (evt.eventTypeId == MouseDownEvent.TypeId())
{
// ...
}
else if (evt.eventTypeId == MouseUpEvent.TypeId())
{
// ...
}
// More event types
}
Implementing your default actions in ExecuteDefaultAction()
allows you to stop or prevent the execution of a default action.
If you want the target default action to execute before its parent callback, implement the default actions in ExecuteDefaultActionAtTarget()
.
You should view default actions as the behaviors that an element type should have when it receives an event. For example, a checkbox should toggle its state in response to a click event. To execute this, you can override a default action virtual function, instead of registering callbacks on all checkboxes.
The following are best practices for custom controls.
You should implement behaviors from your element with default actions. You can call PreventDefault()
in a callback attached to an instance to cancel default element behaviors.
Additional benefits of implementing behaviors as default actions are:
For greater flexibility, you can execute default actions of the event target at two moments during the event dispatch process:
ExecuteDefaultActionsAtTarget()
.ExecuteDefaultActions()
.Implement your class default actions in ExecuteDefaultActions()
, if possible. This allows more options to override the class. You can call PreventDefault()
to override the class during the trickle-down phase or the bubble-up phase of the event propagation process.
You must stop propagation of an event during a default action if the event shouldn’t propagate to the parent element. For example, a text field receives a KeyDownEvent
that modifies its value, such as the Delete
key to delete content. This event must not propagate to the parent visual element. Use ExecuteDefaultActionsAtTarget()
to implement a default action, and call StopPropagation()
to make sure the event isn’t processed during the bubble-up phase.
Default actions only execute for an event target. For a class to react to events that target their child or parent elements, you must register a callback to receive the event either during the trickle-down or the bubble-up propagation phase. Avoid registering callbacks in your class to improve performance.
When handling an event inside a callback or a default action, you can stop further event propagation and the execution of default actions. For example, a parent panel could stop propagation during the trickle-down phase to prevent its children from receiving events.
You can’t prevent the execution of the EventBase.PreDispatch()
and EventBase.PostDispatch()
methods inside the event class itself.
The following methods affect event propagation and default actions:
StopImmediatePropagation()
: Stops the event propagation process immediately, so no other callbacks execute for the event. However, the ExecuteDefaultActionAtTarget()
and ExecuteDefaultAction()
default actions still execute.StopPropagation()
: Stops the event propagation process after the last callback on the current element. This ensures that all callbacks execute on the current element, but no further elements react to the event. The ExecuteDefaultActionAtTarget()
and ExecuteDefaultAction()
default actions still execute.PreventDefault()
: Prevents the event propagation process from calling the ExecuteDefaultActionAtTarget()
and ExecuteDefaultAction()
default actions. PreventDefault()
doesn’t prevent the execution of other callbacks and doesn’t affect the ExecuteDefaultActionAtTarget()
action during the bubble-up phase.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.