gtk.IconFactory
Prev | The gtk Class Reference | Next

## gtk.IconFactory

gtk.IconFactory — an object that manages a group of icon sets.

## Synopsis

    class gtk.IconFactory(gobject.GObject):
        gtk.IconFactory()
        def add(stock_id, icon_set)
        def lookup(stock_id)
        def add_default()
        def remove_default()

    Functions

        def gtk.icon_factory_lookup_default(stock_id)

## Ancestry

    +-- gobject.GObject
      +-- gtk.IconFactory

## gtk.IconFactory Signal Prototypes

gobject.GObject Signal Prototypes

## Description

A `gtk.IconFactory` manages a group of `gtk.IconSet`s that manage a set of variants (for different sizes and states) of a specific icon. Icons in an icon factory are named by a stock ID, which is a simple string identifying the icon e.g "gtk-ok". Each `gtk.Style` has a list of `gtk.IconFactory`s derived from the current theme; those icon factories are consulted first when searching for an icon. If the theme doesn't set a particular icon, the search continues for the icon in a list of default icon factories, maintained by the `add_default`()() and `remove_default`()() methods. Applications with icons should add a default icon factory with their icons, which will allow themes to override the icons for the application.

To display an icon, always use `gtk.Style.lookup_icon_set`() on the widget that will display the icon, or the convenience function `gtk.Widget.render_icon`(). These functions take the theme into account when looking up the icon to use for a given stock ID.

## Constructor

        gtk.IconFactory()

Returns : | a new `gtk.IconFactory` object

Creates a new `gtk.IconFactory`.

## Methods

### gtk.IconFactory.add

        def add(stock_id, icon_set)

`stock_id` : | an icon name
`icon_set` : | an icon set

The `add`() method adds the specified `icon_set` to the icon factory, under the name `stock_id`. the `stock_id` string should include the name of your application, e.g. "myapp-whatever-icon". Normally applications create a `gtk.IconFactory`, then add it to the list of default factories with the `add_default`(). Then they pass the `stock_id` to widgets such as `gtk.Image` to display the icon. Themes can provide an icon with the same name (such as "myapp-whatever-icon") to override your application's default icons. If an icon already existed in the icon factory for `stock_id`, it is unreferenced and replaced with the new `icon_set`.

### gtk.IconFactory.lookup

        def lookup(stock_id)

`stock_id` : | an icon name
Returns : | the icon set named `stock_id`.

The `lookup`() method looks up `stock_id` in the icon factory, returning an icon set if found, otherwise `None`. For display to the user, you should use `gtk.Style.lookup_icon_set`() on the `gtk.Style` for the widget that will display the icon, instead of using this function directly, so that themes are taken into account.

### gtk.IconFactory.add_default

        def add_default()

The `add_default`() method adds the icon factory to the list of icon factories searched by `gtk.Style.lookup_icon_set`(). This means that, for example, `gtk.Image.set_from_stock`() will be able to find icons in the icon factory. There will normally be an icon factory added for each library or application that comes with icons. The default icon factories can be overridden by themes.

### gtk.IconFactory.remove_default

        def remove_default()

The `remove_default`() method removes an icon factory from the list of default icon factories. Not normally used though you might use it for a library that can be unloaded or shut down.

## Functions

### gtk.icon_factory_lookup_default

        def gtk.icon_factory_lookup_default(stock_id)

`stock_id` : | the stock ID to lookup
Returns : | the icon set matching `stock_id` or `None` if no icon set matches

The `gtk.icon_factory_lookup_default`() function returns the `gtk.IconSet` that has the name specified by `stock_id`. If the icon set cannot be found the function returns `None`.

Prev | Up | Next
gtk.HSeparator | Home | gtk.IconInfo