Improve the debugPaintPointersEnabled feature. (#5435)

We have so many render objects going on these days that showing every
box that gets an event just makes the screen blue. This limits it down
to only the ones that are actually doing something with the events.

packages/flutter/lib/src/material/slider.dart

@@ -326,6 +326,7 @@ class _RenderSlider extends RenderConstrainedBox implements SemanticActionHandle
 
   @override
   void handleEvent(PointerEvent event, BoxHitTestEntry entry) {
+    assert(debugHandleEvent(event, entry));
     if (event is PointerDownEvent && isInteractive)
       _drag.addPointer(event);
   }

packages/flutter/lib/src/material/switch.dart

@@ -286,6 +286,7 @@ class _RenderSwitch extends RenderToggleable {
 
   @override
   void handleEvent(PointerEvent event, BoxHitTestEntry entry) {
+    assert(debugHandleEvent(event, entry));
     if (event is PointerDownEvent && onChanged != null)
       _drag.addPointer(event);
     super.handleEvent(event, entry);

packages/flutter/lib/src/material/toggleable.dart

@@ -242,6 +242,7 @@ abstract class RenderToggleable extends RenderConstrainedBox implements Semantic
 
   @override
   void handleEvent(PointerEvent event, BoxHitTestEntry entry) {
+    assert(debugHandleEvent(event, entry));
     if (event is PointerDownEvent && isInteractive)
       _tap.addPointer(event);
   }

packages/flutter/lib/src/rendering/box.dart

@@ -1255,16 +1255,46 @@ abstract class RenderBox extends RenderObject {
   @override
   Rect get paintBounds => Point.origin & size;
 
-  int _debugActivePointers = 0;
-
   /// Override this method to handle pointer events that hit this render object.
   ///
   /// For [RenderBox] objects, the `entry` argument is a [BoxHitTestEntry]. From this
   /// object you can determine the [PointerDownEvent]'s position in local coordinates.
   /// (This is useful because [PointerEvent.position] is in global coordinates.)
+  ///
+  /// If you override this, consider calling [debugHandleEvent] as follows, so
+  /// that you can support [debugPaintPointersEnabled]:
+  ///
+  /// ```dart
+  /// @override
+  /// void handleEvent(PointerEvent event, HitTestEntry entry) {
+  ///   assert(debugHandleEvent(event, entry));
+  ///   // ... handle the event ...
+  /// }
+  /// ```
+  // TODO(ianh): Fix the type of the argument here once https://github.com/dart-lang/sdk/issues/25232 is fixed
   @override
   void handleEvent(PointerEvent event, HitTestEntry entry) {
     super.handleEvent(event, entry);
+  }
+
+  int _debugActivePointers = 0;
+
+  /// Implements the [debugPaintPointersEnabled] debugging feature.
+  ///
+  /// [RenderBox] subclasses that implement [handleEvent] should call
+  /// [debugHandleEvent] from their [handleEvent] method, as follows:
+  ///
+  /// ```dart
+  /// @override
+  /// void handleEvent(PointerEvent event, HitTestEntry entry) {
+  ///   assert(debugHandleEvent(event, entry));
+  ///   // ... handle the event ...
+  /// }
+  /// ```
+  ///
+  /// If you call this for a [PointerDownEvent], make sure you also call it for
+  /// the corresponding [PointerUpEvent] or [PointerCancelEvent].
+  bool debugHandleEvent(PointerEvent event, HitTestEntry entry) {
     assert(() {
       if (debugPaintPointersEnabled) {
         if (event is PointerDownEvent) {
@@ -1276,6 +1306,7 @@ abstract class RenderBox extends RenderObject {
       }
       return true;
     });
+    return true;
   }
 
   @override
@@ -1338,9 +1369,13 @@ abstract class RenderBox extends RenderObject {
     });
   }
 
-  /// In debug mode, paints a rectangle if this render box has received more pointer downs than pointer up events.
+  /// In debug mode, paints a rectangle if this render box has counted more
+  /// pointer downs than pointer up events.
   ///
   /// Called for every [RenderBox] when [debugPaintPointersEnabled] is true.
+  ///
+  /// By default, events are not counted. For details on how to ensure that
+  /// events are counted for your class, see [debugHandleEvent].
   @protected
   void debugPaintPointers(PaintingContext context, Offset offset) {
     assert(() {

packages/flutter/lib/src/rendering/debug.dart

@@ -42,10 +42,15 @@ bool debugPaintLayerBordersEnabled = false;
 /// The color to use when painting Layer borders.
 Color debugPaintLayerBordersColor = const Color(0xFFFF9800);
 
-/// Causes RenderBox objects to flash while they are being tapped.
-bool debugPaintPointersEnabled = false;
+/// Causes objects like [RenderPointerListener] to flash while they are being
+/// tapped. This can be useful to see how large the hit box is, e.g. when
+/// debugging buttons that are harder to hit than expected.
+///
+/// For details on how to support this in your [RenderBox] subclass, see
+/// [RenderBox.debugHandleEvent].
+bool debugPaintPointersEnabled = true;
 
-/// The color to use when reporting pointers.
+/// The color to use when reporting pointers for [debugPaintPointersEnabled].
 int debugPaintPointersColorValue = 0x00BBBB;
 
 /// Overlay a rotating set of colors when repainting layers in checked mode.

packages/flutter/lib/src/rendering/editable_line.dart

@@ -209,6 +209,7 @@ class RenderEditableLine extends RenderBox {
 
   @override
   void handleEvent(PointerEvent event, BoxHitTestEntry entry) {
+    assert(debugHandleEvent(event, entry));
     if (event is PointerDownEvent && onSelectionChanged != null) {
       _tap.addPointer(event);
       _longPress.addPointer(event);

packages/flutter/lib/src/rendering/paragraph.dart

@@ -132,6 +132,7 @@ class RenderParagraph extends RenderBox {
 
   @override
   void handleEvent(PointerEvent event, BoxHitTestEntry entry) {
+    assert(debugHandleEvent(event, entry));
     if (event is! PointerDownEvent)
       return;
     _layoutText(minWidth: constraints.minWidth, maxWidth: constraints.maxWidth);

packages/flutter/lib/src/rendering/proxy_box.dart

@@ -1771,6 +1771,7 @@ class RenderPointerListener extends RenderProxyBoxWithHitTestBehavior {
 
   @override
   void handleEvent(PointerEvent event, HitTestEntry entry) {
+    assert(debugHandleEvent(event, entry));
     if (onPointerDown != null && event is PointerDownEvent)
       return onPointerDown(event);
     if (onPointerMove != null && event is PointerMoveEvent)