To use custom controls with UXML and UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary Builder, you must expose them.
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> {}
// ...
}
With this factory defined, you can use the <StatusBar>
element in UXML files.
You can define UXML traits for a new class and set its factory to use these traits.
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);
}
}
// ...
}
The UxmlTraits
serves two purposes:
The code example above does the following:
m_Status
defines an XML attribute named status
.uxmlChildElementsDescription
returns an empty IEnumerable
which indicates that StatusBar
element has no child.Init()
member reads the value of the status
attribute in a property bag from the XML parser and sets the StatusBar.status
property to this value.UxmlTraits
class is placed inside the StatusBar
class. This allows the Init()
method to access the private members of StatusBar
.UxmlTraits
class inherits from the base class UxmlTraits
, so it shares the attributes of the base class.Init()
calls base.Init()
to initialize the base class properties.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:
Attribute | Attribute value |
---|---|
UxmlStringAttributeDescription |
A string |
UxmlFloatAttributeDescription |
A single precision floating point value in the range of the C# float type. |
UxmlDoubleAttributeDescription |
A double precision floating point value in the range of the C# double type. |
UxmlIntAttributeDescription |
An integer value in the range of the C# int type. |
UxmlLongAttributeDescription |
A long integer value in the range of the C# long type. |
UxmlBoolAttributeDescription |
true or false
|
UxmlColorAttributeDescription |
A string that represents a color defined in USS format. |
UxmlEnumAttributeDescription<T> |
A string that represents one of the values for the Enum type T . |
UxmlTypeAttributeDescription<T> |
A string that represents the assembly-qualified name of the 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));
}
}
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")]
You can do this at the root level (outside any namespace) of any C# file of the assembly.
The schema generation system does the following:
<UXML>
element in newly created UXML files.xsi:schemaLocation
attribute.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.
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.