Merge branch 'main' into fix-header-add-compose-return-type

Author: willmcgugan

CHANGELOG.md

@@ -20,11 +20,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Added `OptionList.set_options` https://github.com/Textualize/textual/pull/6048
 - Added `TextArea.suggestion` https://github.com/Textualize/textual/pull/6048
 - Added `TextArea.placeholder` https://github.com/Textualize/textual/pull/6048
+- Added `Header.format_title` and `App.format_title` for easier customization of title in the Header https://github.com/Textualize/textual/pull/6051
 - Added `Widget.get_line_filters` and `App.get_line_filters` https://github.com/Textualize/textual/pull/6057
 
 ### Changed
 
 - Breaking change: The `renderable` property on the `Static` widget has been changed to `content`. https://github.com/Textualize/textual/pull/6041
+- Breaking change: `HeaderTitle` widget is now a static, with no `text` and `sub_text` reactives https://github.com/Textualize/textual/pull/6051
 - Breaking change: Renamed `Label` constructor argument `renderable` to `content` for consistency https://github.com/Textualize/textual/pull/6045
 - Breaking change: Optimization to line API to avoid applying background styles to widget content. In practice this means that you can no longer rely on blank Segments automatically getting the background color.
 

docs/how-to/style-inline-apps.md

@@ -19,6 +19,11 @@ The following app displays the the current time (and keeps it up to date).
 
 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.
 
+!!! note
+
+    Textual also adds a blank line above inline apps for padding.
+    To remove this default padding, you can set `INLINE_PADDING = 0` on your app class.
+
 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:
 

src/textual/app.py

@@ -94,6 +94,7 @@
 from textual.binding import Binding, BindingsMap, BindingType, Keymap
 from textual.command import CommandListItem, CommandPalette, Provider, SimpleProvider
 from textual.compose import compose
+from textual.content import Content
 from textual.css.errors import StylesheetError
 from textual.css.query import NoMatches
 from textual.css.stylesheet import RulesMap, Stylesheet
@@ -971,6 +972,27 @@ def clipboard(self) -> str:
         """
         return self._clipboard
 
+    def format_title(self, title: str, sub_title: str) -> Content:
+        """Format the title for display.
+
+        Args:
+            title: The title.
+            sub_title: The sub title.
+
+        Returns:
+            Content instance with title and subtitle.
+        """
+        title_content = Content(title)
+        sub_title_content = Content(sub_title)
+        if sub_title_content:
+            return Content.assemble(
+                title_content,
+                (" — ", "dim"),
+                sub_title_content.stylize("dim"),
+            )
+        else:
+            return title_content
+
     @contextmanager
     def batch_update(self) -> Generator[None, None, None]:
         """A context manager to suspend all repaints until the end of the batch."""

src/textual/demo/widgets.py

@@ -587,7 +587,7 @@ class Switches(containers.VerticalGroup):
     SWITCHES_MD = """\
 ## Switches
 
-Functionally almost identical to a Checkbox, but more displays more prominently in the UI.
+Functionally almost identical to a Checkbox, but displays more prominently in the UI.
 """
     DEFAULT_CSS = """\
 Switches {    

src/textual/widgets/_header.py

@@ -7,10 +7,12 @@
 from rich.text import Text
 
 from textual.app import ComposeResult, RenderResult
+from textual.content import Content
 from textual.dom import NoScreen
 from textual.events import Click, Mount
 from textual.reactive import Reactive
 from textual.widget import Widget
+from textual.widgets import Static
 
 
 class HeaderIcon(Widget):
@@ -98,34 +100,18 @@ def render(self) -> RenderResult:
         return Text(datetime.now().time().strftime(self.time_format))
 
 
-class HeaderTitle(Widget):
+class HeaderTitle(Static):
     """Display the title / subtitle in the header."""
 
     DEFAULT_CSS = """
     HeaderTitle {
+        text-wrap: nowrap;
+        text-overflow: ellipsis;
         content-align: center middle;
         width: 100%;
     }
     """
 
-    text: Reactive[str] = Reactive("")
-    """The main title text."""
-
-    sub_text = Reactive("")
-    """The sub-title text."""
-
-    def render(self) -> RenderResult:
-        """Render the title and sub-title.
-
-        Returns:
-            The value to render.
-        """
-        text = Text(self.text, no_wrap=True, overflow="ellipsis")
-        if self.sub_text:
-            text.append(" — ")
-            text.append(self.sub_text, "dim")
-        return text
-
 
 class Header(Widget):
     """A header widget with icon and clock."""
@@ -196,6 +182,17 @@ def watch_tall(self, tall: bool) -> None:
     def _on_click(self):
         self.toggle_class("-tall")
 
+    def format_title(self) -> Content:
+        """Format the title and subtitle.
+
+        Defers to [App.format_title][textual.app.App.format_title] by default.
+        Override this method if you want to customize how the title is displayed in the header.
+
+        Returns:
+            Content for title display.
+        """
+        return self.app.format_title(self.screen_title, self.screen_sub_title)
+
     @property
     def screen_title(self) -> str:
         """The title that this header will display.
@@ -221,17 +218,11 @@ def screen_sub_title(self) -> str:
     def _on_mount(self, _: Mount) -> None:
         async def set_title() -> None:
             try:
-                self.query_one(HeaderTitle).text = self.screen_title
-            except NoScreen:
-                pass
-
-        async def set_sub_title() -> None:
-            try:
-                self.query_one(HeaderTitle).sub_text = self.screen_sub_title
+                self.query_one(HeaderTitle).update(self.format_title())
             except NoScreen:
                 pass
 
         self.watch(self.app, "title", set_title)
-        self.watch(self.app, "sub_title", set_sub_title)
+        self.watch(self.app, "sub_title", set_title)
         self.watch(self.screen, "title", set_title)
-        self.watch(self.screen, "sub_title", set_sub_title)
+        self.watch(self.screen, "sub_title", set_title)

tests/snapshot_tests/__snapshots__/test_snapshots/test_header_format.svg

@@ -25,7 +25,7 @@ class ScreenSplitApp(App[None]):
         background: $panel;
     }
 
-    Static {
+    #scroll1 Static, #scroll2 Static {
         width: 1fr;
         content-align: center middle;
         background: $boost;

tests/snapshot_tests/snapshot_apps/fr_with_min.py

@@ -4610,3 +4610,19 @@ def compose(self) -> ComposeResult:
             yield TextArea(placeholder="Your text here")
 
     assert snap_compare(TextApp())
+
+
+def test_header_format(snap_compare):
+    """Test title and sub-title are formatted as expected.
+
+    You should see "Title - Sub-title" in the header. Where sub-title is dimmed.
+    """
+
+    class HeaderApp(App):
+        TITLE = "Title"
+        SUB_TITLE = "Sub-title"
+
+        def compose(self) -> ComposeResult:
+            yield Header()
+
+    assert snap_compare(HeaderApp())