GNOME.org

/!\ This page describes best practices for dialogs in GTK3. With GTK4, some details might be different. /!\

Themed Icons

The GtkIconTheme API gives access to icons that are shipped with the icon theme. Icon themes are a mechanism by which themes can replace icons in all applications, as long as they are using icons that are named according to the icon naming spec.

Extending the icon theme

Sometimes, applications need icons that are too domain-specific to be included in a generic icon theme.

The standard practice for this is to extend the icon theme by installing the icons in a directory structure that matches the hicolor icon theme. Typically, the icons will be located in your application's datadir, e.g. /usr/share/org.gnome.YourApp: 

action_icons_dir = get_option('datadir') / meson.project_name() / 'icons/hicolor/16x16/actions'
action_icons = [
  'action-name-1.png',
  'action-name-2.png',
]

install_data(action_icons, install_dir: action_icons_dir)

Then, add the base directory to the icon theme search path: 

  gtk_icon_theme_append_search_path (gtk_icon_theme_get_default (),
                                     PKG_DATA_DIR "/icons");

Where PKG_DATA_DIR is a pre-processor symbol that expands to your application's datadir.

It is recommended to follow the principles of the icon naming specification even for these private icons.

This approach to icon theme extension has some advantages over others:

  • The application-specific icons don't pollute the shared namespace for themed icons, and other applications won't unintentionally pick up an icon that was only meant for your application
  • Since the icons are installed into a directory below 'hicolor', the theme can override the icons to make your application fit in with the rest of the system.

Note that GTK4 has replaced gtk_icon_theme_get_default() with gtk_icon_theme_get_for_display (gdk_display_get_default()).

Resources

Starting with GTK 3.14, it is possible to include application-specific icons directly in the application binary as resources, instead of installing them in the file system.

To do so, place your icons in a resource directory structure that matches the hicolor icon theme: 

<gresources>
  <gresource prefix="/my/resources/icons/16x16/actions">
    <file>icon1.png</file>
    <file>icon2.png</file>
    ...
  </gresource>
</gresources>

Note that in contrast to the search path example, we don't include 'hicolor' in the path.

Then, tell GtkIconTheme about the resource path where your icons are located: 

  gtk_icon_theme_add_resource_path (gtk_icon_theme_get_default (),
                                    "/my/resources/icons");

Using resources for icons has some advantages:

  • Less file system lookups and searches
  • No 'broken installation' error condition to deal with

But there is also some downsides:

  • Changing an icon requires rebuilding the binary
  • The binary gets bigger

Automatic resources

GtkApplication automatically sets up a resource path based on the application id of your application. If your applications id is 'org.my.App', then icons will be looked for under "/org/my/App/icons".

Flipped icons

Some icons benefit from being 'flipped' in right-to-left (rtl) locales. In the past, applications had to do this manually, by appending an -rtl (or -ltr) suffix to the icon name. Since 3.14, GTK does this automatically, by passing a GTK_ICON_LOOKUP_DIR_RTL or GTK_ICON_LOOKUP_DIR_LTR flag to GtkIconTheme when loading icons.

If you are loading icons manually using the GtkIconTheme API, you may want to do the same for icons where flipping is relevant.

Of course, RTL variants must be present in the icon theme for this to make any difference.

Symbolic Icons

Symbolic icons have a simple form, and can be used much like text. The will be recolored according to the context in which they are used. By convention, symbolic icons are named with a -symbolic suffix.

Passing an icon name like "pan-start-symbolic" to GTK functions like gtk_image_set_from_icon_name() will automatically do the right thing. When you are manually loading a symbolic icon using the GtkIconTheme APIs, make sure to use the 'symbolic' variants, such as gtk_icon_info_load_symbolic() to ensure that the icon is properly colored.

When installing your own symbolic icons, you can either install an svg (the traditional form in which symbolic icons are created) or use the gtk-encode-symbolic-svg utility to convert the icon into specially crafted .symbolic.png files, which can be installed into the fixed-size subdirectories of the icon theme: 

gtk-encode-symbolic-svg -o /usr/share/icons/hicolor/48x48/apps my-app-symbolic.svg 48x48

Application icons

The icon theme specification defines a universal fallback theme, called hicolor, in which applications can install icons that need to be known by the rest of the system.

The main example for this is the application icon that is used in the applications desktop file. This icon should be named to match the application name, and be installed in /usr/share/icons/hicolor/48x48/apps/. Other sizes are optional, but a 256x256 icon is the default size used by GNOME in its application grid, so you're strongly encouraged to provide one.

Applications are also encouraged to install a symbolic version of the application icon into the hicolor theme, with the same name and a -symbolic suffix. The symbolic icon will be used in the HighContrast theme. Symbolic icons can be installed as SVG, in the /usr/share/icons/hicolor/symbolic/apps directory (which was added to hicolor in 0.15), or as .symbolic.png files in /usr/share/icons/hicolor/48x48/apps/. Other sizes are optional.