Migrate from Immediate Mode GUI (IMGUI) to UI Toolkit

This guide is for developers experienced with Immediate Mode GUI (IMGUI) to migrate to UI Toolkit. This guide focuses on the Editor UI, but its information can also apply to the runtime UI as well.

Key differences

Code-driven versus UI-driven

IMGUI is code-driven by calls to the OnGUI function in an C# script which implements it. UI Toolkit provides more options for Editor UI creation. With UI Toolkit, you define the behaviors in C# scripts. However, when defining UI elements and styles, in addition to C#, you can visually define UI controls in UI Builder or write in an XML-like text file (called UXML) directly. For more information, see Simple UI Toolkit workflow.

Immediate versus retained mode

With IMGUI, you describe the UI tree when the UI is repainted within the OnGUI() function. You must call this function when an event enters the UI or when you repaint the UI. There is no persistent information pertaining the UI tree between different events. Whereas, you create visual elements with UI Toolkit in a tree structure called Visual Tree. Information in the Visual Trees is retained persistently.

Constant versus state changes

IMGUI is based around the OnGUI() function that runs at least once every frame. You define the look and the behaviors of the UI for every possible frame. The body of OnGUI() might contain many conditions and different states.

UI Toolkit operates in an event-driven system. You define the look of the UI in its default state and define the behaviors of the UI in response to events. Any changes you make in UI Toolkit cause persistent changes to the state of your UI.

For example, the declaration of a button in IMGUI looks like the following:

if (GUILayout.Button("Click me!"))
{
    //Code runs here in frames where the user clicks the button.

    //Code makes changes to the UI for frames where the user has just clicked the button.
}
else
{
    //Code specifies what happens in all other frames.
}

The example above looks like the following in UI Toolkit:

UIDocument document = GetComponent<UIDocument>();

//Create button.
Button button = new Button();
button.text = "Click me!";

//Set up event handler.
button.RegisterCallback<ClickEvent>((ClickEvent evt) =>
{
    //Code runs here after button receives ClickEvent.
});

//Add button to UI.
document.rootVisualElement.Add(button);

For a completed example on how to create a custom Editor window with UI Toolkit, see Simple UI Toolkit workflow.

IMGUI support

使用 IMGUIContainer 可将 IMGUI 代码放在 VisualElement 中。通常可在 OnGUI() 中执行的所有操作都受支持。

You can arrange multiple IMGUIContainers and lay them out by mixing GUILayout and UI Toolkit layouts. Note that it’s not possible to add VisualElement instances inside of an IMGUIContainer.

From IMGUI to UI Toolkit conversion

The following table lists the equivalent functions between IMGUI and UI Toolkit:

The following table lists the equivalent methods, classes, attributes between IMGUI and UI Toolkit:

其他资源

• Get started with UI Toolkit
• Unity style sheets (USS)
• Examples
• IMGUI events