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 along the propagation path in the visual element tree. The event isn’t only sent to the target visual element, but to all elements within the propagation path.
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.
Registering an event callback lets you 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. For example, if you want a parent element to react before its child, register your callback with the TrickleDown.TrickleDown
option:
// 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, you must register an event callback on that element. For example, the following code registers a callback for the MouseDownEvent
:
// Register a callback on a mouse down event
myElement.RegisterCallback<MouseDownEvent>(MyCallback);
Your callback signature should look like this:
void MyCallback(MouseDownEvent evt) { /* ... */ }
You can register multiple callbacks for an event. 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 code 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 callback function should return this signature:
void MyCallbackWithData(MouseDownEvent evt, MyType data) { /* ... */ }
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.GetEventTypeId() == MouseDownEvent.TypeId())
{
// ...
}
else if (evt.GetEventTypeId() == 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.
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()
ExecuteDefaultActionAtTarget()
and ExecuteDefaultAction()
default actions still execute.StopPropagation()
ExecuteDefaultActionAtTarget()
and ExecuteDefaultAction()
default actions still execute.PreventDefaultAction()
ExecuteDefaultActionAtTarget()
and ExecuteDefaultAction()
default actions. PreventDefaultAction()
doesn’t prevent the execution of other callbacks, and is ineffective on ExecuteDefaultActionAtTarget()
when called during the bubble-up phase.When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.