SystemUiOverlayStyle, add examples and improve documentation (#122187)

SystemUiOverlayStyle, add two examples and improve documentation

examples/api/lib/services/system_chrome/system_chrome.set_system_u_i_overlay_style.0.dart

@@ -0,0 +1,70 @@
+// 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 [AppBar.systemOverlayStyle].
+
+import 'dart:math' as math;
+
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+
+void main() => runApp(const SystemOverlayStyleApp());
+
+class SystemOverlayStyleApp extends StatelessWidget {
+  const SystemOverlayStyleApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      theme: ThemeData(
+        useMaterial3: true,
+        brightness: Brightness.light,
+      ),
+      home: const SystemOverlayStyleExample(),
+    );
+  }
+}
+
+class SystemOverlayStyleExample extends StatefulWidget {
+  const SystemOverlayStyleExample({super.key});
+
+  @override
+  State<SystemOverlayStyleExample> createState() => _SystemOverlayStyleExampleState();
+}
+
+class _SystemOverlayStyleExampleState extends State<SystemOverlayStyleExample> {
+  final math.Random _random = math.Random();
+  SystemUiOverlayStyle _currentStyle = SystemUiOverlayStyle.light;
+
+  void _changeColor() {
+    final Color color = Color.fromRGBO(
+      _random.nextInt(255),
+      _random.nextInt(255),
+      _random.nextInt(255),
+      1.0,
+    );
+    setState(() {
+      _currentStyle = SystemUiOverlayStyle.dark.copyWith(
+        statusBarColor: color,
+        systemNavigationBarColor: color,
+      );
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('SystemUiOverlayStyle Sample'),
+        systemOverlayStyle: _currentStyle,
+      ),
+      body: Center(
+        child: ElevatedButton(
+          onPressed: _changeColor,
+          child: const Text('Change Color'),
+        ),
+      ),
+    );
+  }
+}

examples/api/lib/services/system_chrome/system_chrome.set_system_u_i_overlay_style.1.dart

@@ -2,37 +2,38 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-// Flutter code sample for [SystemChrome.setSystemUIOverlayStyle].
+// Flutter code sample for setting the [SystemUiOverlayStyle] with an [AnnotatedRegion].
 
 import 'dart:math' as math;
 
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 
-void main() => runApp(const MyApp());
+void main() => runApp(const SystemOverlayStyleApp());
 
-class MyApp extends StatelessWidget {
-  const MyApp({super.key});
-
-  static const String _title = 'Flutter Code Sample';
+class SystemOverlayStyleApp extends StatelessWidget {
+  const SystemOverlayStyleApp({super.key});
 
   @override
   Widget build(BuildContext context) {
-    return const MaterialApp(
-      title: _title,
-      home: MyStatefulWidget(),
+    return MaterialApp(
+      theme: ThemeData(
+        useMaterial3: true,
+        brightness: Brightness.light,
+      ),
+      home: const SystemOverlayStyleExample(),
     );
   }
 }
 
-class MyStatefulWidget extends StatefulWidget {
-  const MyStatefulWidget({super.key});
+class SystemOverlayStyleExample extends StatefulWidget {
+  const SystemOverlayStyleExample({super.key});
 
   @override
-  State<MyStatefulWidget> createState() => _MyStatefulWidgetState();
+  State<SystemOverlayStyleExample> createState() => _SystemOverlayStyleExampleState();
 }
 
-class _MyStatefulWidgetState extends State<MyStatefulWidget> {
+class _SystemOverlayStyleExampleState extends State<SystemOverlayStyleExample> {
   final math.Random _random = math.Random();
   SystemUiOverlayStyle _currentStyle = SystemUiOverlayStyle.light;
 
@@ -46,6 +47,7 @@ class _MyStatefulWidgetState extends State<MyStatefulWidget> {
     setState(() {
       _currentStyle = SystemUiOverlayStyle.dark.copyWith(
         statusBarColor: color,
+        systemNavigationBarColor: color,
       );
     });
   }
@@ -54,10 +56,26 @@ class _MyStatefulWidgetState extends State<MyStatefulWidget> {
   Widget build(BuildContext context) {
     return AnnotatedRegion<SystemUiOverlayStyle>(
       value: _currentStyle,
-      child: Center(
-        child: ElevatedButton(
-          onPressed: _changeColor,
-          child: const Text('Change Color'),
+      child: Scaffold(
+        body: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: <Widget>[
+            Padding(
+              padding: const EdgeInsets.all(16.0),
+              child: Text(
+                'SystemUiOverlayStyle Sample',
+                style: Theme.of(context).textTheme.titleLarge,
+              ),
+            ),
+            Expanded(
+              child: Center(
+                child: ElevatedButton(
+                  onPressed: _changeColor,
+                  child: const Text('Change Color'),
+                ),
+              ),
+            ),
+          ],
         ),
       ),
     );

examples/api/test/services/system_chrome/system_chrome.set_system_u_i_overlay_style.0_test.dart

@@ -0,0 +1,30 @@
+// 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/services.dart';
+import 'package:flutter_api_samples/services/system_chrome/system_chrome.set_system_u_i_overlay_style.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('AppBar.systemOverlayStyle can change system overlays styles.', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.SystemOverlayStyleApp(),
+    );
+
+    final SystemUiOverlayStyle? firstStyle = SystemChrome.latestStyle;
+
+    await tester.tap(find.byType(ElevatedButton));
+    await tester.pump();
+    final SystemUiOverlayStyle? secondStyle = SystemChrome.latestStyle;
+    expect(secondStyle?.statusBarColor, isNot(firstStyle?.statusBarColor));
+    expect(secondStyle?.systemNavigationBarColor, isNot(firstStyle?.systemNavigationBarColor));
+
+    await tester.tap(find.byType(ElevatedButton));
+    await tester.pump();
+    final SystemUiOverlayStyle? thirdStyle = SystemChrome.latestStyle;
+    expect(thirdStyle?.statusBarColor, isNot(secondStyle?.statusBarColor));
+    expect(thirdStyle?.systemNavigationBarColor, isNot(secondStyle?.systemNavigationBarColor));
+  });
+}

examples/api/test/services/system_chrome/system_chrome.set_system_u_i_overlay_style.1_test.dart

@@ -0,0 +1,30 @@
+// 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/services.dart';
+import 'package:flutter_api_samples/services/system_chrome/system_chrome.set_system_u_i_overlay_style.1.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('AnnotatedRegion can change system overlays style.', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.SystemOverlayStyleApp(),
+    );
+
+    final SystemUiOverlayStyle? firstStyle = SystemChrome.latestStyle;
+
+    await tester.tap(find.byType(ElevatedButton));
+    await tester.pump();
+    final SystemUiOverlayStyle? secondStyle = SystemChrome.latestStyle;
+    expect(secondStyle?.statusBarColor, isNot(firstStyle?.statusBarColor));
+    expect(secondStyle?.systemNavigationBarColor, isNot(firstStyle?.systemNavigationBarColor));
+
+    await tester.tap(find.byType(ElevatedButton));
+    await tester.pump();
+    final SystemUiOverlayStyle? thirdStyle = SystemChrome.latestStyle;
+    expect(thirdStyle?.statusBarColor, isNot(secondStyle?.statusBarColor));
+    expect(thirdStyle?.systemNavigationBarColor, isNot(secondStyle?.systemNavigationBarColor));
+  });
+}

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

@@ -678,7 +678,8 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   final TextStyle? titleTextStyle;
 
   /// {@template flutter.material.appbar.systemOverlayStyle}
-  /// Specifies the style to use for the system overlays that overlap the AppBar.
+  /// Specifies the style to use for the system overlays (e.g. the status bar on
+  /// Android or iOS, the system navigation bar on Android).
   ///
   /// If this property is null, then [AppBarTheme.systemOverlayStyle] of
   /// [ThemeData.appBarTheme] is used. If that is also null, an appropriate
@@ -692,7 +693,10 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   /// {@endtemplate}
   //
   /// See also:
-  ///  * [SystemChrome.setSystemUIOverlayStyle]
+  ///
+  ///  * [AnnotatedRegion], for placing [SystemUiOverlayStyle] in the layer tree.
+  ///  * [SystemChrome.setSystemUIOverlayStyle], the imperative API for setting
+  ///    system overlays style.
   final SystemUiOverlayStyle? systemOverlayStyle;
 
   /// {@template flutter.material.appbar.forceMaterialTransparency}

packages/flutter/lib/src/services/system_chrome.dart

@@ -182,7 +182,9 @@ enum SystemUiMode {
 
 /// Specifies a preference for the style of the system overlays.
 ///
-/// Used by [SystemChrome.setSystemUIOverlayStyle].
+/// Used by [AppBar.systemOverlayStyle] for declaratively setting the style of
+/// the system overlays, and by [SystemChrome.setSystemUIOverlayStyle] for
+/// imperatively setting the style of the systeme overlays.
 @immutable
 class SystemUiOverlayStyle {
   /// Creates a new [SystemUiOverlayStyle].
@@ -492,8 +494,8 @@ class SystemChrome {
     );
   }
 
-  /// Specifies the style to use for the system overlays that are visible (if
-  /// any).
+  /// Specifies the style to use for the system overlays (e.g. the status bar on
+  /// Android or iOS, the system navigation bar on Android) that are visible (if any).
   ///
   /// This method will schedule the embedder update to be run in a microtask.
   /// Any subsequent calls to this method during the current event loop will
@@ -512,14 +514,11 @@ class SystemChrome {
   /// If a particular style is not supported on the platform, selecting it will
   /// have no effect.
   ///
-  /// {@tool snippet}
-  /// ```dart
-  /// @override
-  /// Widget build(BuildContext context) {
-  ///   SystemChrome.setSystemUIOverlayStyle(SystemUiOverlayStyle.dark);
-  ///   return const Placeholder();
-  /// }
-  /// ```
+  /// {@tool sample}
+  /// The following example uses an `AppBar` to set the system status bar color and
+  /// the system navigation bar color.
+  ///
+  /// ** See code in examples/api/lib/services/system_chrome/system_chrome.set_system_u_i_overlay_style.0.dart **
   /// {@end-tool}
   ///
   /// For more complex control of the system overlay styles, consider using
@@ -537,15 +536,18 @@ class SystemChrome {
   /// overlay style navigation bar properties.
   ///
   /// {@tool sample}
-  /// The following example creates a widget that changes the status bar color
-  /// to a random value on Android.
+  /// The following example uses an `AnnotatedRegion<SystemUiOverlayStyle>` to set
+  /// the system status bar color and the system navigation bar color.
   ///
   /// ** See code in examples/api/lib/services/system_chrome/system_chrome.set_system_u_i_overlay_style.1.dart **
   /// {@end-tool}
   ///
   /// See also:
   ///
-  ///  * [AnnotatedRegion], the widget used to place data into the layer tree.
+  ///  * [AppBar.systemOverlayStyle], a convenient property for declaratively setting
+  ///    the style of the system overlays.
+  ///  * [AnnotatedRegion], the widget used to place a `SystemUiOverlayStyle` into
+  ///    the layer tree.
   static void setSystemUIOverlayStyle(SystemUiOverlayStyle style) {
     if (_pendingStyle != null) {
       // The microtask has already been queued; just update the pending value.