Notifications

[davep]

This PR seeks to satisfy #2846. In doing so it does the following:

• Adds a general Notification/Notifications pair of classes for holding details on an individual notification, as well as holding a list of timed notifications.
• Adds a small collection of widgets (which should sort of be considered to be "internal" at the moment, but which are named non-internal so as not to discourage styling) that show and handle the display of the above notifications via a Toast.
• Adds a core App.notify method, which takes a message and a title, as well as an optional severity level (information, warning or error -- default being information) and an optional timeout (3 seconds by default).
• Adds App.unnotify for removing a notification.
• Adds App.clear_notifications for clearing notifications.
• Adds a Screen.notify method, which is a thin wrapper around App.notify.
• Adds a Widget.notify method, which is a thin wrapper around App.notify.

The Toasts are always shown above the main display, scrolling up from the bottom right, and they persist between screens and modes.

By way of illustration:

Screen.Recording.2023-07-12.at.13.14.02.mov

was produced with this code:

from pathlib import Path
from random import choice

from textual import on
from textual.app import App, ComposeResult
from textual.containers import Horizontal, Vertical, VerticalScroll
from textual.widgets import Markdown, Button, Checkbox, Input

QUOTES = [
    "Are either of you paleontologists? I'm in desperate need of a paleontologist.",
    "I should reach Defcon 1 and release my missiles in 28 hours. Would you like to see some projected kill ratios?",
    "A strange game."
    "The only winning move is not to play.",
    "How about a nice game of chess?",
    "Joshua called me.",
    "The WOPR spends all it's time thinking about World War III.",
    "Did you ever play tic-tac-toe?",
    "I loved it when you nuked Las Vegas."
]

class ToastyApp(App[None]):

    CSS = """
    Horizontal {
        align: center middle;
        height: auto;
    }
    Horizontal Button {
        margin-left: 1;
    }
    Input {
        width: 20%;
    }
    """

    def compose(self) -> ComposeResult:
        with Vertical():
            with Horizontal():
                yield Checkbox("Titled", value=True)
                yield Input(placeholder="Timeout (default 3 seconds)")
                yield Button("Information", id="information")
                yield Button("Warning", id="warning")
                yield Button("Error", id="error")
            with VerticalScroll():
                yield Markdown()

    async def on_mount(self) -> None:
        await self.query_one(Markdown).load(Path("/Users/davep/develop/python/textual/README.md"))

    @on(Button.Pressed)
    def yell(self, event: Button.Pressed) -> None:
        try:
            timeout = float(self.query_one(Input).value)
        except ValueError:
            timeout = 3
        self.notify(
            choice(QUOTES),
            severity=event.button.id,
            title=None if self.query_one(Checkbox).value else "",
            timeout=timeout
        )

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

In addition to the above, a requirement some people may have (it's already been asked about as soon as this development was mentioned) is the ability to route the notifications elsewhere. While not directly handled right now, this can be done by overriding the App._refresh_notifications method and routing the notifications as required. As a very quick and dirty example on macOS, with the addition of this:

    def _refresh_notifications(self) -> None:
        for notification in self._notifications:
            title = notification.severity.capitalize() if notification.title is None else notification.title
            run([
                "osascript",
                "-e",
                f'display notification \"{notification.message}\" with title \"{title}\"'
            ])
        self._notifications.clear()

to ToastyApp above, the messages go via the normal macOS notification facility:

Screen.Recording.2023-07-12.at.13.50.48.mov

[willmcgugan]

@davep Forgive me for hacking your CSS. I've gone for something a little more minimal. Also made the width uniform.

[davep]

@willmcgugan If we're going with uniform width, I suspect we can drop ToastHolder (unless of course we want to allow for devs to have non-uniform width, I guess).

[davep]

If we're going with uniform width, I suspect we can drop ToastHolder (unless of course we want to allow for devs to have non-uniform width, I guess).

For any other reader down the line: in local conversation we've decided to leave it as it is in case anyone does want to style notifications for their application such that they have non-uniform size.