Add opacity docs

docs/examples/styles/opacity.css

@@ -0,0 +1,30 @@
+#zero-opacity {
+    opacity: 0%;
+}
+
+#quarter-opacity {
+    opacity: 25%;
+}
+
+#half-opacity {
+    opacity: 50%;
+}
+
+#three-quarter-opacity {
+    opacity: 75%;
+}
+
+#full-opacity {
+    opacity: 100%;
+}
+
+Screen {
+    background: antiquewhite;
+}
+
+Static {
+    height: 1fr;
+    background: lightseagreen;
+    content-align: center middle;
+    text-style: bold;
+}

docs/examples/styles/opacity.py

@@ -0,0 +1,14 @@
+from textual.app import App
+from textual.widgets import Static
+
+
+class OpacityApp(App):
+    def compose(self):
+        yield Static("opacity: 0%", id="zero-opacity")
+        yield Static("opacity: 25%", id="quarter-opacity")
+        yield Static("opacity: 50%", id="half-opacity")
+        yield Static("opacity: 75%", id="three-quarter-opacity")
+        yield Static("opacity: 100%", id="full-opacity")
+
+
+app = OpacityApp(css_path="opacity.css")

docs/styles/opacity.md

@@ -0,0 +1,54 @@
+# Opacity
+
+The `opacity` property can be used to make a widget partially or fully transparent.
+
+
+## Syntax
+
+```
+opacity: <FRACTIONAL>;
+```
+
+### Values
+
+As a fractional property, `opacity` can be set to either a float (between 0 and 1),
+or a percentage, e.g. `45%`.
+Float values will be clamped between 0 and 1.
+Percentage values will be clamped between 0% and 100%.
+
+## Example
+
+This example shows, from top to bottom, increase opacity values.
+
+=== "opacity.py"
+
+    ```python
+    --8<-- "docs/examples/styles/opacity.py"
+    ```
+
+=== "opacity.css"
+
+    ```scss
+    --8<-- "docs/examples/styles/opacity.css"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/opacity.py"}
+    ```
+
+## CSS
+
+```sass
+/* Set the text to be "half-faded" against the background of the widget */
+Widget {
+    opacity: 50%;
+}
+```
+
+## Python
+
+```python
+# Set the text to be "half-faded" against the background of the widget
+widget.styles.opacity = "50%"
+```

docs/styles/text_opacity.md

@@ -1,6 +1,6 @@
 # Text-opacity
 
-The `text-opacity` blends the color of the text in a widget with the color of the background.
+The `text-opacity` blends the color of the content of a widget with the color of the background.
 
 ## Syntax
 

mkdocs.yml

@@ -51,6 +51,7 @@ nav:
     - "styles/min_height.md"
     - "styles/min_width.md"
     - "styles/offset.md"
+    - "styles/opacity.md"
     - "styles/outline.md"
     - "styles/overflow.md"
     - "styles/padding.md"
@@ -59,6 +60,7 @@ nav:
     - "styles/scrollbar_size.md"
     - "styles/text_align.md"
     - "styles/text_style.md"
+    - "styles/text_opacity.md"
     - "styles/tint.md"
     - "styles/visibility.md"
     - "styles/width.md"

sandbox/darren/just_a_box.css

@@ -1,29 +1,8 @@
 Screen {
-    background: lightcoral;
-}
-
-#sidebar {
-  color: $text-panel;
-  background: $panel;
-  dock: left;
-  width: 30;
-  offset-x: -100%;
-  transition: offset 500ms in_out_cubic 2s;
-  layer: sidebar;
-}
-
-#sidebar.-active {
-  offset-x: 0;
+    background: darkslategrey;
 }
 
 .box1 {
-    background: orangered;
-    height: 12;
-    width: 30;
-}
-
-.box2 {
-    background: blueviolet;
-    height: 6;
-    width: 12;
+    background: darkmagenta;
+    width: auto;
 }

sandbox/darren/just_a_box.py

@@ -1,48 +1,12 @@
 from __future__ import annotations
 
-from rich.console import RenderableType
-
-from textual import events
 from textual.app import App, ComposeResult
-from textual.widget import Widget
-
-
-class Box(Widget, can_focus=True):
-    CSS = "#box {background: blue;}"
-
-    def __init__(
-        self, id: str | None = None, classes: str | None = None, *children: Widget
-    ):
-        super().__init__(*children, id=id, classes=classes)
-
-    def render(self) -> RenderableType:
-        return "Box"
+from textual.widgets import Static
 
 
 class JustABox(App):
-    def on_load(self):
-        self.bind("s", "toggle_class('#sidebar', '-active')", description="Sidebar")
-
     def compose(self) -> ComposeResult:
-        self.box = Box(classes="box1")
-        self.box.styles.opacity = "50%"
-        yield self.box
-        yield Box(classes="box2")
-        yield Widget(id="sidebar")
-
-    def key_a(self):
-        self._animate_out()
-
-    def _animate_out(self):
-        def p():
-            print("done")
-
-        self.animator.animate(
-            self.box.styles, "opacity", value=0.0, duration=2.0, on_complete=p
-        )
-
-    async def on_key(self, event: events.Key) -> None:
-        await self.dispatch_key(event)
+        yield Static("Hello, world!", classes="box1")
 
 
 if __name__ == "__main__":

src/textual/_opacity.py

@@ -6,7 +6,7 @@ from rich.style import Style
 from textual.color import Color
 
 
-def _apply_widget_opacity(
+def _apply_opacity(
     segments: Iterable[Segment],
     base_background: Color,
     opacity: float,

src/textual/_styles_cache.py

@@ -7,7 +7,7 @@ from rich.segment import Segment
 from rich.style import Style
 
 from ._border import get_box, render_row
-from ._opacity import _apply_widget_opacity
+from ._opacity import _apply_opacity
 from ._segment_tools import line_crop, line_pad, line_trim
 from ._types import Lines
 from .color import Color
@@ -243,9 +243,7 @@ class StylesCache:
             if styles.tint.a:
                 segments = Tint.process_segments(segments, styles.tint)
             if styles.opacity != 1.0:
-                segments = _apply_widget_opacity(
-                    segments, base_background, styles.opacity
-                )
+                segments = _apply_opacity(segments, base_background, styles.opacity)
             segments = list(segments)
             return segments if isinstance(segments, list) else list(segments)