gtk.IconSource
Prev | The gtk Class Reference | Next

## gtk.IconSource

gtk.IconSource — a source for icon variants

## Synopsis

    class gtk.IconSource(gobject.GBoxed):
        gtk.IconSource()
        def copy()
        def free()
        def set_filename(filename)
        def set_pixbuf(pixbuf)
        def get_filename()
        def get_pixbuf()
        def set_direction_wildcarded(setting)
        def set_state_wildcarded(setting)
        def set_size_wildcarded(setting)
        def get_size_wildcarded()
        def get_state_wildcarded()
        def get_direction_wildcarded()
        def set_direction(direction)
        def set_state(state)
        def set_size(size)
        def get_direction()
        def get_state()
        def get_size()
        def set_icon_name(icon_name)
        def get_icon_name()

    Functions

        def gtk.icon_size_lookup(icon_size)
        def gtk.icon_size_lookup_for_settings(settings, icon_size)
        def gtk.icon_size_register(name, width, height)
        def gtk.icon_size_register_alias(alias, target)
        def gtk.icon_size_from_name(name)
        def gtk.icon_size_get_name(size)

## Description

A `gtk.IconSource` contains a `gtk.gdk.Pixbuf` (or an image filename) that serves as the base image for one or more of the icons in a `gtk.IconSet`, along with a specification for which icons in the icon set will be based on that pixbuf or image file. By default, the icon source has all parameters wildcarded. That is, the icon source can be used as the base icon for any desired text direction, widget state, or icon size.

## Constructor

        gtk.IconSource()

Returns : | a new `gtk.IconSource`

Creates a new `gtk.IconSource`. A `gtk.IconSource` contains a `gtk.gdk.Pixbuf` (or image filename) that serves as the base image for one or more of the icons in a `gtk.IconSet`, along with a specification for which icons in the icon set will be based on that pixbuf or image file. By default, the icon source has all parameters wildcarded. That is, the icon source will be used as the base icon for any desired text direction, widget state, or icon size.

## Methods

### gtk.IconSource.copy

        def copy()

Returns : | a new `gtk.IconSource`

The `copy`() method creates a copy of the icon source.

### gtk.IconSource.free

        def free()

### Warning

This method is deprecated and should not be used. Use of this method may cause your application to crash.

The `free`() method frees a dynamically-allocated icon source, along with its filename, size, and pixbuf fields if those are not `None`.

### gtk.IconSource.set_filename

        def set_filename(filename)

`filename` : | the image file to use

The `set_filename`() method sets the name of the image file (specified by `filename`) to use as the base image when creating icon variants for a `gtk.IconSet`. The filename must be absolute.

### gtk.IconSource.set_pixbuf

        def set_pixbuf(pixbuf)

`pixbuf` : | the pixbuf to use as a source

The `set_pixbuf`() method sets a pixbuf (specified by `pixbuf`) to use as a base image when creating icon variants for a `gtk.IconSet`. If an icon source has both a filename and a pixbuf set, the pixbuf will take priority.

### gtk.IconSource.get_filename

        def get_filename()

Returns : | the image filename

The `get_filename`() method retrieves the source filename, or `None` if none is set.

### gtk.IconSource.get_pixbuf

        def get_pixbuf()

Returns : | the source pixbuf

The `get_pixbuf`() method retrieves the source pixbuf, or `None` if none is set.

### gtk.IconSource.set_direction_wildcarded

        def set_direction_wildcarded(setting)

`setting` : | if `True` wildcard the text direction

The `set_direction_wildcarded`() method determines whether the icon source direction is wildcarded according to the value specified by `setting`. If `setting` is `True` the text direction is wildcarded and the icon source can be used as the base image for an icon in any text direction (`gtk.TEXT_DIR_NONE`, `gtk.TEXT_DIR_LTR` or `gtk.TEXT_DIR_RTL`). If the text direction is not wildcarded, then the text direction the icon source applies to should be set with the `set_direction`() method and the icon source will only be used with that text direction. Non-wildcarded icon sources (exact matches) are preferred over wildcarded icon sources. An exact match will be used when possible.

### gtk.IconSource.set_state_wildcarded

        def set_state_wildcarded(setting)

`setting` : | if `True` wildcard the widget state

The `set_state_wildcarded`() method determines whether the icon source state is wildcarded according to the value of `setting`. If `setting` is `True` the widget state is wildcarded and the icon source can be used as the base image for an icon in any widget state (`gtk.STATE_NORMAL`, `gtk.STATE_ACTIVE`, `gtk.STATE_PRELIGHT`, `gtk.STATE_SELECTED` or `gtk.STATE_INSENSITIVE`). If the widget state is not wildcarded, then the widget state the icon source applies to should be set with the `set_state`() method and the icon source will only be used with that specific state. Non-wildcarded icon sources (exact matches) are preferred over wildcarded icon sources. An exact match will be used when possible.

A `gtk.IconSet` will normally transform wildcarded icon source images to produce an appropriate icon for a given state, for example lightening an image on prelight, but will not modify source images that match exactly.

### gtk.IconSource.set_size_wildcarded

        def set_size_wildcarded(setting)

`setting` : | if `True` wildcard the widget state

The `set_size_wildcarded`() determines whether the icon source can be used as the basis for an icon of any size according to the value of `setting`. If `setting` is `True` the icon size is wildcarded and the icon source can be used as the base image for an icon of any size. If the size is not wildcarded, then the size the icon source applies to should be set with `gtk.IconSource.set_size()` and the icon source will only be used with that specific size. Non-wildcarded icon sources (exact matches) are preferred over wildcarded icon sources. An exact match will be used when possible.

`gtk.IconSet` will normally scale wildcarded source images to produce an appropriate icon at a given size, but will not change the size of source images that match exactly.

### gtk.IconSource.get_size_wildcarded

        def get_size_wildcarded()

Returns : | `True` if this icon source is a base for any icon size variant

The `get_size_wildcarded`() method gets the value set by the `set_size_wildcarded`() method.

### gtk.IconSource.get_state_wildcarded

        def get_state_wildcarded()

Returns : | `True` if this icon source is a base for any widget state variant

The `get_state_wildcarded`() method gets the value set by the `set_state_wildcarded`() method.

### gtk.IconSource.get_direction_wildcarded

        def get_direction_wildcarded()

Returns : | `True` if this icon source is a base for any text direction variant

The `get_direction_wildcarded`() method gets the value set by the `set_direction_wildcarded`() method.

### gtk.IconSource.set_direction

        def set_direction(direction)

`direction` : | the text direction this icon source applies to

The `set_direction`() method sets the text direction according to the value of `direction` that the icon source is intended to be used with. The value of direction must be one of: `gtk.TEXT_DIR_NONE`, `gtk.TEXT_DIR_LTR` or `gtk.TEXT_DIR_RTL`.

Setting the text direction on an icon source makes no difference if the text direction is wildcarded. Therefore, you should usually call the `set_direction_wildcarded`() method with a setting of `False` to un-wildcard it in addition to calling this function.

### gtk.IconSource.set_state

        def set_state(state)

`state` : | the widget state this source applies to

The `set_state`() method sets the widget state specified by `state` that the icon source is intended to be used with. The value of `state` must be one of: `gtk.STATE_NORMAL`, `gtk.STATE_ACTIVE`, `gtk.STATE_PRELIGHT`, `gtk.STATE_SELECTED` or `gtk.STATE_INSENSITIVE`. Setting the widget state on an icon source makes no difference if the state is wildcarded. Therefore, you should usually call the `set_state_wildcarded`() method with a setting of `False` to un-wildcard it in addition to calling this function.

### gtk.IconSource.set_size

        def set_size(size)

`size` : | the icon size this source applies to

The `set_size`() method sets the icon size specified by `size` that the icon source is intended to be used with. Setting the icon size for an icon source makes no difference if the size is wildcarded. Therefore, you should usually call the `gtk.IconSource.set_size_wildcarded()` method with a setting of `False` to un-wildcard it in addition to calling this function.

### gtk.IconSource.get_direction

        def get_direction()

Returns : | the text direction the icon source matches

The `get_direction`() method obtains the text direction this icon source applies to. The return value is only useful and meaningful if the text direction is not wildcarded.

### gtk.IconSource.get_state

        def get_state()

Returns : | the widget state the icon source matches

The `get_state`() method obtains the widget state this icon source applies to. The return value is only useful and meaningful if the widget state is not wildcarded.

### gtk.IconSource.get_size

        def get_size()

Returns : | the icon size this source matches.

The `get_size`() method obtains the icon size this source applies to. The return value is only useful and meaningful if the icon size is not wildcarded.

### gtk.IconSource.set_icon_name

        def set_icon_name(icon_name)

`icon_name` : | an icon name to

### Note

This method is available in PyGTK 2.4 and above.

The `set_icon_name`() method uses the name specified by `icon_name` to look up an icon in the current icon theme to use as a base image when creating icon variants for `gtk.IconSet`.

In PyGTK 2.10 and above, `icon_name` may be `None` to unset the icon name.

### gtk.IconSource.get_icon_name

        def get_icon_name()

Returns : | the icon name or `None` if no name is set.

### Note

This method is available in PyGTK 2.4 and above.

The `get_icon`() method returns the source icon name, or `None` if no name is set.

## Functions

### gtk.icon_size_lookup

        def gtk.icon_size_lookup(icon_size)

`icon_size` : | an icon size
Returns : | a 2-tuple containing the width and height of the specified `icon_size`

The `gtk.icon_size_lookup`() function returns a 2-tuple containing the width and height of the icon size specified by `icon_size`. The value of `icon_size` must be one of:

- `gtk.ICON_SIZE_MENU`
- `gtk.ICON_SIZE_SMALL_TOOLBAR`
- `gtk.ICON_SIZE_LARGE_TOOLBAR`
- `gtk.ICON_SIZE_BUTTON`
- `gtk.ICON_SIZE_DND`
- `gtk.ICON_SIZE_DIALOG`

or an integer value returned from the `gtk.icon_size_register`() function.

### gtk.icon_size_lookup_for_settings

        def gtk.icon_size_lookup_for_settings(settings, icon_size)

`settings` : | a `gtk.Settings` object used to determine which user preferences to use.
`icon_size` : | an icon size
Returns : | a 2-tuple containing the width and height of the specified `icon_size` or `None` if `icon_size` was invalid.

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.icon_size_lookup_for_settings`() function returns a 2-tuple containing the width and height of the icon size specified by `icon_size` of `None` if `icon_size` was not valid. The value of `icon_size` must be one of:

- `gtk.ICON_SIZE_MENU`
- `gtk.ICON_SIZE_SMALL_TOOLBAR`
- `gtk.ICON_SIZE_LARGE_TOOLBAR`
- `gtk.ICON_SIZE_BUTTON`
- `gtk.ICON_SIZE_DND`
- `gtk.ICON_SIZE_DIALOG`

or an integer value returned from the `gtk.icon_size_register`() function.

### gtk.icon_size_register

        def gtk.icon_size_register(name, width, height)

`name` : | the name of the icon size
`width` : | the width of the icon size
`height` : | the height of the icon size
Returns : | an integer representing the icon size

The `gtk.icon_size_register`() function registers a new icon size for the specified `width` and `height` with the specified `name` and returns the integer used to represent the icon size.

### gtk.icon_size_register_alias

        def gtk.icon_size_register_alias(alias, target)

`alias` : | an alias for `target`
`target` : | an integer representing an existing icon size

The `gtk.icon_size_register_alias`() function registers the specified `alias` as another name for the icon size specified by `target`.

### gtk.icon_size_from_name

        def gtk.icon_size_from_name(name)

`name` : | a name of an existing icon size
Returns : | the icon size associated with `name`

The `gtk.icon_size_from_name`() function returns the integer representing the icon size associated with the specified `name`.

### gtk.icon_size_get_name

        def gtk.icon_size_get_name(size)

`size` : | an integer representing an existing icon size
Returns : | the name associated with the icon size represented by `size`

The `gtk.icon_size_get_name`() function returns the name of the icon size represented by `size`.

Prev | Up | Next
gtk.IconSet | Home | gtk.IconTheme