Screen docs (#2579)

* screen docs

* docstrings

* modal example

* docstring

* docstrings

* Apply suggestions from code review

Co-authored-by: Dave Pearson <davep@davep.org>

---------

Co-authored-by: Dave Pearson <davep@davep.org>

docs/examples/guide/screens/modal02.py

@@ -42,6 +42,7 @@ class ModalApp(App):
         yield Footer()
 
     def action_request_quit(self) -> None:
+        """Action to display the quit dialog."""
         self.push_screen(QuitScreen())
 
 

docs/examples/guide/screens/modal03.py

@@ -0,0 +1,57 @@
+from textual.app import App, ComposeResult
+from textual.containers import Grid
+from textual.screen import ModalScreen
+from textual.widgets import Button, Footer, Header, Label
+
+TEXT = """I must not fear.
+Fear is the mind-killer.
+Fear is the little-death that brings total obliteration.
+I will face my fear.
+I will permit it to pass over me and through me.
+And when it has gone past, I will turn the inner eye to see its path.
+Where the fear has gone there will be nothing. Only I will remain."""
+
+
+class QuitScreen(ModalScreen[bool]):  # (1)!
+    """Screen with a dialog to quit."""
+
+    def compose(self) -> ComposeResult:
+        yield Grid(
+            Label("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.dismiss(True)
+        else:
+            self.dismiss(False)
+
+
+class ModalApp(App):
+    """An app with a modal dialog."""
+
+    CSS_PATH = "modal01.css"
+    BINDINGS = [("q", "request_quit", "Quit")]
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Label(TEXT * 8)
+        yield Footer()
+
+    def action_request_quit(self) -> None:
+        """Action to display the quit dialog."""
+
+        def check_quit(quit: bool) -> None:
+            """Called when QuitScreen is dismissed."""
+            if quit:
+                self.exit()
+
+        self.push_screen(QuitScreen(), check_quit)
+
+
+if __name__ == "__main__":
+    app = ModalApp()
+    app.run()