Skip to content

Explain self.app in the guide more explicitly [Documentation] #5975

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/guide/command_palette.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,10 @@ The following example will display a blank screen initially, but if you bring up
5. Highlights matching letters in the search.
6. Adds our custom command provider and the default command provider.

!!! note

Unlike widgets and screens, command providers aren’t part of Textual’s normal widget hierarchy—they’re plain Python classes. For convenience, Textual still sets a [self.app][textual.command.Provider.app] attribute on them, giving you access to the running app instance. As with widgets and screens, you won’t often need to reach into the app directly, but it’s the right approach when you need to call app-level methods such as `open_file()` in this example.

There are four methods you can override in a command provider: [`startup`][textual.command.Provider.startup], [`search`][textual.command.Provider.search], [`discover`][textual.command.Provider.discover] and [`shutdown`][textual.command.Provider.shutdown].
All of these methods should be coroutines (`async def`). Only `search` is required, the other methods are optional.
Let's explore those methods in detail.
Expand Down
2 changes: 2 additions & 0 deletions docs/guide/screens.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,8 @@ From the quit screen you can click either Quit to exit the app immediately, or C
Note the `request_quit` action in the app which pushes a new instance of `QuitScreen`.
This makes the quit screen active. If you click Cancel, the quit screen calls [pop_screen][textual.app.App.pop_screen] to return the default screen. This also removes and deletes the `QuitScreen` object.

This example also shows [`self.app`][textual.message_pump.MessagePump.app], which gives you access to the running app instance from within a screen. You won’t often need to reach into the app directly, since it's usually preferable for widgets or screens to communicate through messages. But when you do need to call app-level methods—such as [`pop_screen()`][textual.app.App.pop_screen] in this example—[`self.app`][textual.message_pump.MessagePump.app] is the normal way to do it. You can access it on any widget or screen that is mounted in the app.

There are two flaws with this modal screen, which we can fix in the same way.

The first flaw is that the app adds a new quit screen every time you press ++q++, even when the quit screen is still visible.
Expand Down