How to include custom icons in a Relm4 app?

[chriskilding]

Say that you have made some application-specific custom icons which live in your Relm4 app's repository, e.g. icon-foo.svg, icon-bar.svg.

You want to reference these from code with the set_icon_name method, e.g.

gtk::Button {
    set_icon_name: "icon-foo"
}

How would you configure your Relm4 app to include these icons? (And if applicable, is there a preferred location / folder structure for the icons within your repository?)

[AaronErhardt]

If you use a meson based build system like relm4-template, you can do the following steps:

1. Add icons into a folder: https://github.com/AaronErhardt/tuxedo-rs/blob/crisidev/tailor_gui/data/resources/icons
2. Add a gresource file for icons: https://github.com/AaronErhardt/tuxedo-rs/blob/crisidev/tailor_gui/data/resources/icons.gresource.xml
3. Add the file to your meson.build: https://github.com/AaronErhardt/tuxedo-rs/blob/crisidev/tailor_gui/data/resources/meson.build
4. Add a constant to your config.rs template: https://github.com/AaronErhardt/tuxedo-rs/blob/crisidev/tailor_gui/src/config.rs.in#L8C1-L8C81
5. Load and register the resource within your application: https://github.com/AaronErhardt/tuxedo-rs/blob/crisidev/tailor_gui/src/setup.rs#L18-L19

If you do not use meson, you can do something similar by including the gresource into your binary instead of installing it: https://github.com/Relm4/icons/blob/main/src/lib.rs#L28-L32

Alternatively, you can also contribute or suggest icons for relm4-icons to make them easier to access for others as well.

[chriskilding]

Thanks for the suggestions - based on your second option, I have come up with a Cargo-only approach (which does not require Meson), which is also (fairly) portable across environments, which I'll write up in a separate answer.

[chriskilding]

This is a Cargo-only approach to including resources (like icons) which does not require Meson, and is also (fairly) portable across environments.

We add the following new files:

data/
  icons/
    icon-foo.svg
    icon-bar.svg
  icons.gresource.xml

The icons are placed under the data/icons directory.

The icons.gresource.xml file looks like this (adapt it as required, e.g. using -symbolic icon names):

<?xml version="1.0" encoding="UTF-8"?>
<gresources>
    <gresource prefix="com/example/Foobar/icons/24x24/actions/">
        <file preprocess="xml-stripblanks" alias="icon-foo.svg">icons/icon-foo.svg</file>
        <file preprocess="xml-stripblanks" alias="icon-bar.svg">icons/icon-bar.svg</file>
    </gresource>
</gresources>

In Cargo.toml, we add a build dependency on glib-build-tools, which gives us access to the glib_build_tools::compile_resources function:

[package]
name = "foobar"

[build-dependencies]
glib-build-tools = "0.17.10"

In build.rs, we call the compile_resources function which creates a Gresource bundle from the icons:

use glib_build_tools::compile_resources;

fn main() {
    compile_resources(
        &["data"],
        "data/icons.gresource.xml",
        "icons.gresource",
    );
}

Finally, in main.rs (or wherever you initialise your Relm app), we load the icons.gresource bundle:

fn initialize_custom_icons() {
    gio::resources_register_include!("icons.gresource").unwrap();

    let display = gdk::Display::default().unwrap();
    let theme = gtk::IconTheme::for_display(&display);
    theme.add_resource_path("/com/example/Foobar/icons");
}

fn main() {
    let app = RelmApp::new("com.example.Foobar");

    // default icons
    relm4_icons::initialize_icons();

    // custom icons
    initialize_custom_icons();
}

---

Side note: By adding a Cargo dependency on glib-build-tools, rather than calling it in a shell command (as some examples would have you do), we make the build.rs a little more robust, and it also ensures the build.rs works well within IDEs like IntelliJ.

[chriskilding]

If this approach is generally suitable for Relm4 apps, I would be happy to write it up as a new page in the Relm4 book - just let me know

[chriskilding]

Written up in Relm4/book#49

[frehberg]

not exactly an Icon, but this example shows how to embed PNG images (Logos) into your executable https://github.com/Relm4/Relm4/blob/main/examples/embedded_logo.rs