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

import 'dart:ui' show Color;

import 'framework.dart';

/// An interactive button within either material's [BottomNavigationBar]
/// or the iOS themed [CupertinoTabBar] with an icon and title.
///
12 13
/// This class is rarely used in isolation. It is typically embedded in one of
/// the bottom navigation widgets above.
xster's avatar
xster committed
14 15 16 17
///
/// See also:
///
///  * [BottomNavigationBar]
18
///  * <https://material.io/design/components/bottom-navigation.html>
xster's avatar
xster committed
19
///  * [CupertinoTabBar]
20
///  * <https://developer.apple.com/ios/human-interface-guidelines/bars/tab-bars>
xster's avatar
xster committed
21 22 23
class BottomNavigationBarItem {
  /// Creates an item that is used with [BottomNavigationBar.items].
  ///
24
  /// The argument [icon] should not be null and the argument [label] should not be null when used in a Material Design's [BottomNavigationBar].
xster's avatar
xster committed
25
  const BottomNavigationBarItem({
26
    required this.icon,
27
    this.label,
28
    Widget? activeIcon,
xster's avatar
xster committed
29
    this.backgroundColor,
30
    this.tooltip,
31
  }) : activeIcon = activeIcon ?? icon,
32
       assert(icon != null);
xster's avatar
xster committed
33 34 35 36 37 38

  /// The icon of the item.
  ///
  /// Typically the icon is an [Icon] or an [ImageIcon] widget. If another type
  /// of widget is provided then it should configure itself to match the current
  /// [IconTheme] size and color.
39 40 41 42 43 44 45 46 47 48 49 50
  ///
  /// If [activeIcon] is provided, this will only be displayed when the item is
  /// not selected.
  ///
  /// To make the bottom navigation bar more accessible, consider choosing an
  /// icon with a stroked and filled version, such as [Icons.cloud] and
  /// [Icons.cloud_queue]. [icon] should be set to the stroked version and
  /// [activeIcon] to the filled version.
  ///
  /// If a particular icon doesn't have a stroked or filled version, then don't
  /// pair unrelated icons. Instead, make sure to use a
  /// [BottomNavigationBarType.shifting].
xster's avatar
xster committed
51 52
  final Widget icon;

53 54 55 56 57 58 59 60
  /// An alternative icon displayed when this bottom navigation item is
  /// selected.
  ///
  /// If this icon is not provided, the bottom navigation bar will display
  /// [icon] in either state.
  ///
  /// See also:
  ///
61
  ///  * [BottomNavigationBarItem.icon], for a description of how to pair icons.
62 63
  final Widget activeIcon;

64 65
  /// The text label for this [BottomNavigationBarItem].
  ///
66
  /// This will be used to create a [Text] widget to put in the bottom navigation bar.
67
  final String? label;
68

xster's avatar
xster committed
69 70 71 72
  /// The color of the background radial animation for material [BottomNavigationBar].
  ///
  /// If the navigation bar's type is [BottomNavigationBarType.shifting], then
  /// the entire bar is flooded with the [backgroundColor] when this item is
73
  /// tapped. This will override [BottomNavigationBar.backgroundColor].
xster's avatar
xster committed
74 75 76 77 78 79 80
  ///
  /// Not used for [CupertinoTabBar]. Control the invariant bar color directly
  /// via [CupertinoTabBar.backgroundColor].
  ///
  /// See also:
  ///
  ///  * [Icon.color] and [ImageIcon.color] to control the foreground color of
81
  ///    the icons themselves.
82
  final Color? backgroundColor;
83

84
  /// The text to display in the [Tooltip] for this [BottomNavigationBarItem].
85
  ///
86
  /// A [Tooltip] will only appear on this item if [tooltip] is set to a non-empty string.
87
  ///
88
  /// Defaults to null, in which case the tooltip is not shown.
89
  final String? tooltip;
xster's avatar
xster committed
90
}