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:
Add or remove a class with C# methods, such as element.ToggleInClassList()
(where element
is any VisualElement
).
Use USS with selectors like :hover
.
Manipulate the element’s style
property.
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:
イベント | 説明 | トリクルダウン (下降) 伝播 | バブルアップ (上昇) 伝播 | キャンセル可能 |
---|---|---|---|---|
TransitionRunEvent | Sent when a transition is created. | あり | ||
TransitionStartEvent | Sent when a transition’s delay phase ends and the transition starts. | あり | ||
TransitionEndEvent | Sent when a transition ends. | あり | ||
TransitionCancelEvent | Sent when an a transition is canceled. | あり |
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 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 Tree Asset field in the Inspector 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.