1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5import 'dart:ui' show Color;
6
7import 'framework.dart';
8
9/// An interactive button within either material's [BottomNavigationBar]
10/// or the iOS themed [CupertinoTabBar] with an icon and title.
11///
12/// This class is rarely used in isolation. It is typically embedded in one of
13/// the bottom navigation widgets above.
14///
15/// See also:
16///
17/// * [BottomNavigationBar]
18/// * <https://material.io/design/components/bottom-navigation.html>
19/// * [CupertinoTabBar]
20/// * <https://developer.apple.com/ios/human-interface-guidelines/bars/tab-bars>
21class BottomNavigationBarItem {
22 /// Creates an item that is used with [BottomNavigationBar.items].
23 ///
24 /// The argument [icon] should not be null and the argument [label] should not be null when used in a Material Design's [BottomNavigationBar].
25 const BottomNavigationBarItem({
26 this.key,
27 required this.icon,
28 this.label,
29 Widget? activeIcon,
30 this.backgroundColor,
31 this.tooltip,
32 }) : activeIcon = activeIcon ?? icon;
33
34 /// A key to be passed through to the resultant widget.
35 ///
36 /// This allows the identification of different [BottomNavigationBarItem]s through their keys.
37 ///
38 /// When changing the number of bar items in response to a bar item being tapped, giving
39 /// each item a key will allow the inkwell / splash animation to be correctly positioned.
40 final Key? key;
41
42 /// The icon of the item.
43 ///
44 /// Typically the icon is an [Icon] or an [ImageIcon] widget. If another type
45 /// of widget is provided then it should configure itself to match the current
46 /// [IconTheme] size and color.
47 ///
48 /// If [activeIcon] is provided, this will only be displayed when the item is
49 /// not selected.
50 ///
51 /// To make the bottom navigation bar more accessible, consider choosing an
52 /// icon with a stroked and filled version, such as [Icons.cloud] and
53 /// [Icons.cloud_queue]. [icon] should be set to the stroked version and
54 /// [activeIcon] to the filled version.
55 ///
56 /// If a particular icon doesn't have a stroked or filled version, then don't
57 /// pair unrelated icons. Instead, make sure to use a
58 /// [BottomNavigationBarType.shifting].
59 final Widget icon;
60
61 /// An alternative icon displayed when this bottom navigation item is
62 /// selected.
63 ///
64 /// If this icon is not provided, the bottom navigation bar will display
65 /// [icon] in either state.
66 ///
67 /// See also:
68 ///
69 /// * [BottomNavigationBarItem.icon], for a description of how to pair icons.
70 final Widget activeIcon;
71
72 /// The text label for this [BottomNavigationBarItem].
73 ///
74 /// This will be used to create a [Text] widget to put in the bottom navigation bar.
75 final String? label;
76
77 /// The color of the background radial animation for material [BottomNavigationBar].
78 ///
79 /// If the navigation bar's type is [BottomNavigationBarType.shifting], then
80 /// the entire bar is flooded with the [backgroundColor] when this item is
81 /// tapped. This will override [BottomNavigationBar.backgroundColor].
82 ///
83 /// Not used for [CupertinoTabBar]. Control the invariant bar color directly
84 /// via [CupertinoTabBar.backgroundColor].
85 ///
86 /// See also:
87 ///
88 /// * [Icon.color] and [ImageIcon.color] to control the foreground color of
89 /// the icons themselves.
90 final Color? backgroundColor;
91
92 /// The text to display in the [Tooltip] for this [BottomNavigationBarItem].
93 ///
94 /// A [Tooltip] will only appear on this item if [tooltip] is set to a non-empty string.
95 ///
96 /// Defaults to null, in which case the tooltip is not shown.
97 final String? tooltip;
98}
99