mirror of
https://github.com/danbulant/icon
synced 2026-05-19 04:08:36 +00:00
64 lines
2.5 KiB
Rust
64 lines
2.5 KiB
Rust
//! Turns out finding icons correctly on linux is kind of hard.
|
|
//!
|
|
//! This crate, `icon`, implements the XDG icon theme specification fully, while (hopefully) giving maximum coverage in usecases without sacrificing speed or compliance.
|
|
//!
|
|
//! # Quick start
|
|
//!
|
|
//! ```
|
|
//! let icons = icon::Icons::new();
|
|
//! // TODO.
|
|
//! ```
|
|
//!
|
|
//! # High level design
|
|
//!
|
|
//! Finding icons is a multi-stage procedure, and depending on your use case, you might want to stop
|
|
//! doing work at any one of them.
|
|
//! This crate is laid out to allow you to do exactly that, befitting those who need to find
|
|
//! just one icon in one theme but also those who need a reliable cache of many icons for many themes.
|
|
//!
|
|
//! In general, the steps are as follows:
|
|
//!
|
|
//! 1. *Finding standalone icons and themes*:
|
|
//!
|
|
//! Icons are found either in icon themes, or 'standalone' (outside a theme) in XDG base directories.
|
|
//! While a number of directories should always be scanned for icons, the user or application is
|
|
//! allowed to search additional directories as it sees fit.
|
|
//!
|
|
//! [IconSearch] handles this part, and is also the main entrypoint for `icon`.
|
|
//!
|
|
//! 2. *Parsing icon themes*:
|
|
//!
|
|
//! Each icon theme lives in a directory in the root of one or more of the "search directories".
|
|
//! The name of its directory is called the theme's _internal name_, and in it lies the theme's
|
|
//! definition, `index.theme`.
|
|
//!
|
|
//! To find icons in a theme, its `index.theme` file must be parsed to understand the directory
|
|
//! structure within the theme itself.
|
|
//! This is handled by [theme::ThemeInfo].
|
|
//!
|
|
//! 3a. *Find just one icon* (oneshot):
|
|
//!
|
|
//! // TODO
|
|
//!
|
|
//! 3b. *Find many icons*:
|
|
//!
|
|
//! // TODO
|
|
//!
|
|
//! # Alternative crates
|
|
//!
|
|
//! - [linicon](https://crates.io/crates/linicon) also implements icon finding, but:
|
|
//! - it does not scan "standalone" icons correctly, such as those usually found in `/usr/share/pixmaps`.
|
|
//! - it adopts a one-shot approach, repeating all parsing and file-finding work for each icon.
|
|
//! - it does not provide support for caching.
|
|
//!
|
|
//! - [icon-loader](https://crates.io/crates/icon-loader) also implements icon finding, but:
|
|
//! - like `linicon`, it does not scan "standalone" icons correctly.
|
|
//! - it only supports a rust-native icon cache, which you cannot opt out of.
|
|
//! - it provides only icon loading—you cannot use it to obtain information about Icon Themes.
|
|
|
|
mod icon;
|
|
mod search;
|
|
pub mod theme;
|
|
|
|
pub use search::*;
|
|
pub use theme::Icons;
|