diff --git a/docs/examples/guide/screens/modal01.css b/docs/examples/guide/screens/modal01.css
new file mode 100644
index 000000000..8c7bea071
--- /dev/null
+++ b/docs/examples/guide/screens/modal01.css
@@ -0,0 +1,16 @@
+#dialog {
+ grid-size: 2;
+ grid-gutter: 1 2;
+ margin: 1 2;
+}
+
+#question {
+ column-span: 2;
+ content-align: center bottom;
+ width: 100%;
+ height: 100%;
+}
+
+Button {
+ width: 100%;
+}
diff --git a/docs/examples/guide/screens/modal01.py b/docs/examples/guide/screens/modal01.py
new file mode 100644
index 000000000..2ae1dd990
--- /dev/null
+++ b/docs/examples/guide/screens/modal01.py
@@ -0,0 +1,37 @@
+from textual.app import App, ComposeResult
+from textual.containers import Grid
+from textual.screen import Screen
+from textual.widgets import Static, Header, Footer, Button
+
+
+class QuitScreen(Screen):
+ def compose(self) -> ComposeResult:
+ yield Grid(
+ Static("Are you sure you want to quit?", id="question"),
+ Button("Quit", variant="error", id="quit"),
+ Button("Cancel", variant="primary", id="cancel"),
+ id="dialog",
+ )
+
+ def on_button_pressed(self, event: Button.Pressed) -> None:
+ if event.button.id == "quit":
+ self.app.exit()
+ else:
+ self.app.pop_screen()
+
+
+class ModalApp(App):
+ CSS_PATH = "modal01.css"
+ BINDINGS = [("q", "request_quit", "Quit")]
+
+ def compose(self) -> ComposeResult:
+ yield Header()
+ yield Footer()
+
+ def action_request_quit(self) -> None:
+ self.push_screen(QuitScreen())
+
+
+if __name__ == "__main__":
+ app = ModalApp()
+ app.run()
diff --git a/docs/examples/guide/screens/screen01.css b/docs/examples/guide/screens/screen01.css
new file mode 100644
index 000000000..0ee028ebe
--- /dev/null
+++ b/docs/examples/guide/screens/screen01.css
@@ -0,0 +1,18 @@
+BSOD {
+ align: center middle;
+ background: blue;
+ color: white;
+}
+
+BSOD>Static {
+ width: 70;
+}
+
+#title {
+ content-align-horizontal: center;
+ text-style: reverse;
+}
+
+#any-key {
+ content-align-horizontal: center;
+}
diff --git a/docs/examples/guide/screens/screen01.py b/docs/examples/guide/screens/screen01.py
new file mode 100644
index 000000000..63a24fd4e
--- /dev/null
+++ b/docs/examples/guide/screens/screen01.py
@@ -0,0 +1,34 @@
+from textual.app import App, Screen, ComposeResult
+from textual.widgets import Static
+
+
+ERROR_TEXT = """
+An error has occurred. To continue:
+
+Press Enter to return to Windows, or
+
+Press CTRL+ALT+DEL to restart your computer. If you do this,
+you will lose any unsaved information in all open applications.
+
+Error: 0E : 016F : BFF9B3D4
+"""
+
+
+class BSOD(Screen):
+ BINDINGS = [("escape", "app.pop_screen", "Pop screen")]
+
+ def compose(self) -> ComposeResult:
+ yield Static(" Windows ", id="title")
+ yield Static(ERROR_TEXT)
+ yield Static("Press any key to continue [blink]_[/]", id="any-key")
+
+
+class BSODApp(App):
+ CSS_PATH = "screen01.css"
+ SCREENS = {"bsod": BSOD()}
+ BINDINGS = [("b", "push_screen('bsod')", "BSOD")]
+
+
+if __name__ == "__main__":
+ app = BSODApp()
+ app.run()
diff --git a/docs/examples/guide/screens/screen02.css b/docs/examples/guide/screens/screen02.css
new file mode 100644
index 000000000..0ee028ebe
--- /dev/null
+++ b/docs/examples/guide/screens/screen02.css
@@ -0,0 +1,18 @@
+BSOD {
+ align: center middle;
+ background: blue;
+ color: white;
+}
+
+BSOD>Static {
+ width: 70;
+}
+
+#title {
+ content-align-horizontal: center;
+ text-style: reverse;
+}
+
+#any-key {
+ content-align-horizontal: center;
+}
diff --git a/docs/examples/guide/screens/screen02.py b/docs/examples/guide/screens/screen02.py
new file mode 100644
index 000000000..0d5d01e46
--- /dev/null
+++ b/docs/examples/guide/screens/screen02.py
@@ -0,0 +1,36 @@
+from textual.app import App, Screen, ComposeResult
+from textual.widgets import Static
+
+
+ERROR_TEXT = """
+An error has occurred. To continue:
+
+Press Enter to return to Windows, or
+
+Press CTRL+ALT+DEL to restart your computer. If you do this,
+you will lose any unsaved information in all open applications.
+
+Error: 0E : 016F : BFF9B3D4
+"""
+
+
+class BSOD(Screen):
+ BINDINGS = [("escape", "app.pop_screen", "Pop screen")]
+
+ def compose(self) -> ComposeResult:
+ yield Static(" Windows ", id="title")
+ yield Static(ERROR_TEXT)
+ yield Static("Press any key to continue [blink]_[/]", id="any-key")
+
+
+class BSODApp(App):
+ CSS_PATH = "screen02.css"
+ BINDINGS = [("b", "push_screen('bsod')", "BSOD")]
+
+ def on_mount(self) -> None:
+ self.install_screen(BSOD(), name="bsod")
+
+
+if __name__ == "__main__":
+ app = BSODApp()
+ app.run()
diff --git a/docs/guide/actions.md b/docs/guide/actions.md
index 1d6fec643..517751450 100644
--- a/docs/guide/actions.md
+++ b/docs/guide/actions.md
@@ -131,10 +131,26 @@ Textual supports the following builtin actions which are defined on the app.
options:
show_root_heading: false
+### Push screen
+
+::: textual.app.App.action_push_screen
+
+
+### Pop screen
+
+::: textual.app.App.action_pop_screen
+
+
### Screenshot
::: textual.app.App.action_screenshot
+
+### Switch screen
+
+::: textual.app.App.action_switch_screen
+
+
### Toggle_dark
::: textual.app.App.action_toggle_dark
diff --git a/docs/guide/screens.md b/docs/guide/screens.md
index 688684a43..94c61794e 100644
--- a/docs/guide/screens.md
+++ b/docs/guide/screens.md
@@ -1,12 +1,151 @@
# Screens
-TODO: Screens docs
+This chapter covers Textual's screen API. We will discuss how to create screens and switch between them.
-- Explanation of screens
-- Screens API
- - Install screen
- - Uninstall screen
- - Push screen
- - Pop screen
- - Switch Screen
-- Screens example
+## What is a screen?
+
+Screens are containers for widgets that occupy the dimensions of your terminal. There can be many screens in a given app, but only one screen is visible at a time.
+
+Textual requires that there be at least one screen object and will create one implicitly in the App class. If you don't change the screen, any widgets you [mount][textual.widget.Widget.mount] or [compose][textual.widget.Widget.compose] will be added to this default screen.
+
+!!! tip
+
+ Try printing `widget.parent` to see what object your widget is connected to.
+
+
+--8<-- "docs/images/dom1.excalidraw.svg"
+
+
+## Creating a screen
+
+You can create a screen by extending the [Screen][textual.screen.Screen] class which you can import from `textual.screen`. The screen may be styled in the same way as other widgets, with the exception that you can't modify the screen's dimensions (as these will always be the size of your terminal).
+
+Let's look at a simple example of writing a screen class to simulate Window's [blue screen of death](https://en.wikipedia.org/wiki/Blue_screen_of_death).
+
+=== "screen01.py"
+
+ ```python title="screen01.py" hl_lines="17-23 28"
+ --8<-- "docs/examples/guide/screens/screen01.py"
+ ```
+
+=== "screen01.css"
+
+ ```sass title="screen01.css"
+ --8<-- "docs/examples/guide/screens/screen01.css"
+ ```
+
+=== "Output"
+
+ ```{.textual path="docs/examples/guide/screens/screen01.py" press="b,_"}
+ ```
+
+If you run this you will see an empty screen. Hit the ++b++ screen to show a blue screen of death. Hit ++escape++ to return to the default screen.
+
+The `BSOD` class above defines a screen with a key binding and compose method. These should be familiar as they work in the same way as apps.
+
+The app class has a new `SCREENS` class variable. Textual uses this class variable to associated a name with screen object (the name is used to reference screens in the screen API). Also in the app is a key binding associated with the action `"push_screen('bsod')"`. The screen class has a similar action `"pop_screen"` bound to the ++escape++ key. We will cover these actions below.
+
+## Named screens
+
+You can associate a screen with a name by defining a `SCREENS` class variable in your app, which should be dict that maps names on to Screen objects. The name of the screen may be used interchangeably with screen objects in much of the screen API.
+
+You can also _install_ new named screens dynamically with the [install_screen][textual.app.App.install_screen] method. The following example installs the `BSOD` screen in a mount handler rather than from the `SCREENS` variable.
+
+=== "screen02.py"
+
+ ```python title="screen02.py" hl_lines="30-31"
+ --8<-- "docs/examples/guide/screens/screen02.py"
+ ```
+
+=== "screen02.css"
+
+ ```sass title="screen02.css"
+ --8<-- "docs/examples/guide/screens/screen02.css"
+ ```
+
+=== "Output"
+
+ ```{.textual path="docs/examples/guide/screens/screen02.py" press="b,_"}
+ ```
+
+Although both do the same thing, we recommend the `SCREENS` for screens that exist for the lifetime of your app.
+
+### Uninstalling screens
+
+Screens defined in `SCREENS` or added with [install_screen][textual.app.App.install_screen] are _installed_ screens. Textual will keep these screens in memory for the lifetime of your app.
+
+If you have installed a screen, but you later want it to be removed and cleaned up, you can call [uninstall_screen][textual.app.App.uninstall_screen].
+
+## Screen stack
+
+Textual keeps track of a _stack_ of screens. You can think of the screen stack as a stack of paper, where only the very top sheet is visible. If you remove the top sheet the paper underneath becomes visible. Screens work in a similar way.
+
+The active screen (top of the stack) will render the screen and receive input events. The following API methods on the App class can manipulate this stack, and let you decide which screen the user can interact with.
+
+### Push screen
+
+The [push_screen][textual.app.App.push_screen] method puts a screen on top of the stack and makes that screen active. You can call this method with the name of an installed screen, or a screen object.
+
+
+
+#### Action
+
+You can also push screens with the `"app.push_screen"` action, which requires the name of an installed screen.
+
+### Pop screen
+
+The [pop_screen][textual.app.App.pop_screen] method removes the top-most screen from the stack, and makes the new top screen active.
+
+!!! note
+
+ The screen stack must always have at least one screen. If you attempt to remove the last screen, Textual will raise a [ScreenStackError][textual.app.ScreenStackError] exception.
+
+
+
+
+When you pop a screen it will be removed and deleted unless it has been installed or there is another copy of the screen on the stack.
+
+#### Action
+
+You can also pop screens with the `"app.pop_screen"` action.
+
+### Switch screen
+
+The [switch_screen][textual.app.App.switch_screen] method replaces the top of the stack with a new screen.
+
+
+
+Like [pop_screen](#pop-screen), if the screen being replaced is not installed it will be removed and deleted.
+
+#### Action
+
+You can also switch screens with the `"app.switch_screen"` action which accepts the name of the screen to switch to.
+
+## Modal screens
+
+Screens can be used to implement modal dialogs. The following example pushes a screen when you hit the ++q++ key to ask you if you really want to quit.
+
+=== "modal01.py"
+
+ ```python title="modal01.py" hl_lines="18 20 32"
+ --8<-- "docs/examples/guide/screens/modal01.py"
+ ```
+
+=== "modal01.css"
+
+ ```sass title="modal01.css"
+ --8<-- "docs/examples/guide/screens/modal01.css"
+ ```
+
+=== "Output"
+
+ ```{.textual path="docs/examples/guide/screens/modal01.py" press="q,_"}
+ ```
+
+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` to return the default screen. This also removes and deletes the `QuitScreen` object.
diff --git a/docs/images/screens/pop_screen.excalidraw.svg b/docs/images/screens/pop_screen.excalidraw.svg
new file mode 100644
index 000000000..b87957f6a
--- /dev/null
+++ b/docs/images/screens/pop_screen.excalidraw.svg
@@ -0,0 +1,16 @@
+
\ No newline at end of file
diff --git a/docs/images/screens/push_screen.excalidraw.svg b/docs/images/screens/push_screen.excalidraw.svg
new file mode 100644
index 000000000..7bfde1748
--- /dev/null
+++ b/docs/images/screens/push_screen.excalidraw.svg
@@ -0,0 +1,16 @@
+
\ No newline at end of file
diff --git a/docs/images/screens/switch_screen.excalidraw.svg b/docs/images/screens/switch_screen.excalidraw.svg
new file mode 100644
index 000000000..02340e556
--- /dev/null
+++ b/docs/images/screens/switch_screen.excalidraw.svg
@@ -0,0 +1,16 @@
+
\ No newline at end of file
diff --git a/docs/reference/app.md b/docs/reference/app.md
index 0321acaaf..3a797ce06 100644
--- a/docs/reference/app.md
+++ b/docs/reference/app.md
@@ -1 +1 @@
-::: textual.app.App
+::: textual.app
diff --git a/src/textual/app.py b/src/textual/app.py
index 188a49791..241e385fe 100644
--- a/src/textual/app.py
+++ b/src/textual/app.py
@@ -26,20 +26,11 @@ import nanoid
import rich
import rich.repr
from rich.console import Console, RenderableType
-from rich.measure import Measurement
from rich.protocol import is_renderable
from rich.segment import Segment, Segments
from rich.traceback import Traceback
-from . import (
- Logger,
- LogGroup,
- LogVerbosity,
- actions,
- events,
- log,
- messages,
-)
+from . import Logger, LogGroup, LogVerbosity, actions, events, log, messages
from ._animator import Animator
from ._callback import invoke
from ._context import active_app
@@ -113,7 +104,7 @@ class ScreenError(Exception):
class ScreenStackError(ScreenError):
- pass
+ """Raised when attempting to pop the last screen from the stack."""
ReturnType = TypeVar("ReturnType")
@@ -223,6 +214,7 @@ class App(Generic[ReturnType], DOMNode):
self._installed_screens: WeakValueDictionary[
str, Screen
] = WeakValueDictionary()
+ self._installed_screens.update(**self.SCREENS)
self.devtools = DevtoolsClient()
self._return_value: ReturnType | None = None
@@ -801,7 +793,7 @@ class App(Generic[ReturnType], DOMNode):
try:
next_screen = self._installed_screens[screen]
except KeyError:
- raise KeyError("No screen called {screen!r} installed") from None
+ raise KeyError(f"No screen called {screen!r} installed") from None
else:
next_screen = screen
if not next_screen.is_running:
@@ -829,7 +821,7 @@ class App(Generic[ReturnType], DOMNode):
"""Push a new screen on the screen stack.
Args:
- screen (Screen | str): A Screen instance or an id.
+ screen (Screen | str): A Screen instance or the name of an installed screen.
"""
next_screen = self.get_screen(screen)
@@ -931,7 +923,7 @@ class App(Generic[ReturnType], DOMNode):
widget (Widget): Widget to focus.
scroll_visible (bool, optional): Scroll widget in to view.
"""
- if widget == self.focused:
+ if widget is self.focused:
# Widget is already focused
return
diff --git a/src/textual/geometry.py b/src/textual/geometry.py
index 7c22c1a92..be87975ec 100644
--- a/src/textual/geometry.py
+++ b/src/textual/geometry.py
@@ -223,7 +223,7 @@ class Size(NamedTuple):
class Region(NamedTuple):
"""Defines a rectangular region.
- A Region consists a coordinate (x and y) and dimensions (width and height).
+ A Region consists of a coordinate (x and y) and dimensions (width and height).
```
(x, y)
diff --git a/src/textual/screen.py b/src/textual/screen.py
index 284bdd283..e3c1787cb 100644
--- a/src/textual/screen.py
+++ b/src/textual/screen.py
@@ -40,8 +40,13 @@ class Screen(Widget):
dark: Reactive[bool] = Reactive(False)
- def __init__(self, name: str | None = None, id: str | None = None) -> None:
- super().__init__(name=name, id=id)
+ def __init__(
+ self,
+ name: str | None = None,
+ id: str | None = None,
+ classes: str | None = None,
+ ) -> None:
+ super().__init__(name=name, id=id, classes=classes)
self._compositor = Compositor()
self._dirty_widgets: set[Widget] = set()
self._update_timer: Timer | None = None
diff --git a/src/textual/widgets/_input.py b/src/textual/widgets/_input.py
index 0f82f4f16..8f3a4a4dc 100644
--- a/src/textual/widgets/_input.py
+++ b/src/textual/widgets/_input.py
@@ -10,7 +10,7 @@ from .. import events
from .._segment_tools import line_crop
from ..binding import Binding
from ..geometry import Size
-from ..message import Message, MessageTarget
+from ..message import Message
from ..reactive import reactive
from ..widget import Widget