Merge pull request #629 from Textualize/docs

Document CSS Styles

docs/events/mount.md

@@ -2,6 +2,8 @@
 
 The `Mount` event is sent to a widget and Application when it is first mounted.
 
+The mount event is typically used to set the initial state of a widget or to add new children widgets.
+
 - [ ] Bubbles
 
 ## Parameters

docs/events/resize.md

@@ -17,3 +17,7 @@ The `Resize` event is sent to a widget when its size changes and when it is firs
 `event.container_size`
 
 : The size of the widget's container.
+
+## Code
+
+::: textual.events.Mount

docs/examples/light_dark.py

@@ -17,4 +17,5 @@ def compose(self):
 
     def handle_pressed(self, event):
         self.dark = not self.dark
+        self.bell()
         event.button.label = "Lights ON" if self.dark else "Lights OFF"

docs/examples/styles/README.md

@@ -0,0 +1,9 @@
+These are the examples from the documentation, used to generate screenshots.
+
+You can run them with the textual CLI.
+
+For example:
+
+```
+textual run text_style.py
+```

docs/examples/styles/background.py

@@ -0,0 +1,29 @@
+from textual.app import App
+from textual.widgets import Static
+
+
+class BackgroundApp(App):
+    CSS = """
+    Static {
+        height: 1fr;
+        content-align: center middle;
+        color: white;
+    }    
+    #static1 {
+        background: red;
+    }
+    #static2 {
+        background: rgb(0, 255, 0);
+    }
+    #static3 {
+        background: hsl(240, 100%, 50%);
+    }
+    """
+
+    def compose(self):
+        yield Static("Widget 1", id="static1")
+        yield Static("Widget 2", id="static2")
+        yield Static("Widget 3", id="static3")
+
+
+app = BackgroundApp()

docs/examples/styles/border.py

@@ -0,0 +1,40 @@
+from textual.app import App
+from textual.widgets import Static
+
+
+class BorderApp(App):
+    CSS = """
+    Screen {
+        background: white;
+    }
+    Screen > Static {
+        height: 5;
+        content-align: center middle;
+        color: white;
+        margin: 1;
+        box-sizing: border-box;
+    }    
+    #static1 {
+        background: red 20%;
+        color: red;
+        border: solid red;
+    }
+    #static2 {
+        background: green 20%;
+        color: green;
+        border: dashed green;
+    }
+    #static3 {
+        background: blue 20%;
+        color: blue;
+        border: tall blue;
+    }
+    """
+
+    def compose(self):
+        yield Static("My border is solid red", id="static1")
+        yield Static("My border is dashed green", id="static2")
+        yield Static("My border is tall blue", id="static3")
+
+
+app = BorderApp()

docs/examples/styles/box_sizing.py

@@ -0,0 +1,32 @@
+from textual.app import App
+from textual.widgets import Static
+
+
+class BoxSizingApp(App):
+    CSS = """
+    Screen {
+        background: white;
+        color: black;
+    }
+    Static {
+        background: blue 20%;
+        height: 5;
+        margin: 2;
+        padding: 1;
+        border: wide black;
+    }
+    #static1 {       
+        box-sizing: border-box;
+    }
+    #static2 {        
+        box-sizing: content-box;
+    }
+
+    """
+
+    def compose(self):
+        yield Static("I'm using border-box!", id="static1")
+        yield Static("I'm using content-box!", id="static2")
+
+
+app = BoxSizingApp()

docs/examples/styles/color.py

@@ -0,0 +1,28 @@
+from textual.app import App
+from textual.widgets import Static
+
+
+class ColorApp(App):
+    CSS = """
+    Static {
+        height:1fr;
+        content-align: center middle;
+    }    
+    #static1 {
+        color: red;
+    }
+    #static2 {
+        color: rgb(0, 255, 0);
+    }
+    #static3 {
+        color: hsl(240, 100%, 50%)
+    }
+    """
+
+    def compose(self):
+        yield Static("I'm red!", id="static1")
+        yield Static("I'm rgb(0, 255, 0)!", id="static2")
+        yield Static("I'm hsl(240, 100%, 50%)!", id="static3")
+
+
+app = ColorApp()

docs/examples/styles/display.py

@@ -0,0 +1,27 @@
+from textual.app import App
+from textual.widgets import Static
+
+
+class DisplayApp(App):
+    CSS = """    
+    Screen {
+        background: green;
+    }
+    Static {             
+        height: 5;        
+        background: white;        
+        color: blue;   
+        border: heavy blue;     
+    }
+    Static.remove {
+        display: none;
+    }
+    """
+
+    def compose(self):
+        yield Static("Widget 1")
+        yield Static("Widget 2", classes="remove")
+        yield Static("Widget 3")
+
+
+app = DisplayApp()

docs/examples/styles/height.py

@@ -0,0 +1,18 @@
+from textual.app import App
+from textual.widget import Widget
+
+
+class HeightApp(App):
+    CSS = """    
+    Screen > Widget {     
+        background: green;
+        height: 50%;
+        color: white;
+    }
+    """
+
+    def compose(self):
+        yield Widget()
+
+
+app = HeightApp()

docs/examples/styles/margin.py

@@ -0,0 +1,33 @@
+from textual.app import App
+from textual.widgets import Static
+
+TEXT = """I must not fear.
+Fear is the mind-killer.
+Fear is the little-death that brings total obliteration.
+I will face my fear.
+I will permit it to pass over me and through me.
+And when it has gone past, I will turn the inner eye to see its path.
+Where the fear has gone there will be nothing. Only I will remain."""
+
+
+class MarginApp(App):
+    CSS = """
+
+    Screen {
+        background: white;
+        color: black;
+    }
+   
+    Static {
+        margin: 4 8;  
+        background: blue 20%;  
+        border: blue wide;
+    }    
+    
+    """
+
+    def compose(self):
+        yield Static(TEXT)
+
+
+app = MarginApp()

docs/examples/styles/offset.py

@@ -0,0 +1,46 @@
+from textual.app import App
+from textual.widgets import Static
+
+
+class OffsetApp(App):
+    CSS = """  
+    Screen {
+        background: white;
+        color: black;
+        layout: horizontal;
+    }
+    Static {             
+        width: 20;
+        height: 10;
+        content-align: center middle; 
+    }
+
+    .paul {
+        offset: 8 2;
+        background: red 20%;
+        border: outer red;
+        color: red;
+    }
+
+    .duncan {
+        offset: 4 10;
+        background: green 20%;
+        border: outer green;
+        color: green;
+    }
+
+    .chani {
+        offset: 0 5;
+        background: blue 20%;
+        border: outer blue;
+        color: blue;
+    }
+    """
+
+    def compose(self):
+        yield Static("Paul (offset 8 2)", classes="paul")
+        yield Static("Duncan (offset 4 10)", classes="duncan")
+        yield Static("Chani (offset 0 5)", classes="chani")
+
+
+app = OffsetApp()

docs/examples/styles/outline.py

@@ -0,0 +1,31 @@
+from textual.app import App
+from textual.widgets import Static
+
+
+TEXT = """I must not fear.
+Fear is the mind-killer.
+Fear is the little-death that brings total obliteration.
+I will face my fear.
+I will permit it to pass over me and through me.
+And when it has gone past, I will turn the inner eye to see its path.
+Where the fear has gone there will be nothing. Only I will remain."""
+
+
+class OutlineApp(App):
+    CSS = """
+    Screen {
+        background: white;
+        color: black;
+    }
+    Static {
+        margin: 4 8;
+        background: green 20%;
+        outline: wide green;
+    }
+    """
+
+    def compose(self):
+        yield Static(TEXT)
+
+
+app = OutlineApp()

docs/examples/styles/overflow.py

@@ -0,0 +1,44 @@
+from textual.app import App
+from textual.widgets import Static
+from textual.layout import Horizontal, Vertical
+
+TEXT = """I must not fear.
+Fear is the mind-killer.
+Fear is the little-death that brings total obliteration.
+I will face my fear.
+I will permit it to pass over me and through me.
+And when it has gone past, I will turn the inner eye to see its path.
+Where the fear has gone there will be nothing. Only I will remain."""
+
+
+class OverflowApp(App):
+    CSS = """
+    Screen {
+        background: $background;
+        color: black;
+    }
+   
+    Vertical {
+        width: 1fr;
+    }
+
+    Static {
+        margin: 1 2;  
+        background: blue 20%;  
+        border: blue wide;
+        height: auto;
+    }    
+
+    #right {
+        overflow-y: hidden;
+    }
+    """
+
+    def compose(self):
+        yield Horizontal(
+            Vertical(Static(TEXT), Static(TEXT), Static(TEXT), id="left"),
+            Vertical(Static(TEXT), Static(TEXT), Static(TEXT), id="right"),
+        )
+
+
+app = OverflowApp()