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.