UIElements developer guide

[antoine-unity]

Hello,

As the API is going out of experimental in 2019.1 we have improved the developer guide and moved it out of the experimental section.

Any feedback is appreciated about what you feel is missing or should be further documented.

We are working on a best practice guide explaining how to best implement custom elements as well as potential performance considerations.

Thanks.

[jwvanderbeck]

The page on uQuery is painfully sparse. Is there more complete documentation with examples anywhere? At the very least there should be examples of how to query objects with different selectors.

[antoine-unity]

You are right that the uQuery doc is lacking. We will improve this.

[Baste]

I’d love to see links to basic examples in that page. How to create a custom inspector using UIElements, how to write an editor window, etc.

I’ve seen such examples earlier, but I can’t quite remember where they are, so having links in the developer guide would be nice.

As for now, the developer guide has a ton of information about the parts of the system (visual tree, layout engine, etc.), but no context for any of those things.

[GilbertoBitt]

i think you guys should have a look at this github. https://github.com/rocktavious/UIEX i

[antoine-unity]

Have you guys seen this page about bindings ? It also contains an example of a custom inspector made with UIElements.

Unity - Manual: Bindings

[Murgilod]

Do we have a roadmap for the game UI phase?

[MaxKarpinsky]

@antoine-unity Hi, could you have a look at this thread, please? Node Graph [Custom Purpose Unity Built-in Node Graph] - Unity Engine - Unity Discussions

[Baste]

Okay, so I came back to this now half a year after I wrote my last post. I’ve recently upgraded an old project to 2019.2, and I was looking at a custom editor for a MonoBehaviour that was behaving kinda weirdly.

I figured “you know what, why don’t I try to rebuild it in UI Elements? It’s the new thing, and it looks pretty good”. So I googled, and the first hit was the developer guide.

Now, my goal when opening that page was to figure out how I go about writing a custom editor using UI elements. And there’s nothing there. There’s all this information about the parts of the system and how they work, but not how you do anything. I think there’s some very good reasons to put a hello world very early in the documentation. There are two main things people will use UI elements for; custom editors and editor windows. Those things should be the entry point.

In other words, the two first links on the developer guide should be “this is how you write a custom editor” and “this is how you write an editor window”. That’s the most important things, and the natural way to start out understanding the system.

[MaxKarpinsky]

@Baste

Okay, so I came back to this now half a year after I wrote my last post. I’ve recently upgraded an old project to 2019.2, and I was looking at a custom editor for a MonoBehaviour that was behaving kinda weirdly.

I figured “you know what, why don’t I try to rebuild it in UI Elements? It’s the new thing, and it looks pretty good”. So I googled, and the first hit was the developer guide.

Now, my goal when opening that page was to figure out how I go about writing a custom editor using UI elements. And there’s nothing there. There’s all this information about the parts of the system and how they work, but not how you do anything. I think there’s some very good reasons to put a hello world very early in the documentation. There are two main things people will use UI elements for; custom editors and editor windows. Those things should be the entry point.

In other words, the two first links on the developer guide should be “this is how you write a custom editor” and “this is how you write an editor window”. That’s the most important things, and the natural way to start out understanding the system.

Those are good points. Meanwhile you can look at these videos
https://www.youtube.com/watch?v=GSRVI1HqlF4

https://www.youtube.com/watch?v=MNNURw0LeoQ

And this one https://github.com/Unity-Technologies/UIElementsExamples , I haven’t checked them out yet but I keep those tabs open for when I have the time.

[SLGSimon]

@Baste

Okay, so I came back to this now half a year after I wrote my last post. I’ve recently upgraded an old project to 2019.2, and I was looking at a custom editor for a MonoBehaviour that was behaving kinda weirdly.

I figured “you know what, why don’t I try to rebuild it in UI Elements? It’s the new thing, and it looks pretty good”. So I googled, and the first hit was the developer guide.

Now, my goal when opening that page was to figure out how I go about writing a custom editor using UI elements. And there’s nothing there. There’s all this information about the parts of the system and how they work, but not how you do anything. I think there’s some very good reasons to put a hello world very early in the documentation. There are two main things people will use UI elements for; custom editors and editor windows. Those things should be the entry point.

In other words, the two first links on the developer guide should be “this is how you write a custom editor” and “this is how you write an editor window”. That’s the most important things, and the natural way to start out understanding the system.

This is pretty much my experience too.

[antoine-unity]

We are currently working on making the manual more helpful and task based.

We will post in thread when improvements are available.

[Cleverlie]

does anybody know anything about that UI Builder they mentioned in the last roadmap video? does it work to create UI for both editor tools and for in-game UI? does it allow us to replace UGUI with it?

[uDamian]

@Cleverlie

does anybody know anything about that UI Builder they mentioned in the last roadmap video? does it work to create UI for both editor tools and for in-game UI? does it allow us to replace UGUI with it?

We’ll post more info on the UI Builder once the Unite talk this week introducing it is posted on YouTube. For now, to answer your questions:

1. Yes, the UI Builder just generates UXML and USS assets. They can be consumed by a custom inspector, an Editor window, or the runtime panel (that renders UIElements in runtime).
2. The plan with UIElements, the framework (including UI Builder), is to become the main UI framework for Unity, for both runtime and Editor. However, UGUI and IMGUI, the older Unity UI frameworks, will not be deprecated anytime soon and will continue to be maintained.

[Cleverlie]

@uDamian

We’ll post more info on the UI Builder once the Unite talk this week introducing it is posted on YouTube. For now, to answer your questions:

1. Yes, the UI Builder just generates UXML and USS assets. They can be consumed by a custom inspector, an Editor window, or the runtime panel (that renders UIElements in runtime).
2. The plan with UIElements, the framework (including UI Builder), is to become the main UI framework for Unity, for both runtime and Editor. However, UGUI and IMGUI, the older Unity UI frameworks, will not be deprecated anytime soon and will continue to be maintained.

I hope this happens soon, I’m eager to try it, I realize that after 5 years of using UGUI there are things that are simple not scalable, hard to implement in a good battle-proven architecture like MVC or MVVM or just by design hard to accomplish, like having some rectTransform be anchored to something different than its parent in the hierarchy, or like having a different render order than the order given by the hierarchy, those things are crucial to some UI designs, but since HTML+CSS is used along the entire industry this will be a change for good probably.

[uMathieu]

@Cleverlie

[…] just by design hard to accomplish, like having some rectTransform be anchored to something different than its parent in the hierarchy, or like having a different render order than the order given by the hierarchy, those things are crucial to some UI designs, […]

You seem to need more control than specifying z-order. Can you share a ui design where what you mention would be needed?

[Cleverlie]

I can’t bring a detailed repro project right now, but for example one difficulty that I usually encounter is when you want a background Image follow the preferred size of a TextMeshProUGUI text, you could do this ideally by adding a ContentSizeFitter to the TMP object, now it’s rect will change its size dynamically to fit the entire text, now I could add an Image as child of the text object and then set the anchors to fit the parent rect, the problem now is that the image will render in front of the text, if I could simple give it a different sort order this would be an easy thing to do, even if I could put the Image as a sibling of the text, but somehow have it’s rectTransform think it’s parent is the text (like how we can do with the recently added ParentConstraint for gameObjects) this problem could be easily solved. But I can’t see an easy way with the current system other than making a custom script that adjusts sizes constantly, maybe there is a way if I learn how the layout system works to implement some ILayoutElement or something like that, but that would require knowledge and time, and I tried it before but I’m still a bit helpless about the UGUI layout system, I didn’t find much detailed documentation, the devil is on the details and is not as straight forward as, say, how I solved this problem with NGUI in the old days.

other examples are, when you want at runtime to bring something to the front, like if you have multiple panel windows opened, since the hierarchy defines the sorting order then you have to mess with child Indexes and resort childrens to move something to front, or mess around with Canvas objects which are not ideal since they add a layer of additional features and complexity not needed for the case, also I think they break batching.

I’m not saying UGUI is bad or too complex, I’ve been using it for the last 5 years and I can manage to do lots of interesting things with it, I just think that HTML + CSS + jquery (aka UXML + USS + uquery) are nowadays industry standards to create UI for all kinds of platforms, and bringing them to Unity is a good move, I love the idea of developing interfaces in retained mode, and having my logic separated from styles and presentation, way more MVVM-friendly and adapted to industry standard patterns! I also hope UGUI doesn’t go anywhere for the foreseeable future!

[uMathieu]

@Cleverlie

I can’t bring a detailed repro project right now, but for example one difficulty that I usually encounter is when you want a background Image follow the preferred size of a TextMeshProUGUI text, you could do this ideally by adding a ContentSizeFitter to the TMP object, now it’s rect will change its size dynamically to fit the entire text, now I could add an Image as child of the text object and then set the anchors to fit the parent rect, the problem now is that the image will render in front of the text, if I could simple give it a different sort order this would be an easy thing to do, even if I could put the Image as a sibling of the text, but somehow have it’s rectTransform think it’s parent is the text (like how we can do with the recently added ParentConstraint for gameObjects) this problem could be easily solved. But I can’t see an easy way with the current system other than making a custom script that adjusts sizes constantly, maybe there is a way if I learn how the layout system works to implement some ILayoutElement or something like that, but that would require knowledge and time, and I tried it before but I’m still a bit helpless about the UGUI layout system, I didn’t find much detailed documentation, the devil is on the details and is not as straight forward as, say, how I solved this problem with NGUI in the old days.

With UIElements, flex takes care of this. If you need both the image and the text to size dynamically according to their content, you simply parent the text element under an image and sizes would follow as intended. If you only need to display the image as simple background of the text, you can set the label’s background-image to your image and that would be the end of it

other examples are, when you want at runtime to bring something to the front, like if you have multiple panel windows opened, since the hierarchy defines the sorting order then you have to mess with child Indexes and resort childrens to move something to front, or mess around with Canvas objects which are not ideal since they add a layer of additional features and complexity not needed for the case, also I think they break batching.

https://docs.unity3d.com/ScriptReference/UIElements.VisualElement.BringToFront.html
https://docs.unity3d.com/ScriptReference/UIElements.VisualElement.SendToBack.html

These change the children ordering for one level. I guess you could recursively call it on the parent’s element to make sure the entire branch is on top.

[…]I also hope UGUI doesn’t go anywhere for the foreseeable future!

There is no plan for deprecating uGUI anytime soon.

[krassemanne]

Hello, I am trying to prepare for the runtime version of UI Elements by only using the stuff in UnityEngine.

I then discovered that there is no dropdown component to use, so I figured I create one myself, like I did for my CSS/Javascript with absolute position and overlay.

So far so good.

But then I noticed that there is no z-index support in USS, which makes it much harder to implement such overlays.

Any standard solution for this? I noticed that there is a BringToFront() etc. but that doesn’t really work when there are other components.
For example, if you move the overlay outside its hierarchy, the absolute position property will look at another parent and position relative that and the simple specification of positioning within the USS will have to be scripted instead.

The best solution I have come up with so far is to have all the overlays last in the hierarchy and position them absolute by checking the absolute position of the dropdown. This is fine but a z-index would be much cleaner.

[PassivePicasso]

@krassemanne

Hello, I am trying to prepare for the runtime version of UI Elements by only using the stuff in UnityEngine.

I then discovered that there is no dropdown component to use, so I figured I create one myself, like I did for my CSS/Javascript with absolute position and overlay.

So far so good.

But then I noticed that there is no z-index support in USS, which makes it much harder to implement such overlays.

Any standard solution for this? I noticed that there is a BringToFront() etc. but that doesn’t really work when there are other components.
For example, if you move the overlay outside its hierarchy, the absolute position property will look at another parent and position relative that and the simple specification of positioning within the USS will have to be scripted instead.

The best solution I have come up with so far is to have all the overlays last in the hierarchy and position them absolute by checking the absolute position of the dropdown. This is fine but a z-index would be much cleaner.

https://discussions.unity.com/t/762607

See my post about it and comment any thoughts you may have, I see this as a problem overall.