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