process layout hook

Author: willmcgugan

src/textual/_arrange.py

@@ -95,8 +95,10 @@ def arrange(
 
         if layout_widgets:
             # Arrange layout widgets (i.e. not docked)
-            layout_placements = widget.layout.arrange(
-                widget, layout_widgets, dock_region.size, greedy=not optimal
+            layout_placements = widget.process_layout(
+                widget.layout.arrange(
+                    widget, layout_widgets, dock_region.size, greedy=not optimal
+                )
             )
             scroll_spacing = scroll_spacing.grow_maximum(dock_spacing)
             placement_offset = dock_region.offset

src/textual/widget.py

@@ -79,7 +79,7 @@
     Spacing,
     clamp,
 )
-from textual.layout import Layout
+from textual.layout import Layout, WidgetPlacement
 from textual.layouts.vertical import VerticalLayout
 from textual.message import Message
 from textual.messages import CallbackType, Prune
@@ -722,6 +722,22 @@ def _cover(self, widget: Widget) -> None:
         self.app.stylesheet.apply(widget)
         self.refresh(layout=True)
 
+    def process_layout(
+        self, placements: list[WidgetPlacement]
+    ) -> list[WidgetPlacement]:
+        """A hook to allow for the manipulation of widget placements before rendering.
+
+        You could use this as a way to modify the positions / margins of widgets if your requirement is
+        not supported in TCSS. In practice, this method is rarely needed!
+
+        Args:
+            placements: A list of [`WidgetPlacement`][textual.layout.WidgetPlacement] objects.
+
+        Returns:
+            A new list of placements.
+        """
+        return placements
+
     def _uncover(self) -> None:
         """Remove any widget, previously set via [`_cover`][textual.widget.Widget._cover]."""
         if self._cover_widget is not None: