setSystemUIOverlayStyle method Null safety

void setSystemUIOverlayStyle(
  1. SystemUiOverlayStyle style
)

Specifies the style to use for the system overlays 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 overwrite the pending value, such that only the last specified value takes effect.

Call this API in code whose lifecycle matches that of the desired system UI styles. For instance, to change the system UI style on a new page, consider calling when pushing/popping a new PageRoute.

However, the AppBar widget automatically sets the system overlay style based on its AppBar.brightness, so configure that instead of calling this method directly. Likewise, do the same for CupertinoNavigationBar via CupertinoNavigationBar.backgroundColor.

If a particular style is not supported on the platform, selecting it will have no effect.

@override
Widget build(BuildContext context) {
  SystemChrome.setSystemUIOverlayStyle(SystemUiOverlayStyle.dark);
  return const Placeholder();
}

For more complex control of the system overlay styles, consider using an AnnotatedRegion widget instead of calling setSystemUIOverlayStyle directly. This widget places a value directly into the layer tree where it can be hit-tested by the framework. On every frame, the framework will hit-test and select the annotated region it finds under the status and navigation bar and synthesize them into a single style. This can be used to configure the system styles when an app bar is not used.

The following example creates a widget that changes the status bar color to a random value on Android.
import 'dart:math' as math;

// ...

import 'package:flutter/services.dart';

// ...

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,
    );
  });
}

@override
Widget build(BuildContext context) {
  return AnnotatedRegion<SystemUiOverlayStyle>(
    value: _currentStyle,
    child: Center(
      child: ElevatedButton(
        child: const Text('Change Color'),
        onPressed: _changeColor,
       ),
     ),
   );
 }

See also:

Implementation

static void setSystemUIOverlayStyle(SystemUiOverlayStyle style) {
  assert(style != null);
  if (_pendingStyle != null) {
    // The microtask has already been queued; just update the pending value.
    _pendingStyle = style;
    return;
  }
  if (style == _latestStyle) {
    // Trivial success: no microtask has been queued and the given style is
    // already in effect, so no need to queue a microtask.
    return;
  }
  _pendingStyle = style;
  scheduleMicrotask(() {
    assert(_pendingStyle != null);
    if (_pendingStyle != _latestStyle) {
      SystemChannels.platform.invokeMethod<void>(
        'SystemChrome.setSystemUIOverlayStyle',
        _pendingStyle!._toMap(),
      );
      _latestStyle = _pendingStyle;
    }
    _pendingStyle = null;
  });
}