Query Extensions

Find UI Toolkit elements directly from a VisualElement root with ULB query extensions.

UitkQueryExtensions exposes ULB path and GUID lookup as extension methods on VisualElement. Use these methods when you need the search logic without a MonoBehaviour linker component.

Add using DA_Assets.ULB; so the extension methods and ElementIndexName are available.

GetByPath<T>

GetByPath follows an ElementIndexName array from the supplied root. Index = -1 matches Name; any other Index selects that child position.

csharp
using DA_Assets.ULB;
using UnityEngine.UIElements;

VisualElement root = uiDocument.rootVisualElement;

Button saveButton = root.GetByPath<Button>(
    new ElementIndexName
    {
        Index = UitkConstants.DEFAULT_INDEX,
        Name = "toolbar"
    },
    new ElementIndexName
    {
        Index = UitkConstants.DEFAULT_INDEX,
        Name = "save-button"
    });

GetByGuid<T>

GetByGuid recursively searches descendants for one ULB IHaveGuid element with the requested GUID.

csharp
Button saveButton = root.GetByGuid<Button>(
    "9c7f1231e0aa438687d8804d63053783");

GetByGuidHierarchy<T>

GetByGuidHierarchy follows one exact GUID branch. Every segment in that branch must be a ULB element implementing IHaveGuid.

csharp
Button saveButton = root.GetByGuidHierarchy<Button>(
    "5c3a3a122e654af7a349189ae2038771",
    "92f00728d29540ab98223c54348d2cbd",
    "9c7f1231e0aa438687d8804d63053783");

Return values and search cost

  • All three methods return null when no element is found or the found element cannot be cast to T.
  • GetByGuid recursively scans descendants until it finds a match.
  • GetByPath and GetByGuidHierarchy follow one configured branch.
  • GUID methods require ULB *G elements; normal UI Toolkit elements can be found by path or Unity's standard Query API.

Complete component example

csharp
using DA_Assets.ULB;
using UnityEngine;
using UnityEngine.UIElements;

public sealed class DirectQueryView : MonoBehaviour
{
    [SerializeField] private UIDocument uiDocument;

    private void Start()
    {
        Button button = uiDocument.rootVisualElement.GetByGuid<Button>(
            "9c7f1231e0aa438687d8804d63053783");

        if (button != null)
        {
            button.clicked += OnClicked;
        }
    }

    private void OnClicked()
    {
    }
}