#How it works

This page gives the model behind the windows. Read it before you extend the system.

#The parts

• An Window element in UXML becomes a WindowDescriptor when the workspace attaches. A window from code is a WindowDescriptor from the start.
• The workspace keeps each registered window, open or closed. OpenWindowAsync(id) opens one by its id.
• A tab group is a window whose content is a tab strip. Each tab is a window too, so the same API works on a tab and on a standalone window.
• The Toolbox controls (UIToolbox) do not need a workspace. See Toolbox controls.

#Window states

WindowDescriptor.State is one of Closed, Open, Minimized, Maximized and Restored.

• A closed window stays registered. The next open makes a new chrome.
• When the last tab of a group closes, the group closes. When one tab is left, the group becomes a standalone window. A dock zone never closes.
• A close of a tab group asks each tab first. If one tab refuses, no tab closes.

See Control a window.

#Bounds

Positions are relative to the viewport of the workspace. An WorkspaceToolbar makes the viewport smaller at the top.

The workspace clamps the bounds to the viewport.

#Chrome

The chrome of a window comes from the first of these that works:

1. The custom template of the window.
2. The default window template of the package.
3. A chrome that the chrome factory builds in code.

The workspace adds the same tb-* classes to each chrome, so one style sheet applies to all templates. See Custom chrome templates and Window and workspace classes.

#Drag and drop

• A drag of a title bar moves the window and snaps it to other windows and to the edges of the viewport.
• A drop of a window on another window makes a tab group. A drag of a tab out of its strip makes a standalone window again.
• Any element can take a drop: implement IAcceptsDropPayload<T>. See Drop payloads and drop targets.

#Animations

Animations are USS transitions. The code adds a class, and USS does the motion. So a theme can change each animation with no code. When Workspace.AnimationsEnabled is false, each change applies at once. See Animations.

#Async rules

1. Call the API on the Unity main thread only. UI Toolkit is not thread safe.
2. The state and the focus change at once when an async method starts. The Task completes when the animation ends.
3. OpenWindow, CloseWindow, FocusWindow and SetBounds are synchronous. OpenWindow and CloseWindow start the async version and do not wait.
4. Do not use async void. For a call that you do not await, use AsyncRunner.Run. It logs each exception.
5. Each async method takes a CancellationToken. A cancel ends the animation at its end state.
6. Closing handlers run synchronously. Do not start long work in them.

using UIToolbox;
using UIToolbox.Utils;

public static class OpenExample
{
    public static void OpenFromButton(Workspace workspace)
    {
        AsyncRunner.Run(() => workspace.OpenWindowAsync("Inventory"), "Open Inventory");
    }
}