Merge branch 'main' into add-example-apps-to-tests

Textualize · Apr 16, 2024 · 8385420 · 8385420
2 parents 03932c4 + 86e4dbf
commit 8385420
Show file tree

Hide file tree

Showing 87 changed files with 6,344 additions and 685 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,11 +9,82 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Fixed
 
+- Fixed `Integer` validator missing failure description when not a number https://github.com/Textualize/textual/issues/4413
+- Fixed a crash in `DataTable` if you clicked a link in the border https://github.com/Textualize/textual/issues/4410
+
+### Added
+
+- Added `App.copy_to_clipboard` https://github.com/Textualize/textual/pull/4416
+
+## [0.56.4] - 2024-04-09
+
+### Fixed
+
+- Disabled terminal synchronization in inline mode as it breaks on some terminals
+
+## [0.56.3] - 2024-04-08
+
+### Fixed
+
+- Fixed inline mode not updating https://github.com/Textualize/textual/issues/4403
+
+## [0.56.2] - 2024-04-07
+
+### Fixed
+
+- Fixed inline mode not clearing with multiple screen
+
+## [0.56.1] - 2024-04-07
+
+### Fixed
+
+- Fixed flicker when non-current screen updates https://github.com/Textualize/textual/pull/4401
+
+### Changed
+
+- Removed additional line at the end of an inline app https://github.com/Textualize/textual/pull/4401
+
+## [0.56.0] - 2024-04-06
+
+### Added
+
+- Added `Size.with_width` and `Size.with_height` https://github.com/Textualize/textual/pull/4393
+
+### Fixed
+
+- Fixed issue with inline mode and multiple screens https://github.com/Textualize/textual/pull/4393
+- Fixed issue with priority bindings https://github.com/Textualize/textual/pull/4395
+
+### Changed
+
+- self.prevent can be used in a widget constructor to prevent messages on mount https://github.com/Textualize/textual/pull/4392
+
+
+## [0.55.1] - 2024-04-2
+
+### Fixed
+
+- Fixed mouse escape sequences being generated with `mouse=False` 
+
+## [0.55.0] - 2024-04-1
+
+### Fixed
+
+- Fix priority bindings not appearing in footer when key clashes with focused widget https://github.com/Textualize/textual/pull/4342
+- Reverted auto-width change https://github.com/Textualize/textual/pull/4369
+
+### Changed
+
 - Exceptions inside `Widget.compose` or workers weren't bubbling up in tests https://github.com/Textualize/textual/issues/4282
+- Fixed `DataTable` scrolling issues by changing `max-height` back to 100% https://github.com/Textualize/textual/issues/4286
+- Fixed `Button` not rendering correctly with console markup https://github.com/Textualize/textual/issues/4328
 
 ### Added
 
 - Added `Document.start` and `end` location properties for convenience https://github.com/Textualize/textual/pull/4267
+- Added support for JavaScript, Golang, Rust, Bash, Java and Kotlin to `TextArea` https://github.com/Textualize/textual/pull/4350
+- Added `inline` parameter to `run` and `run_async` to run app inline (under the prompt). https://github.com/Textualize/textual/pull/4343
+- Added `mouse` parameter to disable mouse support https://github.com/Textualize/textual/pull/4343
 
 ## [0.54.0] - 2024-03-26
 
@@ -1811,6 +1882,12 @@ https://textual.textualize.io/blog/2022/11/08/version-040/#version-040
 - New handler system for messages that doesn't require inheritance
 - Improved traceback handling
 
+[0.56.3]: https://github.com/Textualize/textual/compare/v0.56.2...v0.56.3
+[0.56.2]: https://github.com/Textualize/textual/compare/v0.56.1...v0.56.2
+[0.56.1]: https://github.com/Textualize/textual/compare/v0.56.0...v0.56.1
+[0.56.0]: https://github.com/Textualize/textual/compare/v0.55.1...v0.56.0
+[0.55.1]: https://github.com/Textualize/textual/compare/v0.55.0...v0.55.1
+[0.55.0]: https://github.com/Textualize/textual/compare/v0.54.0...v0.55.0
 [0.54.0]: https://github.com/Textualize/textual/compare/v0.53.1...v0.54.0
 [0.53.1]: https://github.com/Textualize/textual/compare/v0.53.0...v0.53.1
 [0.53.0]: https://github.com/Textualize/textual/compare/v0.52.1...v0.53.0

diff --git a/docs/examples/how-to/inline01.py b/docs/examples/how-to/inline01.py
@@ -0,0 +1,31 @@
+from datetime import datetime
+
+from textual.app import App, ComposeResult
+from textual.widgets import Digits
+
+
+class ClockApp(App):
+    CSS = """
+    Screen {
+        align: center middle;
+    }
+    #clock {
+        width: auto;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Digits("", id="clock")
+
+    def on_ready(self) -> None:
+        self.update_clock()
+        self.set_interval(1, self.update_clock)
+
+    def update_clock(self) -> None:
+        clock = datetime.now().time()
+        self.query_one(Digits).update(f"{clock:%T}")
+
+
+if __name__ == "__main__":
+    app = ClockApp()
+    app.run(inline=True)  #  (1)!
diff --git a/docs/examples/how-to/inline02.py b/docs/examples/how-to/inline02.py
@@ -0,0 +1,38 @@
+from datetime import datetime
+
+from textual.app import App, ComposeResult
+from textual.widgets import Digits
+
+
+class ClockApp(App):
+    CSS = """
+    Screen {
+        align: center middle;
+        &:inline {
+            border: none;
+            height: 50vh;
+            Digits {
+                color: $success;
+            }
+        }
+    }
+    #clock {
+        width: auto;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Digits("", id="clock")
+
+    def on_ready(self) -> None:
+        self.update_clock()
+        self.set_interval(1, self.update_clock)
+
+    def update_clock(self) -> None:
+        clock = datetime.now().time()
+        self.query_one(Digits).update(f"{clock:%T}")
+
+
+if __name__ == "__main__":
+    app = ClockApp()
+    app.run(inline=True)
diff --git a/docs/examples/widgets/clock.py b/docs/examples/widgets/clock.py
@@ -28,4 +28,4 @@ def update_clock(self) -> None:
 
 if __name__ == "__main__":
     app = ClockApp()
-    app.run()
+    app.run(inline=True)
diff --git a/docs/guide/CSS.md b/docs/guide/CSS.md
@@ -321,12 +321,13 @@ The `background: green` is only applied to the Button underneath the mouse curso
 
 Here are some other pseudo classes:
 
+- `:blur` Matches widgets which *do not* have input focus.
+- `:dark` Matches widgets in dark mode (where `App.dark == True`).
 - `:disabled` Matches widgets which are in a disabled state.
 - `:enabled` Matches widgets which are in an enabled state.
-- `:focus` Matches widgets which have input focus.
-- `:blur` Matches widgets which *do not* have input focus.
 - `:focus-within` Matches widgets with a focused child widget.
-- `:dark` Matches widgets in dark mode (where `App.dark == True`).
+- `:focus` Matches widgets which have input focus.
+- `:inline` Matches widgets when the app is running in inline mode.
 - `:light` Matches widgets in dark mode (where `App.dark == False`).
 
 ## Combinators

diff --git a/docs/guide/app.md b/docs/guide/app.md
@@ -38,6 +38,14 @@ If you hit ++ctrl+c++ Textual will exit application mode and return you to the c
 
     A side effect of application mode is that you may no longer be able to select and copy text in the usual way. Terminals typically offer a way to bypass this limit with a key modifier. On iTerm you can select text if you hold the ++option++ key. See the documentation for your terminal software for how to select text in application mode.
 
+#### Run inline
+
+!!! tip "Added in version 0.55.0"
+
+You can also run apps in _inline_ mode, which will cause the app to appear beneath the prompt (and won't go in to application mode).
+Inline apps are useful for tools that integrate closely with the typical workflow of a terminal.
+
+To run an app in inline mode set the `inline` parameter to `True` when you call [App.run()][textual.app.App.run]. See [Style Inline Apps](../how-to/style-inline-apps.md) for how to apply additional styles to inline apps.
 
 ## Events
 

diff --git a/docs/guide/queries.md b/docs/guide/queries.md
@@ -4,6 +4,10 @@ In the previous chapter we introduced the [DOM](../guide/CSS.md#the-dom) which i
 
 Selectors are a very useful idea and can do more than apply styles. We can also find widgets in Python code with selectors, and make updates to widgets in a simple expressive way. Let's look at how!
 
+!!! tip
+
+    See the [Textual Query Sandbox](https://github.com/davep/textual-query-sandbox/) project for an interactive way of experimenting with DOM queries.
+
 ## Query one
 
 The [query_one][textual.dom.DOMNode.query_one] method gets a single widget in an app or other widget. If you call it with a selector it will return the first matching widget.

diff --git a/docs/how-to/style-inline-apps.md b/docs/how-to/style-inline-apps.md
@@ -0,0 +1,37 @@
+# Style Inline Apps
+
+Version 0.55.0 of Textual added support for running apps *inline* (below the prompt).
+Running an inline app is as simple as adding `inline=True` to [`run()`][textual.app.App.run].
+
+<iframe width="100%" style="aspect-ratio:757/804;" src="https://www.youtube.com/embed/dxAf3vDr4aQ" title="Textual Inline mode" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+Your apps will typically run inline without modification, but you may want to make some tweaks for inline mode, which you can do with a little CSS.
+This How-To will explain how.
+
+Let's look at an inline app.
+The following app displays the the current time (and keeps it up to date).
+
+```python hl_lines="31"
+--8<-- "docs/examples/how-to/inline01.py"
+```
+
+1. The `inline=True` runs the app inline.
+
+With Textual's default settings, this clock will be displayed in 5 lines; 3 for the digits and 2 for a top and bottom border.
+
+You can change the height or the border with CSS and the `:inline` pseudo-selector, which only matches rules in inline mode.
+Let's update this app to remove the default border, and increase the height:
+
+```python hl_lines="11-17"
+--8<-- "docs/examples/how-to/inline02.py"
+```
+
+The highlighted CSS targets online inline mode.
+By setting the `height` rule on Screen we can define how many lines the app should consume when it runs.
+Setting `border: none` removes the default border when running in inline mode.
+
+We've also added a rule to change the color of the clock when running inline.
+
+## Summary
+
+Most apps will not require modification to run inline, but if you want to tweak the height and border you can write CSS that targets inline mode with the `:inline` pseudo-selector.
diff --git a/docs/styles/grid/column_span.md b/docs/styles/grid/column_span.md
@@ -9,7 +9,7 @@ The `column-span` style specifies how many columns a widget will span in a grid
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-column-span: <a href="../../css_types/integer">&lt;integer&gt;</a>;
+column-span: <a href="../../../css_types/integer">&lt;integer&gt;</a>;
 --8<-- "docs/snippets/syntax_block_end.md"
 
 The `column-span` style accepts a single non-negative [`<integer>`](../../css_types/integer.md) that quantifies how many columns the given widget spans.

diff --git a/docs/styles/grid/grid_columns.md b/docs/styles/grid/grid_columns.md
@@ -9,7 +9,7 @@ The `grid-columns` style allows to define the width of the columns of the grid.
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-grid-columns: <a href="../../css_types/scalar">&lt;scalar&gt;</a>+;
+grid-columns: <a href="../../../css_types/scalar">&lt;scalar&gt;</a>+;
 --8<-- "docs/snippets/syntax_block_end.md"
 
 The `grid-columns` style takes one or more [`<scalar>`](../../css_types/scalar.md) that specify the length of the columns of the grid.

diff --git a/docs/styles/grid/grid_gutter.md b/docs/styles/grid/grid_gutter.md
@@ -13,7 +13,7 @@ No spacing is added between the edges of the cells and the edges of the containe
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-grid-gutter: <a href="../../css_types/integer">&lt;integer&gt;</a> [<a href="../../css_types/integer">&lt;integer&gt;</a>];
+grid-gutter: <a href="../../../css_types/integer">&lt;integer&gt;</a> [<a href="../../../css_types/integer">&lt;integer&gt;</a>];
 --8<-- "docs/snippets/syntax_block_end.md"
 
 The `grid-gutter` style takes one or two [`<integer>`](../../css_types/integer.md) that set the length of the gutter along the vertical and horizontal axes.

diff --git a/docs/styles/grid/grid_rows.md b/docs/styles/grid/grid_rows.md
@@ -9,7 +9,7 @@ The `grid-rows` style allows to define the height of the rows of the grid.
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-grid-rows: <a href="../../css_types/scalar">&lt;scalar&gt;</a>+;
+grid-rows: <a href="../../../css_types/scalar">&lt;scalar&gt;</a>+;
 --8<-- "docs/snippets/syntax_block_end.md"
 
 The `grid-rows` style takes one or more [`<scalar>`](../../css_types/scalar.md) that specify the length of the rows of the grid.

diff --git a/docs/styles/grid/grid_size.md b/docs/styles/grid/grid_size.md
@@ -11,7 +11,7 @@ The number of rows can be left unspecified and it will be computed automatically
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-grid-size: <a href="../../css_types/integer">&lt;integer&gt;</a> [<a href="../../css_types/integer">&lt;integer&gt;</a>];
+grid-size: <a href="../../../css_types/integer">&lt;integer&gt;</a> [<a href="../../../css_types/integer">&lt;integer&gt;</a>];
 --8<-- "docs/snippets/syntax_block_end.md"
 
 The `grid-size` style takes one or two non-negative [`<integer>`](../../css_types/integer.md).

diff --git a/docs/styles/grid/index.md b/docs/styles/grid/index.md
@@ -16,17 +16,17 @@ For an in-depth look at the grid layout, visit the grid [guide](../../guide/layo
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-<a href="./column_span.md">column-span</a>: <a href="../../css_types/integer">&lt;integer&gt;</a>;
+<a href="./column_span.md">column-span</a>: <a href="../../../css_types/integer">&lt;integer&gt;</a>;
 
-<a href="./grid_columns.md">grid-columns</a>: <a href="../../css_types/scalar">&lt;scalar&gt;</a>+;
+<a href="./grid_columns.md">grid-columns</a>: <a href="../../../css_types/scalar">&lt;scalar&gt;</a>+;
 
-<a href="./grid_gutter.md">grid-gutter</a>: <a href="../../css_types/scalar">&lt;scalar&gt;</a> [<a href="../../css_types/scalar">&lt;scalar&gt;</a>];
+<a href="./grid_gutter.md">grid-gutter</a>: <a href="../../../css_types/scalar">&lt;scalar&gt;</a> [<a href="../../../css_types/scalar">&lt;scalar&gt;</a>];
 
-<a href="./grid_rows.md">grid-rows</a>: <a href="../../css_types/scalar">&lt;scalar&gt;</a>+;
+<a href="./grid_rows.md">grid-rows</a>: <a href="../../../css_types/scalar">&lt;scalar&gt;</a>+;
 
-<a href="./grid_size.md">grid-size</a>: <a href="../../css_types/integer">&lt;integer&gt;</a> [<a href="../../css_types/integer">&lt;integer&gt;</a>];
+<a href="./grid_size.md">grid-size</a>: <a href="../../../css_types/integer">&lt;integer&gt;</a> [<a href="../../../css_types/integer">&lt;integer&gt;</a>];
 
-<a href="./row_span.md">row-span</a>: <a href="../../css_types/integer">&lt;integer&gt;</a>;
+<a href="./row_span.md">row-span</a>: <a href="../../../css_types/integer">&lt;integer&gt;</a>;
 --8<-- "docs/snippets/syntax_block_end.md"
 
 Visit each style's reference page to learn more about how the values are used.

diff --git a/docs/styles/grid/row_span.md b/docs/styles/grid/row_span.md
@@ -9,7 +9,7 @@ The `row-span` style specifies how many rows a widget will span in a grid layout
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-row-span: <a href="../../css_types/integer">&lt;integer&gt;</a>;
+row-span: <a href="../../../css_types/integer">&lt;integer&gt;</a>;
 --8<-- "docs/snippets/syntax_block_end.md"
 
 The `row-span` style accepts a single non-negative [`<integer>`](../../css_types/integer.md) that quantifies how many rows the given widget spans.

diff --git a/docs/styles/links/index.md b/docs/styles/links/index.md
@@ -19,17 +19,17 @@ There are a number of styles which influence the appearance of these links withi
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-<a href="./link_background">link-background</a>: <a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+<a href="./link_background">link-background</a>: <a href="../../../css_types/color">&lt;color&gt;</a> [<a href="../../../css_types/percentage">&lt;percentage&gt;</a>];
 
-<a href="./link_color">link-color</a>: <a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+<a href="./link_color">link-color</a>: <a href="../../../css_types/color">&lt;color&gt;</a> [<a href="../../../css_types/percentage">&lt;percentage&gt;</a>];
 
-<a href="./link_style">link-style</a>: <a href="../../css_types/text_style">&lt;text-style&gt;</a>;
+<a href="./link_style">link-style</a>: <a href="../../../css_types/text_style">&lt;text-style&gt;</a>;
 
-<a href="./link_background_hover">link-background-hover</a>: <a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+<a href="./link_background_hover">link-background-hover</a>: <a href="../../../css_types/color">&lt;color&gt;</a> [<a href="../../../css_types/percentage">&lt;percentage&gt;</a>];
 
-<a href="./link_color_hover">link-color-hover</a>: <a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+<a href="./link_color_hover">link-color-hover</a>: <a href="../../../css_types/color">&lt;color&gt;</a> [<a href="../../../css_types/percentage">&lt;percentage&gt;</a>];
 
-<a href="./link_style_hover">link-style-hover</a>: <a href="../../css_types/text_style">&lt;text-style&gt;</a>;
+<a href="./link_style_hover">link-style-hover</a>: <a href="../../../css_types/text_style">&lt;text-style&gt;</a>;
 --8<-- "docs/snippets/syntax_block_end.md"
 
 Visit each style's reference page to learn more about how the values are used.

diff --git a/docs/styles/links/link_background.md b/docs/styles/links/link_background.md
@@ -9,7 +9,7 @@ The `link-background` style sets the background color of the link.
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-link-background: <a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+link-background: <a href="../../../css_types/color">&lt;color&gt;</a> [<a href="../../../css_types/percentage">&lt;percentage&gt;</a>];
 --8<-- "docs/snippets/syntax_block_end.md"
 
 `link-background` accepts a [`<color>`](../../css_types/color.md) (with an optional opacity level defined by a [`<percentage>`](../../css_types/percentage.md)) that is used to define the background color of text enclosed in Textual action links.
@@ -63,4 +63,4 @@ widget.styles.link_background = Color(100, 30, 173)
 ## See also
 
  - [`link-color`](./link_color.md) to set the color of link text.
- - [`link-background-hover](./link_background_hover.md) to set the background color of link text when the mouse pointer is over it.
+ - [`link-background-hover`](./link_background_hover.md) to set the background color of link text when the mouse pointer is over it.
diff --git a/docs/styles/links/link_background_hover.md b/docs/styles/links/link_background_hover.md
@@ -9,7 +9,7 @@ The `link-background-hover` style sets the background color of the link when the
 ## Syntax
 
 --8<-- "docs/snippets/syntax_block_start.md"
-link-background-hover: <a href="../../css_types/color">&lt;color&gt;</a> [<a href="../../css_types/percentage">&lt;percentage&gt;</a>];
+link-background-hover: <a href="../../../css_types/color">&lt;color&gt;</a> [<a href="../../../css_types/percentage">&lt;percentage&gt;</a>];
 --8<-- "docs/snippets/syntax_block_end.md"
 
 `link-background-hover` accepts a [`<color>`](../../css_types/color.md) (with an optional opacity level defined by a [`<percentage>`](../../css_types/percentage.md)) that is used to define the background color of text enclosed in Textual action links when the mouse pointer is over it.
@@ -73,5 +73,5 @@ widget.styles.link_background_hover = Color(100, 30, 173)
 ## See also
 
  - [`link-background`](./link_background.md) to set the background color of link text.
- - [`link-color-hover](./link_color_hover.md) to set the color of link text when the mouse pointer is over it.
- - [`link-style-hover](./link_style_hover.md) to set the style of link text when the mouse pointer is over it.
+ - [`link-color-hover`](./link_color_hover.md) to set the color of link text when the mouse pointer is over it.
+ - [`link-style-hover`](./link_style_hover.md) to set the style of link text when the mouse pointer is over it.