zng/
icon.rs

1//! Icons service, icon font widget and other types.
2//!
3//! # Service
4//!
5//! The [`ICONS`] service bridges icon providers and icon users. Icon theme providers can register
6//! handlers that provide a node that renders the icon identified by name. Widget styles or other UI
7//! only need to request the icon, avoiding having to embed icon resources in lib crates and avoiding
8//! icons having a fixed appearance.
9//!
10//! ```
11//! use zng::{icon, prelude::*};
12//! # fn example() {
13//!
14//! icon::ICONS.register(wgt_fn!(|a: icon::IconRequestArgs| {
15//!     match a.name() {
16//!         "accessibility" => Text!("A"),
17//!         "settings" => Text!("S"),
18//!         _ => UiNode::nil(),
19//!     }
20//! })); }
21//! ```
22//!
23//! The example above registers a handler that provides two "icons" that are rendered by a `Text!` widgets.
24//!
25//! # Widget
26//!
27//! The [`Icon!`](struct@Icon) widget renders icons using an icon font, it allows setting the font and icon in a single value
28//! and can auto size the font size, this makes it a better alternative to just using the `Text!` widget.
29//!
30//! ```
31//! use zng::{icon, prelude::*};
32//! # fn example() {
33//!
34//! # let _ =
35//! icon::Icon! {
36//!     ico = icon::material::rounded::req("accessibility");
37//!     ico_size = 80;
38//! }
39//! # ; }
40//! ```
41//!
42//! You can implement your own icon sets by providing [`GlyphIcon`] instances or a type that converts to `GlyphIcon`.
43//! Glyph icons define a font name and a [`GlyphSource`] that can be a `char` or a ligature text.
44//!
45//! ```
46//! # fn main() { }
47//! use zng::{font, icon, prelude::*};
48//! # async fn demo() {
49//!
50//! let font = font::CustomFont::from_file("Font Awesome 6 Free-Regular", r#"Font Awesome 6 Free-Regular-400.otf"#, 0);
51//! font::FONTS.register(font).wait_rsp().await.unwrap();
52//!
53//! # let _ =
54//! icon::Icon! {
55//!     ico = icon::GlyphIcon::new("Font Awesome 6 Free-Regular", "address-book").with_ligatures();
56//!     ico_size = 80;
57//! }
58//! # ;
59//! # }
60//! ```
61//!
62//! The example above loads an icon font and display one of the icons selected using a ligature that matches `"address-book"`.
63//!
64//! # Full API
65//!
66//! See [`zng_wgt_text::icon`] for the full widget API.
67
68pub use zng_wgt::{CommandIconExt, ICONS, IconRequestArgs};
69pub use zng_wgt_text::icon::{GlyphIcon, GlyphSource, Icon, ico_color, ico_size};
70
71/// Material Icons
72///
73/// The [Material Design Icons] can be embedded using the `"material_icons*"` crate features.
74///
75/// [Material Design Icons]: https://github.com/google/material-design-icons
76///
77/// ```toml
78/// zng = { version = "0.19.2", features = ["material_icons"] }
79/// ```
80///
81/// Handlers are registered for [`ICONS`] that provides the icons, the raw codepoints and glyph icon metadata is available in each font module.
82///
83/// If multiple material icons are enabled they are resolved in this order:
84///
85/// * outlined
86/// * filled
87/// * rounded
88/// * sharp
89///
90/// You can disambiguate icons by using a the `"material/{set}/{name}"` where `{set}` is one of the items from the list above,
91/// and `{name}` is the icon name.
92///
93/// # Full API
94///
95/// See [`zng_wgt_material_icons`] for the full API.
96pub mod material {
97    #[cfg(feature = "material_icons_filled")]
98    pub use zng_wgt_material_icons::filled;
99    #[cfg(feature = "material_icons_outlined")]
100    pub use zng_wgt_material_icons::outlined;
101    #[cfg(feature = "material_icons_rounded")]
102    pub use zng_wgt_material_icons::rounded;
103    #[cfg(feature = "material_icons_sharp")]
104    pub use zng_wgt_material_icons::sharp;
105}
zng/icon.rs

zng/
icon.rs
