Switch: Add an interactive example (#103045)

* `Switch`: Add an interactive examples

* Update docs

* Update doc

examples/api/lib/material/switch/switch.0.dart

@@ -0,0 +1,51 @@
+// 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 Switch
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const SwitchApp());
+
+class SwitchApp extends StatelessWidget {
+  const SwitchApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        appBar: AppBar(title: const Text('Switch Sample')),
+        body: const Center(
+          child: SwitchExample(),
+        ),
+      ),
+    );
+  }
+}
+
+class SwitchExample extends StatefulWidget {
+  const SwitchExample({super.key});
+
+  @override
+  State<SwitchExample> createState() => _SwitchExampleState();
+}
+
+class _SwitchExampleState extends State<SwitchExample> {
+  bool light = true;
+
+  @override
+  Widget build(BuildContext context) {
+    return Switch(
+      // This bool value toggles the switch.
+      value: light,
+      activeColor: Colors.red,
+      onChanged: (bool value) {
+        // This is called when the user toggles the switch.
+        setState(() {
+          light = value;
+        });
+      },
+    );
+  }
+}

examples/api/lib/material/switch/switch.1.dart

@@ -0,0 +1,82 @@
+// 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 Switch
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const SwitchApp());
+
+class SwitchApp extends StatelessWidget {
+  const SwitchApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        appBar: AppBar(title: const Text('Switch Sample')),
+        body: const Center(
+          child: SwitchExample(),
+        ),
+      ),
+    );
+  }
+}
+
+class SwitchExample extends StatefulWidget {
+  const SwitchExample({super.key});
+
+  @override
+  State<SwitchExample> createState() => _SwitchExampleState();
+}
+
+class _SwitchExampleState extends State<SwitchExample> {
+  bool light = true;
+
+  @override
+  Widget build(BuildContext context) {
+    final MaterialStateProperty<Color?> trackColor = MaterialStateProperty.resolveWith<Color?>(
+      (Set<MaterialState> states) {
+        // Track color when the switch is selected.
+        if (states.contains(MaterialState.selected)) {
+          return Colors.amber;
+        }
+        // Otherwise return null to set default track color
+        // for remaining states such as when the switch is
+        // hovered, focused, or disabled.
+        return null;
+      },
+    );
+    final MaterialStateProperty<Color?> overlayColor = MaterialStateProperty.resolveWith<Color?>(
+      (Set<MaterialState> states) {
+        // Material color when switch is selected.
+        if (states.contains(MaterialState.selected)) {
+          return Colors.amber.withOpacity(0.54);
+        }
+        // Material color when switch is disabled.
+        if (states.contains(MaterialState.disabled)) {
+          return Colors.grey.shade400;
+        }
+        // Otherwise return null to set default material color
+        // for remaining states such as when the switch is
+        // hovered, or focused.
+        return null;
+      },
+    );
+
+    return Switch(
+      // This bool value toggles the switch.
+      value: light,
+      overlayColor: overlayColor,
+      trackColor: trackColor,
+      thumbColor: MaterialStateProperty.all<Color>(Colors.black),
+      onChanged: (bool value) {
+        // This is called when the user toggles the switch.
+        setState(() {
+          light = value;
+        });
+      },
+    );
+  }
+}

examples/api/test/material/switch/switch.0_test.dart

@@ -0,0 +1,24 @@
+// 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/material/switch/switch.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Can toggle switch', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.SwitchApp(),
+    );
+
+    final Finder switchFinder = find.byType(Switch);
+    Switch materialSwitch = tester.widget<Switch>(switchFinder);
+    expect(materialSwitch.value, true);
+
+    await tester.tap(switchFinder);
+    await tester.pumpAndSettle();
+    materialSwitch = tester.widget<Switch>(switchFinder);
+    expect(materialSwitch.value, false);
+  });
+}

examples/api/test/material/switch/switch.1_test.dart

@@ -0,0 +1,24 @@
+// 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/material/switch/switch.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Can toggle switch', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.SwitchApp(),
+    );
+
+    final Finder switchFinder = find.byType(Switch);
+    Switch materialSwitch = tester.widget<Switch>(switchFinder);
+    expect(materialSwitch.value, true);
+
+    await tester.tap(switchFinder);
+    await tester.pumpAndSettle();
+    materialSwitch = tester.widget<Switch>(switchFinder);
+    expect(materialSwitch.value, false);
+  });
+}

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

@@ -44,6 +44,20 @@ enum _SwitchType { material, adaptive }
 ///
 /// Requires one of its ancestors to be a [Material] widget.
 ///
+/// {@tool dartpad}
+/// This example shows a toggleable [Switch]. When the thumb slides to the other
+/// side of the track, the switch is toggled between on/off.
+///
+/// ** See code in examples/api/lib/material/switch/switch.0.dart **
+/// {@end-tool}
+///
+/// {@tool dartpad}
+/// This example shows how to customize [Switch] using [MaterialStateProperty]
+/// switch properties.
+///
+/// ** See code in examples/api/lib/material/switch/switch.1.dart **
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [SwitchListTile], which combines this widget with a [ListTile] so that
@@ -51,6 +65,8 @@ enum _SwitchType { material, adaptive }
 ///  * [Checkbox], another widget with similar semantics.
 ///  * [Radio], for selecting among a set of explicit values.
 ///  * [Slider], for selecting a value in a range.
+///  * [MaterialStateProperty], an interface for objects that "resolve" to
+///    different values depending on a widget's material state.
 ///  * <https://material.io/design/components/selection-controls.html#switches>
 class Switch extends StatelessWidget {
   /// Creates a Material Design switch.