VisualElementReference
Represents a reference to a VisualElement in a PanelRenderer.
Read time 3 minutesLast updated 4 days ago
Definition
- Type: Class
- Namespace: UnityEngine.UIElements
- Assembly: UnityEngine.UIElementsModule
- Implements: IEquatable<VisualElementReference>, IDisposable
public class VisualElementReference : IEquatable<VisualElementReference>, IDisposable
Remarks
This example shows how to use VisualElementReference to reference an element in a UXML file that is loaded by a .
PanelRendererusing UnityEngine;using UnityEngine.UIElements;public class VisualElementReference_Example : MonoBehaviour{ // Set via the inspector public VisualElementReference elementReference = new VisualElementReference(); public Color customColor = Color.red; void Start() { elementReference.RegisterReferenceResolvedCallback(SetupElementBackground); } void SetupElementBackground(VisualElement ve) { ve.style.backgroundColor = customColor; }}
The following example configures paths to reference elements in a nested UXML structure. Root UXML:
<ui:UXML xmlns:ui="UnityEngine.UIElements" editor-extension-mode="False"> <ui:Template name="VisualElementReference_ExampleTemplate" src="./VisualElementReference_ExampleTemplate.uxml"/> <ui:VisualElement name="my-element" authoring-id="123"/> <ui:Button text="Button" name="my-button" authoring-id="-5"/> <ui:Instance template="VisualElementReference_ExampleTemplate" name="instance1" authoring-id="1"/> <ui:Instance template="VisualElementReference_ExampleTemplate" name="instance2" authoring-id="2"/></ui:UXML>
Template UXML:
<ui:UXML xmlns:ui="UnityEngine.UIElements" editor-extension-mode="False"> <ui:VisualElement name="template-element" authoring-id="1"/> <ui:Button text="Button" name="template-button" authoring-id="101"/></ui:UXML>
using UnityEngine;using UnityEngine.UIElements;public class VisualElementReference_ExampleNested : MonoBehaviour{ public VisualElementReference<Button> templateInstance1Button = new VisualElementReference<Button>(); public VisualElementReference elementReference = new VisualElementReference(); void Start() { var pr = GetComponent<PanelRenderer>(); // 101 is the AuthoringId of the Button inside the template instance with AuthoringId 1 templateInstance1Button.SetReference(pr, new AuthoringIdPath(1, 101)); templateInstance1Button.RegisterReferenceResolvedCallback(SetupButtonReference); templateInstance1Button.RegisterReferenceUnloadedCallback(TeardownButtonReference); // 123 is the AuthoringId of a VisualElement in the root UXML file elementReference.SetReference(pr, new AuthoringIdPath(123)); elementReference.RegisterReferenceResolvedCallback(SetupElementReference); } void SetupButtonReference(Button button) { button.clicked += OnButtonClick; } void TeardownButtonReference(Button button) { button.clicked -= OnButtonClick; } void OnButtonClick() { Debug.Log("Button inside template instance clicked!"); } void SetupElementReference(VisualElement ve) { ve.Add(new Label { text = "Element Reference Resolved!" }); }}
Constructors
Constructor | Description |
|---|---|
| VisualElementReference() | Creates a new empty VisualElementReference. |
| VisualElementReference(UnityEngine.UIElements.PanelRenderer,UnityEngine.UIElements.AuthoringIdPath) | Creates a new VisualElementReference pointing to the given renderer and path. |
Properties
Property | Description |
|---|---|
| authoringPath | The path to the referenced element. VisualElementReference.SetReference |
| panelRenderer | The provider used to resolve the reference. VisualElementReference.SetReference |
Methods
Method | Description |
|---|---|
| Equals | Indicates whether the current object is equal to another element reference. |
| RegisterReferenceResolvedCallback | Registers a callback for when the reference is resolved from the document. When you register a callback, if the reference is already resolved, the callback is immediately invoked. |
| RegisterReferenceUnloadedCallback | Registers a callback for when the referenced object is unloaded. This occurs when the document is destroyed, such as when a live reload occurs after the VisualTreeAsset changes. At this point, all references are invalid and should be cleared. |
| SetReference | Sets the reference to point to the given document and path. |
| UnregisterReferenceResolvedCallback | Unregisters a callback for when the reference is resolved from the document. |
| UnregisterReferenceUnloadedCallback | Unregisters a callback for when the referenced object is unloaded. |