From 82d0ac5fff61fbf2b5a277b3c27ce77033d19cfa Mon Sep 17 00:00:00 2001 From: Darren Burns Date: Tue, 17 Dec 2024 11:41:53 +0000 Subject: [PATCH 1/2] Fix query_one docs mistake, and note that query_one searches under the widget it is called on --- docs/guide/queries.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/guide/queries.md b/docs/guide/queries.md index c0ce0be51f..b71790f684 100644 --- a/docs/guide/queries.md +++ b/docs/guide/queries.md @@ -1,6 +1,6 @@ # DOM Queries -In the previous chapter we introduced the [DOM](../guide/CSS.md#the-dom) which is how Textual apps keep track of widgets. We saw how you can apply styles to the DOM with CSS [selectors](./CSS.md#selectors). +In the [CSS chapter](./CSS.md) we introduced the [DOM](../guide/CSS.md#the-dom) which is how Textual apps keep track of widgets. We saw how you can apply styles to the DOM with CSS [selectors](./CSS.md#selectors). Selectors are a very useful idea and can do more than apply styles. We can also find widgets in Python code with selectors, and make updates to widgets in a simple expressive way. Let's look at how! @@ -19,7 +19,7 @@ We could do this with the following line of code: send_button = self.query_one("#send") ``` -This will retrieve a widget with an ID of `send`, if there is exactly one. +This will retrieve the first widget discovered with an ID of `send`. If there are no matching widgets, Textual will raise a [NoMatches][textual.css.query.NoMatches] exception. You can also add a second parameter for the expected type, which will ensure that you get the type you are expecting. @@ -41,6 +41,15 @@ For instance, the following would return a `Button` instance (assuming there is my_button = self.query_one(Button) ``` +`query_one` searches *below* the widget it is called on, so if you call `query_one` on a widget, it will only find widgets that are descendants of that widget. + +If you wish to search the entire DOM, you should call `query_one` on the `App` or `Screen` instance. + +```python +# Search the entire Screen for a widget with an ID of "send-email" +self.screen.query_one("#send-email") +``` + ## Making queries 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. From 83f92f926a34dbdfbeeab60796480db8ad43817b Mon Sep 17 00:00:00 2001 From: Darren Burns Date: Tue, 17 Dec 2024 11:45:57 +0000 Subject: [PATCH 2/2] Clarify --- docs/guide/queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/queries.md b/docs/guide/queries.md index b71790f684..ea64b64d54 100644 --- a/docs/guide/queries.md +++ b/docs/guide/queries.md @@ -41,7 +41,7 @@ For instance, the following would return a `Button` instance (assuming there is my_button = self.query_one(Button) ``` -`query_one` searches *below* the widget it is called on, so if you call `query_one` on a widget, it will only find widgets that are descendants of that widget. +`query_one` searches the DOM *below* the widget it is called on, so if you call `query_one` on a widget, it will only find widgets that are descendants of that widget. If you wish to search the entire DOM, you should call `query_one` on the `App` or `Screen` instance.