snack_bar.dart 19.5 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'package:flutter/rendering.dart';
6
import 'package:flutter/widgets.dart';
7

8
import 'button_style.dart';
9
import 'color_scheme.dart';
10
import 'material.dart';
11
import 'material_state.dart';
12
import 'scaffold.dart';
13
import 'snack_bar_theme.dart';
14 15
import 'text_button.dart';
import 'text_button_theme.dart';
16
import 'theme.dart';
17
import 'theme_data.dart';
Matt Perry's avatar
Matt Perry committed
18

19
const double _singleLineVerticalPadding = 14.0;
Matt Perry's avatar
Matt Perry committed
20

Hixie's avatar
Hixie committed
21 22
// TODO(ianh): We should check if the given text and actions are going to fit on
// one line or not, and if they are, use the single-line layout, and if not, use
23 24 25
// the multiline layout, https://github.com/flutter/flutter/issues/32782
// See https://material.io/components/snackbars#specs, 'Longer Action Text' does
// not match spec.
Hixie's avatar
Hixie committed
26

27 28
const Duration _snackBarTransitionDuration = Duration(milliseconds: 250);
const Duration _snackBarDisplayDuration = Duration(milliseconds: 4000);
29
const Curve _snackBarHeightCurve = Curves.fastOutSlowIn;
30 31
const Curve _snackBarFadeInCurve = Interval(0.45, 1.0, curve: Curves.fastOutSlowIn);
const Curve _snackBarFadeOutCurve = Interval(0.72, 1.0, curve: Curves.fastOutSlowIn);
Hixie's avatar
Hixie committed
32

33 34
/// Specify how a [SnackBar] was closed.
///
35
/// The [ScaffoldMessengerState.showSnackBar] function returns a
36 37 38
/// [ScaffoldFeatureController]. The value of the controller's closed property
/// is a Future that resolves to a SnackBarClosedReason. Applications that need
/// to know how a snackbar was closed can use this value.
39 40 41 42
///
/// Example:
///
/// ```dart
43
/// ScaffoldMessenger.of(context).showSnackBar(
44
///   SnackBar( ... )
45 46 47 48 49 50 51 52
/// ).closed.then((SnackBarClosedReason reason) {
///    ...
/// });
/// ```
enum SnackBarClosedReason {
  /// The snack bar was closed after the user tapped a [SnackBarAction].
  action,

53
  /// The snack bar was closed through a [SemanticsAction.dismiss].
54 55
  dismiss,

56 57 58 59
  /// The snack bar was closed by a user's swipe.
  swipe,

  /// The snack bar was closed by the [ScaffoldFeatureController] close callback
60
  /// or by calling [ScaffoldMessengerState.hideCurrentSnackBar] directly.
61 62
  hide,

63
  /// The snack bar was closed by an call to [ScaffoldMessengerState.removeCurrentSnackBar].
64 65 66 67 68 69
  remove,

  /// The snack bar was closed because its timer expired.
  timeout,
}

70 71 72 73 74
/// A button for a [SnackBar], known as an "action".
///
/// Snack bar actions are always enabled. If you want to disable a snack bar
/// action, simply don't include it in the snack bar.
///
75 76
/// Snack bar actions can only be pressed once. Subsequent presses are ignored.
///
77 78 79
/// See also:
///
///  * [SnackBar]
jslavitz's avatar
jslavitz committed
80
///  * <https://material.io/design/components/snackbars.html>
81
class SnackBarAction extends StatefulWidget {
82 83 84
  /// Creates an action for a [SnackBar].
  ///
  /// The [label] and [onPressed] arguments must be non-null.
85
  const SnackBarAction({
86
    Key? key,
jslavitz's avatar
jslavitz committed
87 88
    this.textColor,
    this.disabledTextColor,
89 90
    required this.label,
    required this.onPressed,
91 92 93
  }) : assert(label != null),
       assert(onPressed != null),
       super(key: key);
94

95 96
  /// The button label color. If not provided, defaults to
  /// [SnackBarThemeData.actionTextColor].
97
  final Color? textColor;
jslavitz's avatar
jslavitz committed
98 99

  /// The button disabled label color. This color is shown after the
100
  /// [SnackBarAction] is dismissed.
101
  final Color? disabledTextColor;
jslavitz's avatar
jslavitz committed
102

103
  /// The button label.
104
  final String label;
105

106
  /// The callback to be called when the button is pressed. Must not be null.
107
  ///
108
  /// This callback will be called at most once each time this action is
109
  /// displayed in a [SnackBar].
110
  final VoidCallback onPressed;
111

112
  @override
113
  State<SnackBarAction> createState() => _SnackBarActionState();
114 115 116 117 118 119 120 121 122 123 124
}

class _SnackBarActionState extends State<SnackBarAction> {
  bool _haveTriggeredAction = false;

  void _handlePressed() {
    if (_haveTriggeredAction)
      return;
    setState(() {
      _haveTriggeredAction = true;
    });
125
    widget.onPressed();
126
    Scaffold.of(context)!.hideCurrentSnackBar(reason: SnackBarClosedReason.action);
127 128
  }

129
  @override
Hixie's avatar
Hixie committed
130
  Widget build(BuildContext context) {
131 132
    Color? resolveForegroundColor(Set<MaterialState> states) {
      final SnackBarThemeData snackBarTheme = Theme.of(context)!.snackBarTheme;
133 134 135 136
      if (states.contains(MaterialState.disabled))
        return widget.disabledTextColor ?? snackBarTheme.disabledActionTextColor;
      return widget.textColor ?? snackBarTheme.actionTextColor;
    }
137

138 139
    return TextButton(
      style: ButtonStyle(
140
        foregroundColor: MaterialStateProperty.resolveWith<Color?>(resolveForegroundColor),
141
      ),
142
      onPressed: _haveTriggeredAction ? null : _handlePressed,
143
      child: Text(widget.label),
144 145 146
    );
  }
}
147

148 149 150
/// A lightweight message with an optional action which briefly displays at the
/// bottom of the screen.
///
151 152
/// {@youtube 560 315 https://www.youtube.com/watch?v=zpO6n_oZWw0}
///
153 154
/// To display a snack bar, call `ScaffoldMessenger.of(context).showSnackBar()`,
/// passing an instance of [SnackBar] that describes the message.
155 156
///
/// To control how long the [SnackBar] remains visible, specify a [duration].
157
///
158 159 160
/// A SnackBar with an action will not time out when TalkBack or VoiceOver are
/// enabled. This is controlled by [AccessibilityFeatures.accessibleNavigation].
///
161
/// See also:
162
///
163 164 165 166 167
///  * [ScaffoldMessenger.of], to obtain the current [ScaffoldMessengerState],
///    which manages the display and animation of snack bars.
///  * [ScaffoldMessengerState.showSnackBar], which displays a [SnackBar].
///  * [ScaffoldMessengerState.removeCurrentSnackBar], which abruptly hides the
///    currently displayed snack bar, if any, and allows the next to be displayed.
168 169
///  * [SnackBarAction], which is used to specify an [action] button to show
///    on the snack bar.
170 171
///  * [SnackBarThemeData], to configure the default property values for
///    [SnackBar] widgets.
jslavitz's avatar
jslavitz committed
172
///  * <https://material.io/design/components/snackbars.html>
173
class SnackBar extends StatefulWidget {
174 175
  /// Creates a snack bar.
  ///
176 177
  /// The [content] argument must be non-null. The [elevation] must be null or
  /// non-negative.
178
  const SnackBar({
179 180
    Key? key,
    required this.content,
181
    this.backgroundColor,
182
    this.elevation,
183 184 185
    this.margin,
    this.padding,
    this.width,
186 187
    this.shape,
    this.behavior,
188
    this.action,
189
    this.duration = _snackBarDisplayDuration,
190
    this.animation,
191
    this.onVisible,
192 193
  }) : assert(elevation == null || elevation >= 0.0),
       assert(content != null),
194 195 196 197 198 199 200 201 202 203 204 205
       assert(
         margin == null || behavior == SnackBarBehavior.floating,
         'Margin can only be used with floating behavior',
       ),
       assert(
         width == null || behavior == SnackBarBehavior.floating,
         'Width can only be used with floating behavior',
       ),
       assert(
         width == null || margin == null,
         'Width and margin can not be used together',
       ),
206
       assert(duration != null),
207
       super(key: key);
208

209 210 211
  /// The primary content of the snack bar.
  ///
  /// Typically a [Text] widget.
212
  final Widget content;
213

214
  /// The snack bar's background color. If not specified it will use
215 216 217 218
  /// [SnackBarThemeData.backgroundColor] of [ThemeData.snackBarTheme]. If that
  /// is not specified it will default to a dark variation of
  /// [ColorScheme.surface] for light themes, or [ColorScheme.onSurface] for
  /// dark themes.
219
  final Color? backgroundColor;
220

221 222 223 224 225
  /// The z-coordinate at which to place the snack bar. This controls the size
  /// of the shadow below the snack bar.
  ///
  /// Defines the card's [Material.elevation].
  ///
226 227 228
  /// If this property is null, then [SnackBarThemeData.elevation] of
  /// [ThemeData.snackBarTheme] is used, if that is also null, the default value
  /// is 6.0.
229
  final double? elevation;
230

231 232 233 234 235 236 237
  /// Empty space to surround the snack bar.
  ///
  /// This property is only used when [behavior] is [SnackBarBehavior.floating].
  /// It can not be used if [width] is specified.
  ///
  /// If this property is null, then the default is
  /// `EdgeInsets.fromLTRB(15.0, 5.0, 15.0, 10.0)`.
238
  final EdgeInsetsGeometry? margin;
239 240 241 242 243 244 245 246

  /// The amount of padding to apply to the snack bar's content and optional
  /// action.
  ///
  /// If this property is null, then the default depends on the [behavior] and
  /// the presence of an [action]. The start padding is 24 if [behavior] is
  /// [SnackBarBehavior.fixed] and 16 if it is [SnackBarBehavior.floating]. If
  /// there is no [action], the same padding is added to the end.
247
  final EdgeInsetsGeometry? padding;
248 249 250 251 252 253 254 255 256

  /// The width of the snack bar.
  ///
  /// If width is specified, the snack bar will be centered horizontally in the
  /// available space. This property is only used when [behavior] is
  /// [SnackBarBehavior.floating]. It can not be used if [margin] is specified.
  ///
  /// If this property is null, then the snack bar will take up the full device
  /// width less the margin.
257
  final double? width;
258

259 260 261 262
  /// The shape of the snack bar's [Material].
  ///
  /// Defines the snack bar's [Material.shape].
  ///
263 264 265 266 267 268
  /// If this property is null then [SnackBarThemeData.shape] of
  /// [ThemeData.snackBarTheme] is used. If that's null then the shape will
  /// depend on the [SnackBarBehavior]. For [SnackBarBehavior.fixed], no
  /// overriding shape is specified, so the [SnackBar] is rectangular. For
  /// [SnackBarBehavior.floating], it uses a [RoundedRectangleBorder] with a
  /// circular corner radius of 4.0.
269
  final ShapeBorder? shape;
270 271 272 273 274 275 276

  /// This defines the behavior and location of the snack bar.
  ///
  /// Defines where a [SnackBar] should appear within a [Scaffold] and how its
  /// location should be adjusted when the scaffold also includes a
  /// [FloatingActionButton] or a [BottomNavigationBar]
  ///
277 278 279
  /// If this property is null, then [SnackBarThemeData.behavior] of
  /// [ThemeData.snackBarTheme] is used. If that is null, then the default is
  /// [SnackBarBehavior.fixed].
280
  final SnackBarBehavior? behavior;
281

282 283 284 285
  /// (optional) An action that the user can take based on the snack bar.
  ///
  /// For example, the snack bar might let the user undo the operation that
  /// prompted the snackbar. Snack bars can have at most one action.
286 287
  ///
  /// The action should not be "dismiss" or "cancel".
288
  final SnackBarAction? action;
289 290

  /// The amount of time the snack bar should be displayed.
291
  ///
jslavitz's avatar
jslavitz committed
292
  /// Defaults to 4.0s.
293 294 295
  ///
  /// See also:
  ///
296
  ///  * [ScaffoldMessengerState.removeCurrentSnackBar], which abruptly hides the
297 298
  ///    currently displayed snack bar, if any, and allows the next to be
  ///    displayed.
jslavitz's avatar
jslavitz committed
299
  ///  * <https://material.io/design/components/snackbars.html>
Hixie's avatar
Hixie committed
300
  final Duration duration;
301 302

  /// The animation driving the entrance and exit of the snack bar.
303
  final Animation<double>? animation;
304

305
  /// Called the first time that the snackbar is visible within a [Scaffold].
306
  final VoidCallback? onVisible;
307

308
  // API for ScaffoldMessengerState.showSnackBar():
309 310

  /// Creates an animation controller useful for driving a snack bar's entrance and exit animation.
311
  static AnimationController createAnimationController({ required TickerProvider vsync }) {
312 313 314 315 316 317 318 319 320 321 322
    return AnimationController(
      duration: _snackBarTransitionDuration,
      debugLabel: 'SnackBar',
      vsync: vsync,
    );
  }

  /// Creates a copy of this snack bar but with the animation replaced with the given animation.
  ///
  /// If the original snack bar lacks a key, the newly created snack bar will
  /// use the given fallback key.
323
  SnackBar withAnimation(Animation<double> newAnimation, { Key? fallbackKey }) {
324 325 326 327 328
    return SnackBar(
      key: key ?? fallbackKey,
      content: content,
      backgroundColor: backgroundColor,
      elevation: elevation,
329 330 331
      margin: margin,
      padding: padding,
      width: width,
332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
      shape: shape,
      behavior: behavior,
      action: action,
      duration: duration,
      animation: newAnimation,
      onVisible: onVisible,
    );
  }

  @override
  State<SnackBar> createState() => _SnackBarState();
}

class _SnackBarState extends State<SnackBar> {
  bool _wasVisible = false;

  @override
  void initState() {
    super.initState();
351
    widget.animation!.addStatusListener(_onAnimationStatusChanged);
352 353 354 355 356
  }

  @override
  void didUpdateWidget(SnackBar oldWidget) {
    if (widget.animation != oldWidget.animation) {
357 358
      oldWidget.animation!.removeStatusListener(_onAnimationStatusChanged);
      widget.animation!.addStatusListener(_onAnimationStatusChanged);
359 360 361 362 363 364
    }
    super.didUpdateWidget(oldWidget);
  }

  @override
  void dispose() {
365
    widget.animation!.removeStatusListener(_onAnimationStatusChanged);
366 367 368 369 370 371 372 373 374 375 376
    super.dispose();
  }

  void _onAnimationStatusChanged(AnimationStatus animationStatus) {
    switch (animationStatus) {
      case AnimationStatus.dismissed:
      case AnimationStatus.forward:
      case AnimationStatus.reverse:
        break;
      case AnimationStatus.completed:
        if (widget.onVisible != null && !_wasVisible) {
377
          widget.onVisible!();
378 379 380 381 382
        }
        _wasVisible = true;
    }
  }

383
  @override
384
  Widget build(BuildContext context) {
385 386
    assert(debugCheckHasMediaQuery(context));
    final MediaQueryData mediaQueryData = MediaQuery.of(context)!;
387
    assert(widget.animation != null);
388
    final ThemeData theme = Theme.of(context)!;
389
    final ColorScheme colorScheme = theme.colorScheme;
390
    final SnackBarThemeData snackBarTheme = theme.snackBarTheme;
391
    final bool isThemeDark = theme.brightness == Brightness.dark;
392
    final Color buttonColor = isThemeDark ? colorScheme.primaryVariant : colorScheme.secondary;
393 394 395 396 397 398 399 400 401 402 403 404 405 406 407

    // SnackBar uses a theme that is the opposite brightness from
    // the surrounding theme.
    final Brightness brightness = isThemeDark ? Brightness.light : Brightness.dark;
    final Color themeBackgroundColor = isThemeDark
      ? colorScheme.onSurface
      : Color.alphaBlend(colorScheme.onSurface.withOpacity(0.80), colorScheme.surface);
    final ThemeData inverseTheme = ThemeData(
      brightness: brightness,
      backgroundColor: themeBackgroundColor,
      colorScheme: ColorScheme(
        primary: colorScheme.onPrimary,
        primaryVariant: colorScheme.onPrimary,
        // For the button color, the spec says it should be primaryVariant, but for
        // backward compatibility on light themes we are leaving it as secondary.
408
        secondary: buttonColor,
409 410 411 412 413 414 415 416 417 418 419
        secondaryVariant: colorScheme.onSecondary,
        surface: colorScheme.onSurface,
        background: themeBackgroundColor,
        error: colorScheme.onError,
        onPrimary: colorScheme.primary,
        onSecondary: colorScheme.secondary,
        onSurface: colorScheme.surface,
        onBackground: colorScheme.background,
        onError: colorScheme.error,
        brightness: brightness,
      ),
420
      snackBarTheme: snackBarTheme,
421
    );
422

423
    final TextStyle? contentTextStyle = snackBarTheme.contentTextStyle ?? inverseTheme.textTheme.subtitle1;
424
    final SnackBarBehavior snackBarBehavior = widget.behavior ?? snackBarTheme.behavior ?? SnackBarBehavior.fixed;
425
    final bool isFloatingSnackBar = snackBarBehavior == SnackBarBehavior.floating;
426 427 428
    final double horizontalPadding = isFloatingSnackBar ? 16.0 : 24.0;
    final EdgeInsetsGeometry padding = widget.padding
      ?? EdgeInsetsDirectional.only(start: horizontalPadding, end: widget.action != null ? 0 : horizontalPadding);
429

430 431
    final double actionHorizontalMargin = (widget.padding?.resolve(TextDirection.ltr).right ?? horizontalPadding) / 2;

432 433
    final CurvedAnimation heightAnimation = CurvedAnimation(parent: widget.animation!, curve: _snackBarHeightCurve);
    final CurvedAnimation fadeInAnimation = CurvedAnimation(parent: widget.animation!, curve: _snackBarFadeInCurve);
434
    final CurvedAnimation fadeOutAnimation = CurvedAnimation(
435
      parent: widget.animation!,
436 437 438 439
      curve: _snackBarFadeOutCurve,
      reverseCurve: const Threshold(0.0),
    );

440 441
    Widget snackBar = Padding(
      padding: padding,
442
      child: Row(
443
        crossAxisAlignment: CrossAxisAlignment.center,
444 445 446 447 448
        children: <Widget>[
          Expanded(
            child: Container(
              padding: const EdgeInsets.symmetric(vertical: _singleLineVerticalPadding),
              child: DefaultTextStyle(
449
                style: contentTextStyle!,
450
                child: widget.content,
451 452 453
              ),
            ),
          ),
454
          if (widget.action != null)
455 456 457 458 459 460 461 462
            Padding(
              padding: EdgeInsets.symmetric(horizontal: actionHorizontalMargin),
              child: TextButtonTheme(
                data: TextButtonThemeData(
                  style: TextButton.styleFrom(
                    primary: buttonColor,
                    padding: EdgeInsets.symmetric(horizontal: horizontalPadding),
                  ),
463
                ),
464
                child: widget.action!,
465
              ),
466
            ),
467
        ],
468 469
      ),
    );
470

471 472 473 474 475 476 477
    if (!isFloatingSnackBar) {
      snackBar = SafeArea(
        top: false,
        child: snackBar,
      );
    }

478 479
    final double elevation = widget.elevation ?? snackBarTheme.elevation ?? 6.0;
    final Color backgroundColor = widget.backgroundColor ?? snackBarTheme.backgroundColor ?? inverseTheme.backgroundColor;
480
    final ShapeBorder? shape = widget.shape
481 482 483 484 485 486 487 488
      ?? snackBarTheme.shape
      ?? (isFloatingSnackBar ? RoundedRectangleBorder(borderRadius: BorderRadius.circular(4.0)) : null);

    snackBar = Material(
      shape: shape,
      elevation: elevation,
      color: backgroundColor,
      child: Theme(
489
        data: inverseTheme,
490 491 492 493 494 495 496 497 498 499
        child: mediaQueryData.accessibleNavigation
            ? snackBar
            : FadeTransition(
                opacity: fadeOutAnimation,
                child: snackBar,
              ),
      ),
    );

    if (isFloatingSnackBar) {
500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523
      const double topMargin = 5.0;
      const double bottomMargin = 10.0;
      // If width is provided, do not include horizontal margins.
      if (widget.width != null) {
        snackBar = Container(
          margin: const EdgeInsets.only(top: topMargin, bottom: bottomMargin),
          width: widget.width,
          child: snackBar,
        );
      } else {
        const double horizontalMargin = 15.0;
        snackBar = Padding(
          padding: widget.margin ?? const EdgeInsets.fromLTRB(
            horizontalMargin,
            topMargin,
            horizontalMargin,
            bottomMargin,
          ),
          child: snackBar,
        );
      }
      snackBar = SafeArea(
        top: false,
        bottom: false,
524 525 526 527 528
        child: snackBar,
      );
    }

    snackBar = Semantics(
529 530 531
      container: true,
      liveRegion: true,
      onDismiss: () {
532
        Scaffold.of(context)!.removeCurrentSnackBar(reason: SnackBarClosedReason.dismiss);
533
      },
534
      child: Dismissible(
535 536 537 538
        key: const Key('dismissible'),
        direction: DismissDirection.down,
        resizeDuration: null,
        onDismissed: (DismissDirection direction) {
539
          Scaffold.of(context)!.removeCurrentSnackBar(reason: SnackBarClosedReason.swipe);
540
        },
541
        child: snackBar,
542 543
      ),
    );
544

545
    final Widget snackBarTransition;
546 547 548 549 550 551 552 553 554
    if (mediaQueryData.accessibleNavigation) {
      snackBarTransition = snackBar;
    } else if (isFloatingSnackBar) {
      snackBarTransition = FadeTransition(
        opacity: fadeInAnimation,
        child: snackBar,
      );
    } else {
      snackBarTransition = AnimatedBuilder(
555
        animation: heightAnimation,
556
        builder: (BuildContext context, Widget? child) {
557
          return Align(
558
            alignment: AlignmentDirectional.topStart,
559
            heightFactor: heightAnimation.value,
560
            child: child,
561
          );
562
        },
563 564 565
        child: snackBar,
      );
    }
566

567 568 569 570
    return Hero(
      child: ClipRect(child: snackBarTransition),
      tag: '<SnackBar Hero tag - ${widget.content}>',
    );
571
  }
572
}