UnityUxmlGenerator

This package is part of UnityMvvmToolkit.

📖 Table of Contents

• About
• Folder Structure
• Installation
• How To Use
  • UxmlElement
  • UxmlAttribute
• Contributing
  • Discussions
  • Report a bug
  • Request a feature
  • Show your support
• License

📝 About

The UnityUxmlGenerator allows you to generate UxmlFactory and UxmlTraits using [UxmlElement] and [UxmlAttribute] attributes.

[UxmlElement]
public partial class CustomVisualElement : VisualElement
{
    [UxmlAttribute]
    private string CustomAttribute { get; set; }
}

🌵 Folder Structure

.
├── src
│   ├── UnityUxmlGenerator
│   └── UnityUxmlGenerator.UnityPackage
│       ...
│       └── UnityUxmlGenerator.dll      # Auto-generated
│
├── UnityUxmlGenerator.sln

⚙️ Installation

You can install UnityUxmlGenerator in one of the following ways:

1. Install via Package Manager

The package is available on the OpenUPM.

• Open Edit/Project Settings/Package Manager

• Add a new Scoped Registry (or edit the existing OpenUPM entry)

  Name      package.openupm.com
  URL       https://package.openupm.com
  Scope(s)  com.chebanovdd.unityuxmlgenerator
  

• Open Window/Package Manager

• Select My Registries

• Install UnityUxmlGenerator package

2. Install via Git URL

You can add https://github.com/LibraStack/UnityUxmlGenerator.git?path=src/UnityUxmlGenerator.UnityPackage/Assets/Plugins/UnityUxmlGenerator to the Package Manager.

If you want to set a target version, UnityUxmlGenerator uses the v*.*.* release tag, so you can specify a version like #v0.0.1. For example https://github.com/LibraStack/UnityUxmlGenerator.git?path=src/UnityUxmlGenerator.UnityPackage/Assets/Plugins/UnityUxmlGenerator#v0.0.1.

🕹️ How To Use

UxmlElement

To create a custom control, just add the [UxmlElement] attribute to the custom control class definition. The custom control class must be declared as a partial class and be inherited from VisualElement or one of its derived classes. By default, the custom control appears in the Library tab in UI Builder.

You can use the [UxmlAttribute] attribute to declare that a property is associated with a UXML attribute.

The following example creates a custom control with multiple attributes:

[UxmlElement]
public partial class CustomVisualElement : VisualElement
{
    [UxmlAttribute]
    private string CustomAttribute { get; set; }
    
    [UxmlAttribute("DefaultValue")]
    private string CustomAttributeWithDefaultValue { get; set; }
}

Generated code

CustomVisualElement.UxmlFactory.g.cs

partial class CustomVisualElement
{
    [global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
    [global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
    public new class UxmlFactory : global::UnityEngine.UIElements.UxmlFactory<CustomVisualElement, UxmlTraits>
    {
    }
}

CustomVisualElement.UxmlTraits.g.cs

partial class CustomVisualElement
{
    [global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
    [global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
    public new class UxmlTraits : global::UnityEngine.UIElements.VisualElement.UxmlTraits
    {
        [global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
        private readonly global::UnityEngine.UIElements.UxmlStringAttributeDescription _customAttribute = new()
        {
            name = "custom-attribute",
            defaultValue = default
        };
  
        [global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
        private readonly global::UnityEngine.UIElements.UxmlStringAttributeDescription _customAttributeWithDefaultValue = new()
        {
            name = "custom-attribute-with-default-value",
            defaultValue = "DefaultValue"
        };
  
        [global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
        [global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
        public override void Init(global::UnityEngine.UIElements.VisualElement visualElement, 
            global::UnityEngine.UIElements.IUxmlAttributes bag, 
            global::UnityEngine.UIElements.CreationContext context)
        {
            base.Init(visualElement, bag, context);
            var control = (CustomVisualElement)visualElement;
            control.CustomAttribute = _customAttribute.GetValueFromBag(bag, context);
            control.CustomAttributeWithDefaultValue = _customAttributeWithDefaultValue.GetValueFromBag(bag, context);
        }
    }
}

The following UXML document uses the custom control:

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <CustomVisualElement custom-attribute="Hello World" custom-attribute-with-default-value="DefaultValue" />
</ui:UXML>

UxmlAttribute

By default, the property name splits into lowercase words connected by hyphens. The original uppercase characters in the name are used to denote where the name should be split. For example, if the property name is CustomAttribute, the corresponding attribute name would be custom-attribute.

The following example creates a custom control with custom attributes:

[UxmlElement]
public partial class CustomVisualElement : VisualElement
{
    [UxmlAttribute]
    private bool MyBoolValue { get; set; }

    [UxmlAttribute]
    private int MyIntValue { get; set; }

    [UxmlAttribute]
    private long MyLongValue { get; set; }

    [UxmlAttribute]
    private float MyFloatValue { get; set; }

    [UxmlAttribute]
    private double MyDoubleValue { get; set; }

    [UxmlAttribute]
    private string MyStringValue { get; set; }

    [UxmlAttribute]
    private MyEnum MyEnumValue { get; set; }

    [UxmlAttribute]
    private Color MyColorValue { get; set; }
}

Use the [UxmlAttribute] constructor to provide a default value for an attribute. Note that the provided value type and the property type must match. The only exception is for the Color type, where you must pass the name of the desired color.

[UxmlElement]
public partial class CustomVisualElement : VisualElement
{
    [UxmlAttribute(69)]
    private int MyIntValue { get; set; }

    [UxmlAttribute(6.9f)]
    private float MyFloatValue { get; set; }

    [UxmlAttribute("Hello World")]
    private string MyStringValue { get; set; }

    [UxmlAttribute(MyEnum.One)]
    private MyEnum MyEnumValue { get; set; }

    [UxmlAttribute(nameof(Color.red))]
    private Color MyColorValue { get; set; }
}

📑 Contributing

You may contribute in several ways like creating new features, fixing bugs or improving documentation and examples.

Discussions

Use discussions to have conversations and post answers without opening issues.

Discussions is a place to:

• Share ideas
• Ask questions
• Engage with other community members

Report a bug

If you find a bug in the source code, please create bug report.

Please browse existing issues to see whether a bug has previously been reported.

Request a feature

If you have an idea, or you're missing a capability that would make development easier, please submit feature request.

If a similar feature request already exists, don't forget to leave a "+1" or add additional information, such as your thoughts and vision about the feature.

Show your support

Give a ⭐ if this project helped you!

⚖️ License

Usage is provided under the MIT License.