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 <[email protected]>

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(

doc/flame/examples/lib/value_route.dart

@@ -54,22 +54,21 @@ 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,
             );
           },
           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);

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: