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

import 'package:flutter/widgets.dart';

7
import 'debug.dart';
8
import 'icon_button.dart';
9
import 'icons.dart';
10
import 'material_localizations.dart';
11
import 'theme.dart';
12

13 14
/// A "back" icon that's appropriate for the current [TargetPlatform].
///
15 16
/// The current platform is determined by querying for the ambient [Theme].
///
17 18 19 20 21 22
/// See also:
///
///  * [BackButton], an [IconButton] with a [BackButtonIcon] that calls
///    [Navigator.maybePop] to return to the previous route.
///  * [IconButton], which is a more general widget for creating buttons
///    with icons.
23
///  * [Icon], a Material Design icon.
24
///  * [ThemeData.platform], which specifies the current platform.
25
class BackButtonIcon extends StatelessWidget {
26 27
  /// Creates an icon that shows the appropriate "back" image for
  /// the current platform (as obtained from the [Theme]).
28
  const BackButtonIcon({ super.key });
29

30
  /// Returns the appropriate "back" icon for the given `platform`.
31 32 33 34
  static IconData _getIconData(TargetPlatform platform) {
    switch (platform) {
      case TargetPlatform.android:
      case TargetPlatform.fuchsia:
35 36
      case TargetPlatform.linux:
      case TargetPlatform.windows:
37 38
        return Icons.arrow_back;
      case TargetPlatform.iOS:
39
      case TargetPlatform.macOS:
40 41 42 43 44
        return Icons.arrow_back_ios;
    }
  }

  @override
45
  Widget build(BuildContext context) => Icon(_getIconData(Theme.of(context).platform));
46 47
}

48
/// A Material Design back button.
49 50 51
///
/// A [BackButton] is an [IconButton] with a "back" icon appropriate for the
/// current [TargetPlatform]. When pressed, the back button calls
52 53
/// [Navigator.maybePop] to return to the previous route unless a custom
/// [onPressed] callback is provided.
54 55 56 57 58 59 60 61 62 63 64 65
///
/// When deciding to display a [BackButton], consider using
/// `ModalRoute.of(context)?.canPop` to check whether the current route can be
/// popped. If that value is false (e.g., because the current route is the
/// initial route), the [BackButton] will not have any effect when pressed,
/// which could frustrate the user.
///
/// Requires one of its ancestors to be a [Material] widget.
///
/// See also:
///
///  * [AppBar], which automatically uses a [BackButton] in its
66 67
///    [AppBar.leading] slot when the [Scaffold] has no [Drawer] and the
///    current [Route] is not the [Navigator]'s first route.
68 69
///  * [BackButtonIcon], which is useful if you need to create a back button
///    that responds differently to being pressed.
70 71
///  * [IconButton], which is a more general widget for creating buttons with
///    icons.
72 73
///  * [CloseButton], an alternative which may be more appropriate for leaf
///    node pages in the navigation tree.
74 75 76
class BackButton extends StatelessWidget {
  /// Creates an [IconButton] with the appropriate "back" icon for the current
  /// target platform.
77
  const BackButton({ super.key, this.color, this.onPressed });
78 79 80 81 82

  /// The color to use for the icon.
  ///
  /// Defaults to the [IconThemeData.color] specified in the ambient [IconTheme],
  /// which usually matches the ambient [Theme]'s [ThemeData.iconTheme].
83
  final Color? color;
84

85 86 87 88
  /// An override callback to perform instead of the default behavior which is
  /// to pop the [Navigator].
  ///
  /// It can, for instance, be used to pop the platform's navigation stack
89
  /// via [SystemNavigator] instead of Flutter's [Navigator] in add-to-app
90 91 92
  /// situations.
  ///
  /// Defaults to null.
93
  final VoidCallback? onPressed;
94

95 96
  @override
  Widget build(BuildContext context) {
97
    assert(debugCheckHasMaterialLocalizations(context));
98
    return IconButton(
99
      icon: const BackButtonIcon(),
100
      color: color,
101
      tooltip: MaterialLocalizations.of(context).backButtonTooltip,
102
      onPressed: () {
103
        if (onPressed != null) {
104
          onPressed!();
105 106 107
        } else {
          Navigator.maybePop(context);
        }
108
      },
109 110 111
    );
  }
}
112

113
/// A Material Design close button.
114 115 116 117 118 119 120 121 122 123 124
///
/// A [CloseButton] is an [IconButton] with a "close" icon. When pressed, the
/// close button calls [Navigator.maybePop] to return to the previous route.
///
/// Use a [CloseButton] instead of a [BackButton] on fullscreen dialogs or
/// pages that may solicit additional actions to close.
///
/// See also:
///
///  * [AppBar], which automatically uses a [CloseButton] in its
///    [AppBar.leading] slot when appropriate.
125
///  * [BackButton], which is more appropriate for middle nodes in the
126 127
///    navigation tree or where pages can be popped instantaneously with
///    no user data consequence.
128
///  * [IconButton], to create other Material Design icon buttons.
129
class CloseButton extends StatelessWidget {
130
  /// Creates a Material Design close button.
131
  const CloseButton({ super.key, this.color, this.onPressed });
132 133 134 135 136

  /// The color to use for the icon.
  ///
  /// Defaults to the [IconThemeData.color] specified in the ambient [IconTheme],
  /// which usually matches the ambient [Theme]'s [ThemeData.iconTheme].
137
  final Color? color;
138

139 140 141 142
  /// An override callback to perform instead of the default behavior which is
  /// to pop the [Navigator].
  ///
  /// It can, for instance, be used to pop the platform's navigation stack
143
  /// via [SystemNavigator] instead of Flutter's [Navigator] in add-to-app
144 145 146
  /// situations.
  ///
  /// Defaults to null.
147
  final VoidCallback? onPressed;
148

149 150
  @override
  Widget build(BuildContext context) {
151
    assert(debugCheckHasMaterialLocalizations(context));
152
    return IconButton(
153
      icon: const Icon(Icons.close),
154
      color: color,
155
      tooltip: MaterialLocalizations.of(context).closeButtonTooltip,
156
      onPressed: () {
157
        if (onPressed != null) {
158
          onPressed!();
159 160 161
        } else {
          Navigator.maybePop(context);
        }
162 163 164 165
      },
    );
  }
}