CupertinoSegmentedControl: Add an interactive example (#98154)

examples/api/lib/cupertino/segmented_control/cupertino_segmented_control.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 CupertinoSegmentedControl
+
+import 'package:flutter/cupertino.dart';
+
+enum Sky { midnight, viridian, cerulean }
+
+Map<Sky, Color> skyColors = <Sky, Color> {
+  Sky.midnight: const Color(0xff191970),
+  Sky.viridian: const Color(0xff40826d),
+  Sky.cerulean: const Color(0xff007ba7),
+};
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatelessWidget {
+  const MyApp({Key? key}) : super(key: key);
+
+  static const String _title = 'CupertinoSegmentedControl Sample';
+
+  @override
+  Widget build(BuildContext context) {
+    return const CupertinoApp(
+      title: _title,
+      home: SegmentedControlSample(),
+    );
+  }
+}
+
+class SegmentedControlSample extends StatefulWidget {
+  const SegmentedControlSample({Key? key}) : super(key: key);
+
+  @override
+  State<SegmentedControlSample> createState() => _SegmentedControlSampleState();
+}
+
+class _SegmentedControlSampleState extends State<SegmentedControlSample> {
+  Sky _selectedSegment = Sky.midnight;
+
+  @override
+  Widget build(BuildContext context) {
+    return CupertinoPageScaffold(
+      backgroundColor: skyColors[_selectedSegment],
+      navigationBar: CupertinoNavigationBar(
+        // This Cupertino segmented control has the enum "Sky" as the type.
+        middle: CupertinoSegmentedControl<Sky>(
+          selectedColor: skyColors[_selectedSegment],
+          // Provide horizontal padding around the children.
+          padding: const EdgeInsets.symmetric(horizontal: 12),
+          // This represents a currently selected segmented control.
+          groupValue: _selectedSegment,
+          // Callback that sets the selected segmented control.
+          onValueChanged: (Sky value) {
+            setState(() {
+              _selectedSegment = value;
+            });
+          },
+          children: const <Sky, Widget>{
+            Sky.midnight: Padding(
+              padding: EdgeInsets.symmetric(horizontal: 20),
+              child: Text(
+                'Midnight',
+                style: TextStyle(color: CupertinoColors.white),
+              ),
+            ),
+            Sky.viridian: Padding(
+              padding: EdgeInsets.symmetric(horizontal: 20),
+              child: Text(
+                'Viridian',
+                style: TextStyle(color: CupertinoColors.white),
+              ),
+            ),
+            Sky.cerulean: Padding(
+              padding: EdgeInsets.symmetric(horizontal: 20),
+              child: Text(
+                'Cerulean',
+                style: TextStyle(color: CupertinoColors.white),
+              ),
+            ),
+          },
+        ),
+      ),
+      child: Center(
+        child: Text(
+          'Selected Segment: ${_selectedSegment.name}',
+          style: const TextStyle(color: CupertinoColors.white),
+        ),
+      ),
+    );
+  }
+}

examples/api/test/cupertino/segmented_control/cupertino_segmented_control.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_api_samples/cupertino/segmented_control/cupertino_segmented_control.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Can change a selected segmented control', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.MyApp(),
+    );
+
+    expect(find.text('Selected Segment: midnight'), findsOneWidget);
+    await tester.tap(find.text('Cerulean'));
+    await tester.pumpAndSettle();
+    expect(find.text('Selected Segment: cerulean'), findsOneWidget);
+  });
+}

packages/flutter/lib/src/cupertino/segmented_control.dart

@@ -58,6 +58,15 @@ const Duration _kFadeDuration = Duration(milliseconds: 165);
 /// arguments can be used to override the segmented control's colors from
 /// [CupertinoTheme] defaults.
 ///
+/// {@tool dartpad}
+/// This example shows a [CupertinoSegmentedControl] with an enum type.
+///
+/// The callback provided to [onValueChanged] should update the state of
+/// the parent [StatefulWidget] using the [State.setState] method, so that
+/// the parent gets rebuilt; for example:
+///
+/// ** See code in examples/api/lib/cupertino/segmented_control/cupertino_segmented_control.0.dart **
+/// {@end-tool}
 /// See also:
 ///
 ///  * [CupertinoSegmentedControl], a segmented control widget in the style used
@@ -118,44 +127,6 @@ class CupertinoSegmentedControl<T extends Object> extends StatefulWidget {
   /// The segmented control passes the newly selected widget's associated key
   /// to the callback but does not actually change state until the parent
   /// widget rebuilds the segmented control with the new [groupValue].
-  ///
-  /// The callback provided to [onValueChanged] should update the state of
-  /// the parent [StatefulWidget] using the [State.setState] method, so that
-  /// the parent gets rebuilt; for example:
-  ///
-  /// {@tool snippet}
-  ///
-  /// ```dart
-  /// class SegmentedControlExample extends StatefulWidget {
-  ///   const SegmentedControlExample({Key? key}) : super(key: key);
-  ///
-  ///   @override
-  ///   State createState() => SegmentedControlExampleState();
-  /// }
-  ///
-  /// class SegmentedControlExampleState extends State<SegmentedControlExample> {
-  ///   final Map<int, Widget> children = const <int, Widget>{
-  ///     0: Text('Child 1'),
-  ///     1: Text('Child 2'),
-  ///   };
-  ///
-  ///   late int currentValue;
-  ///
-  ///   @override
-  ///   Widget build(BuildContext context) {
-  ///     return CupertinoSegmentedControl<int>(
-  ///       children: children,
-  ///       onValueChanged: (int newValue) {
-  ///         setState(() {
-  ///           currentValue = newValue;
-  ///         });
-  ///       },
-  ///       groupValue: currentValue,
-  ///     );
-  ///   }
-  /// }
-  /// ```
-  /// {@end-tool}
   final ValueChanged<T> onValueChanged;
 
   /// The color used to fill the backgrounds of unselected widgets and as the