Search Unity

  1. Megacity Metro Demo now available. Download now.
    Dismiss Notice
  2. Unity support for visionOS is now available. Learn more in our blog post.
    Dismiss Notice

Official UIElements developer guide

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

Thread Status:
Not open for further replies.
  1. uDamian

    uDamian

    Unity Technologies

    Joined:
    Dec 11, 2017
    Posts:
    1,231
    The intro video is a bit dated, yes, though the API did not change that much. I liked it as a resource to get an idea of the basic parts of UI Toolkit and how they work together. The First Steps tutorial should also be a good resource.

    As for deleting the template data in the auto-generated UXML files, indeed, you can't have an empty UXML file and still be valid. You need at least the `<UXML></UXML>` root tag. You can also try building UXML and USS using the UI Builder and look at what it generates to get an idea of how to work with UXML.

    Also, you can get more info in UI Toolkit's documentation:
    https://docs.unity3d.com/Packages/com.unity.ui@1.0/manual/index.html
     
  2. a436t4ataf

    a436t4ataf

    Joined:
    May 19, 2013
    Posts:
    1,924
    Came here searching for exactly this, but ...

    Sadly that page doesn't expain how to make custom inspectors in general, it simply shows "load a USS/UXML pair" and then skips to the next section. There's nothing there on actually writing custom inspectors :(. If anyone has a concrete example of an actual custom inspector - with code, not styling - I'd love to see it (can't find one in the docs, can't find one in the forums so far).
     
  3. JuliaP_Unity

    JuliaP_Unity

    Unity Technologies

    Joined:
    Mar 26, 2020
    Posts:
    696
    If you're using the UI Toolkit package, both the UIDocument and PanelSettings classes have custom inspectors and you can check out their codes in there ;)
    They use UXML and USS as well, but you could do it all by code if you prefer.
     
  4. a436t4ataf

    a436t4ataf

    Joined:
    May 19, 2013
    Posts:
    1,924
    I'm sorry if this wasn't clear, but I was specifically saying we need examples of how to *write* custom inspectors - write as in "code", not "external proprietary stylesheets that don't use code and aren't C#".

    If you just want to display some stylesheets - that page already shows how to do some of it.
     
  5. Phenotype

    Phenotype

    Joined:
    Oct 26, 2010
    Posts:
    53
    I am trying to build my own controls based on visualelement but you have so many internal classes, methods, interfaces, etc. I'm not sure how I'm supposed to work with it. I tried to derive my own button following your example but I get numerous internal errors. You do want developers to derive from your libraries don't you?
     
  6. marcospgp

    marcospgp

    Joined:
    Jun 11, 2018
    Posts:
    194
    Are you guys planning to introduce code examples anywhere in the near future? The documentation is not very helpful at the moment, and seems more guided towards someone who's going to contribute to the package itself than for someone wanting to use it.
     
    snam23 likes this.
  7. snam23

    snam23

    Joined:
    Jul 7, 2013
    Posts:
    1
    I second all those requests asking for code examples. Why is it so hard to find out how to actually implement this great new system?
     
    marcospgp likes this.
  8. tonycoculuzzi

    tonycoculuzzi

    Joined:
    Jun 2, 2011
    Posts:
    301
    I posted more about it here but, I think the developer guide is severely lacking when it comes to creating your own editor elements with binding using SerializedObject/SerializedProperty

    Like others have mentioned, it seems as if the documentation just skips this section for no reason. The Bindings page tells us next to nothing about using BindableElement, IBindable, or IBindings
     
    dannyalgorithmic and marcospgp like this.
  9. Jadefire16

    Jadefire16

    Joined:
    Jul 14, 2019
    Posts:
    19
    So I decided to take a walk through UIElements, recently I've been re-learning the old way of doing things trying to make a custom tool and I thought there should be a better way. So I made the mistake of trying to use UIElements.
    The docs are atrocious. Half of the stuff they mention doesn't even EXIST anymore never mind work, and having to bounce between obscure Stackoverflow posts and poor documentation to get a single button to show up, after 3 hours, is stressing even my patience.
    The whole system feels thrown together, and if there was a decent design behind all of it its been lost through the updates and lack of concrete documentation. Maybe if I had a deeper understanding of XML I'd be having less issues, so I'll probably end up going and learning XML while I wait for Unity to ever release new and up to date documentation.
    The short of it? If you plan on doing any editor tools I'm going to recommend wholeheartedly avoiding the UI Elements system for at least another couple years, unless you have a strong background in XML and C#. Even then I can't really make any promises that the experience will be anything better than okay.
     
    Supergeek and TJHeuvel-net like this.
  10. a436t4ataf

    a436t4ataf

    Joined:
    May 19, 2013
    Posts:
    1,924
    I agree the docs are very bad, but I feel the actual code/implemetnation/API is mostly very easy to use once you figure out a few basics.

    I've been writing-up my own notes here: https://flexbox4unity.com/2020/10/2...ditorwindows-custom-inspectors-and-raw-imgui/ - and I refer back to them each time I have to do a new Inspector UI or new EditorWindow and forget something obvious. I've got another 3-5 pages of notes to add, but just been too busy recently - the one in progress is all about Buttons (there's some non-obvious, non-documented stuff you need to know - but is easy once you know it) - I'll try to get the rest of this posted this weekend.

    For reference: I made a new tabbed-UI from scratch last weekend, with buttons, rollovers, dynamic sizing, flowing grids, etc in the space of a couple of hours. I didn't use any Unity code for the tabbed panels, I made them from scratch because it was so quick to do with Unity buttons + VisualElements. So: don't give up on it, it gets very fast to work with once you work out the things that should definitely have been documented but haven't been (and after you discover some thigns that used to work but the team changed/removed in more recent versions, so you need to discover the replacevments/workarounds)

    I strongly recommend using UIToolkit(UIElements) for editor tools.
     
  11. tonycoculuzzi

    tonycoculuzzi

    Joined:
    Jun 2, 2011
    Posts:
    301
    I second this.
     
  12. Ruchir

    Ruchir

    Joined:
    May 26, 2015
    Posts:
    934
    Please extend this to include more UI Toolkit methods, this is the best documentation/Example I've seen so far for UI Toolkit :)
     
  13. a436t4ataf

    a436t4ataf

    Joined:
    May 19, 2013
    Posts:
    1,924
    OK, I've added four more tutorials, and created an index page with links to all of them - https://flexbox4unity.com/2021/02/25/2021-uitoolkit-all-tutorials/

    Added: Labels, Clickable Labels, Buttons, Styling / mouseover support

    If you've got specific parts of UIToolkit you want me to write a tutorial on, PM me. I can't promise anything, but if it's a part of UIToolkit I've already used a lot I will try to do a writeup soon!
     
    marcospgp and Ruchir like this.
  14. yuemco

    yuemco

    Joined:
    Jul 1, 2018
    Posts:
    36
    Hi @a436t4ataf,

    Thank you for your valuable tutorials. I liked that. I hope you will keep feed that branch in future. You also used editor examples as well like me, Is there any way to use visual elements for game UI. Do you have any experiences of that?
     
  15. a436t4ataf

    a436t4ataf

    Joined:
    May 19, 2013
    Posts:
    1,924
    You can definitely use VisualElement in game UI - lots of posts on that in this forum - but it was only added recently and still is missing a lot of important features and fixes, so I don't use it for game UI.

    Also: it is incompatible / not integrated with core Unity features, which is OK for some people, but personally I like to include any/all of Unity3D rendering, animation, 3D, shaders, particles/Shuriken, etc in my interfaces. So I don't expect to adopt it for game UI for at least another 2 years.

    (NB: I'm also biased -- because I wanted the CSS Flexbox layout system, inside core Unity, I wrote my own asset. So that already solves all my needs for game UI, and has many features that UIToolkit does not have / will not have - so my *biased* view is that I'm less likely to use UIToolkit for game UI for quite a long time :). Make your own mind up!)
     
  16. Emiles

    Emiles

    Joined:
    Jan 22, 2014
    Posts:
    61
    There is so much to cover regards the transition from IMGUI to ToolKit that its hard to convey in one post exactly what would have helped me onboard a lot quicker. To convey where I spent hours trying to understand a simple concept that once i understood it could be conveyed in 3 lines of code.

    Heres what comes to mind in terms of how you could improve this. Context is i'm wanting to build custom property inspectors, maybe a custom editor window, so the below suggestions are with that in mind.

    1. Your announcement demos are not good to learn from. They show how to make a rather contrived example that isn't really the first thing i want to work out to do, and barely cover the main issues one encounters when making a custom property inspector. Yet its the main thing you find in searchs. All the good stuff is super hidden.

    2. The very first link, landing page, search result for UIElements, UIToolkit should send you to the THE perfect Homepage that contains the rational, what it is, links to videos, links to tutorials, definitive github, forum, set of examples, learning aids and class references. I found all of this trawling through endless search queries trying to work out how to render List<MyClass> mylistofthings in a custom inspector and add/remove list items.

    3. Your examples need to be relevant and adress the most common things people need to do.

    Critically, it should be one example, that builds up on previous steps. Rather than disparate examples that have really contrived purposes that aren't the norm and unrelated.

    • Start with how to make a custom editor. sure.
    • Make sure to next show how a custom property inspector works with that prio example.
    • Point out that a custom property Inspector has to be a parent of a UIToolkit editor otherwise it wont render and will default to the none existent IMGUI implementation.

    • Show how to best structure anything that requires redrawing as methods that either get passed references to visual elements, or re-aquires them. i.e. that bit about
    • CreatePropertyGUI is only called once. So when updating lists make sure to understand how to use change events etc.
    • Show that rootVisualElement.bind(serialisedObject) needs to be called when redrawing layouts with re-bound items for them to even appear. I'm not sure i've even got this bit right, but it works.
    • Show how to listen for change events from child property inspectors (I haven't worked this out yet)
    • Show how to add/remove items from a List. This is what i've settled on. Yet to work out how to get a button in the child property inspector to insert an item in a specific location.
    Code (CSharp):
    1. Button addTaskButton = new Button(() =>
    2.             {
    3.                 Debug.Log("Add Item");
    4.                 Undo.RecordObject(property.serializedObject.targetObject , "Added SubTask");
    5.                 SerializedProperty subTasks = property.FindPropertyRelative("subTasks");
    6.                 subTasks.InsertArrayElementAtIndex(0);
    7.                 property.serializedObject.ApplyModifiedProperties();
    8.                 DrawList(taskList,property);
    9.             }){text = "Add Task"};
    10.             addTaskButton.AddToClassList("subtask-button");
    11.  
    • Show an example of how to properly deal with nested classes. Last time i tried [serialiseReference] it didn't work. only displayed 'element 0, element 1' didn't render the custom property inspector, i guess i somehow needed to tell it what class it was or something.
    Code (CSharp):
    1. class Task{
    2.     [SerialiseReference] // <--- this supposedly solves the problem of recursive nesting but i'll be damned if i can get it to work in the custom property inspector.
    3.     public List<Task> subTasks;
    4. }
    • Don't write layouts in C# with custom styles. Take the leap to using USS and UXML as its much more efficient and easy when you know how. Litterly read notes from Unity devs stating that styles applied in css code aren't great.

    I feel like you should have the equivelent of test cases but for common property inspector tasks. They should be the same for every version of Unity.

    Now that i've worked this all out (like a whole week of searching and head banging) I think its great and i've built exactly what i wanted and know that there are a couple of refactors i can do to make it much better. But seriously, this should have taken an hour or two to understand and resolve basic tasks. Perhap i'm just thick.

    Some things i'm still looking to explore
    • Write my own meta tags for class properties to add extra functionality.
    • Write my own UXML components, work out how to bind them properly.

    [edit]
    I'll try and post the articles i found most usefull, some of them in the forum, but really should have been in the documentation.
     
    Last edited: Feb 26, 2021
  17. a436t4ataf

    a436t4ataf

    Joined:
    May 19, 2013
    Posts:
    1,924
    (begin rant; feel free to ignore - but it really annoys me how many people have a similar experience. SO MANY people I speak to think that they find UIToolkit hard because they aren't smart enough. No. You are not "thick". Do not blame yourself. Blame UIToolkit for dismally missing basic documentation - some of which they have been promising to do for more than a year)

    Unpopular opinion: No, it's not you. UIToolkit is great. The docs are terrible and have a lot of room for improvement.
     
    Last edited: Mar 1, 2021
  18. a436t4ataf

    a436t4ataf

    Joined:
    May 19, 2013
    Posts:
    1,924
    Both are valuable. But unless you want to allow other people to make custom styling you should be avoiding USS in my opinion.

    It takes me about 10 seconds to make relatively complex custom styles in C# (I'm using Rider; VS Code should be much the same - everything is auto-completed very fast). And to make anything *complex* takes me < 15 minutes - stuff that takes literally an hour or more to make in USS. Most of my classes are method signatures like "private VisualElement CreateXXX( param, param, param ... )" that creates an entire subset of UI that I can invoke from anywhere and .Add() to a parent VisualElement and it all Just Works.

    C# is a very powerful modern programming language: if you have an impressive, interactive, visually appealing UI you want to make then C# is your super-power. It lets you write most of your UI procedurally. That is literally impossible in USS.
     
  19. Emiles

    Emiles

    Joined:
    Jan 22, 2014
    Posts:
    61
    I'm on Rider too, it's amazing!

    I think the issue is that C# styles are implemented 'in-line' and thats less efficient than the uss equivelent. Probably only an issue if you have say lots of elements.

    so my eventual setup will be a bunch of predefined styles, for example, standardButton, roundButton, gradientButton.
    Then just use AddClass to apply the particular style and override the default settings. USS really should be quicker and more efficient than C# could ever achieve. If uss works anything like normal css, you'll find that C# styles, because they are inline, can't be overriden. So i'm not sure thats the best approach.

    That said, i despise html and css, Old gen flash dev here ;-p

    [Edit]
    actually, I think i totally get you now, interms of building the layout, i'm definately a fan of doing it in C#, i was thinking just specifically the styling is best done in uss.

    [Edit]
    To @a436t4ataf point, i actually keep finding myself writing everything in C# because it is just easier, mentally, but i can't help think that it should be quicker to use uss&uxml. But then I remember programming flash and hated Flex. I tried the UIBuilder package but it doesn't work in my version of unity, i'll see if i can update to the latest 2019 LTS to see if it makes a difference.
     
    Last edited: Feb 28, 2021
    Ruchir likes this.
  20. Emiles

    Emiles

    Joined:
    Jan 22, 2014
    Posts:
    61
    I think below is prime example of how Unity's documentation could be improved.

    The bit thats missing here is why or when you would use `src` over `path`. Their is an assumption that who'ever is reading this knows the value or side effects of using Resources.

    I imagine that its perhaps something to do with using path & Resource folder for ingame UI. To ensure the assets are added to the project. Where as using src is ok for property inspectors, but you've have to perhaps do something extra for ingame UI where the uss & uxml files might not be packaged up at build time. But i'm not exactly sure about that and thats why clarity in the documentation on WHY and When is really important, and generally missing completely.


    Code (CSharp):
    1. Referencing other files from UXML
    2. UXML files can reference other UXML files and USS files via the element.
    3.  
    4. Both the <Template> and the <Style> elements accept either an “src” attribute or a “path” attribute.
    5.  
    6. The src attribute allows relative paths, provides error messages at import time (for example, when files are missing), and ensures that Unity properly includes the Assets your UXML files reference in player builds.
    7.  
    8. The path attribute permits usage of Unity Resources mechanisms, but does not provide error reporting at import time, and does not allow relative paths.
     
  21. a436t4ataf

    a436t4ataf

    Joined:
    May 19, 2013
    Posts:
    1,924
    You should be writing re-usable styles for some cases, and inline styles for others, and using both together, depending on context. Both kinds of styles should be a mix of C# created (using C# methods for reusability) and USS created (using cascades for reusability - which is useless in most cases, but sometimes saves time). In general: USS can never be as fast as C# here. But ... using *both*, and choosing the right one for the job at each moment, is is a big part of what CSS was designed for :).

    It's just that Unity currently prevent us from doing this properly (they made the required classes private/internal), so you have to jump through some hoops if you want the best of both worlds right now (it's possible, but you have to write some custom classes to fix the Unity ones).
     
Thread Status:
Not open for further replies.