From a9e87b59c082326e841627faff3968b958e5309f Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Tue, 7 May 2024 21:09:33 +0100 Subject: [PATCH] query_one docs --- docs/guide/queries.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/guide/queries.md b/docs/guide/queries.md index 5401257874..0227c71be4 100644 --- a/docs/guide/queries.md +++ b/docs/guide/queries.md @@ -10,17 +10,20 @@ Selectors are a very useful idea and can do more than apply styles. We can also ## Query one -The [query_one][textual.dom.DOMNode.query_one] method gets a single widget in an app or other widget. If you call it with a selector it will return the first matching widget. +The [query_one][textual.dom.DOMNode.query_one] method is used to retrieve a single widget that matches a selector or a type. -Let's say we have a widget with an ID of `send` and we want to get a reference to it in our app. We could do this with the following: +Let's say we have a widget with an ID of `send` and we want to get a reference to it in our app. +We could do this with the following line of code: ```python send_button = self.query_one("#send") ``` -If there is no widget with an ID of `send`, Textual will raise a [NoMatches][textual.css.query.NoMatches] exception. Otherwise it will return the matched widget. +This will retrieve a widget with an ID of `send`, if there is exactly one. +If there are no matching widgets, Textual will raise a [NoMatches][textual.css.query.NoMatches] exception. +If there are more than one match, Textual will raise a [TooManyMatches][textual.css.query.TooManyMatches] exception. -You can also add a second parameter for the expected type. +You can also add a second parameter for the expected type, which will ensure that you get the type you are expecting. ```python send_button = self.query_one("#send", Button) @@ -32,9 +35,16 @@ If the matched widget is *not* a button (i.e. if `isinstance(widget, Button)` eq The second parameter allows type-checkers like MyPy to know the exact return type. Without it, MyPy would only know the result of `query_one` is a Widget (the base class). +You can also specify a widget type in place of a selector, which will return a widget of that type. +For instance, the following would return a `Button` instance (assuming there is a single Button). + +```python +my_button = self.query_one(Button) +``` + ## Making queries -Apps and widgets have a [query][textual.dom.DOMNode.query] method which finds (or queries) widgets. This method returns a [DOMQuery][textual.css.query.DOMQuery] object which is a list-like container of widgets. +Apps and widgets also have a [query][textual.dom.DOMNode.query] method which finds (or queries) widgets. This method returns a [DOMQuery][textual.css.query.DOMQuery] object which is a list-like container of widgets. If you call `query` with no arguments, you will get back a `DOMQuery` containing all widgets. This method is *recursive*, meaning it will also return child widgets (as many levels as required).