Merge branch 'main' into themes

Author: darrenburns

CHANGELOG.md

@@ -11,6 +11,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Fixed duplicated key displays in the help panel https://github.com/Textualize/textual/issues/5037
 
+### Added
+
+- Added `can_focus` and `can_focus_children` parameters to scrollable container types. https://github.com/Textualize/textual/pull/5226
+- Added `textual.lazy.Reveal` https://github.com/Textualize/textual/pull/5226
+- Added `Screen.action_blur` https://github.com/Textualize/textual/pull/5226
+
 ## [0.85.2] - 2024-11-02
 
 - Fixed broken focus-within https://github.com/Textualize/textual/pull/5190

src/textual/app.py

@@ -761,6 +761,9 @@ def __init__(
 
         self._hover_effects_timer: Timer | None = None
 
+        self._css_update_count: int = 0
+        """Incremented when CSS is invalidated."""
+
         if self.ENABLE_COMMAND_PALETTE:
             for _key, binding in self._bindings:
                 if binding.action in {"command_palette", "app.command_palette"}:
@@ -1243,17 +1246,24 @@ def _watch_theme(self, theme_name: str) -> None:
         self.set_class(dark, "-dark-mode", update=False)
         self.set_class(not dark, "-light-mode", update=False)
         self._refresh_truecolor_filter(self.ansi_theme)
+        self._invalidate_css()
         self.call_next(self.refresh_css)
         self.call_next(self.theme_changed_signal.publish, theme)
 
+    def _invalidate_css(self) -> None:
+        """Invalidate CSS, so it will be refreshed."""
+        self._css_update_count += 1
+        
     def watch_ansi_theme_dark(self, theme: TerminalTheme) -> None:
         if self.current_theme.dark:
             self._refresh_truecolor_filter(theme)
+            self._invalidate_css()
             self.call_next(self.refresh_css)
 
     def watch_ansi_theme_light(self, theme: TerminalTheme) -> None:
         if not self.current_theme.dark:
             self._refresh_truecolor_filter(theme)
+            self._invalidate_css()
             self.call_next(self.refresh_css)
 
     @property
@@ -2283,7 +2293,9 @@ def _init_mode(self, mode: str) -> AwaitMount:
             screen, await_mount = self._get_screen(new_screen)
             stack.append(screen)
             self._load_screen_css(screen)
-            self.refresh_css()
+            if screen._css_update_count != self._css_update_count:
+                self.refresh_css()
+
             screen.post_message(events.ScreenResume())
         else:
             # Mode is not defined
@@ -2328,7 +2340,8 @@ def switch_mode(self, mode: str) -> AwaitMount:
             await_mount = AwaitMount(self.screen, [])
 
         self._current_mode = mode
-        self.refresh_css()
+        if self.screen._css_update_count != self._css_update_count:
+            self.refresh_css()
         self.screen._screen_resized(self.size)
         self.screen.post_message(events.ScreenResume())
 
@@ -3445,6 +3458,7 @@ def refresh_css(self, animate: bool = True) -> None:
         stylesheet.update(self.app, animate=animate)
         try:
             self.screen._refresh_layout(self.size)
+            self.screen._css_update_count = self._css_update_count
         except ScreenError:
             pass
         # The other screens in the stack will need to know about some style
@@ -3453,6 +3467,7 @@ def refresh_css(self, animate: bool = True) -> None:
         for screen in self.screen_stack:
             if screen != self.screen:
                 stylesheet.update(screen, animate=animate)
+                screen._css_update_count = self._css_update_count
 
     def _display(self, screen: Screen, renderable: RenderableType | None) -> None:
         """Display a renderable within a sync.

src/textual/containers.py

@@ -73,6 +73,40 @@ class ScrollableContainer(Widget, can_focus=True, inherit_bindings=False):
     | ctrl+pagedown | Scroll right one page, if horizontal scrolling is available. |
     """
 
+    def __init__(
+        self,
+        *children: Widget,
+        name: str | None = None,
+        id: str | None = None,
+        classes: str | None = None,
+        disabled: bool = False,
+        can_focus: bool | None = None,
+        can_focus_children: bool | None = None,
+    ) -> None:
+        """
+
+        Args:
+            *children: Child widgets.
+            name: The name of the widget.
+            id: The ID of the widget in the DOM.
+            classes: The CSS classes for the widget.
+            disabled: Whether the widget is disabled or not.
+            can_focus: Can this container be focused?
+            can_focus_children: Can this container's children be focused?
+        """
+
+        super().__init__(
+            *children,
+            name=name,
+            id=id,
+            classes=classes,
+            disabled=disabled,
+        )
+        if can_focus is not None:
+            self.can_focus = can_focus
+        if can_focus_children is not None:
+            self.can_focus_children = can_focus_children
+
 
 class Vertical(Widget, inherit_bindings=False):
     """An expanding container with vertical layout and no scrollbars."""

src/textual/demo/demo_app.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from textual.app import App
 from textual.binding import Binding
 from textual.demo.home import HomeScreen

src/textual/demo/home.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 from importlib.metadata import version
 

src/textual/demo/page.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import inspect
 
 from rich.syntax import Syntax

src/textual/demo/projects.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dataclasses import dataclass
 
 from textual import events, on

src/textual/demo/widgets.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import csv
 import io
 from math import sin
@@ -6,7 +8,7 @@
 from rich.table import Table
 from rich.traceback import Traceback
 
-from textual import containers
+from textual import containers, lazy
 from textual.app import ComposeResult
 from textual.binding import Binding
 from textual.demo.data import COUNTRIES
@@ -439,19 +441,21 @@ class WidgetsScreen(PageScreen):
     CSS = """
     WidgetsScreen { 
         align-horizontal: center;
-        & > VerticalScroll > * {            
-            &:last-of-type { margin-bottom: 2; } 
-            &:even { background: $boost; }            
-            padding-bottom: 1;                                        
-        }                           
+        & > VerticalScroll {
+            scrollbar-gutter: stable;
+            &> * {            
+                &:last-of-type { margin-bottom: 2; } 
+                &:even { background: $boost; }
+                padding-bottom: 1;
+            }
+        }
     }
     """
 
-    BINDINGS = [Binding("escape", "unfocus", "Unfocus any focused widget", show=False)]
+    BINDINGS = [Binding("escape", "blur", "Unfocus any focused widget", show=False)]
 
     def compose(self) -> ComposeResult:
-        with containers.VerticalScroll() as container:
-            container.can_focus = False
+        with lazy.Reveal(containers.VerticalScroll(can_focus=False)):
             yield Markdown(WIDGETS_MD, classes="column")
             yield Buttons()
             yield Checkboxes()
@@ -461,6 +465,3 @@ def compose(self) -> ComposeResult:
             yield Logs()
             yield Sparklines()
         yield Footer()
-
-    def action_unfocus(self) -> None:
-        self.set_focus(None)

src/textual/lazy.py

@@ -4,6 +4,8 @@
 
 from __future__ import annotations
 
+from functools import partial
+
 from textual.widget import Widget
 
 
@@ -61,3 +63,85 @@ async def mount() -> None:
             await self.remove()
 
         self.call_after_refresh(mount)
+
+
+class Reveal(Widget):
+    DEFAULT_CSS = """
+    Reveal {
+        display: none;
+    }
+    """
+
+    def __init__(self, widget: Widget, delay: float = 1 / 60) -> None:
+        """Similar to [Lazy][textual.lazy.Lazy], but also displays *children* sequentially.
+
+        The first frame will display the first child with all other children hidden.
+        The remaining children will be displayed 1-by-1, over as may frames are required.
+
+        This is useful when you have so many child widgets that there is a noticeable delay before
+        you see anything. By mounting the children over several frames, the user will feel that
+        something is happening.
+
+        Example:
+            ```python
+            def compose(self) -> ComposeResult:
+                with lazy.Reveal(containers.VerticalScroll(can_focus=False)):
+                    yield Markdown(WIDGETS_MD, classes="column")
+                    yield Buttons()
+                    yield Checkboxes()
+                    yield Datatables()
+                    yield Inputs()
+                    yield ListViews()
+                    yield Logs()
+                    yield Sparklines()
+                yield Footer()
+        ```
+
+        Args:
+            widget: A widget that should be mounted after a refresh.
+            delay: A (short) delay between mounting widgets.
+        """
+        self._replace_widget = widget
+        self._delay = delay
+        super().__init__()
+
+    @classmethod
+    def _reveal(cls, parent: Widget, delay: float = 1 / 60) -> None:
+        """Reveal children lazily.
+
+        Args:
+            parent: The parent widget.
+            delay: A delay between reveals.
+        """
+
+        def check_children() -> None:
+            """Check for un-displayed children."""
+            iter_children = iter(parent.children)
+            for child in iter_children:
+                if not child.display:
+                    child.display = True
+                    break
+            for child in iter_children:
+                if not child.display:
+                    parent.set_timer(
+                        delay, partial(parent.call_after_refresh, check_children)
+                    )
+                    break
+
+        check_children()
+
+    def compose_add_child(self, widget: Widget) -> None:
+        widget.display = False
+        self._replace_widget.compose_add_child(widget)
+
+    async def mount_composed_widgets(self, widgets: list[Widget]) -> None:
+        parent = self.parent
+        if parent is None:
+            return
+        assert isinstance(parent, Widget)
+
+        if self._replace_widget.children:
+            self._replace_widget.children[0].display = True
+        await parent.mount(self._replace_widget, after=self)
+        await self.remove()
+        self._reveal(self._replace_widget, self._delay)

src/textual/screen.py

@@ -266,6 +266,9 @@ def __init__(
         self.bindings_updated_signal: Signal[Screen] = Signal(self, "bindings_updated")
         """A signal published when the bindings have been updated"""
 
+        self._css_update_count = -1
+        """Track updates to CSS."""
+
     @property
     def is_modal(self) -> bool:
         """Is the screen modal?"""
@@ -779,6 +782,10 @@ def action_minimize(self) -> None:
         """Action to minimize the currently maximized widget."""
         self.minimize()
 
+    def action_blur(self) -> None:
+        """Action to remove focus (if set)."""
+        self.set_focus(None)
+
     def _reset_focus(
         self, widget: Widget, avoiding: list[Widget] | None = None
     ) -> None: