This version of Unity is unsupported.

UxmlObjectReferenceAttribute

class in UnityEngine.UIElements

/

Implemented in:UnityEngine.UIElementsModule

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

name The name of the nested UXML element that the UXML Objects are serialized to. Note: A null or empty value will result in the objects being serialized into the root.
types In UI Builder, when adding a UXML Object to a field that has multiple derived types, a dropdown list appears with a selection of available types that can be added to the field. By default, this list comprises all types that inherit from the UXML object type. You can use a parameter to specify a list of accepted types to be displayed, rather than showing all available types

Constructors

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