More docs

Author: darrenburns

docs/examples/guide/widgets/counter01.py

@@ -0,0 +1,26 @@
+from textual.app import App, ComposeResult
+from textual.reactive import reactive
+from textual.widgets import Footer, Static
+
+
+class Counter(Static, can_focus=True):
+    """A counter that can be incremented and decremented by pressing keys."""
+
+    count = reactive(0)
+
+    def render(self) -> str:
+        return f"Count: {self.count}"
+
+
+class CounterApp(App[None]):
+    CSS_PATH = "counter.tcss"
+
+    def compose(self) -> ComposeResult:
+        yield Counter()
+        yield Counter()
+        yield Footer()
+
+
+if __name__ == "__main__":
+    app = CounterApp()
+    app.run()

docs/examples/guide/widgets/counter.py renamed to docs/examples/guide/widgets/counter02.py

@@ -1,5 +1,4 @@
 from textual.app import App, ComposeResult
-from textual.binding import Binding
 from textual.reactive import reactive
 from textual.widgets import Footer, Static
 
@@ -8,16 +7,16 @@ class Counter(Static, can_focus=True):
     """A counter that can be incremented and decremented by pressing keys."""
 
     BINDINGS = [
-        Binding("up,k", "change_count(1)", "Increment"),
-        Binding("down,j", "change_count(-1)", "Decrement"),
+        ("up,k", "change_count(1)", "Increment"),
+        ("down,j", "change_count(-1)", "Decrement"),
     ]
 
     count = reactive(0)
 
     def render(self) -> str:
         return f"Count: {self.count}"
 
-    def action_change_count(self, amount: int) -> None:
+    def action_change_count(self, amount: int):
         self.count += amount
 
 

docs/guide/widgets.md

@@ -51,19 +51,6 @@ The addition of the CSS has completely transformed our custom widget.
 ```{.textual path="docs/examples/guide/widgets/hello02.py"}
 ```
 
-### Responding to key presses
-
-Widgets can have a list of associated key [bindings](../guide/input.md#bindings),
-which enable a it to call [actions](../guide/actions.md) in response to key presses.
-
-A widget's bindings will only be checked if it or one of its descendants has focus.
-
-Let's look at Textual's builtin [Button](../widgets/button.md) widget to see an example of how widget bindings work.
-The `Button` widget has a single binding for the `enter` key.
-When a button is focused, and the user presses ++enter++, the `action_press` method inside `Button` is called.
-
-
-
 ## Static widget
 
 While you can extend the Widget class, a subclass will typically be a better starting point. The [Static][textual.widgets.Static] class is a widget subclass which caches the result of render, and provides an [update()][textual.widgets.Static.update] method to update the content area.
@@ -203,6 +190,41 @@ If the supplied text is too long to fit within the widget, it will be cropped (a
 There are a number of styles that influence how titles are displayed (color and alignment).
 See the [style reference](../styles/index.md) for details.
 
+## Interacting with widgets
+
+Widgets can have a list of associated key [bindings](../guide/input.md#bindings),
+which let them call [actions](../guide/actions.md) in response to key presses.
+
+A widget is only be able to handle key presses if it or one of its descendants has [focus](./guide/input.md#input-focus).
+
+Let's design a simple interactive `Counter` widget.
+We'll set `can_focus=True` to allow the widget to receive focus, and give it some simple to highlight it when it has focus:
+
+=== "counter01.py"
+
+    ```python title="counter01.py" hl_lines="6"
+    --8<-- "docs/examples/guide/widgets/counter01.py"
+    ```
+
+=== "counter.tcss"
+
+    ```css title="counter.tcss"
+    --8<-- "docs/examples/guide/widgets/counter.tcss"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/guide/widgets/counter01.py"}
+    ```
+
+Textual will automatically focus the first counter, and you'll notice that it's been highlighted with a blue background thanks to the CSS we applied using the `:focus` pseudo-selector! ++tab++ and ++shift+tab++ moves focus between the two counters.
+
+Now that we have a focusable widget, let's add some key bindings to it for incrementing and decrementing the counter.
+To do this, we'll add a `BINDINGS` class variable to the `Counter`.
+
+
+
+
 ## Rich renderables
 
 In previous examples we've set strings as content for Widgets. You can also use special objects called [renderables](https://rich.readthedocs.io/en/latest/protocol.html) for advanced visuals. You can use any renderable defined in [Rich](https://github.com/Textualize/rich) or third party libraries.