How to (#2592)

* words

* how to

* Apply suggestions from code review

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

---------

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

docs/examples/how-to/layout.py

@@ -0,0 +1,69 @@
+from textual.app import App, ComposeResult
+from textual.containers import HorizontalScroll, VerticalScroll
+from textual.screen import Screen
+from textual.widgets import Placeholder
+
+
+class Header(Placeholder):
+    DEFAULT_CSS = """
+    Header {
+        height: 3;
+        dock: top;
+    }
+    """
+
+
+class Footer(Placeholder):
+    DEFAULT_CSS = """
+    Footer {
+        height: 3;
+        dock: bottom;
+    }
+    """
+
+
+class Tweet(Placeholder):
+    DEFAULT_CSS = """
+    Tweet {
+        height: 5;
+        width: 1fr;
+        border: tall $background;
+    }
+    """
+
+
+class Column(VerticalScroll):
+    DEFAULT_CSS = """
+    Column {
+        height: 1fr;
+        width: 32;
+        margin: 0 2;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        for tweet_no in range(1, 20):
+            yield Tweet(id=f"Tweet{tweet_no}")
+
+
+class TweetScreen(Screen):
+    def compose(self) -> ComposeResult:
+        yield Header(id="Header")
+        yield Footer(id="Footer")
+        with HorizontalScroll():
+            yield Column()
+            yield Column()
+            yield Column()
+            yield Column()
+
+
+class LayoutApp(App):
+    CSS_PATH = "layout.css"
+
+    def on_ready(self) -> None:
+        self.push_screen(TweetScreen())
+
+
+if __name__ == "__main__":
+    app = LayoutApp()
+    app.run()

docs/examples/how-to/layout01.py

@@ -0,0 +1,27 @@
+from textual.app import App, ComposeResult
+from textual.screen import Screen
+from textual.widgets import Placeholder
+
+
+class Header(Placeholder):  # (1)!
+    pass
+
+
+class Footer(Placeholder):  # (2)!
+    pass
+
+
+class TweetScreen(Screen):
+    def compose(self) -> ComposeResult:
+        yield Header(id="Header")  # (3)!
+        yield Footer(id="Footer")  # (4)!
+
+
+class LayoutApp(App):
+    def on_mount(self) -> None:
+        self.push_screen(TweetScreen())
+
+
+if __name__ == "__main__":
+    app = LayoutApp()
+    app.run()

docs/examples/how-to/layout02.py

@@ -0,0 +1,37 @@
+from textual.app import App, ComposeResult
+from textual.screen import Screen
+from textual.widgets import Placeholder
+
+
+class Header(Placeholder):
+    DEFAULT_CSS = """
+    Header {
+        height: 3;
+        dock: top;
+    }
+    """
+
+
+class Footer(Placeholder):
+    DEFAULT_CSS = """
+    Footer {
+        height: 3;
+        dock: bottom;
+    }
+    """
+
+
+class TweetScreen(Screen):
+    def compose(self) -> ComposeResult:
+        yield Header(id="Header")
+        yield Footer(id="Footer")
+
+
+class LayoutApp(App):
+    def on_ready(self) -> None:
+        self.push_screen(TweetScreen())
+
+
+if __name__ == "__main__":
+    app = LayoutApp()
+    app.run()

docs/examples/how-to/layout03.py

@@ -0,0 +1,48 @@
+from textual.app import App, ComposeResult
+from textual.screen import Screen
+from textual.widgets import Placeholder
+
+
+class Header(Placeholder):
+    DEFAULT_CSS = """
+    Header {
+        height: 3;
+        dock: top;
+    }
+    """
+
+
+class Footer(Placeholder):
+    DEFAULT_CSS = """
+    Footer {
+        height: 3;
+        dock: bottom;
+    }
+    """
+
+
+class ColumnsContainer(Placeholder):
+    DEFAULT_CSS = """
+    ColumnsContainer {
+        width: 1fr;
+        height: 1fr;
+        border: solid white;
+    }
+    """  # (1)!
+
+
+class TweetScreen(Screen):
+    def compose(self) -> ComposeResult:
+        yield Header(id="Header")
+        yield Footer(id="Footer")
+        yield ColumnsContainer(id="Columns")
+
+
+class LayoutApp(App):
+    def on_ready(self) -> None:
+        self.push_screen(TweetScreen())
+
+
+if __name__ == "__main__":
+    app = LayoutApp()
+    app.run()

docs/examples/how-to/layout04.py

@@ -0,0 +1,39 @@
+from textual.app import App, ComposeResult
+from textual.containers import HorizontalScroll
+from textual.screen import Screen
+from textual.widgets import Placeholder
+
+
+class Header(Placeholder):
+    DEFAULT_CSS = """
+    Header {
+        height: 3;
+        dock: top;
+    }
+    """
+
+
+class Footer(Placeholder):
+    DEFAULT_CSS = """
+    Footer {
+        height: 3;
+        dock: bottom;
+    }
+    """
+
+
+class TweetScreen(Screen):
+    def compose(self) -> ComposeResult:
+        yield Header(id="Header")
+        yield Footer(id="Footer")
+        yield HorizontalScroll()  # (1)!
+
+
+class LayoutApp(App):
+    def on_ready(self) -> None:
+        self.push_screen(TweetScreen())
+
+
+if __name__ == "__main__":
+    app = LayoutApp()
+    app.run()

docs/examples/how-to/layout05.py

@@ -0,0 +1,55 @@
+from textual.app import App, ComposeResult
+from textual.containers import HorizontalScroll, VerticalScroll
+from textual.screen import Screen
+from textual.widgets import Placeholder
+
+
+class Header(Placeholder):
+    DEFAULT_CSS = """
+    Header {
+        height: 3;
+        dock: top;
+    }
+    """
+
+
+class Footer(Placeholder):
+    DEFAULT_CSS = """
+    Footer {
+        height: 3;
+        dock: bottom;
+    }
+    """
+
+
+class Tweet(Placeholder):
+    pass
+
+
+class Column(VerticalScroll):
+    def compose(self) -> ComposeResult:
+        for tweet_no in range(1, 20):
+            yield Tweet(id=f"Tweet{tweet_no}")
+
+
+class TweetScreen(Screen):
+    def compose(self) -> ComposeResult:
+        yield Header(id="Header")
+        yield Footer(id="Footer")
+        with HorizontalScroll():
+            yield Column()
+            yield Column()
+            yield Column()
+            yield Column()
+
+
+class LayoutApp(App):
+    CSS_PATH = "layout.css"
+
+    def on_ready(self) -> None:
+        self.push_screen(TweetScreen())
+
+
+if __name__ == "__main__":
+    app = LayoutApp()
+    app.run()

docs/examples/how-to/layout06.py

@@ -0,0 +1,69 @@
+from textual.app import App, ComposeResult
+from textual.containers import HorizontalScroll, VerticalScroll
+from textual.screen import Screen
+from textual.widgets import Placeholder
+
+
+class Header(Placeholder):
+    DEFAULT_CSS = """
+    Header {
+        height: 3;
+        dock: top;
+    }
+    """
+
+
+class Footer(Placeholder):
+    DEFAULT_CSS = """
+    Footer {
+        height: 3;
+        dock: bottom;
+    }
+    """
+
+
+class Tweet(Placeholder):
+    DEFAULT_CSS = """
+    Tweet {
+        height: 5;
+        width: 1fr;
+        border: tall $background;
+    }
+    """
+
+
+class Column(VerticalScroll):
+    DEFAULT_CSS = """
+    Column {
+        height: 1fr;
+        width: 32;
+        margin: 0 2;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        for tweet_no in range(1, 20):
+            yield Tweet(id=f"Tweet{tweet_no}")
+
+
+class TweetScreen(Screen):
+    def compose(self) -> ComposeResult:
+        yield Header(id="Header")
+        yield Footer(id="Footer")
+        with HorizontalScroll():
+            yield Column()
+            yield Column()
+            yield Column()
+            yield Column()
+
+
+class LayoutApp(App):
+    CSS_PATH = "layout.css"
+
+    def on_ready(self) -> None:
+        self.push_screen(TweetScreen())
+
+
+if __name__ == "__main__":
+    app = LayoutApp()
+    app.run()