Skip to content

Commit db7c63b

Browse files
authored
Update readme file.
1 parent bc4e19e commit db7c63b

File tree

1 file changed

+96
-20
lines changed

1 file changed

+96
-20
lines changed

README.md

Lines changed: 96 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ This package is part of [UnityMvvmToolkit](https://github.com/LibraStack/UnityMv
88
- [Folder Structure](#cactus-folder-structure)
99
- [Installation](#gear-installation)
1010
- [How To Use](#joystick-how-to-use)
11+
- [UxmlElement](#uxmlelement)
12+
- [UxmlAttribute](#uxmlattribute)
1113
- [Contributing](#bookmark_tabs-contributing)
1214
- [Discussions](#discussions)
1315
- [Report a bug](#report-a-bug)
@@ -57,13 +59,15 @@ You can install **UnityUxmlGenerator** in one of the following ways:
5759

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

60-
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-preview1`.
62+
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`.
6163

6264
</details>
6365

6466
## :joystick: How To Use
6567

66-
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.
68+
### UxmlElement
69+
70+
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.
6771

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

@@ -85,52 +89,124 @@ public partial class CustomVisualElement : VisualElement
8589
<br />
8690

8791
`CustomVisualElement.UxmlFactory.g.cs`
88-
92+
8993
```csharp
9094
partial class CustomVisualElement
9195
{
92-
[global::System.CodeDom.Compiler.GeneratedCodeAttribute("UnityUxmlGenerator", "1.0.0.0")]
93-
public new class UxmlFactory : global::UnityEngine.UIElements.UxmlFactory<CustomVisualElement, UxmlTraits>
96+
[global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
97+
[global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
98+
public new class UxmlFactory : global::UnityEngine.UIElements.UxmlFactory<CustomVisualElement, UxmlTraits>
9499
{
95100
}
96101
}
97102
```
98103

99104
`CustomVisualElement.UxmlTraits.g.cs`
100-
105+
101106
```csharp
102107
partial class CustomVisualElement
103108
{
104-
[global::System.CodeDom.Compiler.GeneratedCodeAttribute("UnityUxmlGenerator", "1.0.0.0")]
109+
[global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
110+
[global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
105111
public new class UxmlTraits : global::UnityEngine.UIElements.VisualElement.UxmlTraits
106112
{
107-
[global::System.CodeDom.Compiler.GeneratedCodeAttribute("UnityUxmlGenerator", "1.0.0.0")]
108-
private readonly global::UnityEngine.UIElements.UxmlStringAttributeDescription _customAttribute = new()
109-
{ name = "custom-attribute", defaultValue = "" };
110-
111-
[global::System.CodeDom.Compiler.GeneratedCodeAttribute("UnityUxmlGenerator", "1.0.0.0")]
112-
private readonly global::UnityEngine.UIElements.UxmlStringAttributeDescription _customAttributeWithDefaultValue = new()
113-
{ name = "custom-attribute-with-default-value", defaultValue = "DefaultValue" };
114-
115-
[global::System.CodeDom.Compiler.GeneratedCodeAttribute("UnityUxmlGenerator", "1.0.0.0")]
113+
[global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
114+
private readonly global::UnityEngine.UIElements.UxmlStringAttributeDescription _customAttribute = new()
115+
{
116+
name = "custom-attribute",
117+
defaultValue = default
118+
};
119+
120+
[global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
121+
private readonly global::UnityEngine.UIElements.UxmlStringAttributeDescription _customAttributeWithDefaultValue = new()
122+
{
123+
name = "custom-attribute-with-default-value",
124+
defaultValue = "DefaultValue"
125+
};
126+
127+
[global::System.CodeDom.Compiler.GeneratedCode("UnityUxmlGenerator", "1.0.0.0")]
116128
[global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
117129
public override void Init(global::UnityEngine.UIElements.VisualElement visualElement,
118130
global::UnityEngine.UIElements.IUxmlAttributes bag,
119131
global::UnityEngine.UIElements.CreationContext context)
120132
{
121133
base.Init(visualElement, bag, context);
122-
123-
var control = (CustomVisualElement) visualElement;
134+
var control = (CustomVisualElement)visualElement;
124135
control.CustomAttribute = _customAttribute.GetValueFromBag(bag, context);
125136
control.CustomAttributeWithDefaultValue = _customAttributeWithDefaultValue.GetValueFromBag(bag, context);
126137
}
127138
}
128139
}
129140
```
130-
141+
131142
</details>
132143

133-
> **Note:** For now, only `string` attributes are supported.
144+
The following UXML document uses the custom control:
145+
146+
```xml
147+
<ui:UXML xmlns:ui="UnityEngine.UIElements">
148+
<CustomVisualElement custom-attribute="Hello World" custom-attribute-with-default-value="DefaultValue" />
149+
</ui:UXML>
150+
```
151+
152+
### UxmlAttribute
153+
154+
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`.
155+
156+
The following example creates a custom control with custom attributes:
157+
158+
```csharp
159+
[UxmlElement]
160+
public partial class CustomVisualElement : VisualElement
161+
{
162+
[UxmlAttribute]
163+
private bool MyBoolValue { get; set; }
164+
165+
[UxmlAttribute]
166+
private int MyIntValue { get; set; }
167+
168+
[UxmlAttribute]
169+
private long MyLongValue { get; set; }
170+
171+
[UxmlAttribute]
172+
private float MyFloatValue { get; set; }
173+
174+
[UxmlAttribute]
175+
private double MyDoubleValue { get; set; }
176+
177+
[UxmlAttribute]
178+
private string MyStringValue { get; set; }
179+
180+
[UxmlAttribute]
181+
private MyEnum MyEnumValue { get; set; }
182+
183+
[UxmlAttribute]
184+
private Color MyColorValue { get; set; }
185+
}
186+
```
187+
188+
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.
189+
190+
```csharp
191+
[UxmlElement]
192+
public partial class CustomVisualElement : VisualElement
193+
{
194+
[UxmlAttribute(69)]
195+
private int MyIntValue { get; set; }
196+
197+
[UxmlAttribute(6.9f)]
198+
private float MyFloatValue { get; set; }
199+
200+
[UxmlAttribute("Hello World")]
201+
private string MyStringValue { get; set; }
202+
203+
[UxmlAttribute(MyEnum.One)]
204+
private MyEnum MyEnumValue { get; set; }
205+
206+
[UxmlAttribute(nameof(Color.red))]
207+
private Color MyColorValue { get; set; }
208+
}
209+
```
134210

135211
## :bookmark_tabs: Contributing
136212

0 commit comments

Comments
 (0)