diff options
Diffstat (limited to 'iced_fontello/README.md')
| -rw-r--r-- | iced_fontello/README.md | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/iced_fontello/README.md b/iced_fontello/README.md new file mode 100644 index 0000000..52a59c1 --- /dev/null +++ b/iced_fontello/README.md @@ -0,0 +1,109 @@ +<div align="center"> + +# iced_fontello + +[](https://docs.rs/iced_fontello) +[](https://crates.io/crates/iced_fontello) +[](https://github.com/hecrj/iced_fontello/blob/master/LICENSE) +[](https://crates.io/crates/iced_fontello) +[](https://github.com/hecrj/iced_fontello/actions) +[](https://discourse.iced.rs/) +[](https://discord.gg/3xZJ65GAhd) + +A compile-time, type-safe icon font generator for [`iced`]. +Powered by [Fontello]. + +[`iced`]: https://github.com/iced-rs/iced +[Fontello]: https://github.com/fontello/fontello + +</div> + +## Usage +Create a `.toml` file somewhere in your crate with the font definition: + +```toml +# fonts/example-icons.toml +module = "icon" + +[glyphs] +edit = "fontawesome-pencil" +save = "entypo-floppy" +trash = "typicons-trash" +``` + +The `module` value defines the Rust module that will be generated in your `src` +directory containing a type-safe API to use the font. + +Each entry in the `[glyphs]` section corresponds to an icon. The keys will be +used as names for the functions of the module of the font; while the values +specify the glyph for that key using the format: `<font>-<glyph>`. You can browse +the available glyphs in [Fontello] or [the `fonts.json` file](fonts.json). + +Next, add `iced_fontello` to your `build-dependencies`: + +```rust +[build-dependencies] +iced_fontello = "0.13" +``` + +Then, call `iced_fontello::build` in your [build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html), +passing the path of your font definition: + +```rust +pub fn main() { + println!("cargo::rerun-if-changed=fonts/example-icons.toml"); + iced_fontello::build("fonts/example-icons.toml").expect("Build example-icons font"); +} +``` + +The library will generate the font and save its `.ttf` file right next to its definition. +In this example, the library would generate `fonts/example-icons.ttf`. + +Finally, it will generate a type-safe `iced` API that lets you use the font. In our example: + +```rust +// Generated automatically by iced_fontello at build time. +// Do not edit manually. +// d24460a00249b2acd0ccc64c3176452c546ad12d1038974e974d7bdb4cdb4a8f +use iced::widget::{text, Text}; +use iced::Font; + +pub const FONT: &[u8] = include_bytes!("../fonts/example-icons.ttf"); + +pub fn edit<'a>() -> Text<'a> { + icon("\u{270E}") +} + +pub fn save<'a>() -> Text<'a> { + icon("\u{1F4BE}") +} + +pub fn trash<'a>() -> Text<'a> { + icon("\u{E10A}") +} + +fn icon<'a>(codepoint: &'a str) -> Text<'a> { + text(codepoint).font(Font::with_name("example-icons")) +} +``` + +Now you can simply add `mod icon;` to your `lib.rs` or `main.rs` file and enjoy your new font: + +```rust +mod icon; + +use iced::widget::row; + +// ... + +row![icon::edit(), icon::save(), icon::trash()].spacing(10) + +// ... +``` + +Check out [the full example](example) to see it all in action. + +## Packaging +If you plan to package your crate, you must make sure you include the generated module +and font file in the final package. `build` is effectively a no-op when the module and +the font already exist and are up-to-date. |