From 9c1f6f7fad7101aacf129bd0370efd44781bbc85 Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Sun, 26 Feb 2023 10:34:30 +0000 Subject: [PATCH 1/5] Added docs for the new compose method --- .../guide/layout/combining_layouts.py | 41 ++++++++----------- .../layout/utility_containers_using_with.py | 21 ++++++++++ docs/guide/layout.md | 40 +++++++++++++++++- 3 files changed, 77 insertions(+), 25 deletions(-) create mode 100644 docs/examples/guide/layout/utility_containers_using_with.py diff --git a/docs/examples/guide/layout/combining_layouts.py b/docs/examples/guide/layout/combining_layouts.py index d832bd628..c52ecce0d 100644 --- a/docs/examples/guide/layout/combining_layouts.py +++ b/docs/examples/guide/layout/combining_layouts.py @@ -1,6 +1,6 @@ +from textual.app import App, ComposeResult from textual.containers import Container, Horizontal, Vertical -from textual.app import ComposeResult, App -from textual.widgets import Static, Header +from textual.widgets import Header, Static class CombiningLayoutsExample(App): @@ -8,28 +8,21 @@ class CombiningLayoutsExample(App): def compose(self) -> ComposeResult: yield Header() - yield Container( - Vertical( - *[Static(f"Vertical layout, child {number}") for number in range(15)], - id="left-pane", - ), - Horizontal( - Static("Horizontally"), - Static("Positioned"), - Static("Children"), - Static("Here"), - id="top-right", - ), - Container( - Static("This"), - Static("panel"), - Static("is"), - Static("using"), - Static("grid layout!", id="bottom-right-final"), - id="bottom-right", - ), - id="app-grid", - ) + with Container(id="app-grid"): + with Vertical(id="left-pane"): + for number in range(15): + yield Static(f"Vertical layout, child {number}") + with Horizontal(id="top-right"): + yield Static("Horizontally") + yield Static("Positioned") + yield Static("Children") + yield Static("Here") + with Container(id="bottom-right"): + yield Static("This") + yield Static("panel") + yield Static("is") + yield Static("using") + yield Static("grid layout!", id="bottom-right-final") if __name__ == "__main__": diff --git a/docs/examples/guide/layout/utility_containers_using_with.py b/docs/examples/guide/layout/utility_containers_using_with.py new file mode 100644 index 000000000..d09a3481e --- /dev/null +++ b/docs/examples/guide/layout/utility_containers_using_with.py @@ -0,0 +1,21 @@ +from textual.app import App, ComposeResult +from textual.containers import Horizontal, Vertical +from textual.widgets import Static + + +class UtilityContainersExample(App): + CSS_PATH = "utility_containers.css" + + def compose(self) -> ComposeResult: + with Horizontal(): + with Vertical(classes="column"): + yield Static("One") + yield Static("Two") + with Vertical(classes="column"): + yield Static("Three") + yield Static("Four") + + +if __name__ == "__main__": + app = UtilityContainersExample() + app.run() diff --git a/docs/guide/layout.md b/docs/guide/layout.md index 94405d837..99edf2e96 100644 --- a/docs/guide/layout.md +++ b/docs/guide/layout.md @@ -159,7 +159,45 @@ In other words, we have a single row containing two columns. ``` You may be tempted to use many levels of nested utility containers in order to build advanced, grid-like layouts. -However, Textual comes with a more powerful mechanism for achieving this known as _grid layout_, which we'll discuss next. +However, Textual comes with a more powerful mechanism for achieving this known as _grid layout_, which we'll discuss below. + +## Composing with context managers + +In the previous section we've show how you add children to a container (such as `Horizontal` and `Vertical`) with positional arguments. +It's fine to do it this way, but Textual offers a simplified syntax using [context managers](https://docs.python.org/3/reference/datamodel.html#context-managers) which is generally easier to write and edit. + +You can introduce a container using Python's `with` statement. Any widgets yielded within that block are added to the container's children. + +Let's take the [utility containers](#utility-containers) example and update it to use the context manager approach. + +=== "utility_containers_using_with.py" + + Composing with context managers. + + ```python + --8<-- "docs/examples/guide/layout/utility_containers_using_with.py" + ``` + +=== "utility_containers.py" + + This is the original code. + + ```python + --8<-- "docs/examples/guide/layout/utility_containers.py" + ``` + +=== "utility_containers.css" + + ```sass hl_lines="2" + --8<-- "docs/examples/guide/layout/utility_containers.css" + ``` + +=== "Output" + + ```{.textual path="docs/examples/guide/layout/utility_containers_using_with.py"} + ``` + +Note how the end result is the same, but the code with context managers is a little easer to read. It is up to you which method you want to use, and you can mix context managers with positional arguments if you like! ## Grid From b23fbd9be88d2658f08b17eb2b95e1101bf9c66c Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Sun, 26 Feb 2023 10:36:17 +0000 Subject: [PATCH 2/5] words --- docs/guide/layout.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/guide/layout.md b/docs/guide/layout.md index 99edf2e96..4f4b31f3a 100644 --- a/docs/guide/layout.md +++ b/docs/guide/layout.md @@ -163,10 +163,11 @@ However, Textual comes with a more powerful mechanism for achieving this known a ## Composing with context managers -In the previous section we've show how you add children to a container (such as `Horizontal` and `Vertical`) with positional arguments. +In the previous section we've show how you add children to a container (such as `Horizontal` and `Vertical`) using positional arguments. It's fine to do it this way, but Textual offers a simplified syntax using [context managers](https://docs.python.org/3/reference/datamodel.html#context-managers) which is generally easier to write and edit. -You can introduce a container using Python's `with` statement. Any widgets yielded within that block are added to the container's children. +When composing a widget, you can introduce a container using Python's `with` statement. +Any widgets yielded within that block are added as a child of the container. Let's take the [utility containers](#utility-containers) example and update it to use the context manager approach. From da1a82056527468693fcbf3e863a4e1b1ce27197 Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Sun, 26 Feb 2023 12:08:18 +0000 Subject: [PATCH 3/5] highlight lines --- docs/guide/layout.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/layout.md b/docs/guide/layout.md index 4f4b31f3a..5062c492c 100644 --- a/docs/guide/layout.md +++ b/docs/guide/layout.md @@ -175,7 +175,7 @@ Let's take the [utility containers](#utility-containers) example and update it t Composing with context managers. - ```python + ```python hl_lines="10-16" --8<-- "docs/examples/guide/layout/utility_containers_using_with.py" ``` @@ -183,7 +183,7 @@ Let's take the [utility containers](#utility-containers) example and update it t This is the original code. - ```python + ```python hl_lines="10-21" --8<-- "docs/examples/guide/layout/utility_containers.py" ``` From bc620fd46f0053ca5af79f3c0029c89b588191fd Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Sun, 26 Feb 2023 12:24:39 +0000 Subject: [PATCH 4/5] remove highlighted line --- docs/guide/layout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/layout.md b/docs/guide/layout.md index 5062c492c..dd06bb16d 100644 --- a/docs/guide/layout.md +++ b/docs/guide/layout.md @@ -189,7 +189,7 @@ Let's take the [utility containers](#utility-containers) example and update it t === "utility_containers.css" - ```sass hl_lines="2" + ```sass --8<-- "docs/examples/guide/layout/utility_containers.css" ``` From 5b1cba1d85c82ca0619e764d232c0db7936918e8 Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Sun, 26 Feb 2023 12:31:50 +0000 Subject: [PATCH 5/5] update to copy --- docs/guide/layout.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/guide/layout.md b/docs/guide/layout.md index dd06bb16d..3fe1184e0 100644 --- a/docs/guide/layout.md +++ b/docs/guide/layout.md @@ -169,11 +169,13 @@ It's fine to do it this way, but Textual offers a simplified syntax using [conte When composing a widget, you can introduce a container using Python's `with` statement. Any widgets yielded within that block are added as a child of the container. -Let's take the [utility containers](#utility-containers) example and update it to use the context manager approach. +Let's update the [utility containers](#utility-containers) example to use the context manager approach. === "utility_containers_using_with.py" - Composing with context managers. + !!! note + + This code uses context managers to compose widgets. ```python hl_lines="10-16" --8<-- "docs/examples/guide/layout/utility_containers_using_with.py" @@ -181,7 +183,9 @@ Let's take the [utility containers](#utility-containers) example and update it t === "utility_containers.py" - This is the original code. + !!! note + + This is the original code using positional arguments. ```python hl_lines="10-21" --8<-- "docs/examples/guide/layout/utility_containers.py"