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';
10library;
11
12import '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
23class 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.
112class 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
133class _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/// ```
156const Object staticIconProvider = _StaticIconProvider();
157