Merge branch 'main' into markdown-improvements

CHANGELOG.md

@@ -5,14 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## Unreleased
+## [0.28.0] - 2023-06-19
 
 ### Added
 
 - The devtools console now confirms when CSS files have been successfully loaded after a previous error https://github.com/Textualize/textual/pull/2716
 - Class variable `CSS` to screens https://github.com/Textualize/textual/issues/2137
 - Class variable `CSS_PATH` to screens https://github.com/Textualize/textual/issues/2137
 - Added `cursor_foreground_priority` and `cursor_background_priority` to `DataTable` https://github.com/Textualize/textual/pull/2736
+- Added Region.center
+- Added `center` parameter to `Widget.scroll_to_region`
+- Added `origin_visible` parameter to `Widget.scroll_to_region`
+- Added `origin_visible` parameter to `Widget.scroll_to_center`
 - Added `TabbedContent.tab_count` https://github.com/Textualize/textual/pull/2751
 - Added `TabbedContnet.add_pane` https://github.com/Textualize/textual/pull/2751
 - Added `TabbedContent.remove_pane` https://github.com/Textualize/textual/pull/2751
@@ -21,7 +25,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Fixed
 
-- Fixed setting `TreeNode.label` on an existing `Tree` node not immediately https://github.com/Textualize/textual/pull/2713
+- Fixed setting `TreeNode.label` on an existing `Tree` node not immediately refreshing https://github.com/Textualize/textual/pull/2713
 - Correctly implement `__eq__` protocol in DataTable https://github.com/Textualize/textual/pull/2705
 - Fixed exceptions in Pilot tests being silently ignored https://github.com/Textualize/textual/pull/2754
 - Fixed issue where internal data of `OptionList` could be invalid for short window after `clear_options` https://github.com/Textualize/textual/pull/2754
@@ -1056,6 +1060,8 @@ 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.28.0]: https://github.com/Textualize/textual/compare/v0.27.0...v0.28.0
+[0.27.0]: https://github.com/Textualize/textual/compare/v0.26.0...v0.27.0
 [0.26.0]: https://github.com/Textualize/textual/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/Textualize/textual/compare/v0.24.1...v0.25.0
 [0.24.1]: https://github.com/Textualize/textual/compare/v0.24.0...v0.24.1

FAQ.md

@@ -2,17 +2,16 @@
 <!-- Do not edit by hand! -->
 
 # Frequently Asked Questions
-- [Frequently Asked Questions](#frequently-asked-questions)
-  - [Does Textual support images?](#does-textual-support-images)
-  - [How can I fix ImportError cannot import name ComposeResult from textual.app ?](#how-can-i-fix-importerror-cannot-import-name-composeresult-from-textualapp-)
-  - [How can I select and copy text in a Textual app?](#how-can-i-select-and-copy-text-in-a-textual-app)
-  - [How can I set a translucent app background?](#how-can-i-set-a-translucent-app-background)
-  - [How do I center a widget in a screen?](#how-do-i-center-a-widget-in-a-screen)
-  - [How do I pass arguments to an app?](#how-do-i-pass-arguments-to-an-app)
-  - [Why do some key combinations never make it to my app?](#why-do-some-key-combinations-never-make-it-to-my-app)
-  - [Why doesn't Textual look good on macOS?](#why-doesnt-textual-look-good-on-macos)
-  - [Why doesn't Textual support ANSI themes?](#why-doesnt-textual-support-ansi-themes)
-  - [Why doesn't the `DataTable` scroll programmatically?](#why-doesnt-the-datatable-scroll-programmatically)
+- [Does Textual support images?](#does-textual-support-images)
+- [How can I fix ImportError cannot import name ComposeResult from textual.app ?](#how-can-i-fix-importerror-cannot-import-name-composeresult-from-textualapp-)
+- [How can I select and copy text in a Textual app?](#how-can-i-select-and-copy-text-in-a-textual-app)
+- [How can I set a translucent app background?](#how-can-i-set-a-translucent-app-background)
+- [How do I center a widget in a screen?](#how-do-i-center-a-widget-in-a-screen)
+- [How do I pass arguments to an app?](#how-do-i-pass-arguments-to-an-app)
+- [Why do some key combinations never make it to my app?](#why-do-some-key-combinations-never-make-it-to-my-app)
+- [Why doesn't Textual look good on macOS?](#why-doesn't-textual-look-good-on-macos)
+- [Why doesn't Textual support ANSI themes?](#why-doesn't-textual-support-ansi-themes)
+- [Why doesn't the `DataTable` scroll programmatically?](#why-doesn't-the-`datatable`-scroll-programmatically)
 
 <a name="does-textual-support-images"></a>
 ## Does Textual support images?
@@ -212,12 +211,38 @@ work in different environments you can try them out with `textual keys`.
 <a name="why-doesn't-textual-look-good-on-macos"></a>
 ## Why doesn't Textual look good on macOS?
 
-The default macOS `Terminal.app` is getting rather old now; it has problems
-such as being limited to just 256 colors, being slow to draw and not all
-box-drawing characters are fully-supported. We recommend installing a newer
-terminal such as [iTerm2](https://iterm2.com/),
-[Kitty](https://sw.kovidgoyal.net/kitty/) or
-[WezTerm](https://wezfurlong.org/wezterm/).
+You may find that the default macOS Terminal.app doesn't render Textual apps (and likely other TUIs) very well, particuarily when it comes to box characters.
+For instance, you may find it displays misaligned blocks and lines like this:
+
+<img width="1042" alt="Screenshot 2023-06-19 at 10 43 02" src="https://github.com/Textualize/textual/assets/554369/e61f3876-3dd1-4ac8-b380-22922c89c7d6">
+
+You can (mostly) fix this by opening settings -> profiles > Text tab, and changing the font settings.
+We have found that Menlo Regular font, with a character spacing of 1 and line spacing of 0.805 produces reasonable results.
+If you want to use another font, you may have to tweak the line spacing until you get good results.
+
+<img width="737" alt="Screenshot 2023-06-19 at 10 44 00" src="https://github.com/Textualize/textual/assets/554369/0a052a93-b1fd-4327-9d33-d954b51a9ad2">
+
+With these changes, Textual apps render more as intended:
+
+<img width="1042" alt="Screenshot 2023-06-19 at 10 43 23" src="https://github.com/Textualize/textual/assets/554369/a0c4aa05-c509-4ac1-b0b8-e68ce4433f70">
+
+Even with this *fix*, Terminal.app has a few limitations.
+It is limited to 256 colors, and can be a little slow compared to more modern alternatives.
+Fortunately there are a number of free terminal emulators for macOS which produces high quality results.
+
+We recommend any of the following terminals:
+
+- [iTerm2](https://iterm2.com/)
+- [Kitty](https://sw.kovidgoyal.net/kitty/)
+- [WezTerm](https://wezfurlong.org/wezterm/)
+
+### Terminal.app colors
+
+<img width="762" alt="Screenshot 2023-06-19 at 11 00 12" src="https://github.com/Textualize/textual/assets/554369/e0555d23-e141-4069-b318-f3965c880208">
+
+### iTerm2 colors
+
+<img width="1002" alt="Screenshot 2023-06-19 at 11 00 25" src="https://github.com/Textualize/textual/assets/554369/9a8cde57-5121-49a7-a2e0-5f6fc871b7a6">
 
 <a name="why-doesn't-textual-support-ansi-themes"></a>
 ## Why doesn't Textual support ANSI themes?

docs/examples/guide/input/binding01.py

@@ -8,7 +8,6 @@ class Bar(Static):
 
 
 class BindingApp(App):
-
     CSS_PATH = "binding01.css"
     BINDINGS = [
         ("r", "add_bar('red')", "Add Red"),

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "textual"
-version = "0.27.0"
+version = "0.28.0"
 homepage = "https://github.com/Textualize/textual"
 description = "Modern Text User Interface framework"
 authors = ["Will McGugan <[email protected]>"]

questions/why-looks-bad-on-macos.question.md

@@ -10,9 +10,35 @@ alt_titles:
   - "macOS terminal"
 ---
 
-The default macOS `Terminal.app` is getting rather old now; it has problems
-such as being limited to just 256 colors, being slow to draw and not all
-box-drawing characters are fully-supported. We recommend installing a newer
-terminal such as [iTerm2](https://iterm2.com/),
-[Kitty](https://sw.kovidgoyal.net/kitty/) or
-[WezTerm](https://wezfurlong.org/wezterm/).
+You may find that the default macOS Terminal.app doesn't render Textual apps (and likely other TUIs) very well, particuarily when it comes to box characters.
+For instance, you may find it displays misaligned blocks and lines like this:
+
+<img width="1042" alt="Screenshot 2023-06-19 at 10 43 02" src="https://github.com/Textualize/textual/assets/554369/e61f3876-3dd1-4ac8-b380-22922c89c7d6">
+
+You can (mostly) fix this by opening settings -> profiles > Text tab, and changing the font settings.
+We have found that Menlo Regular font, with a character spacing of 1 and line spacing of 0.805 produces reasonable results.
+If you want to use another font, you may have to tweak the line spacing until you get good results.
+
+<img width="737" alt="Screenshot 2023-06-19 at 10 44 00" src="https://github.com/Textualize/textual/assets/554369/0a052a93-b1fd-4327-9d33-d954b51a9ad2">
+
+With these changes, Textual apps render more as intended:
+
+<img width="1042" alt="Screenshot 2023-06-19 at 10 43 23" src="https://github.com/Textualize/textual/assets/554369/a0c4aa05-c509-4ac1-b0b8-e68ce4433f70">
+
+Even with this *fix*, Terminal.app has a few limitations.
+It is limited to 256 colors, and can be a little slow compared to more modern alternatives.
+Fortunately there are a number of free terminal emulators for macOS which produces high quality results.
+
+We recommend any of the following terminals:
+
+- [iTerm2](https://iterm2.com/)
+- [Kitty](https://sw.kovidgoyal.net/kitty/)
+- [WezTerm](https://wezfurlong.org/wezterm/)
+
+### Terminal.app colors
+
+<img width="762" alt="Screenshot 2023-06-19 at 11 00 12" src="https://github.com/Textualize/textual/assets/554369/e0555d23-e141-4069-b318-f3965c880208">
+
+### iTerm2 colors
+
+<img width="1002" alt="Screenshot 2023-06-19 at 11 00 25" src="https://github.com/Textualize/textual/assets/554369/9a8cde57-5121-49a7-a2e0-5f6fc871b7a6">

src/textual/_types.py

@@ -3,6 +3,8 @@
 from typing_extensions import Protocol
 
 if TYPE_CHECKING:
+    from rich.segment import Segment
+
     from .message import Message
 
 

src/textual/app.py

@@ -141,7 +141,9 @@
 ComposeResult = Iterable[Widget]
 RenderResult = RenderableType
 
-AutopilotCallbackType: TypeAlias = "Callable[[Pilot], Coroutine[Any, Any, None]]"
+AutopilotCallbackType: TypeAlias = (
+    "Callable[[Pilot[object]], Coroutine[Any, Any, None]]"
+)
 """Signature for valid callbacks that can be used to control apps."""
 
 
@@ -721,7 +723,7 @@ def animator(self) -> Animator:
         return self._animator
 
     @property
-    def screen(self) -> Screen:
+    def screen(self) -> Screen[object]:
         """The current active screen.
 
         Returns:
@@ -834,8 +836,8 @@ def _log(
     def call_from_thread(
         self,
         callback: Callable[..., CallThreadReturnType | Awaitable[CallThreadReturnType]],
-        *args,
-        **kwargs,
+        *args: object,
+        **kwargs: object,
     ) -> CallThreadReturnType:
         """Run a callable from another thread, and return the result.
 
@@ -1712,7 +1714,7 @@ def uninstall_screen(self, screen: Screen | str) -> str | None:
                     return name
         return None
 
-    def pop_screen(self) -> Screen:
+    def pop_screen(self) -> Screen[object]:
         """Pop the current [screen](/guide/screens) from the stack, and switch to the previous screen.
 
         Returns:

src/textual/dom.py

@@ -457,7 +457,7 @@ def parent(self) -> DOMNode | None:
         return cast("DOMNode | None", self._parent)
 
     @property
-    def screen(self) -> "Screen":
+    def screen(self) -> "Screen[object]":
         """The screen containing this node.
 
         Returns:

src/textual/geometry.py

@@ -439,6 +439,18 @@ def offset(self) -> Offset:
         """
         return Offset(*self[:2])
 
+    @property
+    def center(self) -> tuple[float, float]:
+        """The center of the region.
+
+        Note, that this does *not* return an `Offset`, because the center may not be an integer coordinate.
+
+        Returns:
+            Tuple of floats.
+        """
+        x, y, width, height = self
+        return (x + width / 2.0, y + height / 2.0)
+
     @property
     def bottom_left(self) -> Offset:
         """Bottom left offset of the region.

src/textual/message_pump.py

@@ -31,10 +31,15 @@
 from .timer import Timer, TimerCallback
 
 if TYPE_CHECKING:
+    from typing_extensions import TypeAlias
+
     from .app import App
     from .css.model import SelectorSet
 
 
+Callback: TypeAlias = "Callable[..., Any] | Callable[..., Awaitable[Any]]"
+
+
 class CallbackError(Exception):
     pass
 
@@ -174,7 +179,7 @@ def has_parent(self) -> bool:
         return self._parent is not None
 
     @property
-    def app(self) -> "App":
+    def app(self) -> "App[object]":
         """
         Get the current app.
 
@@ -369,7 +374,7 @@ def set_interval(
         self._timers.add(timer)
         return timer
 
-    def call_after_refresh(self, callback: Callable, *args: Any, **kwargs: Any) -> bool:
+    def call_after_refresh(self, callback: Callback, *args: Any, **kwargs: Any) -> bool:
         """Schedule a callback to run after all messages are processed and the screen
         has been refreshed. Positional and keyword arguments are passed to the callable.
 
@@ -387,7 +392,7 @@ def call_after_refresh(self, callback: Callable, *args: Any, **kwargs: Any) -> b
         message = messages.InvokeLater(partial(callback, *args, **kwargs))
         return self.post_message(message)
 
-    def call_later(self, callback: Callable, *args: Any, **kwargs: Any) -> bool:
+    def call_later(self, callback: Callback, *args: Any, **kwargs: Any) -> bool:
         """Schedule a callback to run after all messages are processed in this object.
         Positional and keywords arguments are passed to the callable.
 
@@ -404,7 +409,7 @@ def call_later(self, callback: Callable, *args: Any, **kwargs: Any) -> bool:
         message = events.Callback(callback=partial(callback, *args, **kwargs))
         return self.post_message(message)
 
-    def call_next(self, callback: Callable, *args: Any, **kwargs: Any) -> None:
+    def call_next(self, callback: Callback, *args: Any, **kwargs: Any) -> None:
         """Schedule a callback to run immediately after processing the current message.
 
         Args: