If you’re implementing custom controls, you can respond to UI Toolkit events in the following ways:
Your response to events depends on the situation. The following are the differences between callbacks and virtual method overrides:
A virtual method override applies to all instances of the class. For a class that overrides HandleEventBubbleUp or HandleEventTrickleDown, you can also register callbacks on its instances.
To override the HandleEventBubbleUp or HandleEventTrickleDown methods, or both, derive a new subclass of VisualElement.
HandleEventBubbleUp and HandleEventTrickleDown execute on each instance of a visual element subclass when that instance receives an event.
The following example shows how to customize those virtual methods:
override void HandleEventBubbleUp(EventBase evt)
{
// Call the base function.
base.HandleEventBubbleUp(evt);
if (evt.eventTypeId == PointerDownEvent.TypeId())
{
// ...
}
else if (evt.eventTypeId == MouseUpEvent.TypeId())
{
// ...
}
// More event types
}
For a given class instance, executing custom code in the following cases have the same results:
In either case, if you stop the propagation of the event, it prevents reactions to the event after you have executed the current target callbacks and method overrides.
The following are best practices for handing events with custom controls.
In general, to implement behaviors from your element, use a HandleEventBubbleUp method override.
Given that the BubbleUp is the default propagation phase for callbacks, you can move any code from callbacks to a HandleEventBubbleUp method without any concerns about changing the timing of code execution.
The benefits of implementing behaviors as method overrides include:
When handling an event inside a callback or a virtual method override, you can stop further event propagation by calling one of the StopPropagation methods on the event. 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:
StopImmediatePropagation(): Stops the event propagation process immediately to prevent any subsequent callbacks from executing for the event.StopPropagation(): Stops the event propagation process after the last callback on the current element. This ensures that all callbacks execute on the current element, while preventing any further elements from responding to the event.