UxmlObjectReferenceAttribute

Description

Declares that a field or property is associated with nested UXML objects.

You can utilize the UxmlObjectReferenceAttribute to indicate that a property or field is linked to one or multiple UXML objects. By adding the UxmlObjectAttribute attribute to a class, you can declare a UXML object. You can use these UXML objects to associate complex data with a field, surpassing the capabilities of a single UxmlAttributeAttribute. The field type must be a UXML object or an interface. When using an interface, only UXML Object types are valid for UXML serialization.

The following example shows a common use case for the UxmlObjectReferenceAttribute. It uses the attribute to associate a list of UXML objects with a field or property:

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UIElements;

[UxmlObject]
public partial class Option
{
    [UxmlAttribute]
    public string name { get; set; }

    [UxmlAttribute]
    public bool bold { get; set; }

    [UxmlAttribute]
    public Color color;
}

[UxmlElement]
public partial class MyColoredListField : VisualElement
{
    private List<Option> m_Options;
    private PopupField<Option> m_PopupField;

    [UxmlObjectReference("options")]
    public List<Option> options
    {
        get => m_Options;
        set
        {
            m_Options = value;
            m_PopupField.choices = m_Options;
        }
    }

    public MyColoredListField()
    {
        m_PopupField = new PopupField<Option>();
        Add(m_PopupField);

        if (options != null)
            m_PopupField.choices = options;

        m_PopupField.formatSelectedValueCallback = FormatItem;
        m_PopupField.formatListItemCallback = FormatItem;
    }

    static string FormatItem(Option option)
    {
        if (option == null)
            return "";

        var coloredString = $"<color=#{ColorUtility.ToHtmlStringRGB(option.color)}>{option.name}</color>";

        if (option.bold)
            return $"<b>{coloredString}</b>";
        return coloredString;
    }
}

Example UXML:

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <MyColoredListField>
        <options>
            <Option name="Red" color="#FF0000FF" bold="true" />
            <Option name="Green" color="#00FF00FF" />
            <Option name="Blue" color="#0000FFFF" />
        </options>
    </MyColoredListField>
</ui:UXML>

You can employ a base type and incorporate derived types as UXML objects. The following example customizes a button to exhibit different behaviors when clicked, such as displaying a label or playing a sound effect.

using UnityEngine;
using UnityEngine.UIElements;

[UxmlObject]
public abstract partial class ButtonBehaviour
{
    [UxmlAttribute]
    public string name { get; set; }

    public abstract void OnClicked(Button button);
}

[UxmlObject]
public partial class CreateLabel : ButtonBehaviour
{
    [UxmlAttribute]
    public string text { get; set; } = "I was clicked!";

    public override void OnClicked(Button button)
    {
        var label = new Label(text);
        button.parent.Add(label);
    }
}

[UxmlObject]
public partial class PlaySound : ButtonBehaviour
{
    [UxmlAttribute]
    public AudioClip sound { get; set; }

    public override void OnClicked(Button button)
    {
        AudioSource.PlayClipAtPoint(sound, Vector3.zero);
    }
}

[UxmlElement]
public partial class ButtonWithClickBehaviourExample : Button
{
    [UxmlObjectReference("clicked")]
    public ButtonBehaviour clickedBehaviour { get; set; }

    public ButtonWithClickBehaviourExample()
    {
        clicked += OnClick;
    }

    void OnClick()
    {
        clickedBehaviour?.OnClicked(this);
    }
}

Example UXML:

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" editor-extension-mode="False">
    <ButtonWithClickBehaviourExample text="Play Sound">
        <clicked>
            <PlaySound sound="project://database/Assets/ClickedSound.wav" />
        </clicked>
    </ButtonWithClickBehaviourExample>
    <ButtonWithClickBehaviourExample text="Show Label">
        <clicked>
            <CreateLabel text="I was clicked!" />
        </clicked>
    </ButtonWithClickBehaviourExample>
</ui:UXML>

You can also use an interface and any UXML objects that implement it.

using System.Collections.Generic;
using UnityEngine.UIElements;

public interface IMyUxmlObjectInterface
{
    string name { get; set; }
}

[UxmlObject]
public partial class MyUxmlObject : IMyUxmlObjectInterface
{
    [UxmlAttribute]
    public string name { get; set; }
}

[UxmlElement]
public partial class MyUxmlObjectElement : VisualElement
{
    [UxmlObjectReference("item")]
    public IMyUxmlObjectInterface item { get; set; }

    [UxmlObjectReference("item-list")]
    public List<IMyUxmlObjectInterface> itemList { get; set; }   
}

Properties

Constructors