Add examples and troubleshooting comment for `ClipRRect` (#101907)

examples/api/lib/widgets/basic/clip_rrect.0.dart

+// 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.
+
+// Flutter code sample for ClipRRect
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const ClipRRectApp());
+
+class ClipRRectApp extends StatelessWidget {
+  const ClipRRectApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        appBar: AppBar(title: const Text('ClipRRect Sample')),
+        body: const ClipRRectExample(),
+      ),
+    );
+  }
+}
+
+class ClipRRectExample extends StatelessWidget {
+  const ClipRRectExample({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    const TextStyle style = TextStyle(color: Colors.white);
+
+    return Center(
+      child: Column(
+        mainAxisAlignment: MainAxisAlignment.spaceEvenly,
+        children: <Widget>[
+          Container(
+            alignment: Alignment.center,
+            constraints: const BoxConstraints(
+              maxWidth: 300,
+              maxHeight: 100,
+            ),
+            color: Colors.blue,
+            child: const Text('No ClipRRect', style: style),
+          ),
+          ClipRRect(
+            borderRadius: BorderRadius.circular(30.0),
+            child: Container(
+              alignment: Alignment.center,
+              constraints: const BoxConstraints(
+                maxWidth: 300,
+                maxHeight: 100,
+              ),
+              color: Colors.green,
+              child: const Text('ClipRRect', style: style),
+            ),
+          ),
+          ClipRRect(
+            borderRadius: const BorderRadius.only(
+              topLeft: Radius.circular(10.0),
+              topRight: Radius.circular(20.0),
+              bottomRight: Radius.circular(30.0),
+              bottomLeft: Radius.circular(40.0),
+            ),
+            child: Container(
+              alignment: Alignment.center,
+              constraints: const BoxConstraints(
+                maxWidth: 300,
+                maxHeight: 100,
+              ),
+              color: Colors.purple,
+              child: const Text('ClipRRect', style: style),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}

examples/api/lib/widgets/basic/clip_rrect.1.dart

+// 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.
+
+// Flutter code sample for ClipRRect
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const ClipRRectApp());
+
+class ClipRRectApp extends StatelessWidget {
+  const ClipRRectApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        appBar: AppBar(title: const Text('ClipRRect Sample')),
+        body: const ClipRRectExample(),
+      ),
+    );
+  }
+}
+
+class ClipRRectExample extends StatelessWidget {
+  const ClipRRectExample({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      padding: const EdgeInsets.all(40.0),
+      constraints: const BoxConstraints.expand(),
+      // Add a FittedBox to make ClipRRect sized accordingly to the image it contains
+      child: FittedBox(
+        child: ClipRRect(
+          borderRadius: BorderRadius.circular(40.0),
+          child: const _FakedImage(),
+        ),
+      ),
+    );
+  }
+}
+
+// A widget exposing the FlutterLogo as a 400x400 image.
+//
+// It can be replaced by a NetworkImage if internet connection is available, e.g. :
+// const Image(
+//   image: NetworkImage(
+//       'https://flutter.github.io/assets-for-api-docs/assets/widgets/owl.jpg'),
+// );
+class _FakedImage extends StatelessWidget {
+  const _FakedImage({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      // Set constraints as if it were a 400x400 image
+      constraints: BoxConstraints.tight(const Size(400, 400)),
+      color: Colors.blueGrey,
+      child: const FlutterLogo(),
+    );
+  }
+}

examples/api/test/widgets/basic/clip_rrect.0_test.dart

+// 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/basic/clip_rrect.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('ClipRRect adds rounded corners to containers', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.ClipRRectApp(),
+    );
+
+    final Finder clipRRectFinder = find.byType(ClipRRect);
+    final Finder containerFinder = find.byType(Container);
+    expect(clipRRectFinder, findsNWidgets(2));
+    expect(containerFinder, findsNWidgets(3));
+
+    final Rect firstClipRect = tester.getRect(clipRRectFinder.first);
+    final Rect secondContainerRect = tester.getRect(containerFinder.at(1));
+    expect(firstClipRect, equals(secondContainerRect));
+
+    final Rect secondClipRect = tester.getRect(clipRRectFinder.at(1));
+    final Rect thirdContainerRect = tester.getRect(containerFinder.at(2));
+    expect(secondClipRect, equals(thirdContainerRect));
+  });
+}

examples/api/test/widgets/basic/clip_rrect.1_test.dart

+// 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/basic/clip_rrect.1.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('ClipRRect fits to its child', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.ClipRRectApp(),
+    );
+
+    final Finder clipRRectFinder = find.byType(ClipRRect);
+    final Finder logoFinder = find.byType(FlutterLogo);
+    expect(clipRRectFinder, findsOneWidget);
+    expect(logoFinder, findsOneWidget);
+
+    final Rect clipRect = tester.getRect(clipRRectFinder);
+    final Rect containerRect = tester.getRect(logoFinder);
+    expect(clipRect, equals(containerRect));
+  });
+}

packages/flutter/lib/src/widgets/basic.dart

@@ -705,6 +705,27 @@ class ClipRect extends SingleChildRenderObjectWidget {
 ///
 /// {@youtube 560 315 https://www.youtube.com/watch?v=eI43jkQkrvs}
 ///
+/// {@tool dartpad}
+/// This example shows various [ClipRRect]s applied to containers.
+///
+/// ** See code in examples/api/lib/widgets/basic/clip_rrect.0.dart **
+/// {@end-tool}
+///
+/// ## Troubleshooting
+///
+/// ### Why doesn't my [ClipRRect] child have rounded corners?
+///
+/// When a [ClipRRect] is bigger than the child it contains, its rounded corners
+/// could be drawn in unexpected positions. Make sure that [ClipRRect] and its child
+/// have the same bounds (by shrinking the [ClipRRect] with a [FittedBox] or by
+/// growing the child).
+///
+/// {@tool dartpad}
+/// This example shows a [ClipRRect] that adds round corners to an image.
+///
+/// ** See code in examples/api/lib/widgets/basic/clip_rrect.1.dart **
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [CustomClipper], for information about creating custom clips.