Expose custom control to UXML and UI Builder

To use custom controls with UXML and UI Builder, you must expose them.

Define a factory

To define new elements, derive a new class from VisualElement or one of its subclasses, and then implement the appropriate functionality within this new class.

Your new class must implement a default constructor. For example:

class StatusBar : VisualElement
{
    public StatusBar()
    {
        m_Status = String.Empty;
    }

    string m_Status;
    public string status { get; set; }
}

In order for UI Toolkit to instantiate a new class when it reads a UXML file, you must define a factory for your class. Unless your factory needs to do something special, you can derive the factory from UxmlFactory<T>. It’s recommended that you put the factory class within your component class.

For example, the following code snippet define a factory named UxmlFactory for the StatusBar class:

class StatusBar : VisualElement
{
    public new class UxmlFactory : UxmlFactory<StatusBar> {}

    // ...
}

이 팩토리를 정의하고 나면 UXML 파일에서 <StatusBar> 요소를 사용할 수 있습니다.

Define attributes on elements

새로운 클래스에 대해 UXML 특성을 정의하고 해당 팩토리가 그러한 특성을 사용하도록 설정할 수 있습니다.

For example, the following code snippet defines a UXML traits class to initialize the status property as a property of the StatusBar class. The status property initializes from UXML data.

class StatusBar : VisualElement
{
    public new class UxmlFactory : UxmlFactory<StatusBar, UxmlTraits> {}

    public new class UxmlTraits : VisualElement.UxmlTraits
    {
        UxmlStringAttributeDescription m_Status = new UxmlStringAttributeDescription { name = "status" };

        public override IEnumerable<UxmlChildElementDescription> uxmlChildElementsDescription
        {
            get { yield break; }
        }

        public override void Init(VisualElement ve, IUxmlAttributes bag, CreationContext cc)
        {
            base.Init(ve, bag, cc);
            ((StatusBar)ve).status = m_Status.GetValueFromBag(bag, cc);
        }
    }

    // ...
}

UxmlTraits는 다음의 두 가지 역할을 수행합니다.

• 팩토리가 새로 생성된 오브젝트를 초기화하는 데 사용합니다.
• 스키마 생성 프로세스가 요소에 대한 정보를 가져오기 위해 분석합니다. 이 정보는 XML 스키마 지시문으로 변환됩니다.

위 코드 예제는 다음을 수행합니다.

• m_Status 선언은 status라는 이름의 XML 속성을 정의합니다.
• uxmlChildElementsDescription은 StatusBar 요소에 자식이 없음을 의미하는 빈 IEnumerable을 반환합니다.
• Init() 멤버는 XML 파서의 프로퍼티 백에 있는 status 속성의 값을 읽은 후 StatusBar.status 프로퍼티를 이 값으로 설정합니다.
• The UxmlTraits class is placed inside the StatusBar class. This allows the Init() method to access the private members of StatusBar.
• 새로운 UxmlTraits 클래스는 UxmlTraits 기본 클래스에서 상속되기 때문에 기본 클래스의 속성을 공유합니다.
• Init()은 base.Init()를 호출하여 기본 클래스 프로퍼티를 초기화합니다.

The code example above declares a string attribute with the UxmlStringAttributeDescription class. UI Toolkit supports the following types of attributes and each links a C# type to a UMXL type:

In the code example above, the uxmlChildElementsDescription returns an empty IEnumerable which indicates that the StatusBar element doesn’t accept child element descriptions to the XML schema.

To have an element accept children of any type, you must override the uxmlChildElementsDescription property. For example, for the StatusBar element to accept children of any type, you must specify the uxmlChildElementsDescription property as follows:

public override IEnumerable<UxmlChildElementDescription> uxmlChildElementsDescription
{
    get
    {
        yield return new UxmlChildElementDescription(typeof(VisualElement));
    }
}

Define a namespace prefix

Once you have defined a new element in C#, you can use the element in your UXML files. To categorize elements, create your class in a namespace. When you define a new namespace, you can define a prefix for the namespace. You must define namespace prefixes as attributes of the root <UXML> element and replace the full namespace name when scoping elements.

To define a namespace prefix, add a UxmlNamespacePrefix attribute to your assembly for each namespace prefix. For example:

[assembly: UxmlNamespacePrefix("My.First.Namespace", "first")]
[assembly: UxmlNamespacePrefix("My.Second.Namespace", "second")]

이 작업은 어셈블리 C# 파일의 루트 수준(모든 네임스페이스 외부)에서 수행할 수 있습니다.

이 스키마 생성 시스템은 다음을 수행합니다.

• 이러한 속성에 대한 검사를 수행하고, 속성을 사용하여 스키마를 생성합니다.
• Adds the namespace prefix definition as an attribute of the <UXML> element in newly created UXML files.
• xsi:schemaLocation 속성의 네임스페이스에 대한 스키마 파일 위치를 포함합니다.

To ensure that your text editor recognizes the new element, select Assets > Update UXML Schema to update the schema definition.

To create a new UXML document with the prefix, select Assets > Create > UI Toolkit > UI Document.

추가 리소스

• Create custom controls
• Create a custom control with two attributes
• Create a slide toggle custom control
• Create a radial progress indicator
• Create a bindable custom control
• Create a custom style for a custom control