【Unity3D】Introduction to UI Toolkit

1 Introduction

        UI Toolkit is a GUI framework based on Web technology. It is a new generation of UI system designed to solve the problem of UGUI efficiency (for the introduction of UGUI, please refer to → UGUI Overview ). Different from UGUI, UI Toolkit does not use GameObject, but refers to the XML and CSS solutions of Web technology. This means it only saves the changed data, not the entire interface state, which makes it more efficient.

        The history of UI Toolkit can be traced back to the UIElement released by Unity in 2018. At first, it was mainly used for UI development in the Editor editing panel. Since Unity 2019, it began to support the runtime UI and was renamed UIToolkit. It uses the Package package (com. unity.ui) exists in the form of Unity 2021.2, and is officially built into Unity in the Unity 2021.2 version, with the same status as UGUI.

        Advantages of UI Toolkit:

• Cross-platform
• High performance (one Draw Call draws all UI)
• Apply custom styles to any element
• Better reusability and flexibility
• Supporting UI editing tool (UI Builder)
• Also supports Editor and Runtime

         Disadvantages of UI Toolkit:

• It is difficult to make an interactive UI placed in the 3D world without relying on GameObject
• Does not support Shader, it is difficult to create special effects
• The Animator component is not supported, and real-time loop animation cannot be made (but there is a Transition animation system)

        For built-in examples of UI Toolkit, see: [Window→UI Toolkit→Samples].

2 UI Toolkit is easy to use

        1) Create a UI Document object

        Right-click on the Hierarchy window, select [UI Toolkit→UI Document], and create a UI Document object, as follows.

• Panel Settings : Define some global configurations, such as fonts, styles and other information. When creating a UI Document object, the PanelSettings.asset file will be automatically created;
• Source Asset : the page resource to be displayed
• Sort Order : sorting order, when there are multiple UIDocument objects, the smaller the serial number is displayed first (at the bottom), and the larger serial number is displayed later (at the top);

        2) Create uxml resource file

        Right-click on the Assets window, select [Create→UI Toolkit→UI Document], a uxml file will be generated, rename it to TestUXMLTemplate, and set Source Asset to TestUXMLTemplate in the Inspector window of the UIDocument object, as follows.

        3) Edit the uxml file

        Double-click the TestUXMLTemplate.uxml file in the Assets window to open the UI Builder window, or select [Window→UI Toolkit→UI Builder] in the menu bar to open the UI Builder window. Drag the VisualElement to the Hierarchy window, as follows.

        Select VisualElement in the Hierarchy window, configure Flex and Background in the Inspector window, as follows, press Ctrl + S to save.

        4) Check the effect

         Back to the Game window, the display effect is as follows. The cube in the middle is the Cube object added in advance, and the translucent yellow is the effect displayed by UI Document.

3 UI Builder window introduction

        Before the Unity 2021.2 version, you need to install the UI Builder in the Package Manager window. Since the Unity 2021.2 version, the UI Builder has been built into the Unity Editor.

        Double-click the uxml file in the Assets window to open the UI Builder window, or select [Window→UI Toolkit→UI Builder] in the menu bar to open the UI Builder window. 

• StyleSheets : style window, used to manage element styles;
• Hierarchy : element level window, used to manage elements;
• Library : container and element library;
• Inspector : Inspector window for configuring container and element properties.

        Rolling the mouse wheel can zoom in and out the size of the preview window; press the middle mouse button and drag to adjust the position of the preview window. Click the Preview button in the upper right corner of the Viewport window to view the running UI interface.

4 Introduction to Style Attributes

        Each element (or container) has the following style properties, which are explained in this section.

4.1 StyleSheet (style sheet)

        In the style sheet module, you can add and export styles, and view the matched style selectors. For the official introduction of style selectors, see → USS selectors .

4.2 Inlined Styles (internal styles)

        For the official introduction of the internal style, please refer to → USS common properties , for the official introduction of the style attribute, please refer to → USS properties reference , and the Box model is as follows.

4.2.1 Display

• Opacity : Opacity, the value is 0 ~ 100. 0 means transparent, 100 means completely opaque.
• Display : placeholder display, the values ​​are flex, none. flex means occupying the remaining space as much as possible; none means not occupying space, and other elements (or containers) will occupy the space of the element (or container), making the element (or container) invisible.
• Visibility : Visibility, the values ​​are visible, hidden. visible means that the element (or container) is visible; hidden means that the element (or container) is invisible, but the space of the element (or container) is still occupied, and other elements will not occupy the space of the element (or container).
• Overflow : The margin strategy when cropping, with values ​​of visible and hidden. In the scenario where the border of the child element (or container) exceeds the current container, visible means that the Margin & Padding of the current container will not constrain the container that exceeds the part; hidden means that the Margin & Padding of the current container will constrain the container that exceeds the part.

        As follows, the overflow property of the container is set to visible, and the margin does not take effect on the text.

4.2.2 Position

• Position : The values ​​are Relative and Absolute. The difference between them is: Relative means the offset relative to itself after tiling; Absolute means the offset relative to the parent container. For the official definition, see → Relative and absolute positioning .
• Left : The position to the left of the element (or container).
• Top : The position of the top of the element (or container).
• Right : The position on the right side of the element (or container).
• Bottom : The position on the left side of the element (or container).

        The value types of Position are: px, %, auto, initial, the meanings are as follows:

• px : The value unit is pixel.
• % : The value unit is a percentage.
• auto : Automatic, the value is affected by Flex, Align, style selector, etc.
• initial : The value is affected by Flex, Align, etc., not affected by the style selector.

4.2.3 Flex (stretch)

• Basis : The basic space of the element (or container), the value types are px, %, auto, initial, the meaning is the same as Section 4.2.2.
• Shrink : If there is free space in the horizontal direction, the ratio of the element (or container) to occupy the remaining space in the horizontal direction. The value has a ratio value and initial (does not occupy the remaining space).
• Grow : If there is free space in the vertical direction, the ratio of the element (or container) to occupy the remaining space in the vertical direction. The value has a ratio value and initial (does not occupy the remaining space).
• Direction : The direction in which sub-elements (or containers) are arranged, the values ​​are: column (from top to bottom), column-reserve (from bottom to top), row (from left to right), row-reserve (from right to left ).
• Wrap : The arrangement strategy after sub-elements (or containers) are arranged in more than one line (or one column), the values ​​are nowrap (no line break, truncated display), wrap, wrap-reverse,

4.2.4 Align

• Align Items：auto、flex-start、flex-end、center、stretch
• Justify Content：flex-start、flex-end、center、space-between、space-around

        Explanation: The property of Align is affected by the Direction of Flex.

4.2.5 Size

• Width : The width of the element (or container), the value types are px, %, auto, initial, the meaning is the same as Section 4.2.2.
• Height : the height of the element (or container), the value types are px, %, auto, initial, the meaning is the same as Section 4.2.2.
• Max : the maximum width and height of the element (or container), the value types are px, %, none (unlimited), initial, the meaning is the same as Section 4.2.2.
• Min : The minimum width and height of the element (or container), the value types are px, %, auto, initial, the meaning is the same as Section 4.2.2.

4.2.6 Margin & Padding (outer margins and inner margins)

• Margin : Margin, the value types are px, %, auto, initial, the meaning is the same as section 4.2.2.
• Padding : inner margin, the value types are px, %, auto, initial, the meaning is the same as section 4.2.2.

4.2.7 Text (text)

• Font : Font type.
• Font Asset : Font resource.
• Font Style : font style, the values ​​are bold (bold), italic (italic).
• Size : font size.
• Color : font color.
• Align : font alignment, the values ​​are left (left), center (horizontal center), right (right), upper (top), middle (vertical center), lower (bottom).
• Wrap : Font wrapping method, that is, the display method after the text exceeds one line. The values ​​are normal (automatically wrap), nowrap (truncated display).
• Outline Width : stroke width.
• Outline Color : stroke color.
• Text Shadow : text shadow.
• Letter Spacing : character spacing, the value types are px, initial, the meaning is the same as section 4.2.2.
• World Spacing : Word spacing, the value types are px, initial, the meaning is the same as section 4.2.2.
• Paragraph Spacing : Paragraph spacing, the value types are px, initial, the meaning is the same as Section 4.2.2.

4.2.8 Background

• Color : Background color.
• Image : The background image.
• Image Tint : Background image color.
• Scale Mode : Image scaling mode, the values ​​are stretch-to-fill (the width and height are full, which will destroy the original aspect ratio of the image), scale-and-crop (the width and height are full, keeping the original image Aspect ratio, the image may be cropped), scale-to-fit (width or height is tiled, and the original aspect ratio of the image is maintained).
• Slice : Slice ratio, divide the picture into 9 grids, keep the original size of the picture at the 4 corners, and can be used for the background of the dialog box.

4.2.9 Border

• Color : Border color.
• Width : border width, the value types are px, initial, the meaning is the same as section 4.2.2.
• Radius : Rounded corners of the border, the value types are px, %, initial, the meaning is the same as Section 4.2.2.

4.2.10 Transform

        For the official introduction of Transform, see → USS transform .

• Pivot Origin : The center of transformation, the value types are px, %, the meaning is the same as Section 4.2.2.
• Translate : translation offset, the value types are px, %, the meaning is the same as section 4.2.2.
• Scale : Scale offset, the value types include proportional value, none, initial, the meaning is the same as section 4.2.2.
• Rotate : Rotation angle, the value units are deg (angle), grad (gradient, 100 grad = 90 deg), rad (radian), turn (circle, 1 turn = 360 deg).

4.2.11 Cursor

• Cursor Image : Mouse image.

4.2.12 Transition Animations (transition animation)

        For the official introduction of Transition Animations, see → USS transition .

• Property : The property on which the animation works.
• Duration : The execution time of the transition animation, the value types are s (seconds), ms (milliseconds), and initial.
• Easing : A function of the change of properties over time, similar to an interpolator.
• Delay : animation delay execution time, the value types are s (second), ms (millisecond), initial.

5 UQuery

        UQuery is mainly used to find sub-elements (or sub-containers), which can be found by type and name. The Query method of an element (or container) is used to find all sub-elements (or sub-containers) that meet the conditions, and the Q method of an element (or container) is used to find the first sub-element (or sub-container) that meets the conditions.

5.1 UQuery multi-element search (Query method)

        1) Find by type

rootVisualElement.Query<Label>().ForEach(OnSelectedMultipleElements);

private void OnSelectedMultipleElements(Label obj) {
    obj.text = "xxx";
}

        rootVisualElement is the root VisualElement container, the acquisition method is as follows, the same below.

VisualElement rootVisualElement = GetComponent<UIDocument>().rootVisualElement;

        2) Find by name

rootVisualElement.Query("VisualElementName").ForEach(OnSelectedMultipleElements);

private void OnSelectedMultipleElements(VisualElement obj) {
    obj.style.backgroundColor = Color.black;
}

         3) Search by type and name

rootVisualElement.Query<Label>("LabelName").ForEach(OnSelectedMultipleElements);
rootVisualElement.Query<Label>("LabelName").AtIndex(1).text = "yyy";

private void OnSelectedMultipleElements(Label obj) {
    obj.text = "xxx";
}

5.2 UQuery single element search (Q method)

        1) Find by type

Label label = rootVisualElement.Q<Label>();
label.text = "xxx";

        2) Find by name

VisualElement visualElement = rootVisualElement.Q("VisualElementName");
visualElement.style.backgroundColor = Color.black;

        3) Search by type and name

Label label = rootVisualElement.Q<Label>("LabelName");
label.text = "xxx";

6 UI Toolkit Debugger (debugger)

        1) Open UI Toolkit Debugger

        Click More in the upper right corner of the UI Builder window, expand and click UI Toolkit Debugger to open the debug window, or you can open the debug window through [Window→UI Toolkit→Debugger].

        2) View the Box model

        Click the Show Layout button to see the layout boundaries of the canvas elements, as follows.

         Select the element (or container), and you can see the Box model and other information in the Debugger window, as follows. Click the Pick Element button to pick up element information in the Viewport window.