## XfceIconTheme

XfceIconTheme — a class for looking up themed icons.

## Synopsis

    #include <libxfcegui4/libxfcegui4.h>

    struct      XfceIconTheme;
    enum        XfceIconThemeCategory;
    XfceIconTheme* xfce_icon_theme_get_for_screen
                                                (GdkScreen *screen);
    gchar*      xfce_icon_theme_lookup          (XfceIconTheme *icon_theme,
                                                 const gchar *icon_name,
                                                 gint icon_size);
    gchar*      xfce_icon_theme_lookup_list     (XfceIconTheme *icon_theme,
                                                 GList *icon_names,
                                                 gint icon_size);
    gchar*      xfce_icon_theme_lookup_category (XfceIconTheme *icon_theme,
                                                 XfceIconThemeCategory category,
                                                 gint icon_size);
    GdkPixbuf*  xfce_icon_theme_load            (XfceIconTheme *icon_theme,
                                                 const gchar *icon_name,
                                                 gint icon_size);
    GdkPixbuf*  xfce_icon_theme_load_list       (XfceIconTheme *icon_theme,
                                                 GList *icon_names,
                                                 gint icon_size);
    GdkPixbuf*  xfce_icon_theme_load_category   (XfceIconTheme *icon_theme,
                                                 XfceIconThemeCategory category,
                                                 gint icon_size);
    GList*      xfce_icon_theme_get_search_path (XfceIconTheme *icon_theme);
    void        xfce_icon_theme_set_search_path (XfceIconTheme *icon_theme,
                                                 GList *search_paths);
    void        xfce_icon_theme_prepend_search_path
                                                (XfceIconTheme *icon_theme,
                                                 const gchar *search_path);
    void        xfce_icon_theme_append_search_path
                                                (XfceIconTheme *icon_theme,
                                                 const gchar *search_path);
    XfceIconThemeCategory xfce_icon_theme_register_category
                                                (XfceIconTheme *icon_theme,
                                                 GList *icon_names);
    void        xfce_icon_theme_unregister_category
                                                (XfceIconTheme *icon_theme,
                                                 XfceIconThemeCategory category);

## Object Hierarchy

      GObject
       +----XfceIconTheme

## Signal Prototypes

    "changed"   void        user_function      (XfceIconTheme *icon_theme,
                                                gpointer user_data);

## Description

XfceIconTheme is used to look up themed icons. It is actually a singleton object, so successive calls to `xfce_icon_theme_get_for_screen()` will use any previously-generated icon data, if available. There are three ways of finding icons: with a simple name, with a list of names, or with a predefined category. Custom categories can also be registered. XfceIconTheme uses the XDG basedir spec when determining directories in the icon search path. If you need to change these directories for any reason, an API is provided for that.

## Details

### struct XfceIconTheme

    struct XfceIconTheme;

This struct only contains private data and should not be accessed directly.

### enum XfceIconThemeCategory

    typedef enum
    {
    	XFCE_ICON_CATEGORY_UNKNOWN = 0,
    	XFCE_ICON_CATEGORY_EDITOR,
    	XFCE_ICON_CATEGORY_FILEMAN,
    	XFCE_ICON_CATEGORY_UTILITY,
    	XFCE_ICON_CATEGORY_GAME,
    	XFCE_ICON_CATEGORY_HELP,
    	XFCE_ICON_CATEGORY_MULTIMEDIA,
    	XFCE_ICON_CATEGORY_NETWORK,
    	XFCE_ICON_CATEGORY_GRAPHICS,
    	XFCE_ICON_CATEGORY_PRINTER,
    	XFCE_ICON_CATEGORY_PRODUCTIVITY,
    	XFCE_ICON_CATEGORY_SOUND,
    	XFCE_ICON_CATEGORY_TERMINAL,
    	XFCE_ICON_CATEGORY_DEVELOPMENT,
    	XFCE_ICON_CATEGORY_SETTINGS,
    	XFCE_ICON_CATEGORY_SYSTEM,
    	XFCE_ICON_CATEGORY_WINE,
    	XFCE_N_BUILTIN_ICON_CATEGORIES
    } XfceIconThemeCategory;

These make up the `category` values passed to `xfce_icon_theme_lookup_category()` and `xfce_icon_theme_load_category()`.

`XFCE_ICON_CATEGORY_UNKNOWN` | An icon representing an 'unknown' state.
`XFCE_ICON_CATEGORY_EDITOR` | An icon representing a text editor or other editing application.
`XFCE_ICON_CATEGORY_FILEMAN` | An icon representing a file manager, or applications that do file manipulations.
`XFCE_ICON_CATEGORY_UTILITY` | An icon representing a utility application.
`XFCE_ICON_CATEGORY_GAME` | An icon representing a computer game.
`XFCE_ICON_CATEGORY_HELP` | An icon representing an application used to retrieve help or documentation.
`XFCE_ICON_CATEGORY_MULTIMEDIA` | An icon representing a multimedia application (e.g., a music player).
`XFCE_ICON_CATEGORY_NETWORK` | An icon representing an application that accesses network resources (e.g., a web browser).
`XFCE_ICON_CATEGORY_GRAPHICS` | An icon representing a graphics editing or viewing application.
`XFCE_ICON_CATEGORY_PRINTER` | An icon representing an application that interacts with a printing system.
`XFCE_ICON_CATEGORY_PRODUCTIVITY` | An icon representing a productivity application (e.g., an office suite).
`XFCE_ICON_CATEGORY_SOUND` | An icon representing an application that interacts with sound or sound files.
`XFCE_ICON_CATEGORY_TERMINAL` | An icon representing a terminal emulator.
`XFCE_ICON_CATEGORY_DEVELOPMENT` | An icon representing an application that interacts with a development environment.
`XFCE_ICON_CATEGORY_SETTINGS` | An icon represending an application that allows the user to modify system or desktop settings.
`XFCE_ICON_CATEGORY_SYSTEM` | An icon representing a system management tool.
`XFCE_ICON_CATEGORY_WINE` | An icon represeting a Microsoft(tm) Windows application, or an application that allows users to run Microsoft(tm) Windows applications on a UNIX(tm)-like system.
`XFCE_N_BUILTIN_ICON_CATEGORIES` | The number of builtin icon categories.

### xfce_icon_theme_get_for_screen ()

    XfceIconTheme* xfce_icon_theme_get_for_screen
                                                (GdkScreen *screen);

Retrieves the icon theme for the specified GdkScreen (or `NULL` for the default screen), creating it if necessary.

Since 4.1

`screen` : | A GdkScreen, or `NULL`.
Returns : | A new XfceIconTheme.

### xfce_icon_theme_lookup ()

    gchar*      xfce_icon_theme_lookup          (XfceIconTheme *icon_theme,
                                                 const gchar *icon_name,
                                                 gint icon_size);

Tries to find `icon_name` in the current theme. This function may return a filename of a size different than that requested in `icon_size`, if a scalable icon is found.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`icon_name` : | The name of an icon to look up.
`icon_size` : | The preferred icon size.
Returns : | A filename (free with `g_free()` when done), or `NULL` if no suitable icon could be found.

### xfce_icon_theme_lookup_list ()

    gchar*      xfce_icon_theme_lookup_list     (XfceIconTheme *icon_theme,
                                                 GList *icon_names,
                                                 gint icon_size);

Tries to find one of `icon_names` in the current theme. This function may return a filename of a size different than that requested in `icon_size`, if a scalable icon is found.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`icon_names` : | A list of names of icons to look up, in order of preference.
`icon_size` : | The preferred icon size.
Returns : | A filename (free with `g_free()` when done), or `NULL` if no suitable icon could be found.

### xfce_icon_theme_lookup_category ()

    gchar*      xfce_icon_theme_lookup_category (XfceIconTheme *icon_theme,
                                                 XfceIconThemeCategory category,
                                                 gint icon_size);

Tries to find an icon of type `category` in the current theme. This function may return a filename of a size different than that requested in `icon_size`, if a scalable icon is found. The `category` can be a builtin XfceIconThemeCategory, or a custom category registered with `xfce_icon_theme_register_category()`.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`category` : | The type of icon to look up.
`icon_size` : | The preferred icon size.
Returns : | A filename (free with `g_free()` when done), or `NULL` if no suitable icon could be found.

### xfce_icon_theme_load ()

    GdkPixbuf*  xfce_icon_theme_load            (XfceIconTheme *icon_theme,
                                                 const gchar *icon_name,
                                                 gint icon_size);

Tries to find `icon_name` in the current theme. If a suitable icon can be found, this function will always return an icon of the specified `icon_size`, even if it requires scaling to do so.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`icon_name` : | The name of an icon to look up.
`icon_size` : | The preferred icon size.
Returns : | A new GdkPixbuf (free with `g_object_unref()` when done), or `NULL` if no suitable icon could be found.

### xfce_icon_theme_load_list ()

    GdkPixbuf*  xfce_icon_theme_load_list       (XfceIconTheme *icon_theme,
                                                 GList *icon_names,
                                                 gint icon_size);

Tries to find one of `icon_names` in the current theme. If a suitable icon can be found, this function will always return an icon of the specified `icon_size`, even if it requires scaling to do so.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`icon_names` : | The names of icons to look up.
`icon_size` : | The preferred icon size.
Returns : | A new GdkPixbuf (free with `g_object_unref()` when done), or `NULL` if no suitable icon could be found.

### xfce_icon_theme_load_category ()

    GdkPixbuf*  xfce_icon_theme_load_category   (XfceIconTheme *icon_theme,
                                                 XfceIconThemeCategory category,
                                                 gint icon_size);

Tries to find an icon of type `category` in the current theme. If a suitable icon can be found, this function will always return an icon of the specified `icon_size`, even if it requires scaling to do so. The `category` can be a builtin XfceIconThemeCategory, or a custom category registered with `xfce_icon_theme_register_category()`.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`category` : | The type of icon to look up.
`icon_size` : | The preferred icon size.
Returns : | A new GdkPixbuf (free with `g_object_unref()` when done), or `NULL` if no suitable icon could be found.

### xfce_icon_theme_get_search_path ()

    GList*      xfce_icon_theme_get_search_path (XfceIconTheme *icon_theme);

Retrieves the current icon search path.

Since 4.1

`icon_theme` : | An XfceIconTheme.
Returns : | A GList of search paths. Free with `g_list_free()` when done.

### xfce_icon_theme_set_search_path ()

    void        xfce_icon_theme_set_search_path (XfceIconTheme *icon_theme,
                                                 GList *search_paths);

Sets the current search path to the list of `search_paths`. Note that this will discard any currently-set search path.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`search_paths` : | A GList of path names, each one terminated with '/'.

### xfce_icon_theme_prepend_search_path ()

    void        xfce_icon_theme_prepend_search_path
                                                (XfceIconTheme *icon_theme,
                                                 const gchar *search_path);

Prepends `search_path` to the current icon theme search path.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`search_path` : | A pathname, terminated with '/'.

### xfce_icon_theme_append_search_path ()

    void        xfce_icon_theme_append_search_path
                                                (XfceIconTheme *icon_theme,
                                                 const gchar *search_path);

Appends `search_path` to the current icon theme search path.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`search_path` : | A pathname, terminated with '/'.

### xfce_icon_theme_register_category ()

    XfceIconThemeCategory xfce_icon_theme_register_category
                                                (XfceIconTheme *icon_theme,
                                                 GList *icon_names);

Registers a new XfceIconThemeCategory for use with #`xfce_icon_theme_lookup_category()` and `xfce_icon_theme_load_category()`.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`icon_names` : | A GList of icon names.
Returns : | An identifier that can be used for future category lookups.

### xfce_icon_theme_unregister_category ()

    void        xfce_icon_theme_unregister_category
                                                (XfceIconTheme *icon_theme,
                                                 XfceIconThemeCategory category);

Unregisters `category`, which must have been registered previously with `xfce_icon_theme_register_category()`. After this call, the category may no longer be used for icon lookups.

Since 4.1

`icon_theme` : | An XfceIconTheme.
`category` : | An XfceIconThemeCategory registered previously with `xfce_icon_theme_register_category()`.

## Signals

### The "changed" signal

    void        user_function                  (XfceIconTheme *icon_theme,
                                                gpointer user_data);

Emitted when the current icon theme is switched or GTK+ detects that a change has occurred in the contents of the current icon theme.

Since 4.1

`icon_theme` : | the icon theme
`user_data` : | user data set when the signal handler was connected.