border classvars (#3097)

* border classvars

* changelog

* copy

* remove whitespace

* copy

Author: willmcgugan

CHANGELOG.md

@@ -16,9 +16,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `MouseMove` events bubble up from widgets. `App` and `Screen` receive `MouseMove` events even if there's no Widget under the cursor. https://github.com/Textualize/textual/issues/2905
 
 ### Added
-- Added an interface for replacing prompt of an individual option in an `OptionList` https://github.com/Textualize/textual/issues/2603 
+- Added an interface for replacing prompt of an individual option in an `OptionList` https://github.com/Textualize/textual/issues/2603
 - Added `DirectoryTree.reload_node` method https://github.com/Textualize/textual/issues/2757
 - Added widgets.Digit https://github.com/Textualize/textual/pull/3073
+- Added `BORDER_TITLE` and `BORDER_SUBTITLE` classvars to Widget https://github.com/Textualize/textual/pull/3097
 
 ## [0.32.0] - 2023-08-03
 

docs/examples/guide/widgets/hello06.css

@@ -0,0 +1,12 @@
+Screen {
+    align: center middle;
+}
+
+Hello {
+    width: 40;
+    height: 9;
+    padding: 1 2;
+    background: $panel;
+    border: $secondary tall;
+    content-align: center middle;
+}

docs/examples/guide/widgets/hello06.py

@@ -0,0 +1,47 @@
+from itertools import cycle
+
+from textual.app import App, ComposeResult
+from textual.widgets import Static
+
+hellos = cycle(
+    [
+        "Hola",
+        "Bonjour",
+        "Guten tag",
+        "Salve",
+        "Nǐn hǎo",
+        "Olá",
+        "Asalaam alaikum",
+        "Konnichiwa",
+        "Anyoung haseyo",
+        "Zdravstvuyte",
+        "Hello",
+    ]
+)
+
+
+class Hello(Static):
+    """Display a greeting."""
+
+    BORDER_TITLE = "Hello Widget"  # (1)!
+
+    def on_mount(self) -> None:
+        self.action_next_word()
+        self.border_subtitle = "Click for next hello"  # (2)!
+
+    def action_next_word(self) -> None:
+        """Get a new hello and update the content area."""
+        hello = next(hellos)
+        self.update(f"[@click='next_word']{hello}[/], [b]World[/b]!")
+
+
+class CustomApp(App):
+    CSS_PATH = "hello05.css"
+
+    def compose(self) -> ComposeResult:
+        yield Hello()
+
+
+if __name__ == "__main__":
+    app = CustomApp()
+    app.run()

docs/guide/widgets.md

@@ -142,6 +142,47 @@ Let's use markup links in the hello example so that the greeting becomes a link
 If you run this example you will see that the greeting has been underlined, which indicates it is clickable. If you click on the greeting it will run the `next_word` action which updates the next word.
 
 
+## Border titles
+
+Every widget has a [`border_title`][textual.widgets.Widget.border_title] and [`border_subtitle`][textual.widgets.Widget.border_subtitle] attribute.
+Setting `border_title` will display text within the top border, and setting `border_subtitle` will display text within the bottom border.
+
+!!! note
+
+    Border titles will only display if the widget has a [border](../styles/border.md) enabled.
+
+The default value for these attributes is empty string, which disables the title.
+You can change the default value for the title attributes with the [`BORDER_TITLE`][textual.widget.Widget.BORDER_TITLE] and [`BORDER_SUBTITLE`][textual.widget.Widget.BORDER_SUBTITLE] class variables.
+
+Let's demonstrate setting a title, both as a class variable and a instance variable:
+
+
+=== "hello06.py"
+
+    ```python title="hello06.py"  hl_lines="26 30"
+    --8<-- "docs/examples/guide/widgets/hello06.py"
+    ```
+
+    1. Setting the default for the `title` attribute via class variable.
+    2. Setting `subtitle` via an instance attribute.
+
+=== "hello06.css"
+
+    ```sass title="hello06.css"
+    --8<-- "docs/examples/guide/widgets/hello06.css"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/guide/widgets/hello06.py"}
+    ```
+
+Note that titles are limited to a single line of text.
+If the supplied text is too long to fit within the widget, it will be cropped (and an ellipsis added).
+
+There are a number of styles that influence how titles are displayed (color and alignment).
+See the [style reference](../styles/index.md) for details.
+
 ## Rich renderables
 
 In previous examples we've set strings as content for Widgets. You can also use special objects called [renderables](https://rich.readthedocs.io/en/latest/protocol.html) for advanced visuals. You can use any renderable defined in [Rich](https://github.com/Textualize/rich) or third party libraries.

src/textual/widget.py

@@ -45,7 +45,6 @@
 from ._arrange import DockArrangeResult, arrange
 from ._asyncio import create_task
 from ._cache import FIFOCache
-from ._callback import invoke
 from ._compose import compose
 from ._context import NoActiveAppError, active_app
 from ._easing import DEFAULT_SCROLL_EASING
@@ -256,6 +255,12 @@ class Widget(DOMNode):
     """
     COMPONENT_CLASSES: ClassVar[set[str]] = set()
 
+    BORDER_TITLE: ClassVar[str] = ""
+    """Initial value for border_title attribute."""
+
+    BORDER_SUBTITLE: ClassVar[str] = ""
+    """Initial value for border_subtitle attribute."""
+
     can_focus: bool = False
     """Widget may receive focus."""
     can_focus_children: bool = True
@@ -349,6 +354,10 @@ def __init__(
 
         self._add_children(*children)
         self.disabled = disabled
+        if self.BORDER_TITLE:
+            self.border_title = self.BORDER_TITLE
+        if self.BORDER_SUBTITLE:
+            self.border_subtitle = self.BORDER_SUBTITLE
 
     virtual_size: Reactive[Size] = Reactive(Size(0, 0), layout=True)
     """The virtual (scrollable) [size][textual.geometry.Size] of the widget."""

tests/test_border_subtitle.py

@@ -0,0 +1,18 @@
+from textual.app import App, ComposeResult
+from textual.widget import Widget
+
+
+async def test_border_subtitle():
+    class BorderWidget(Widget):
+        BORDER_TITLE = "foo"
+        BORDER_SUBTITLE = "bar"
+
+    class SimpleApp(App):
+        def compose(self) -> ComposeResult:
+            yield BorderWidget()
+
+    empty_app = SimpleApp()
+    async with empty_app.run_test() as pilot:
+        widget = empty_app.query_one(BorderWidget)
+        assert widget.border_title == "foo"
+        assert widget.border_subtitle == "bar"