Merge pull request #5779 from Textualize/breakpoints

Breakpoints

Author: willmcgugan

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Added `toggle_class` parameter to reactives https://github.com/Textualize/textual/pull/5778
 - Added `compact` parameter and reactive to `Button`, `Input`, `ToggleButton`, `RadioSet`, `OptionList`, `TextArea` https://github.com/Textualize/textual/pull/5778
+- Added `HORIZONTAL_BREAKPOINTS` and `VERTICAL_BREAKPOINTS` to `App` and `Screen` https://github.com/Textualize/textual/pull/5779
 
 ### Changed
 

examples/breakpoints.py

@@ -0,0 +1,53 @@
+from textual.app import App, ComposeResult
+from textual.containers import Grid
+from textual.widgets import Footer, Markdown, Placeholder
+
+HELP = """\
+## Breakpoints
+
+A demonstration of how to make an app respond to the dimensions of the terminal.
+
+Try resizing the terminal, then have a look at the source to see how it works!
+"""
+
+
+class BreakpointApp(App):
+
+    # A breakpoint consists of a width and a class name to set
+    HORIZONTAL_BREAKPOINTS = [
+        (0, "-narrow"),
+        (40, "-normal"),
+        (80, "-wide"),
+        (120, "-very-wide"),
+    ]
+
+    CSS = """
+    Screen {        
+        Placeholder { padding: 2; }
+        Grid { grid-rows: auto; height: auto; }
+        # Change the styles according to the breakpoint classes
+        &.-narrow {
+            Grid { grid-size: 1; }
+        }
+        &.-normal {
+            Grid { grid-size: 2; }
+        }
+        &.-wide {
+            Grid { grid-size: 4; }
+        }
+        &.-very-wide {
+            Grid { grid-size: 6; }
+        }
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Markdown(HELP)
+        with Grid():
+            for n in range(16):
+                yield Placeholder(f"Placeholder {n+1}")
+        yield Footer()
+
+
+if __name__ == "__main__":
+    BreakpointApp().run()

src/textual/app.py

@@ -482,6 +482,31 @@ class MyApp(App[None]):
     SUSPENDED_SCREEN_CLASS: ClassVar[str] = ""
     """Class to apply to suspended screens, or empty string for no class."""
 
+    HORIZONTAL_BREAKPOINTS: ClassVar[list[tuple[int, str]]] | None = []
+    """List of horizontal breakpoints for responsive classes.
+
+    This allows for styles to be responsive to the dimensions of the terminal.
+    For instance, you might want to show less information, or fewer columns on a narrow displays -- or more information when the terminal is sized wider than usual.
+    
+    A breakpoint consists of a tuple containing the minimum width where the class should applied, and the name of the class to set.
+
+    Note that only one class name is set, and if you should avoid having more than one breakpoint set for the same size.
+
+    Example:
+        ```python
+        # Up to 80 cells wide, the app has the class "-normal"
+        # 80 - 119 cells wide, the app has the class "-wide"
+        # 120 cells or wider, the app has the class "-very-wide"
+        HORIZONTAL_BREAKPOINTS = [(0, "-normal"), (80, "-wide"), (120, "-very-wide")]
+        ```
+    
+    """
+    VERTICAL_BREAKPOINTS: ClassVar[list[tuple[int, str]]] | None = []
+    """List of vertical breakpoints for responsive classes.
+    
+    Contents are the same as [`HORIZONTAL_BREAKPOINTS`][textual.app.App.HORIZONTAL_BREAKPOINTS], but the integer is compared to the height, rather than the width.
+    """
+
     _PSEUDO_CLASSES: ClassVar[dict[str, Callable[[App[Any]], bool]]] = {
         "focus": lambda app: app.app_focus,
         "blur": lambda app: not app.app_focus,

src/textual/screen.py

@@ -196,6 +196,11 @@ class Screen(Generic[ScreenResultType], Widget):
     you can set the [sub_title][textual.screen.Screen.sub_title] attribute.
     """
 
+    HORIZONTAL_BREAKPOINTS: ClassVar[list[tuple[int, str]]] | None = None
+    """Horizontal breakpoints, will override [App.HORIZONTAL_BREAKPOINTS][textual.app.App.HORIZONTAL_BREAKPOINTS] if not `None`."""
+    VERTICAL_BREAKPOINTS: ClassVar[list[tuple[int, str]]] | None = None
+    """Vertical breakpoints, will override [App.VERTICAL_BREAKPOINTS][textual.app.App.VERTICAL_BREAKPOINTS] if not `None`."""
+
     focused: Reactive[Widget | None] = Reactive(None)
     """The focused [widget][textual.widget.Widget] or `None` for no focus.
     To set focus, do not update this value directly. Use [set_focus][textual.screen.Screen.set_focus] instead."""
@@ -1354,6 +1359,41 @@ async def _on_resize(self, event: events.Resize) -> None:
         for screen in self.app._background_screens:
             screen._screen_resized(event.size)
 
+        horizontal_breakpoints = (
+            self.app.HORIZONTAL_BREAKPOINTS
+            if self.HORIZONTAL_BREAKPOINTS is None
+            else self.HORIZONTAL_BREAKPOINTS
+        ) or []
+
+        vertical_breakpoints = (
+            self.app.VERTICAL_BREAKPOINTS
+            if self.VERTICAL_BREAKPOINTS is None
+            else self.VERTICAL_BREAKPOINTS
+        ) or []
+
+        width, height = event.size
+        if horizontal_breakpoints:
+            self._set_breakpoints(width, horizontal_breakpoints)
+        if vertical_breakpoints:
+            self._set_breakpoints(height, horizontal_breakpoints)
+
+    def _set_breakpoints(
+        self, dimension: int, breakpoints: list[tuple[int, str]]
+    ) -> None:
+        """Set horizontal or vertical breakpoints.
+
+        Args:
+            dimension: Either the width or the height.
+            breakpoints: A list of breakpoints.
+
+        """
+        class_names = [class_name for _breakpoint, class_name in breakpoints]
+        self.remove_class(*class_names)
+        for breakpoint, class_name in sorted(breakpoints, reverse=True):
+            if dimension >= breakpoint:
+                self.add_class(class_name)
+                return
+
     def _update_tooltip(self, widget: Widget) -> None:
         """Update the content of the tooltip."""
         try: