icon_loader/lib.rs
1//!
2//! Crate to load and cache themed icons.
3//!
4//! # Examples
5//!
6//! * Using a global [`IconLoader`](IconLoader) object to load icons from the systems `hicolor` icon theme:
7//! ```no_run
8//! use icon_loader::icon_loader_hicolor;
9//!
10//! if let Some(icon) = icon_loader_hicolor().load_icon("audio-headphones") {
11//! let path = icon.file_for_size(64).path();
12//! }
13//! ```
14//!
15//! * Loading icons from the default icon theme set in KDE:
16//! ```no_run
17//! use icon_loader::IconLoader;
18//!
19//! let loader = IconLoader::new_kde().unwrap();
20//!
21//! if let Some(icon) = loader.load_icon("audio-headphones") {
22//! let path = icon.file_for_size(64).path();
23//! }
24//! ```
25//!
26//! * Loading icons from a custom theme in a provided folder:
27//! ```no_run
28//! use icon_loader::IconLoader;
29//!
30//! let mut loader = IconLoader::new();
31//! loader.set_search_paths(&["path_to_your_icon_theme"]);
32//! loader.set_theme_name_provider("name_of_your_icon_theme");
33//! loader.update_theme_name().unwrap();
34//!
35//! if let Some(icon) = loader.load_icon("icon_name") {
36//! let path = icon.file_for_size(32).path();
37//! }
38//! ```
39
40#![deny(
41 missing_docs,
42 missing_debug_implementations,
43 missing_copy_implementations,
44 trivial_casts,
45 trivial_numeric_casts
46)]
47#![forbid(unsafe_code, unstable_features)]
48
49mod error;
50mod icon;
51mod loader;
52mod search_paths;
53mod theme_name_provider;
54
55pub use error::{Error, ProviderError, Result};
56pub use icon::{Icon, IconDir, IconFile, IconFileType, IconSizeType};
57pub use loader::*;
58pub use search_paths::SearchPaths;
59pub use theme_name_provider::ThemeNameProvider;
60
61use std::sync::OnceLock;
62
63/// This function returns a reference to a global [`IconLoader`](IconLoader) object with default settings.
64pub fn icon_loader_hicolor() -> &'static IconLoader {
65 static LOADER: OnceLock<IconLoader> = OnceLock::new();
66
67 LOADER.get_or_init(IconLoader::new)
68}