Added example for Magnifier and TextMagnifier (#110218)

Author: antholeole

examples/api/lib/widgets/magnifier/magnifier.0.dart

@@ -0,0 +1,62 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatefulWidget {
+  const MyApp({super.key});
+  static const Size loupeSize = Size(200, 200);
+
+  @override
+  State<MyApp> createState() => _MyAppState();
+}
+
+class _MyAppState extends State<MyApp> {
+  Offset dragGesturePositon = Offset.zero;
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        body: Center(
+          child: Column(
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: <Widget>[
+              const Text('Drag on the logo!'),
+              RepaintBoundary(
+                child: Stack(
+                  children: <Widget>[
+                    GestureDetector(
+                      onPanUpdate: (DragUpdateDetails details) => setState(
+                        () {
+                          dragGesturePositon = details.localPosition;
+                        },
+                      ),
+                      child: const FlutterLogo(size: 200),
+                    ),
+                    Positioned(
+                      left: dragGesturePositon.dx,
+                      top: dragGesturePositon.dy,
+                      child: const RawMagnifier(
+                        decoration: MagnifierDecoration(
+                          shape: CircleBorder(
+                            side: BorderSide(color: Colors.pink, width: 3),
+                          ),
+                        ),
+                        size: Size(100, 100),
+                        magnificationScale: 2,
+                      ),
+                    )
+                  ],
+                ),
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}

examples/api/lib/widgets/text_magnifier/text_magnifier.0.dart

@@ -0,0 +1,112 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+
+void main() => runApp(const MyApp(text: 'Hello world!'));
+
+class MyApp extends StatelessWidget {
+  const MyApp({
+    super.key,
+    this.textDirection = TextDirection.ltr,
+    required this.text,
+  });
+
+  final TextDirection textDirection;
+  final String text;
+
+  static const Size loupeSize = Size(200, 200);
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        body: Padding(
+          padding: const EdgeInsets.symmetric(horizontal: 48.0),
+          child: Center(
+            child: TextField(
+              textDirection: textDirection,
+              // Create a custom magnifier configuration that
+              // this `TextField` will use to build a magnifier with.
+              magnifierConfiguration: TextMagnifierConfiguration(
+                magnifierBuilder: (_, __, ValueNotifier<MagnifierInfo> magnifierInfo) => CustomMagnifier(
+                  magnifierInfo: magnifierInfo,
+                ),
+              ),
+              controller: TextEditingController(text: text),
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+class CustomMagnifier extends StatelessWidget {
+  const CustomMagnifier({super.key, required this.magnifierInfo});
+
+  static const Size magnifierSize = Size(200, 200);
+
+  // This magnifier will consume some text data and position itself
+  // based on the info in the magnifier.
+  final ValueNotifier<MagnifierInfo> magnifierInfo;
+
+  @override
+  Widget build(BuildContext context) {
+    // Use a value listenable builder because we want to rebuild
+    // every time the text selection info changes.
+    // `CustomMagnifier` could also be a `StatefulWidget` and call `setState`
+    // when `magnifierInfo` updates. This would be useful for more complex
+    // positioning cases.
+    return ValueListenableBuilder<MagnifierInfo>(
+        valueListenable: magnifierInfo,
+        builder: (BuildContext context,
+            MagnifierInfo currentMagnifierInfo, _) {
+          // We want to position the magnifier at the global position of the gesture.
+          Offset magnifierPosition = currentMagnifierInfo.globalGesturePosition;
+
+          // You may use the `MagnifierInfo` however you'd like:
+          // In this case, we make sure the magnifier never goes out of the current line bounds.
+          magnifierPosition = Offset(
+            clampDouble(
+              magnifierPosition.dx,
+              currentMagnifierInfo.currentLineBoundaries.left,
+              currentMagnifierInfo.currentLineBoundaries.right,
+            ),
+            clampDouble(
+              magnifierPosition.dy,
+              currentMagnifierInfo.currentLineBoundaries.top,
+              currentMagnifierInfo.currentLineBoundaries.bottom,
+            ),
+          );
+
+          // Finally, align the magnifier to the bottom center. The inital anchor is
+          // the top left, so subtract bottom center alignment.
+          magnifierPosition -= Alignment.bottomCenter.alongSize(magnifierSize);
+
+          return Positioned(
+            left: magnifierPosition.dx,
+            top: magnifierPosition.dy,
+            child: RawMagnifier(
+              magnificationScale: 2,
+              // The focal point starts at the center of the magnifier.
+              // We probably want to point below the magnifier, so
+              // offset the focal point by half the magnifier height.
+              focalPointOffset: Offset(0, magnifierSize.height / 2),
+              // Decorate it however we'd like!
+              decoration: const MagnifierDecoration(
+                shape: StarBorder(
+                  side: BorderSide(
+                    color: Colors.green,
+                    width: 2,
+                  ),
+                ),
+              ),
+              size: magnifierSize,
+            ),
+          );
+        });
+  }
+}

examples/api/test/widgets/magnifier/magnifier.0_test.dart

@@ -0,0 +1,56 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/widgets/magnifier/magnifier.0.dart'
+    as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('should update magnifier position on drag', (WidgetTester tester) async {
+    await tester.pumpWidget(const example.MyApp());
+
+    Matcher isPositionedAt(Offset at) {
+      return isA<Positioned>().having(
+        (Positioned positioned) => Offset(positioned.left!, positioned.top!),
+        'magnifier position',
+        at,
+      );
+    }
+
+    expect(
+      tester.widget(find.byType(Positioned)),
+      isPositionedAt(Offset.zero),
+    );
+
+    final Offset centerOfFlutterLogo = tester.getCenter(find.byType(Positioned));
+    final Offset topLeftOfFlutterLogo = tester.getTopLeft(find.byType(FlutterLogo));
+
+    const Offset dragDistance = Offset(10, 10);
+
+    await tester.dragFrom(centerOfFlutterLogo, dragDistance);
+    await tester.pump();
+
+    expect(
+      tester.widget(find.byType(Positioned)),
+      // Need to adjust by the topleft since the position is local.
+      isPositionedAt((centerOfFlutterLogo - topLeftOfFlutterLogo) + dragDistance),
+    );
+  });
+
+  testWidgets('should match golden', (WidgetTester tester) async {
+    await tester.pumpWidget(const example.MyApp());
+
+    final Offset centerOfFlutterLogo = tester.getCenter(find.byType(Positioned));
+    const Offset dragDistance = Offset(10, 10);
+
+    await tester.dragFrom(centerOfFlutterLogo, dragDistance);
+    await tester.pump();
+
+    await expectLater(
+      find.byType(RepaintBoundary).last,
+      matchesGoldenFile('magnifier.0_test.png'),
+    );
+  });
+}

examples/api/test/widgets/text_magnifier/text_magnifier.0_test.dart

@@ -0,0 +1,111 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter_api_samples/widgets/text_magnifier/text_magnifier.0.dart'
+    as example;
+import 'package:flutter_test/flutter_test.dart';
+
+List<TextSelectionPoint> _globalize(
+    Iterable<TextSelectionPoint> points, RenderBox box) {
+  return points.map<TextSelectionPoint>((TextSelectionPoint point) {
+    return TextSelectionPoint(
+      box.localToGlobal(point.point),
+      point.direction,
+    );
+  }).toList();
+}
+
+RenderEditable _findRenderEditable<T extends State<StatefulWidget>>(WidgetTester tester) {
+  return (tester.state(find.byType(TextField))
+          as TextSelectionGestureDetectorBuilderDelegate)
+      .editableTextKey
+      .currentState!
+      .renderEditable;
+}
+
+Offset _textOffsetToPosition<T extends State<StatefulWidget>>(WidgetTester tester, int offset) {
+  final RenderEditable renderEditable = _findRenderEditable(tester);
+
+  final List<TextSelectionPoint> endpoints = renderEditable
+      .getEndpointsForSelection(
+        TextSelection.collapsed(offset: offset),
+      )
+      .map<TextSelectionPoint>((TextSelectionPoint point) => TextSelectionPoint(
+            renderEditable.localToGlobal(point.point),
+            point.direction,
+          ))
+      .toList();
+
+  return endpoints[0].point + const Offset(0.0, -2.0);
+}
+
+void main() {
+  const Duration durationBetweenActons = Duration(milliseconds: 20);
+  const String defaultText = 'I am a magnifier, fear me!';
+
+  Future<void> showMagnifier(WidgetTester tester, String characterToTapOn) async {
+    final Offset tapOffset = _textOffsetToPosition(tester, defaultText.indexOf(characterToTapOn));
+
+    // Double tap 'Magnifier' word to show the selection handles.
+    final TestGesture testGesture = await tester.startGesture(tapOffset);
+    await tester.pump(durationBetweenActons);
+    await testGesture.up();
+    await tester.pump(durationBetweenActons);
+    await testGesture.down(tapOffset);
+    await tester.pump(durationBetweenActons);
+    await testGesture.up();
+    await tester.pumpAndSettle();
+
+    final TextSelection selection = tester
+        .firstWidget<TextField>(find.byType(TextField))
+        .controller!
+        .selection;
+
+    final RenderEditable renderEditable = _findRenderEditable(tester);
+    final List<TextSelectionPoint> endpoints = _globalize(
+      renderEditable.getEndpointsForSelection(selection),
+      renderEditable,
+    );
+
+    final Offset handlePos = endpoints.last.point + const Offset(10.0, 10.0);
+
+    final TestGesture gesture = await tester.startGesture(handlePos);
+
+    await gesture.moveTo(
+      _textOffsetToPosition(
+        tester,
+        defaultText.length - 2,
+      ),
+    );
+    await tester.pump();
+  }
+
+  testWidgets('should show custom magnifier on drag', (WidgetTester tester) async {
+    await tester.pumpWidget(const example.MyApp(text: defaultText));
+
+    await showMagnifier(tester, 'e');
+    expect(find.byType(example.CustomMagnifier), findsOneWidget);
+
+    await expectLater(
+      find.byType(example.MyApp),
+      matchesGoldenFile('text_magnifier.0_test.png'),
+    );
+  }, variant: const TargetPlatformVariant(<TargetPlatform>{ TargetPlatform.iOS, TargetPlatform.android }));
+
+
+  for (final TextDirection textDirection in TextDirection.values) {
+    testWidgets('should show custom magnifier in $textDirection', (WidgetTester tester) async {
+      final String text = textDirection == TextDirection.rtl ? 'أثارت زر' : defaultText;
+      final String textToTapOn = textDirection == TextDirection.rtl ? 'ت' : 'e';
+
+      await tester.pumpWidget(example.MyApp(textDirection: textDirection, text: text));
+
+      await showMagnifier(tester, textToTapOn);
+
+      expect(find.byType(example.CustomMagnifier), findsOneWidget);
+    });
+  }
+}