textual.getters

Descriptors to define properties on your widget, screen, or App.

app

app(app_type)

Bases: Generic[AppType]

Create a property to return the active app.

All widgets have a default app property which returns an App instance. Type checkers will complain if you try to access attributes defined on your App class, which aren't present in the base class. To keep the type checker happy you can add this property to get your specific App subclass.

Example

class MyWidget(Widget):
    app = getters.app(MyApp)

Parameters:

Name	Type	Description	Default
app_type	type[AppType] | Callable[[], type[AppType]]	The App subclass, or a callable which returns an App subclass.	required

child_by_id

child_by_id(child_id: str)

child_by_id(child_id: str, expect_type: type[QueryType])

child_by_id(child_id, expect_type=None)

Bases: Generic[QueryType]

Create a child_by_id property, which returns the child with the given ID.

This is similar using query_one with an id selector, except that only the immediate children are considered. It is also more efficient as it doesn't need to search the DOM.

Example

from textual import getters

class MyScreen(screen):

    # Note this is at the class level
    output_log = getters.child_by_id("output", RichLog)

    def compose(self) -> ComposeResult:
        yield RichLog(id="output")

    def on_mount(self) -> None:
        self.output_log.write("Screen started")

Parameters:

Name	Type	Description	Default
child_id	str	The id of the widget to get (not a selector).	required
expect_type	type[QueryType] | None	The type of the expected widget, e.g. Input.	None

query_one

query_one(selector: str)

query_one(selector: type[QueryType])

query_one(selector: str, expect_type: type[QueryType])

query_one(
    selector: type[QueryType], expect_type: type[QueryType]
)

query_one(selector, expect_type=None)

Bases: Generic[QueryType]

Create a query one property.

A query one property calls Widget.query_one when accessed, and returns a widget. If the widget doesn't exist, then the property will raise the same exceptions as Widget.query_one.

Example

from textual import getters

class MyScreen(screen):

    # Note this is at the class level
    output_log = getters.query_one("#output", RichLog)

    def compose(self) -> ComposeResult:
        with containers.Vertical():
            yield RichLog(id="output")

    def on_mount(self) -> None:
        self.output_log.write("Screen started")
        # Equivalent to the following line:
        # self.query_one("#output", RichLog).write("Screen started")

Parameters:

Name	Type	Description	Default
selector	str | type[QueryType]	A TCSS selector, e.g. "#mywidget". Or a widget type, i.e. Input.	required
expect_type	type[QueryType] | None	The type of the expected widget, e.g. Input, if the first argument is a selector.	None