Search Unity

UIElements developer guide

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

  1. antoine-unity

    antoine-unity

    Unity Technologies

    Joined:
    Sep 10, 2015
    Posts:
    102
    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:
    611
    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:
    102
    You are right that the uQuery doc is lacking. We will improve this.
     
    Last edited: Mar 27, 2019
    mandisaw and JamesArndt like this.
  4. Baste

    Baste

    Joined:
    Jan 24, 2013
    Posts:
    4,286
    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.
     
  5. GilbertoBitt

    GilbertoBitt

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

    antoine-unity

    Unity Technologies

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

    Murgilod

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

    PixelLifetime

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

    Baste

    Joined:
    Jan 24, 2013
    Posts:
    4,286
    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.
     
  10. PixelLifetime

    PixelLifetime

    Joined:
    Mar 30, 2017
    Posts:
    52
    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:
    13
    This is pretty much my experience too.
     
  12. antoine-unity

    antoine-unity

    Unity Technologies

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

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

    Cleverlie

    Joined:
    Dec 23, 2013
    Posts:
    203
    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:
    299
    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:
    203
    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:
    45
    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:
    203
    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:
    45
    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 at 1:39 PM
    PassivePicasso likes this.
  20. PassivePicasso

    PassivePicasso

    Joined:
    Sep 17, 2012
    Posts:
    54
    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:
    3
    UIElementsEditorUtility appears to be missing from the docs. This is useful if you are going to change the mouse cursor through code.