From 86a6fcc18dcce2f85abbe052d456a60207fd3ad5 Mon Sep 17 00:00:00 2001
From: Darren Burns <darrenb900@gmail.com>
Date: Wed, 25 Sep 2024 11:42:14 +0100
Subject: [PATCH] Counter example

---
 docs/examples/guide/widgets/counter01.py |  1 +
 docs/examples/guide/widgets/counter02.py |  1 +
 docs/guide/widgets.md                    | 31 +++++++++++++++++++-----
 3 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/docs/examples/guide/widgets/counter01.py b/docs/examples/guide/widgets/counter01.py
index e6451f0e93..15bbf8b10f 100644
--- a/docs/examples/guide/widgets/counter01.py
+++ b/docs/examples/guide/widgets/counter01.py
@@ -16,6 +16,7 @@ class CounterApp(App[None]):
     CSS_PATH = "counter.tcss"
 
     def compose(self) -> ComposeResult:
+        yield Counter()
         yield Counter()
         yield Counter()
         yield Footer()
diff --git a/docs/examples/guide/widgets/counter02.py b/docs/examples/guide/widgets/counter02.py
index 6794ab60cf..879c87b752 100644
--- a/docs/examples/guide/widgets/counter02.py
+++ b/docs/examples/guide/widgets/counter02.py
@@ -24,6 +24,7 @@ class CounterApp(App[None]):
     CSS_PATH = "counter.tcss"
 
     def compose(self) -> ComposeResult:
+        yield Counter()
         yield Counter()
         yield Counter()
         yield Footer()
diff --git a/docs/guide/widgets.md b/docs/guide/widgets.md
index 8a77d1a6b3..ac09f1f4da 100644
--- a/docs/guide/widgets.md
+++ b/docs/guide/widgets.md
@@ -197,8 +197,9 @@ 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:
+To demonstrate, let's design a simple interactive counter widget which can be incremented and decremented using the keyboard.
+
+In the following example, we define a simple `Counter` widget with `can_focus=True`, and some CSS to make it stand out when focused.
 
 === "counter01.py"
 
@@ -208,7 +209,7 @@ We'll set `can_focus=True` to allow the widget to receive focus, and give it som
 
 === "counter.tcss"
 
-    ```css title="counter.tcss"
+    ```css title="counter.tcss" hl_lines="6-11"
     --8<-- "docs/examples/guide/widgets/counter.tcss"
     ```
 
@@ -217,12 +218,30 @@ We'll set `can_focus=True` to allow the widget to receive focus, and give it som
     ```{.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.
+Notice that Textual automatically focused the first widget, and that pressing ++tab++ and ++shift+tab++ will move focus between widgets.
+
+Now that our counter is focusable, let's add some keybindings for incrementing and decrementing the counter.
+To do this, we add a `BINDINGS` class variable to `Counter`, with bindings for incrementing and decrementing the counter using ++up++ and ++down++ respectively.
+These new bindings are linked to the `change_count` action, which updates the `count` reactive attribute.
+
+=== "counter02.py"
+
+    ```python title="counter02.py" hl_lines="9-12 19-20"
+    --8<-- "docs/examples/guide/widgets/counter02.py"
+    ```
+
+=== "counter.tcss"
 
-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`.
+    ```css title="counter.tcss"
+    --8<-- "docs/examples/guide/widgets/counter.tcss"
+    ```
 
+=== "Output"
+
+    ```{.textual path="docs/examples/guide/widgets/counter02.py"}
+    ```
 
+With our bindings in place, we can now change the count of the _currently focused counter_ using ++up++ and ++down++.
 
 
 ## Rich renderables