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 'package:flutter/foundation.dart';
6
7/// A description of an icon fulfilled by a font glyph.
8///
9/// See [Icons] for a number of predefined icons available for material
10/// design applications.
11///
12/// In release builds, the Flutter tool will tree shake out of bundled fonts
13/// the code points (or instances of [IconData]) which are not referenced from
14/// Dart app code. See the [staticIconProvider] annotation for more details.
15@immutable
16class IconData {
17 /// Creates icon data.
18 ///
19 /// Rarely used directly. Instead, consider using one of the predefined icons
20 /// like the [Icons] collection.
21 ///
22 /// The [fontPackage] argument must be non-null when using a font family that
23 /// is included in a package. This is used when selecting the font.
24 ///
25 /// Instantiating non-const instances of this class in your app will
26 /// mean the app cannot be built in release mode with icon tree-shaking (it
27 /// need to be explicitly opted out at build time). See [staticIconProvider]
28 /// for more context.
29 const IconData(
30 this.codePoint, {
31 this.fontFamily,
32 this.fontPackage,
33 this.matchTextDirection = false,
34 this.fontFamilyFallback,
35 });
36
37 /// The Unicode code point at which this icon is stored in the icon font.
38 final int codePoint;
39
40 /// The font family from which the glyph for the [codePoint] will be selected.
41 final String? fontFamily;
42
43 /// The name of the package from which the font family is included.
44 ///
45 /// The name is used by the [Icon] widget when configuring the [TextStyle] so
46 /// that the given [fontFamily] is obtained from the appropriate asset.
47 ///
48 /// See also:
49 ///
50 /// * [TextStyle], which describes how to use fonts from other packages.
51 final String? fontPackage;
52
53 /// Whether this icon should be automatically mirrored in right-to-left
54 /// environments.
55 ///
56 /// The [Icon] widget respects this value by mirroring the icon when the
57 /// [Directionality] is [TextDirection.rtl].
58 final bool matchTextDirection;
59
60 /// The ordered list of font families to fall back on when a glyph cannot be found in a higher priority font family.
61 ///
62 /// For more details, refer to the documentation of [TextStyle]
63 final List<String>? fontFamilyFallback;
64
65 @override
66 bool operator ==(Object other) {
67 if (other.runtimeType != runtimeType) {
68 return false;
69 }
70 return other is IconData
71 && other.codePoint == codePoint
72 && other.fontFamily == fontFamily
73 && other.fontPackage == fontPackage
74 && other.matchTextDirection == matchTextDirection
75 && listEquals(other.fontFamilyFallback, fontFamilyFallback);
76 }
77
78 @override
79 int get hashCode {
80 return Object.hash(
81 codePoint,
82 fontFamily,
83 fontPackage,
84 matchTextDirection,
85 Object.hashAll(fontFamilyFallback ?? const <String?>[]),
86 );
87 }
88
89 @override
90 String toString() => 'IconData(U+${codePoint.toRadixString(16).toUpperCase().padLeft(5, '0')})';
91}
92
93/// [DiagnosticsProperty] that has an [IconData] as value.
94class IconDataProperty extends DiagnosticsProperty<IconData> {
95 /// Create a diagnostics property for [IconData].
96 IconDataProperty(
97 String super.name,
98 super.value, {
99 super.ifNull,
100 super.showName,
101 super.style,
102 super.level,
103 });
104
105 @override
106 Map<String, Object?> toJsonMap(DiagnosticsSerializationDelegate delegate) {
107 final Map<String, Object?> json = super.toJsonMap(delegate);
108 if (value != null) {
109 json['valueProperties'] = <String, Object>{
110 'codePoint': value!.codePoint,
111 };
112 }
113 return json;
114 }
115}
116
117class _StaticIconProvider {
118 const _StaticIconProvider();
119}
120
121/// Annotation for classes that only provide static const [IconData] instances.
122///
123/// This is a hint to the font tree shaker to ignore the constant instances
124/// of [IconData] appearing in the declaration of this class when tree-shaking
125/// unused code points from the bundled font.
126///
127/// Classes with this annotation must have only "static const" members. The
128/// presence of any non-const [IconData] instances will preclude apps
129/// importing the declaration into their application from being able to use
130/// icon tree-shaking during release builds, resulting in larger font assets.
131///
132/// ```dart
133/// @staticIconProvider
134/// abstract final class MyCustomIcons {
135/// static const String fontFamily = 'MyCustomIcons';
136/// static const IconData happyFace = IconData(1, fontFamily: fontFamily);
137/// static const IconData sadFace = IconData(2, fontFamily: fontFamily);
138/// }
139/// ```
140const Object staticIconProvider = _StaticIconProvider();
141