From 187c09fabe476442a4f9f1a072ec4851ceb8f1f7 Mon Sep 17 00:00:00 2001
From: Lukas Klingsbo <me@lukas.fyi>
Date: Fri, 3 May 2024 12:40:16 +0200
Subject: [PATCH] docs: Add background to `ValueRoute` example that captures
 events (#3145)

Fixes #3143

In the future we should probably add another boolean that controls
whether the events should be able to pass through the route or not,
independent on whether the route below is rendered or not.

---------

Co-authored-by: Renan <6718144+renancaraujo@users.noreply.github.com>
---
 doc/flame/examples/lib/router.dart      |  1 +
 doc/flame/examples/lib/value_route.dart | 15 +++++++++++----
 doc/flame/router.md                     |  4 +++-
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/doc/flame/examples/lib/router.dart b/doc/flame/examples/lib/router.dart
index 80119807c4f..78e8de7d403 100644
--- a/doc/flame/examples/lib/router.dart
+++ b/doc/flame/examples/lib/router.dart
@@ -111,6 +111,7 @@ class RoundedButton extends PositionComponent with TapCallbacks {
     required this.action,
     required Color color,
     required Color borderColor,
+    super.position,
     super.anchor = Anchor.center,
   }) : _textDrawable = TextPaint(
           style: const TextStyle(
diff --git a/doc/flame/examples/lib/value_route.dart b/doc/flame/examples/lib/value_route.dart
index 9a0dbd3d50b..cd60ea74327 100644
--- a/doc/flame/examples/lib/value_route.dart
+++ b/doc/flame/examples/lib/value_route.dart
@@ -54,14 +54,13 @@ class RateRoute extends ValueRoute<int>
     final size = Vector2(250, 130);
     const radius = 18.0;
     final starGap = (size.x - 5 * 2 * radius) / 6;
-    return RectangleComponent(
+    return DialogBackground(
       position: game.size / 2,
       size: size,
-      anchor: Anchor.center,
-      paint: Paint()..color = const Color(0xee858585),
       children: [
         RoundedButton(
           text: 'Ok',
+          position: position = Vector2(size.x / 2, 100),
           action: () {
             completeWith(
               descendants().where((c) => c is Star && c.active).length,
@@ -69,7 +68,7 @@ class RateRoute extends ValueRoute<int>
           },
           color: const Color(0xFFFFFFFF),
           borderColor: const Color(0xFF000000),
-        )..position = Vector2(size.x / 2, 100),
+        ),
         for (var i = 0; i < 5; i++)
           Star(
             value: i + 1,
@@ -81,6 +80,14 @@ class RateRoute extends ValueRoute<int>
   }
 }
 
+class DialogBackground extends RectangleComponent with TapCallbacks {
+  DialogBackground({super.position, super.size, super.children})
+      : super(
+          anchor: Anchor.center,
+          paint: Paint()..color = const Color(0xee858585),
+        );
+}
+
 class Star extends PositionComponent with TapCallbacks {
   Star({required this.value, required this.radius, super.position})
       : super(size: Vector2.all(2 * radius), anchor: Anchor.center);
diff --git a/doc/flame/router.md b/doc/flame/router.md
index e4a132fa2cd..626bdc9f1bb 100644
--- a/doc/flame/router.md
+++ b/doc/flame/router.md
@@ -28,7 +28,9 @@ Each page in the router can be either transparent or opaque. If a page is opaque
 below it in the stack are not rendered and do not receive pointer events (such as taps or drags).
 On the contrary, if a page is transparent, then the page below it will be rendered and receive
 events normally. Such transparent pages are useful for implementing modal dialogs, inventory or
-dialogue UIs, etc.
+dialogue UIs, etc. If you want your route to be visually transparent but for the routes below it
+to not receive events, make sure to add a background component to your route that captures the
+events by using one of the [event capturing mixins](inputs/inputs.md).
 
 Usage example: