Themable Application-specific Icons

Some applications could need custom named icons, i.e. named icons not listed in Icon Naming Spec.

This page will explain to GNOME/GTK+ developers a method to install and use custom named icon. The suggested method will allow developers to provide themeable icons for their applications without causing file conflicts with other packages.

Here are also listed known app-specific named icon, to help artist to build up a complete icon theme for the GNOME Desktop.

Thanks to Rodney Dawes for the original idea.

How to Install Application-specific Named Icon

You have to install application-specific named icons in a special location in filesystem.

This location is ${prefix}/share/<appname>/icons/hicolor/<size>/<context>, where context is one of the the Context directories for icon theme as defined in Context section of Icon Naming Spec and size is the icon size as suggested by the Tango Style Guidelines.

Be sure to use the exact directory name defined in the spec, or the installed icons will be ignored. This because you don't need to provide an index.theme file to make installed pixmaps available as icon theme, but the application will automatically use the one provided by the hicolor-icon-theme. The suggested version of hicolor-icon-theme is the 0.10, providing all context defined in Icon Naming Spec.

Please note that this is relevant only for icons to use inside your application, not for the application icon to use in system menus, and the app's about box and window titlebars. This icon should be installed in system-wide hicolor theme directory (${prefix}/share/icons/hicolor). So, don't install icons that belongs to Applications context in this way. Follow instead those instructions.

How to Use Installed Application Specific Named Icons

In your application, where you initialize GTK+, you also want to do the following, so that your application will find these icons if the theme tree structure in use, doesn't provide them: 

gtk_icon_theme_append_search_path (gtk_icon_theme_get_default (),
                                   APPNAME_DATA_DIR G_DIR_SEPARATOR_S "icons");

You can define APPNAME_DATA_DIR in your Makefile.am using for example: 

INCLUDES = \
        -I$(top_srcdir)                          \
        -I$(top_builddir)                        \
        ...
        -DAPPNAME_DATA_DIR=\"$(pkgdatadir)\"     \
        ...
        $(DISABLE_DEPRECATED)                    \
        $(FR_CFLAGS)

This adds the $pkgdatadir/icons directory to the search path, and GtkIconTheme will then look in here for icons as well as the standard search paths. You can also provide icons for other themes in here, by installing them into a subdirectory for that theme.

Known Applications

Here is a list of GNOME Desktop application that are currenly using this method. Each entry in the list will open a page listing app-specific themable icons installed by this application

And outside the GNOME Desktop module

Example

So, let's assume that you want provide "import", "export" (Actions context), and "conversion-running" (Status context) named and themable icons for your application. To avoid file conflicts with other applications (import, export and conversion-running could be common tasks), you can't install icons in system-wide hicolor theme directory. You have to provide them as app-specific themable icons.

Method 1: Use Helper Script

There is a semi-automated script which will do this for you. The icon-theme-installer script can be used from within make to properly install lots of icons into the theme and also update the icon cache.

Method 2: Add Code in Makefile.am

themedir = $(pkgdatadir)/icons/hicolor
size = 16x16
context = actions

iconsdir = $(themedir)/$(size)/$(context)

icons_DATA = \
        import.png   \
        export.png

noinst_DATA = \
        import.xcf  \
        export.xcf

EXTRA_DIST = \
        $(icons_DATA)   \
        $(noinst_DATA)

themedir = $(pkgdatadir)/icons/hicolor
size = 16x16
context = status

iconsdir = $(themedir)/$(size)/$(context)

icons_DATA = \
        conversion-running.png

noinst_DATA = \
        conversion-running.svg

EXTRA_DIST = \
        $(icons_DATA)   \
        $(noinst_DATA)

ThemableAppSpecificIcons (last edited 2008-04-13 08:46:12 by BaptisteMilleMathias)