Skip to content

Commit af5d2b1

Browse files
ChebanovDDChebanovDD
authored
Update readme
1 parent dd35ace commit af5d2b1

File tree

1 file changed

+168
-1
lines changed

1 file changed

+168
-1
lines changed

‎README.md

Lines changed: 168 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,168 @@
1-
# UnityUxmlGenerator
1+
# UnityUxmlGenerator
2+
3+
This package is part of [UnityMvvmToolkit](https://github.com/LibraStack/UnityMvvmToolkit).
4+
5+
## :open_book: Table of Contents
6+
7+
- [About](#pencil-about)
8+
- [Folder Structure](#cactus-folder-structure)
9+
- [Installation](#gear-installation)
10+
- [How To Use](#joystick-how-to-use)
11+
- [Contributing](#bookmark_tabs-contributing)
12+
- [Discussions](#discussions)
13+
- [Report a bug](#report-a-bug)
14+
- [Request a feature](#request-a-feature)
15+
- [Show your support](#show-your-support)
16+
- [License](#balance_scale-license)
17+
18+
## :pencil: About
19+
20+
The **UnityUxmlGenerator** allows you to generate `UxmlFactory` and `UxmlTraits` using `[UxmlElement]` and `[UxmlAttribute]` attributes.
21+
22+
```csharp
23+
[UxmlElement]
24+
public partial class CustomVisualElement : VisualElement
25+
{
26+
[UxmlAttribute]
27+
private string CustomAttribute { get; set; }
28+
}
29+
```
30+
31+
## :cactus: Folder Structure
32+
33+
.
34+
├── src
35+
│ ├── UnityUxmlGenerator
36+
│ └── UnityUxmlGenerator.UnityPackage
37+
│ ...
38+
│ └── UnityUxmlGenerator.dll # Auto-generated
39+
│
40+
├── UnityUxmlGenerator.sln
41+
42+
## :gear: Installation
43+
44+
You can install **UnityUxmlGenerator** in one of the following ways:
45+
46+
<details><summary>1. Install via package file</summary>
47+
<br />
48+
49+
- Download `unityuxmlgenerator.tgz` from [releases](https://github.com/LibraStack/UnityUxmlGenerator/releases)
50+
- Open `Window/Package Manager`
51+
- Select `Add package from tarball...`
52+
53+
</details>
54+
55+
<details><summary>2. Install via Git URL</summary>
56+
<br />
57+
58+
You can add `https://github.com/LibraStack/UnityUxmlGenerator.git?path=src/UnityUxmlGenerator.UnityPackage/Assets/Plugins/UnityUxmlGenerator` to the Package Manager.
59+
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`.
61+
62+
</details>
63+
64+
## :joystick: How To Use
65+
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.
67+
68+
You can use the `[UxmlAttribute]` attribute to declare that a property is associated with a `UXML` attribute.
69+
70+
The following example creates a custom control with multiple attributes:
71+
72+
```csharp
73+
[UxmlElement]
74+
public partial class CustomVisualElement : VisualElement
75+
{
76+
[UxmlAttribute]
77+
private string CustomAttribute { get; set; }
78+
79+
[UxmlAttribute("DefaultValue")]
80+
private string CustomAttributeWithDefaultValue { get; set; }
81+
}
82+
```
83+
84+
<details><summary><b>Generated code</b></summary>
85+
<br />
86+
87+
`CustomVisualElement.UxmlFactory.g.cs`
88+
89+
```csharp
90+
partial class CustomVisualElement
91+
{
92+
[global::System.CodeDom.Compiler.GeneratedCodeAttribute("UnityUxmlGenerator", "1.0.0.0")]
93+
public new class UxmlFactory : global::UnityEngine.UIElements.UxmlFactory<CustomVisualElement, UxmlTraits>
94+
{
95+
}
96+
}
97+
```
98+
99+
`CustomVisualElement.UxmlTraits.g.cs`
100+
101+
```csharp
102+
partial class CustomVisualElement
103+
{
104+
[global::System.CodeDom.Compiler.GeneratedCodeAttribute("UnityUxmlGenerator", "1.0.0.0")]
105+
public new class UxmlTraits : global::UnityEngine.UIElements.VisualElement.UxmlTraits
106+
{
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")]
116+
[global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
117+
public override void Init(global::UnityEngine.UIElements.VisualElement visualElement,
118+
global::UnityEngine.UIElements.IUxmlAttributes bag,
119+
global::UnityEngine.UIElements.CreationContext context)
120+
{
121+
base.Init(visualElement, bag, context);
122+
123+
var control = (CustomVisualElement) visualElement;
124+
control.CustomAttribute = customAttribute.GetValueFromBag(bag, context);
125+
control.CustomAttributeWithDefaultValue = customAttributeWithDefaultValue.GetValueFromBag(bag, context);
126+
}
127+
}
128+
}
129+
```
130+
131+
</details>
132+
133+
> **Note:** For now, only `string` attributes are supported.
134+
135+
## :bookmark_tabs: Contributing
136+
137+
You may contribute in several ways like creating new features, fixing bugs or improving documentation and examples.
138+
139+
### Discussions
140+
141+
Use [discussions](https://github.com/LibraStack/UnityUxmlGenerator/discussions) to have conversations and post answers without opening issues.
142+
143+
Discussions is a place to:
144+
* Share ideas
145+
* Ask questions
146+
* Engage with other community members
147+
148+
### Report a bug
149+
150+
If you find a bug in the source code, please [create bug report](https://github.com/LibraStack/UnityUxmlGenerator/issues/new?assignees=ChebanovDD&labels=bug&template=bug_report.md&title=).
151+
152+
> Please browse [existing issues](https://github.com/LibraStack/UnityUxmlGenerator/issues) to see whether a bug has previously been reported.
153+
154+
### Request a feature
155+
156+
If you have an idea, or you're missing a capability that would make development easier, please [submit feature request](https://github.com/LibraStack/UnityUxmlGenerator/issues/new?assignees=ChebanovDD&labels=enhancement&template=feature_request.md&title=).
157+
158+
> 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.
159+
160+
### Show your support
161+
162+
Give a :star: if this project helped you!
163+
164+
<a href="https://www.buymeacoffee.com/chebanovdd" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-orange.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
165+
166+
## :balance_scale: License
167+
168+
Usage is provided under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)