Transition events inform you of the changes in a transition’s state.
UI Toolkit uses transitions when a VisualElement’s property is modified. Changes to VisualElement property are immediately reflected visually. However, you can use the transition USS property to interpolate between the initial and end results gradually.
A transition’s lifecycle has the following stages:
A VisualElement’s property is modified when you:
element.ToggleInClassList() (where element is any VisualElement).:hover.style property. For example: element.style.backgroundColor = Color.red; (where element is any VisualElement).A TransitionRunEvent is sent.
If the resolved transition-delay property for the changing property has a value other than 0, nothing happens for the duration of the delay.
After the delay, a TransitionStartEvent is sent, and the transition starts with the property at its initial value.
For the length of time set by transition-duration, the transition occurs. During that time, the property goes from its initial to its final value.
If the property is changed to a new value during the transition, TransitionCancelEvent is sent. The transition process restarts at step 2.
After the transition-duration elapses, the property sets to its final value. A TransitionEndEvent is sent.
The following table describes the transition events and their propagation phases:
| Event | Description | Trickles down | Bubbles up | Cancellable |
|---|---|---|---|---|
| TransitionRunEvent | Sent when a transition is created. | Yes | ||
| TransitionStartEvent | Sent when a transition’s delay phase ends and the transition starts. | Yes | ||
| TransitionEndEvent | Sent when a transition ends. | Yes | ||
| TransitionCancelEvent | Sent when an a transition is canceled. | Yes |
Each transition property has its own lifecycle and its own transition events. You can access the current property with an event’s stylePropertyNames property.
If a shorthand USS property is changed, every component also gets its own lifecycle. For example, if you change margin, margin-left, margin-right, margin-top and margin-bottom, they all get their own TransitionRunEvent, TransitionStartEvent and TransitionEndEvent, for a total of 12 separate events.
If you set transition-delay to 0, the TransitionRunEvent and TransitionStartEvent are sent one after the other within a few milliseconds.
If you set transition-delay to a value below 0, the transition won’t start at the beginning. For example, with a transition-delay of -3 seconds and transition-duration of 5 seconds, the TransitionRunEvent and TransitionStartEvent is sent with an elapsedTime property set to 3 seconds and the transition effectively starts at the third second of a five-second animation.
This section describes the target, stylePropertyNames, and elapsedTime of each transition event.
A TransitionRunEvent event is sent when a transition is created.
target: The element that executes the transition.stylePropertyNames: The list of properties modified by the transition.elapsedTime: The time since the start of the transition.A TransitionStartEvent event is sent when the transition’s delay phase ends and the transition begins.
target: The element that executes the transition.stylePropertyNames: The list of properties modified by the transition.elapsedTime: The time since the start of the transition.A TransitionEndEvent event is sent when a transition ends.
target: The element that executes the transition.stylePropertyNames: The list of properties modified by the transition.elapsedTime: The time since the start of the transition.A TransitionCancelEvent event is sent when a transition is interrupted by the property being changed again.
target: The element that executes the transition.stylePropertyNames: The list of properties modified by the transition.elapsedTime: The time since the start of the transition.The following example demonstrates the lifecycle of a transition. The example creates a custom Editor window with a button and color palette. If you click the button, the following appears:
You can find the completed files that this example creates in this GitHub repository.
To create the example:
Create a project in Unity with any template.
From the menu, select Assets > Create > UI Toolkit > Editor Window.
In the UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary Toolkit Editor Window Creator window, enter TransitionExample.
Save your changes. This creates three files as TransitionExample.cs, TransitionExample.uss, and TransitionExample.uxml.
Replace the contents of TransitionExample.cs with the following:
using System;
using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;
public class TransitionExample : EditorWindow
{
[SerializeField] private VisualTreeAsset m_VisualTreeAsset = default;
private Button clickMeButton;
private VisualElement colorChanger;
private Label eventLabel;
private Label timeLabel;
private DateTime lastEvent;
private static readonly TimeSpan NearlyInstantaneousThreshold = TimeSpan.FromMilliseconds(10);
private static readonly string ClickMeButtonClass = "click-me";
private static readonly string ColorChangerClass = "color-changer";
private static readonly string ColorChangerTransitionClass = "color-transition";
private static readonly string EventLabelName = "eventLabel";
private static readonly string TimeLabelName = "timeLabel";
private static readonly string TimeBelowThresholdText = "Almost instantaneous.";
[MenuItem("Window/UI Toolkit/TransitionExample")]
public static void ShowExample()
{
TransitionExample wnd = GetWindow<TransitionExample>();
wnd.titleContent = new GUIContent("TransitionExample");
wnd.minSize = new Vector2(500f, 400f);
}
public void CreateGUI()
{
lastEvent = DateTime.Now;
// Each editor window contains a root VisualElement object
VisualElement root = rootVisualElement;
// Instantiate UXML
VisualElement uxmlAsset = m_VisualTreeAsset.Instantiate();
root.Add(uxmlAsset);
// Get the relevant elements by querying the root element
clickMeButton = root.Q<Button>(className: ClickMeButtonClass);
colorChanger = root.Q<VisualElement>(className: ColorChangerClass);
eventLabel = root.Q<Label>(name: EventLabelName);
timeLabel = root.Q<Label>(name: TimeLabelName);
// Add callbacks for clicking on the button and monitoring the color changing element.
clickMeButton.RegisterCallback<ClickEvent>(OnClickEvent);
colorChanger.RegisterCallback<TransitionRunEvent>(OnTransitionRun);
colorChanger.RegisterCallback<TransitionStartEvent>(OnTransitionStart);
colorChanger.RegisterCallback<TransitionEndEvent>(OnTransitionEnd);
colorChanger.RegisterCallback<TransitionCancelEvent>(OnTransitionCancel);
}
private void OnDisable()
{
clickMeButton.UnregisterCallback<ClickEvent>(OnClickEvent);
colorChanger.UnregisterCallback<TransitionRunEvent>(OnTransitionRun);
colorChanger.UnregisterCallback<TransitionStartEvent>(OnTransitionStart);
colorChanger.UnregisterCallback<TransitionEndEvent>(OnTransitionEnd);
colorChanger.UnregisterCallback<TransitionCancelEvent>(OnTransitionCancel);
}
private void OnClickEvent(ClickEvent evt)
{
colorChanger.ToggleInClassList(ColorChangerTransitionClass);
}
private void OnTransitionRun(TransitionRunEvent evt)
{
DisplayLatestEvent("TransitionRunEvent", DateTime.Now);
}
private void OnTransitionStart(TransitionStartEvent evt)
{
DisplayLatestEvent("TransitionStartEvent", DateTime.Now);
}
private void OnTransitionEnd(TransitionEndEvent evt)
{
DisplayLatestEvent("TransitionEndEvent", DateTime.Now);
}
private void OnTransitionCancel(TransitionCancelEvent evt)
{
DisplayLatestEvent("TransitionCancelEvent", DateTime.Now);
}
private void DisplayLatestEvent(string eventType, DateTime timestamp)
{
// If two events are sent too close together, add both to the Latest event line.
// This happens if the delay is set to 0 and the TransitionRun and TransitionStart
// are sent at the same time, or if the button was pressed before the transition
// was over, thus sending TransitionCancel and TransitionRun (and potentially
// TransitionStart) events close together.
var elapsed = timestamp - lastEvent;
if (elapsed <= NearlyInstantaneousThreshold)
{
timeLabel.text = TimeBelowThresholdText;
eventLabel.text = $"{eventLabel.text}, {eventType}";
}
else
{
timeLabel.text = $"{elapsed:s\\.ff} s";
eventLabel.text = eventType;
}
lastEvent = timestamp;
}
}
Replace the contents of TransitionExample.uxml with 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">
<Style src="TransitionExample.uss"/>
<ui:VisualElement class="main-container">
<ui:Button text="Click Me!" class="click-me"/>
<ui:VisualElement class="color-changer"/>
<ui:VisualElement class="label-section">
<ui:VisualElement class="label-line">
<ui:Label text="Latest event(s) : "/>
<ui:Label name="eventLabel"/>
</ui:VisualElement>
<ui:VisualElement class="label-line">
<ui:Label text="Time since last event : "/>
<ui:Label name="timeLabel"/>
</ui:VisualElement>
</ui:VisualElement>
</ui:VisualElement>
</ui:UXML>
Replace the contents of TransitionExample.uss with the following:
.click-me {
width: 250px;
height: 50px;
font-size: 40px;
-unity-font-style: bold-and-italic;
margin: 30px;
}
.color-changer {
margin: 10px;
width: 150px;
height: 150px;
border-width: 10px;
border-radius: 75px;
background-color: rgb(0, 31, 138);
transition: background-color 3s ease-in-out 1s;
}
.main-container {
align-items: center;
justify-content: space-between;
flex-grow: 1;
background-color: rgb(60, 60, 60);
}
.label-section {
margin: 10px;
border-width: 2px;
width: 95%;
align-items: center;
}
.label-line {
flex-direction: row;
margin: 5px;
flex-grow: 1;
align-items: center;
width: 90%;
height: 25px;
font-size: 14px;
padding: 0;
}
.color-transition {
background-color: rgb(177, 221, 111);
}
Select TransitionExample.cs and drag TransitionExample.uxml to the Visual TreeAn object graph, made of lightweight nodes, that holds all the elements in a window or panel. It defines every UI you build with the UI Toolkit.
See in Glossary Asset field in the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary if it’s not already there.
To see the example, select Window > UI Toolkit > Transition Example.
Click the button to view the color transition and the description of the events sent. There is a long delay between the TransitionRunEvent and the TransitionStartEvent. During the long duration, you can click the button again to interrupt the transition.