Add support for "returning" a result value from screens.

[davep]

This is still in the "let's see if we like this approach" stage, although I think @willmcgugan and myself are liking this approach. Testing and review of these changes is highly encouraged. Beyond docstrings there are no documentation changes at the moment. This will need a slight reworking of the Screen guide so it's better that we're happy with the approach and the code before we write this up fully.

Please review without worrying about documentation for now.

This PR seeks to satisfy #2267 and does take the suggested callback approach. The alternative was to go with a "use messages" story that, while working well, places more work on the developer using Textual and potentially results in more boilerplate.

Changes of note here are:

• Much like with App, a Screen can now be typed. The type signifies the type of the result that it will "return".
• App.push_screen has acquired a callback parameter. If provided the callback function should be a function that takes a single argument, that is the type of the type given to the screen being pushed.
• Screen has acquired a new method called dismiss. This is a thin wrapper around App.pop_screen. Called with no parameter it performs the same as if App.pop_screen were called. If called with a parameter the callback provided with App.push_screen is called and then the screen is popped.
• Screen has also acquired an action_dismiss method to allow for easy dismissal of a screen from within an action.

Other things to keep in mind:

• A callback can optionally be awaitable.
• Because any given instance of a screen can end up on the screen stack multiple times, the result callback hook is done as a stack.

As an illustration of how this might be used, here's a small program that uses a ModalScreen to ask the user a question and then act on their answer:

from textual.app import App, ComposeResult
from textual.containers import Horizontal, Vertical
from textual.screen import ModalScreen
from textual.widgets import Header, Footer, OptionList, Button, Label


class AyeNaw(ModalScreen[bool]):
    DEFAULT_CSS = """
    AyeNaw {
        align: center middle;
    }

    AyeNaw > Vertical {
        background: $secondary;
        width: auto;
        height: auto;
        border: thick $primary;
        padding: 2 4;
    }

    AyeNaw > Vertical > * {
        width: auto;
        height: auto;
    }

    AyeNaw > Vertical > Label {
        padding-bottom: 2;
    }

    AyeNaw > Vertical > Horizontal {
        align: right middle;
    }

    AyeNaw Button {
        margin-left: 2;
    }
    """

    def compose(self) -> ComposeResult:
        with Vertical():
            yield Label("Well, what do you think?")
            with Horizontal():
                yield Button("Aye!", id="aye")
                yield Button("Naw!", id="naw")

    def on_button_pressed(self, event: Button.Pressed) -> None:
        self.dismiss(result=event.button.id == "aye")


class ScreenResultExampleApp(App[None]):
    BINDINGS = [
        ("question_mark", "ask", "Ask a question"),
    ]

    def compose(self) -> ComposeResult:
        yield Header()
        yield OptionList()
        yield Footer()

    def accept_answer(self, answer: bool) -> None:
        self.query_one(OptionList).add_option(
            f"Computer said {'[green]Aye' if answer else '[red]Naw'}[/]"
        )

    def action_ask(self) -> None:
        self.push_screen(AyeNaw(), callback=self.accept_answer)


if __name__ == "__main__":
    ScreenResultExampleApp().run()

Screen.Recording.2023-04-18.at.14.44.50.mov

[willmcgugan]

I think we will need to discard callbacks for switch screens.

[davep]

I think we will need to discard callbacks for switch screens.

@willmcgugan Good call. Done: 9123a80