Tooltips (#2670)

* inflect

* diagram

* tooltip render

* tooltip property

* add guard

* tooltip docs

* docs

* tidy, fix horizontal

* words, removed comment

* fix screenshot render

* simplify

* simfplify

* changelog

* simplify optimize

* inflect tests

* Apply suggestions from code review

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* docstring

* disable auto focus

* should be fraction

* optimization

* snapshot update

* Update tests/snapshot_tests/snapshot_apps/scroll_to_center.py

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

---------

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

docs/examples/guide/widgets/tooltip01.py

@@ -0,0 +1,26 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Button
+
+TEXT = """I must not fear.
+Fear is the mind-killer.
+Fear is the little-death that brings total obliteration.
+I will face my fear."""
+
+
+class TooltipApp(App):
+    CSS = """
+    Screen {
+        align: center middle;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Button("Click me", variant="success")
+
+    def on_mount(self) -> None:
+        self.query_one(Button).tooltip = TEXT
+
+
+if __name__ == "__main__":
+    app = TooltipApp()
+    app.run()

docs/examples/guide/widgets/tooltip02.py

@@ -0,0 +1,31 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Button
+
+TEXT = """I must not fear.
+Fear is the mind-killer.
+Fear is the little-death that brings total obliteration.
+I will face my fear."""
+
+
+class TooltipApp(App):
+    CSS = """
+    Screen {
+        align: center middle;
+    }
+    Tooltip {
+        padding: 2 4;
+        background: $primary;
+        color: auto 90%;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Button("Click me", variant="success")
+
+    def on_mount(self) -> None:
+        self.query_one(Button).tooltip = TEXT
+
+
+if __name__ == "__main__":
+    app = TooltipApp()
+    app.run()

docs/guide/widgets.md

@@ -193,6 +193,58 @@ Let's modify the default width for the fizzbuzz example. By default, the table w
 
 Note that we've added `expand=True` to tell the `Table` to expand beyond the optimal width, so that it fills the 50 characters returned by `get_content_width`.
 
+## Tooltips
+
+Widgets can have *tooltips* which is content displayed when the user hovers the mouse over the widget.
+You can use tooltips to add supplementary information or help messages.
+
+!!! tip
+
+    It is best not to rely on tooltips for essential information.
+    Some users prefer to use the keyboard exclusively and may never see tooltips.
+
+
+To add a tooltip, assign to the widget's [`tooltip`][textual.widgets.Widget.tooltip] property.
+You can set text or any other [Rich](https://github.com/Textualize/rich) renderable.
+
+The following example adds a tooltip to a button:
+
+=== "tooltip01.py"
+
+    ```python title="tooltip01.py"
+    --8<-- "docs/examples/guide/widgets/tooltip01.py"
+    ```
+
+=== "Output (before hover)"
+
+    ```{.textual path="docs/examples/guide/widgets/tooltip01.py"}
+    ```
+
+=== "Output (after hover)"
+
+    ```{.textual path="docs/examples/guide/widgets/tooltip01.py" hover="Button"}
+    ```
+
+### Customizing the tooltip
+
+If you don't like the default look of the tooltips, you can customize them to your liking with CSS.
+Add a rule to your CSS that targets `Tooltip`. Here's an example:
+
+=== "tooltip02.py"
+
+    ```python title="tooltip02.py" hl_lines="15-19"
+    --8<-- "docs/examples/guide/widgets/tooltip02.py"
+    ```
+
+=== "Output (before hover)"
+
+    ```{.textual path="docs/examples/guide/widgets/tooltip02.py"}
+    ```
+
+=== "Output (after hover)"
+
+    ```{.textual path="docs/examples/guide/widgets/tooltip02.py" hover="Button"}
+    ```
 
 ## Line API