zng/
icon.rs

Help
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::{prelude::*, icon, widget::node::NilUiNode};
12//! # let _scope = APP.defaults();
13//!
14//! icon::ICONS.register(wgt_fn!(|a: icon::IconRequestArgs| {
15//!     match a.name() {
16//!         "accessibility" => Text!("A").boxed(),
17//!         "settings" => Text!("S").boxed(),
18//!         _ => NilUiNode.boxed()
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::{prelude::*, icon};
32//! # let _scope = APP.defaults();
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::{prelude::*, icon, font};
48//! # async fn demo() {
49//! # let _scope = APP.defaults();
50//!
51//! let font = font::CustomFont::from_file(
52//!     "Font Awesome 6 Free-Regular",
53//!     r#"Font Awesome 6 Free-Regular-400.otf"#,
54//!     0,
55//! );
56//! font::FONTS.register(font).wait_into_rsp().await.unwrap();
57//!
58//! # let _ =
59//! icon::Icon! {
60//!     ico = icon::GlyphIcon::new("Font Awesome 6 Free-Regular", "address-book").with_ligatures();
61//!     ico_size = 80;
62//! }
63//! # ;
64//! # }
65//! ```
66//!
67//! The example above loads an icon font and display one of the icons selected using a ligature that matches `"address-book"`.
68//!
69//! # Full API
70//!
71//! See [`zng_wgt_text::icon`] for the full widget API.
72
73pub use zng_wgt::{CommandIconExt, ICONS, IconRequestArgs};
74pub use zng_wgt_text::icon::{GlyphIcon, GlyphSource, Icon, ico_color, ico_size};
75
76/// Material Icons
77///
78/// The [Material Design Icons] can be embedded using the `"material_icons*"` crate features.
79///
80/// [Material Design Icons]: https://github.com/google/material-design-icons
81///
82/// ```toml
83/// zng = { version = "0.14.2", features = ["material_icons"] }
84/// ```
85///
86/// Handlers are registered for [`ICONS`] that provides the icons, the raw codepoints and glyph icon metadata is available in each font module.
87///
88/// If multiple material icons are enabled they are resolved in this order:
89///
90/// * outlined
91/// * filled
92/// * rounded
93/// * sharp
94///
95/// You can disambiguate icons by using a the `"material/{set}/{name}"` where `{set}` is one of the items from the list above,
96/// and `{name}` is the icon name.
97///
98/// # Full API
99///
100/// See [`zng_wgt_material_icons`] for the full API.
101pub mod material {
102    #[cfg(feature = "material_icons_filled")]
103    pub use zng_wgt_material_icons::filled;
104    #[cfg(feature = "material_icons_outlined")]
105    pub use zng_wgt_material_icons::outlined;
106    #[cfg(feature = "material_icons_rounded")]
107    pub use zng_wgt_material_icons::rounded;
108    #[cfg(feature = "material_icons_sharp")]
109    pub use zng_wgt_material_icons::sharp;
110}
zng/icon.rs

zng/
icon.rs
