Where can we find docs for UQuery?

Unity Engine
1

I would like to know:

  1. The most fundamental method of UQuery - “Q()” = what does it actually do? (not documented anywhere that I can find. Not in the manual. Not in the UIT mini-site. Not in the API. Nowhere). Does it return children by default? Are those REAL children, or Unity’s (incorrect, but now we’re stuck with it) GetComponent version of children (which all other languages and lbiraries call “descendants”)? … etc

  2. Why are some UQuery’s allowed and others blocked? e.g. the docs list UQueryBuilder with methods such as “Descendants”, which are not accessible via Q()… etc. Why? What’s the difference? Why is there a difference? How are we supposed to use them?

  3. Assuming (guessing!) that UQueryBuilder is the ‘real’ version of Q/Query, and that we should avoid using Q/Query for anything except trivial cases (Because it’s missing … almost everything) … how do you use UQueryBuilder? Again: no docs. Anywhere. For any part of it. I’ve searched the manual, the mini-site. Nothing.

This is the sum total of docs I’ve found, which amounts to “it was inspired by something else, that’s unrelated to Unity, and we provide no info on what’s the same or different” (NB: forums posts here reveal that it’s materially different - the methods are different, the design, the usage, everything): Unity - Manual: Find visual elements with UQuery

1 Like
2

I’ve resolved most of the above by manually reading through the source code and “hoping” that there are zero bugs in UIToolkit (!), that every line of source is perfectly correct and will never change, and Unity won’t change any of the behaviour in future.

But that’s … not great. Is anyone on the UIT team going to write docs (we’re now more than a year since the alleged “1.0.0” release - this stuff should all have been done before that), or are we stuck forever with a ‘good luck! write random code and hope it works! beg for help in the forums because we don’t write docs!’ UI system?

3

The scripting reference (separate from the manual) cover this, but it is harder to find.

Q : Convenience overload, shorthand for Query<T>.Build().First().

so it only returns the first one, while Querry return all matching elements

For the Query Builder, again, the scripting reference cover all the options.

99% of the queries can be done using the shortcuts extensions (Q or Query), and they exist to reduce the unnecessary verbosity that would be present with the Query Builder.

If you find something else missing from the documentation, don’t hesitate to report it directly in the documentation or to let us know on the forum.

1 Like
4

FYI it would also help if the manual explained the relationship between: Q, Query, UQueryBuilder, and VisualElement. It would only require 2-3 sentences and suddenly they would all become a lot more useful. As it stands, UQueryBuilder is hard to discover unless you luck onto the idea that you can do a “basically pointless” Query call to get access to a useable QueryBuilder

(note: Query is not what you’d find if you were looking for ‘how do I create and use a UQeryBuilder’, it’s not even got the same name, it’s not linked to in the docs, etc.)

A lot of this feels obfuscated for no obvious reason.

1 Like
5

I’ve passed along the suggestion to our documentation team, thanks!