Merge pull request #5278 from Textualize/demo-tweaks

Add position:absolute and game to demo

Author: willmcgugan

CHANGELOG.md

@@ -6,11 +6,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
-## Unreleased
+## [0.87.0] - 2024-11-24
 
 ### Added
 
 - Added Styles.has_any_rules https://github.com/Textualize/textual/pull/5264
+- Added `position` CSS rule. https://github.com/Textualize/textual/pull/5278
+- Added `Widget.set_scroll` https://github.com/Textualize/textual/pull/5278
+- Added `Select.selection` https://github.com/Textualize/textual/pull/5278
 
 ### Fixed 
 
@@ -2573,6 +2576,7 @@ https://textual.textualize.io/blog/2022/11/08/version-040/#version-040
 - New handler system for messages that doesn't require inheritance
 - Improved traceback handling
 
+[0.87.0]: https://github.com/Textualize/textual/compare/v0.86.4...v0.87.0
 [0.86.3]: https://github.com/Textualize/textual/compare/v0.86.2...v0.86.3
 [0.86.2]: https://github.com/Textualize/textual/compare/v0.86.1...v0.86.2
 [0.86.1]: https://github.com/Textualize/textual/compare/v0.86.0...v0.86.1

docs/css_types/position.md

@@ -0,0 +1,31 @@
+# <position>
+
+The `<position>` CSS type defines how the the `offset` rule is applied..
+
+
+## Syntax
+
+A [`<position>`](./position.md) may be any of the following values:
+
+| Value      | Alignment type                                               |
+| ---------- | ------------------------------------------------------------ |
+| `relative` | Offset is applied to widgets default position.               |
+| `absolute` | Offset is applied to the origin (top left) of its container. |
+
+## Examples
+
+### CSS
+
+```css
+Label {
+    position: absolute;
+    offset: 10 5;
+}
+```
+
+### Python
+
+```py
+widget.styles.position = "absolute"
+widget.styles.offset = (10, 5)
+```

docs/examples/styles/position.py

@@ -0,0 +1,15 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Label
+
+
+class PositionApp(App):
+    CSS_PATH = "position.tcss"
+
+    def compose(self) -> ComposeResult:
+        yield Label("Absolute", id="label1")
+        yield Label("Relative", id="label2")
+
+
+if __name__ == "__main__":
+    app = PositionApp()
+    app.run()

docs/examples/styles/position.tcss

@@ -0,0 +1,19 @@
+Screen {
+    align: center middle;
+}
+
+Label {
+    padding: 1;
+    background: $panel;
+    border: thick $border;
+}
+
+Label#label1 {
+    position: absolute;
+    offset: 2 1;
+}
+
+Label#label2 {
+    position: relative;
+    offset: 2 1;
+}

docs/styles/position.md

@@ -0,0 +1,61 @@
+
+# Position
+
+The `position` style modifies what [`offset`](./offset.md) is applied to.
+The default for `position` is `"relative"`, which means the offset is applied to the normal position of the widget.
+In other words, if `offset` is (1, 1), then the widget will be moved 1 cell and 1 line down from its usual position.
+
+The alternative value of `position` is `"absolute"`.
+With absolute positioning, the offset is relative to the origin (i.e. the top left of the container).
+So a widget with offset (1, 1) and absolute positioning will be 1 cell and 1 line down from the top left corner.
+
+!!! note
+
+    Absolute positioning takes precedence over the parent's alignment rule.
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+position: <a href="../../css_types/position">&lt;position&gt;</a>;
+--8<-- "docs/snippets/syntax_block_end.md"
+
+
+## Examples
+
+
+Two labels, the first is absolute positioned and is displayed relative to the top left of the screen.
+The second label is relative and is displayed offset from the center.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/position.py"}
+    ```
+
+=== "position.py"
+
+    ```py
+    --8<-- "docs/examples/styles/position.py"
+    ```
+
+=== "position.tcss"
+
+    ```css
+    --8<-- "docs/examples/styles/position.tcss"
+    ```
+
+
+
+
+## CSS
+
+```css
+position: relative;
+position: absolute;
+```
+
+## Python
+
+```py
+widget.styles.position = "relative"
+widget.styles.position = "absolute"
+```

mkdocs-nav.yml

@@ -37,6 +37,7 @@ nav:
           - "css_types/name.md"
           - "css_types/number.md"
           - "css_types/overflow.md"
+          - "css_types/position.md"
           - "css_types/percentage.md"
           - "css_types/scalar.md"
           - "css_types/text_align.md"
@@ -122,6 +123,7 @@ nav:
           - "styles/outline.md"
           - "styles/overflow.md"
           - "styles/padding.md"
+          - "styles/position.md"
           - Scrollbar colors:
               - "styles/scrollbar_colors/index.md"
               - "styles/scrollbar_colors/scrollbar_background.md"

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "textual"
-version = "0.86.3"
+version = "0.87.0"
 homepage = "https://github.com/Textualize/textual"
 repository = "https://github.com/Textualize/textual"
 documentation = "https://textual.textualize.io/"
@@ -22,6 +22,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Typing :: Typed",
 ]
 include = [

src/textual/_arrange.py

@@ -109,6 +109,8 @@ def arrange(
                     layout_placements, placement_offset
                 )
 
+            WidgetPlacement.apply_absolute(layout_placements)
+
             placements.extend(layout_placements)
 
     return DockArrangeResult(placements, set(display_widgets), scroll_spacing)
@@ -186,6 +188,7 @@ def _arrange_dock_widgets(
                 dock_widget,
                 top_z,
                 True,
+                False,
             )
         )
 
@@ -238,7 +241,7 @@ def _arrange_split_widgets(
 
         append_placement(
             _WidgetPlacement(
-                split_region, null_offset, null_spacing, split_widget, 1, True
+                split_region, null_offset, null_spacing, split_widget, 1, True, False
             )
         )
 

src/textual/_compositor.py

@@ -649,6 +649,7 @@ def add_widget(
                         z,
                         fixed,
                         overlay,
+                        absolute,
                     ) in reversed(placements):
                         layer_index = get_layer_index(sub_widget.layer, 0)
                         # Combine regions with children to calculate the "virtual size"

src/textual/css/_help_text.py

@@ -14,6 +14,7 @@
     VALID_BORDER,
     VALID_KEYLINE,
     VALID_LAYOUT,
+    VALID_POSITION,
     VALID_STYLE_FLAGS,
     VALID_TEXT_ALIGN,
 )
@@ -770,6 +771,23 @@ def offset_single_axis_help_text(property_name: str) -> HelpText:
     )
 
 
+def position_help_text(property_name: str) -> HelpText:
+    """Help text to show when the user supplies the wrong value for position.
+
+    Args:
+        property_name: The name of the property.
+
+    Returns:
+        Renderable for displaying the help text for this property.
+    """
+    return HelpText(
+        summary=f"Invalid value for [i]{property_name}[/]",
+        bullets=[
+            Bullet(f"Valid values are {friendly_list(VALID_POSITION)}"),
+        ],
+    )
+
+
 def style_flags_property_help_text(
     property_name: str, value: str, context: StylingContext
 ) -> HelpText: