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 'icon_button.dart';
6/// @docImport 'navigation_rail.dart';
7/// @docImport 'text_button.dart';
8/// @docImport 'text_theme.dart';
9library;
10
11import 'dart:math' as math;
12
13import 'package:flutter/rendering.dart';
14import 'package:flutter/widgets.dart';
15
16import 'badge_theme.dart';
17import 'color_scheme.dart';
18import 'theme.dart';
19
20/// A Material Design "badge".
21///
22/// A badge's [label] conveys a small amount of information about its
23/// [child], like a count or status. If the label is null then this is
24/// a "small" badge that's displayed as a [smallSize] diameter filled
25/// circle. Otherwise this is a [StadiumBorder] shaped "large" badge
26/// with height [largeSize].
27///
28/// Badges are typically used to decorate the icon within a
29/// [BottomNavigationBarItem] or a [NavigationRailDestination]
30/// or a button's icon, as in [TextButton.icon]. The badge's default
31/// configuration is intended to work well with a default sized (24)
32/// [Icon].
33///
34/// {@tool dartpad}
35/// This example shows how to create a [Badge] with label and count
36/// wrapped on an icon in an [IconButton].
37///
38/// ** See code in examples/api/lib/material/badge/badge.0.dart **
39/// {@end-tool}
40class Badge extends StatelessWidget {
41 /// Create a Badge that stacks [label] on top of [child].
42 ///
43 /// If [label] is null then just a filled circle is displayed. Otherwise
44 /// the [label] is displayed within a [StadiumBorder] shaped area.
45 const Badge({
46 super.key,
47 this.backgroundColor,
48 this.textColor,
49 this.smallSize,
50 this.largeSize,
51 this.textStyle,
52 this.padding,
53 this.alignment,
54 this.offset,
55 this.label,
56 this.isLabelVisible = true,
57 this.child,
58 });
59
60 /// Convenience constructor for creating a badge with a numeric
61 /// label with 1-3 digits based on [count].
62 ///
63 /// Initializes [label] with a [Text] widget that contains [count].
64 /// If [count] is greater than 999, then the label is '999+'.
65 Badge.count({
66 super.key,
67 this.backgroundColor,
68 this.textColor,
69 this.smallSize,
70 this.largeSize,
71 this.textStyle,
72 this.padding,
73 this.alignment,
74 this.offset,
75 required int count,
76 this.isLabelVisible = true,
77 this.child,
78 }) : label = Text(count > 999 ? '999+' : '$count');
79
80 /// The badge's fill color.
81 ///
82 /// Defaults to the [BadgeTheme]'s background color, or
83 /// [ColorScheme.error] if the theme value is null.
84 final Color? backgroundColor;
85
86 /// The color of the badge's [label] text.
87 ///
88 /// This color overrides the color of the label's [textStyle].
89 ///
90 /// Defaults to the [BadgeTheme]'s foreground color, or
91 /// [ColorScheme.onError] if the theme value is null.
92 final Color? textColor;
93
94 /// The diameter of the badge if [label] is null.
95 ///
96 /// Defaults to the [BadgeTheme]'s small size, or 6 if the theme value
97 /// is null.
98 final double? smallSize;
99
100 /// The badge's height if [label] is non-null.
101 ///
102 /// Defaults to the [BadgeTheme]'s large size, or 16 if the theme value
103 /// is null. If the default value is overridden then it may be useful to
104 /// also override [padding] and [alignment].
105 final double? largeSize;
106
107 /// The [DefaultTextStyle] for the badge's label.
108 ///
109 /// The text style's color is overwritten by the [textColor].
110 ///
111 /// This value is only used if [label] is non-null.
112 ///
113 /// Defaults to the [BadgeTheme]'s text style, or the overall theme's
114 /// [TextTheme.labelSmall] if the badge theme's value is null. If
115 /// the default text style is overridden then it may be useful to
116 /// also override [largeSize], [padding], and [alignment].
117 final TextStyle? textStyle;
118
119 /// The padding added to the badge's label.
120 ///
121 /// This value is only used if [label] is non-null.
122 ///
123 /// Defaults to the [BadgeTheme]'s padding, or 4 pixels on the
124 /// left and right if the theme's value is null.
125 final EdgeInsetsGeometry? padding;
126
127 /// Combined with [offset] to determine the location of the [label]
128 /// relative to the [child].
129 ///
130 /// The alignment positions the label in the same way a child of an
131 /// [Align] widget is positioned, except that, the alignment is
132 /// resolved as if the label was a [largeSize] square and [offset]
133 /// is added to the result.
134 ///
135 /// This value is only used if [label] is non-null.
136 ///
137 /// Defaults to the [BadgeTheme]'s alignment, or
138 /// [AlignmentDirectional.topEnd] if the theme's value is null.
139 final AlignmentGeometry? alignment;
140
141 /// Combined with [alignment] to determine the location of the [label]
142 /// relative to the [child].
143 ///
144 /// This value is only used if [label] is non-null.
145 ///
146 /// Defaults to the [BadgeTheme]'s offset, or
147 /// if the theme's value is null then `Offset(4, -4)` for
148 /// [TextDirection.ltr] or `Offset(-4, -4)` for [TextDirection.rtl].
149 final Offset? offset;
150
151 /// The badge's content, typically a [Text] widget that contains 1 to 4
152 /// characters.
153 ///
154 /// If the label is null then this is a "small" badge that's
155 /// displayed as a [smallSize] diameter filled circle. Otherwise
156 /// this is a [StadiumBorder] shaped "large" badge with height [largeSize].
157 final Widget? label;
158
159 /// If false, the badge's [label] is not included.
160 ///
161 /// This flag is true by default. It's intended to make it convenient
162 /// to create a badge that's only shown under certain conditions.
163 final bool isLabelVisible;
164
165 /// The widget that the badge is stacked on top of.
166 ///
167 /// Typically this is an default sized [Icon] that's part of a
168 /// [BottomNavigationBarItem] or a [NavigationRailDestination].
169 final Widget? child;
170
171 @override
172 Widget build(BuildContext context) {
173 if (!isLabelVisible) {
174 return child ?? const SizedBox();
175 }
176
177 final BadgeThemeData badgeTheme = BadgeTheme.of(context);
178 final BadgeThemeData defaults = _BadgeDefaultsM3(context);
179 final Decoration effectiveDecoration = ShapeDecoration(
180 color: backgroundColor ?? badgeTheme.backgroundColor ?? defaults.backgroundColor!,
181 shape: const StadiumBorder(),
182 );
183 final double effectiveWidthOffset;
184 final Widget badge;
185 final bool hasLabel = label != null;
186 if (hasLabel) {
187 final double minSize = effectiveWidthOffset =
188 largeSize ?? badgeTheme.largeSize ?? defaults.largeSize!;
189 badge = DefaultTextStyle(
190 style: (textStyle ?? badgeTheme.textStyle ?? defaults.textStyle!).copyWith(
191 color: textColor ?? badgeTheme.textColor ?? defaults.textColor!,
192 ),
193 child: _IntrinsicHorizontalStadium(
194 minSize: minSize,
195 child: Container(
196 clipBehavior: Clip.antiAlias,
197 decoration: effectiveDecoration,
198 padding: padding ?? badgeTheme.padding ?? defaults.padding!,
199 alignment: Alignment.center,
200 child: label,
201 ),
202 ),
203 );
204 } else {
205 final double effectiveSmallSize = effectiveWidthOffset =
206 smallSize ?? badgeTheme.smallSize ?? defaults.smallSize!;
207 badge = Container(
208 width: effectiveSmallSize,
209 height: effectiveSmallSize,
210 clipBehavior: Clip.antiAlias,
211 decoration: effectiveDecoration,
212 );
213 }
214
215 if (child == null) {
216 return badge;
217 }
218
219 final AlignmentGeometry effectiveAlignment =
220 alignment ?? badgeTheme.alignment ?? defaults.alignment!;
221 final TextDirection textDirection = Directionality.of(context);
222 final Offset defaultOffset = textDirection == TextDirection.ltr
223 ? const Offset(4, -4)
224 : const Offset(-4, -4);
225 // Adds a offset const Offset(0, 8) to avoiding breaking customers after
226 // the offset calculation changes.
227 // See https://github.com/flutter/flutter/pull/146853.
228 final Offset effectiveOffset =
229 (offset ?? badgeTheme.offset ?? defaultOffset) + const Offset(0, 8);
230
231 return Stack(
232 clipBehavior: Clip.none,
233 children: <Widget>[
234 child!,
235 Positioned.fill(
236 child: _Badge(
237 alignment: effectiveAlignment,
238 offset: hasLabel ? effectiveOffset : Offset.zero,
239 hasLabel: hasLabel,
240 widthOffset: effectiveWidthOffset,
241 textDirection: textDirection,
242 child: badge,
243 ),
244 ),
245 ],
246 );
247 }
248}
249
250class _Badge extends SingleChildRenderObjectWidget {
251 const _Badge({
252 required this.alignment,
253 required this.offset,
254 required this.widthOffset,
255 required this.textDirection,
256 required this.hasLabel,
257 super.child, // the badge
258 });
259
260 final AlignmentGeometry alignment;
261 final Offset offset;
262 final double widthOffset;
263 final TextDirection textDirection;
264 final bool hasLabel;
265
266 @override
267 _RenderBadge createRenderObject(BuildContext context) {
268 return _RenderBadge(
269 alignment: alignment,
270 widthOffset: widthOffset,
271 hasLabel: hasLabel,
272 offset: offset,
273 textDirection: Directionality.maybeOf(context),
274 );
275 }
276
277 @override
278 void updateRenderObject(BuildContext context, _RenderBadge renderObject) {
279 renderObject
280 ..alignment = alignment
281 ..offset = offset
282 ..widthOffset = widthOffset
283 ..hasLabel = hasLabel
284 ..textDirection = Directionality.maybeOf(context);
285 }
286
287 @override
288 void debugFillProperties(DiagnosticPropertiesBuilder properties) {
289 super.debugFillProperties(properties);
290 properties.add(DiagnosticsProperty<AlignmentGeometry>('alignment', alignment));
291 properties.add(DiagnosticsProperty<Offset>('offset', offset));
292 }
293}
294
295class _RenderBadge extends RenderAligningShiftedBox {
296 _RenderBadge({
297 super.textDirection,
298 super.alignment,
299 required Offset offset,
300 required bool hasLabel,
301 required double widthOffset,
302 }) : _offset = offset,
303 _hasLabel = hasLabel,
304 _widthOffset = widthOffset;
305
306 Offset get offset => _offset;
307 Offset _offset;
308 set offset(Offset value) {
309 if (_offset == value) {
310 return;
311 }
312 _offset = value;
313 markNeedsLayout();
314 }
315
316 bool get hasLabel => _hasLabel;
317 bool _hasLabel;
318 set hasLabel(bool value) {
319 if (_hasLabel == value) {
320 return;
321 }
322 _hasLabel = value;
323 markNeedsLayout();
324 }
325
326 double get widthOffset => _widthOffset;
327 double _widthOffset;
328 set widthOffset(double value) {
329 if (_widthOffset == value) {
330 return;
331 }
332 _widthOffset = value;
333 markNeedsLayout();
334 }
335
336 @override
337 void performLayout() {
338 final BoxConstraints constraints = this.constraints;
339 assert(constraints.hasBoundedWidth);
340 assert(constraints.hasBoundedHeight);
341 size = constraints.biggest;
342
343 child!.layout(const BoxConstraints(), parentUsesSize: true);
344 final double badgeSize = child!.size.height;
345 final Alignment resolvedAlignment = alignment.resolve(textDirection);
346 final BoxParentData childParentData = child!.parentData! as BoxParentData;
347 Offset badgeLocation =
348 offset + resolvedAlignment.alongOffset(Offset(size.width - widthOffset, size.height));
349 if (hasLabel) {
350 // Adjust for label height.
351 badgeLocation = badgeLocation - Offset(0, badgeSize / 2);
352 }
353 childParentData.offset = badgeLocation;
354 }
355}
356
357/// A widget size itself to the smallest horizontal stadium rect that can still
358/// fit the child's intrinsic size.
359///
360/// A horizontal stadium means a rect that has width >= height.
361///
362/// Uses [minSize] to set the min size of width and height.
363class _IntrinsicHorizontalStadium extends SingleChildRenderObjectWidget {
364 const _IntrinsicHorizontalStadium({super.child, required this.minSize});
365 final double minSize;
366
367 @override
368 _RenderIntrinsicHorizontalStadium createRenderObject(BuildContext context) {
369 return _RenderIntrinsicHorizontalStadium(minSize: minSize);
370 }
371}
372
373class _RenderIntrinsicHorizontalStadium extends RenderProxyBox {
374 _RenderIntrinsicHorizontalStadium({RenderBox? child, required double minSize})
375 : _minSize = minSize,
376 super(child);
377
378 double get minSize => _minSize;
379 double _minSize;
380 set minSize(double value) {
381 if (_minSize == value) {
382 return;
383 }
384 _minSize = value;
385 markNeedsLayout();
386 }
387
388 @override
389 double computeMinIntrinsicWidth(double height) {
390 return getMaxIntrinsicWidth(height);
391 }
392
393 @override
394 double computeMaxIntrinsicWidth(double height) {
395 return math.max(getMaxIntrinsicHeight(double.infinity), super.computeMaxIntrinsicWidth(height));
396 }
397
398 @override
399 double computeMinIntrinsicHeight(double width) {
400 return getMaxIntrinsicHeight(width);
401 }
402
403 @override
404 double computeMaxIntrinsicHeight(double width) {
405 return math.max(minSize, super.computeMaxIntrinsicHeight(width));
406 }
407
408 BoxConstraints _childConstraints(RenderBox child, BoxConstraints constraints) {
409 final double childHeight = math.max(minSize, child.getMaxIntrinsicHeight(constraints.maxWidth));
410 final double childWidth = child.getMaxIntrinsicWidth(constraints.maxHeight);
411 return constraints.tighten(width: math.max(childWidth, childHeight), height: childHeight);
412 }
413
414 Size _computeSize({required ChildLayouter layoutChild, required BoxConstraints constraints}) {
415 final RenderBox child = this.child!;
416 final Size childSize = layoutChild(child, _childConstraints(child, constraints));
417 if (childSize.height > childSize.width) {
418 return Size(childSize.height, childSize.height);
419 }
420 return childSize;
421 }
422
423 @override
424 @protected
425 Size computeDryLayout(covariant BoxConstraints constraints) {
426 return _computeSize(layoutChild: ChildLayoutHelper.dryLayoutChild, constraints: constraints);
427 }
428
429 @override
430 double? computeDryBaseline(BoxConstraints constraints, TextBaseline baseline) {
431 final RenderBox child = this.child!;
432 return child.getDryBaseline(_childConstraints(child, constraints), baseline);
433 }
434
435 @override
436 void performLayout() {
437 size = _computeSize(layoutChild: ChildLayoutHelper.layoutChild, constraints: constraints);
438 }
439}
440
441// BEGIN GENERATED TOKEN PROPERTIES - Badge
442
443// Do not edit by hand. The code between the "BEGIN GENERATED" and
444// "END GENERATED" comments are generated from data in the Material
445// Design token database by the script:
446// dev/tools/gen_defaults/bin/gen_defaults.dart.
447
448// dart format off
449class _BadgeDefaultsM3 extends BadgeThemeData {
450 _BadgeDefaultsM3(this.context) : super(
451 smallSize: 6.0,
452 largeSize: 16.0,
453 padding: const EdgeInsets.symmetric(horizontal: 4),
454 alignment: AlignmentDirectional.topEnd,
455 );
456
457 final BuildContext context;
458 late final ThemeData _theme = Theme.of(context);
459 late final ColorScheme _colors = _theme.colorScheme;
460
461 @override
462 Color? get backgroundColor => _colors.error;
463
464 @override
465 Color? get textColor => _colors.onError;
466
467 @override
468 TextStyle? get textStyle => Theme.of(context).textTheme.labelSmall;
469}
470// dart format on
471
472// END GENERATED TOKEN PROPERTIES - Badge
473