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