Search Unity

  1. Good news ✨ We have more Unite Now videos available for you to watch on-demand! Come check them out and ask our experts any questions!
    Dismiss Notice
  2. Ever participated in one our Game Jams? Want pointers on your project? Our Evangelists will be available on Friday to give feedback. Come share your games with us!
    Dismiss Notice

UIElements developer guide

Discussion in 'UI Toolkit' started by antoine-unity, Mar 20, 2019.

  1. antoine-unity

    antoine-unity

    Unity Technologies

    Joined:
    Sep 10, 2015
    Posts:
    158
    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.
     
  2. jwvanderbeck

    jwvanderbeck

    Joined:
    Dec 4, 2014
    Posts:
    702
    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.
     
  3. antoine-unity

    antoine-unity

    Unity Technologies

    Joined:
    Sep 10, 2015
    Posts:
    158
    You are right that the uQuery doc is lacking. We will improve this.
     
    Last edited: Mar 27, 2019
    fxlange, mandisaw and JamesArndt like this.
  4. Baste

    Baste

    Joined:
    Jan 24, 2013
    Posts:
    4,748
    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.
     
    Alverik, EricLampi, TheValar and 3 others like this.
  5. GilbertoBitt

    GilbertoBitt

    Joined:
    May 27, 2013
    Posts:
    83
  6. antoine-unity

    antoine-unity

    Unity Technologies

    Joined:
    Sep 10, 2015
    Posts:
    158
    Sarkahn likes this.
  7. Murgilod

    Murgilod

    Joined:
    Nov 12, 2013
    Posts:
    7,113
    Do we have a roadmap for the game UI phase?
     
  8. PixelLifetime

    PixelLifetime

    Joined:
    Mar 30, 2017
    Posts:
    64
  9. Baste

    Baste

    Joined:
    Jan 24, 2013
    Posts:
    4,748
    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.
     
    MagicDesignEmerick and Alverik like this.
  10. PixelLifetime

    PixelLifetime

    Joined:
    Mar 30, 2017
    Posts:
    64
    Those are good points. Meanwhile you can look at these videos



    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.
     
    mandisaw likes this.
  11. SLGSimon

    SLGSimon

    Joined:
    Jul 23, 2019
    Posts:
    53
    This is pretty much my experience too.
     
  12. antoine-unity

    antoine-unity

    Unity Technologies

    Joined:
    Sep 10, 2015
    Posts:
    158
    We are currently working on making the manual more helpful and task based.

    We will post in thread when improvements are available.
     
    Sarkahn, SLGSimon and PixelLifetime like this.
  13. Cleverlie

    Cleverlie

    Joined:
    Dec 23, 2013
    Posts:
    209
    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?
     
  14. uDamian

    uDamian

    Unity Technologies

    Joined:
    Dec 11, 2017
    Posts:
    631
    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.
     
    mandisaw and Cleverlie like this.
  15. Cleverlie

    Cleverlie

    Joined:
    Dec 23, 2013
    Posts:
    209
    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.
     
    mandisaw likes this.
  16. uMathieu

    uMathieu

    Unity Technologies

    Joined:
    Jun 6, 2017
    Posts:
    116
    You seem to need more control than specifying z-order. Can you share a ui design where what you mention would be needed?
     
  17. Cleverlie

    Cleverlie

    Joined:
    Dec 23, 2013
    Posts:
    209
    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!
     
    mandisaw likes this.
  18. uMathieu

    uMathieu

    Unity Technologies

    Joined:
    Jun 6, 2017
    Posts:
    116
    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 :)

    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.

    There is no plan for deprecating uGUI anytime soon.
     
    mandisaw likes this.
  19. krassemanne

    krassemanne

    Joined:
    Jun 27, 2015
    Posts:
    8
    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.
     
    Last edited: Oct 22, 2019
    PassivePicasso likes this.
  20. PassivePicasso

    PassivePicasso

    Joined:
    Sep 17, 2012
    Posts:
    79
    https://forum.unity.com/threads/typ...pup-dropdown-screen-space-positioning.764504/

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

    EvgenyVasilyev

    Joined:
    Jul 5, 2019
    Posts:
    5
    UIElementsEditorUtility appears to be missing from the docs. This is useful if you are going to change the mouse cursor through code.
     
  22. sebastiend-unity

    sebastiend-unity

    Unity Technologies

    Joined:
    Nov 9, 2015
    Posts:
    33
    You are right. This is noted and I will notify our UI documentation team.
     
  23. sebastiend-unity

    sebastiend-unity

    Unity Technologies

    Joined:
    Nov 9, 2015
    Posts:
    33
    If/when it becomes public of course.
     
  24. matthew-holtzem

    matthew-holtzem

    Joined:
    Sep 1, 2016
    Posts:
    24
    Any word on when we might see some updated documentation? Trying to get up to speed on this system but finding it pretty difficult to get started due to lack of documentation or Unity Learn tutorials
     
  25. uDamian

    uDamian

    Unity Technologies

    Joined:
    Dec 11, 2017
    Posts:
    631
  26. TJHeuvel-net

    TJHeuvel-net

    Joined:
    Jul 31, 2012
    Posts:
    470
    I have a question regarding the UIBuilder, as a developer is writing the plain XML files still fully supported, and taken into consideration when you are developing the standards?

    My background is in frontend webdevelopment, where nobody uses a visual editor for HTML. Although i see some value in the UI builder for my colleages, i dont plan on using it myself very much and prefer to write plain XML in my text editor. Though when i look at the runtime example the code is quite convoluted with namespaces etc.
     
  27. uDamian

    uDamian

    Unity Technologies

    Joined:
    Dec 11, 2017
    Posts:
    631
    We are striving to have the UI Builder generate clean UXML, as close to a manually written one as possible. What you linked above is about as clean as you could write that UXML manually, including the use of namespaces to shorten the tag names. This also means having the UI Builder properly load and handle any manually written UXML as well.

    Keep in mind that UXML tags are really just C# type names, and they need to be fully qualified with their namespace. UXML is not HTML, in that it has no <div>, <h1>, <p>... tags. It just has a few special types of tags, like <Style> and <Instance>, but even those can be namespaced so they don't conflict with your own custom C# type: "Style".
     
    TJHeuvel-net likes this.
  28. TJHeuvel-net

    TJHeuvel-net

    Joined:
    Jul 31, 2012
    Posts:
    470
    I havent really read into it completely, but when i read the UXML from the manual here it is quite different, and readable. Much more like HTML, and easily human-writable.

    Thanks for your response, but i still dont know if writing it manually is a scenario you want to support or not.
     
  29. uDamian

    uDamian

    Unity Technologies

    Joined:
    Dec 11, 2017
    Posts:
    631
    I see what you mean now. We've changed our UXML standard (and therefore our generation of UXML) to avoid using the default namespace (x
    mlns="UnityEngine.UIElements"
    ). You are free to use the default namespace in your UXML files but we no longer assume the
    UnityEngine.UIElements
    is the default namespace. It conflicted too much with user-made custom C# elements with the same names (ie. "Box"). That's why Builder-generated UXML always uses explicit namespaces.

    To confirm, writing UXML/USS manually is a scenario we will continue to support, including IDE extensions for better auto-completion and syntax highlighting.
     
  30. TJHeuvel-net

    TJHeuvel-net

    Joined:
    Jul 31, 2012
    Posts:
    470
    Awesome, thats great to hear! It makes a lot of sense that generated code is less readable than handwritten.

    Cant wait to use this in runtime!
     
    Last edited: Dec 2, 2019
  31. thepigeonfighter

    thepigeonfighter

    Joined:
    Nov 7, 2017
    Posts:
    26
    I think something that would be really nice would be if the UIElements debugger had a USS dump section similar to the UXML dump section. The values that are edited get added to a generated USS dump section that I can just copy the changes I like and paste them into my file. And obviously as others were saying more "how to docs".Especially on big picture stuff. For example design strategies. I was looking over how shadergraph was implemented using UIElements and it looked awesome although it was very hard to navigate due to Visual Studio not indexing that assembly. Which meant I couldn't jump to definitions. Plus it seemed to be using some sort of variation of a MVC pattern but not a one to one implementation. So I would be interested in the most efficient organizational strategies you all used.
     
  32. JodyMagnopus

    JodyMagnopus

    Joined:
    Sep 17, 2016
    Posts:
    13
    I would just like to mention that there is nothing in the documentation about how to create a UI which consists of an array of objects which comes from a member variable in a Scriptable object using the XML-based approach. It is also hard to know what you can type in with the XML so I avoided it entirely. Perhaps the UI builder is meant to address that part of it. I will definitely give the latest UI Builder a try if I have to make a new UI window in the future.
     
  33. uDamian

    uDamian

    Unity Technologies

    Joined:
    Dec 11, 2017
    Posts:
    631
    If you add a PropertyField in UXML with the binding-path set to the name of the member variable, you should get a resizable list generated for you.

    This is not a list example, but it shows how to use the PropertyField in UXML:
    https://github.com/Unity-Technologi...Intro/Resources/Inspector/inspector_uxml.uxml
    Here's the C# counterpart:
    https://github.com/Unity-Technologi.../Assets/QuickIntro/Editor/BasicsDemoWindow.cs (look for
    #region Bindings


    If you want type of items in the array are custom and have a CustomPropertyDrawer, they will be drawn using the custom drawer. The custom drawer itself can also use UIElements and therefore UXML.
     
  34. TheZaeron

    TheZaeron

    Joined:
    May 10, 2014
    Posts:
    5
    Hi!

    I was recommended to ask about this here.

    I'm trying to get an EnumField style dropdown to display custom strings that represent the actual enum values, and either I really suck (which is entirely possible, I've got no prior experience working with Property Drawers, as was suggested for me to try and work around this) or there doesn't seem to be a straightforward way of achieving this?

    If good documentation or a more straightforward way of doing this is coming, please let me know, otherwise feel free to slap me on the wrist for being low-effort/unskilled and not working harder on this :D

    Many thanks
     
  35. uDamian

    uDamian

    Unity Technologies

    Joined:
    Dec 11, 2017
    Posts:
    631
    Sorry to do this but please start another thread for your question. This thread is just about the developer guide itself.
     
  36. TheZaeron

    TheZaeron

    Joined:
    May 10, 2014
    Posts:
    5
    Sorry!
     
unityunity