The visual tree holds all the visual elements in a window. It is an object graph made of lightweight nodes refered to as visual elements.
These nodes are allocated on the C# heap, either manually or by loading UXML assets from a UXML template file.
Each node contains the layout information, its drawing and redrawing options, and how the node responds to events.
VisualElement is the common base class for all nodes in the visual tree. The
VisualElement base class contains properties for styles, layout data, local transformations, event handlers, and so on.
VisualElement has several subclasses that define additional behaviour and functionality, including specialized controls.
VisualElement may have child elements.
You are not required to derive from the
VisualElement base class to work with UIElements. You can customize the look and behavior of a
VisualElement through stylesheets and event callbacks.
The root object of the visual tree is referred to as the panel. A new element is ignored until it is connected to the panel. You can add elements to an existing element to attach your user interface to the panel.
To verify if a
VisualElement is connected to a panel, you can test the
panel property of this element. When the visual element is not connected, the test returns
Note: While UIElements is experimental, you must go through the extension method
GetRootVisualContainer() in the
UnityEditor.Experimental.UIElements namespace. This namespace is required to prevent accidental usage of this property.
The elements in the visual tree are drawn in the following order:
The only way to change their drawing order is to reorder
VisualElementobjects in their parents.
You can draw a subtree in a
RenderTexture and re-use the pixels for future redraw events by setting
VisualElement.clippingOptions = ClippingOptions.ClipAndCacheContents.
The different coordinate systems are defined as follow:
The layout system computes the
VisualElement.layout property (type
Rect) for each element.
layout.position is expressed as pixels relative to the coordinate space of its parent. Although you can assign a value to
layout.position directly, it is recommended that you use style sheets and the layout system to position elements.
VisualElement also has a
layout.transform property (type
ITransform) that positions an element relative to its parent. By default, the
transform is the identity.
VisualElement.layout.transform properties define how to transform between the local coordinate system and the parent coordinate system.
VisualElementExtensions static class provides the following extension methods that transform points and rectangles between coordinate systems:
WorldToLocal transforms a
Panel space to the referential within the element.
LocalToWorld transforms a
Panel space referential
Rect from the local space of one element to the local space of another.
For example, in the image above, the tree is arranged as follows:
DockArea and labelled “Coordinates”)
VisualElement acts as the root (refered to as “root container”)
VisualElement acts as a parent of the button (“red container”)
From the point of view of the panel:
position property (defined in
layout property) is set as (100, 100) because it is relative to its parent: the root container.
position property (defined in
layout property) is set as (0, 0) because it is relative to its parent: the red container.
The origin of an element is its top left corner.
worldBound property to retrieve the window space coordinates of the
VisualElement, taking into account the transforms and positions of its ancestry.