gtk.Image

gtk.Image
Prev	The gtk Class Reference	Next

gtk.Image — A widget displaying an image

Synopsis

class gtk.Image(gtk.Misc):
    gtk.Image()
    def set_from_pixmap(pixmap, mask)
    def set_from_image(gdk_image, mask)
    def set_from_file(filename)
    def set_from_pixbuf(pixbuf)
    def set_from_stock(stock_id, size)
    def set_from_icon_set(icon_set, size)
    def set_from_animation(animation)
    def get_storage_type()
    def get_pixmap()
    def get_image()
    def get_pixbuf()
    def get_stock()
    def get_icon_set()
    def get_animation()
    def get_icon_name()
    def set_from_icon_name(icon_name, size)
    def set_pixel_size(pixel_size)
    def get_pixel_size()
    def clear()
    def set_from_gicon(gicon, size)

Functions

    def gtk.image_new_from_stock(stock_id, size)
    def gtk.image_new_from_icon_set(icon_set, size)
    def gtk.image_new_from_animation(animation)
    def gtk.image_new_from_icon_name(icon_name, size)
    def gtk.image_new_from_pixmap(pixmap, mask)
    def gtk.image_new_from_image(image, mask)
    def gtk.image_new_from_file(filename)
    def gtk.image_new_from_pixbuf(pixbuf)
    def gtk.image_new_from_gicon(gicon, size)

Ancestry

+-- gobject.GObject
  +-- gtk.Object
    +-- gtk.Widget
      +-- gtk.Misc
        +-- gtk.Image

Implemented Interfaces

gtk.Image implements gtk.Buildable

gtk.Image Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Misc Properties

"file"	Write	A filename containing the image data. Default value: `None`
"gicon"	Read-Write	The GIcon displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically. Available in GTK 2.14 and above.
"icon-name"	Read-Write	The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically. Default value: `None`. Available in GTK 2.6 and above.
"icon-set"	Read-Write	the `gtk.IconSet` to display
"icon-size"	Read-Write	the size to use for a stock icon, named icon or icon set. Allowed values: >= 0. Default value: 4
"image"	Read-Write	a `gtk.gdk.Image` to display
"mask"	Read-Write	a bitmap `gtk.gdk.Pixmap` to use with a `gtk.gdk.Image` or a `gtk.gdk.Pixmap`
"pixbuf"	Read-Write	the `gtk.gdk.Pixbuf` to display
"pixbuf-animation"	Read-Write	the `gtk.gdk.PixbufAnimation` to display
"pixel-size"	Read-Write	a fixed size overriding the "icon-size" property for images of type `gtk.IMAGE_ICON_NAME`. Allowed values: >= -1. Default value: -1. Available in GTK+ 2.6 and above.
"pixmap"	Read-Write	a `gtk.gdk.Pixmap` to display
"stock"	Read-Write	the stock ID for a stock image to display. Default value: `None`
"storage-type"	Read	the type of the image data; one of the GTK Image Type Constants: `gtk.IMAGE_EMPTY`, `gtk.IMAGE_PIXMAP`, `gtk.IMAGE_IMAGE`, `gtk.IMAGE_PIXBUF`, `gtk.IMAGE_STOCK`, `gtk.IMAGE_ICON_SET` or `gtk.IMAGE_ANIMATION`

gtk.Image Style Properties

gtk.Widget Style Properties

gtk.Image Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

Description

The gtk.Image widget displays an image. Various kinds of objects can be displayed as an image; usually, you would load a gtk.gdk.Pixbuf ("pixel buffer") from a file, and then display it. The convenience method set_from_file() will read the file and automatically create a pixbuf that is added to the gtk.Image widget. If the file isn't loaded successfully, the image will contain a "broken image" icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with gtk.gdk.pixbuf_new_from_file(), then add it to the gtk.Image with the set_from_pixbuf() method. The image file may contain an animation; if so, the gtk.Image will display an animation (gtk.gdk.PixbufAnimation) instead of a static image.

gtk.Image is a subclass of gtk.Misc, which implies that you can align it (center, left, right) and add padding to it, using the gtk.Misc methods. gtk.Image is a "no window" widget (has no gtk.gdk.Window of its own), so by default does not receive events. If you want to receive events on the image, such as button clicks, place the image inside a gtk.EventBox, then connect to the event signals on the event box.

When handling events on the event box, keep in mind that coordinates in the image may be different from event box coordinates due to the alignment and padding settings on the image (see gtk.Misc). The simplest way to solve this is to set the alignment to 0.0 (left/top), and set the padding to zero. Then the origin of the image will be the same as the origin of the event box.

Sometimes an application will want to avoid depending on external data files, such as image files. GTK+ comes with a program to avoid this, called gdk-pixbuf-csource. This program allows you to convert an image into a C variable declaration, which can then be loaded into a gtk.gdk.Pixbuf using the gtk.gdk.pixbuf_new_from_inline() function. This can also be used in PyGTK by modifying the output using an editor or the sed command as follows:

  gdk-pixbuf-csource imagefile | \
          sed -n -e 's/{/[/' -e 's/};/]/' -e '/".*"/p' >outfile

You can edit outfile into a Python file where it will be evaluated to a list containing a string. The string can be used directly with the gtk.gdk.pixbuf_new_from_inline() function to create a pixbuf that can be used in a gtk.Image.

Constructor

    gtk.Image()

Returns :

a newly created gtk.Image widget.

Creates a new empty gtk.Image widget.

Methods

gtk.Image.set_from_pixmap

    def set_from_pixmap(pixmap, mask)

`pixmap` :	a `gtk.gdk.Pixmap`
`mask` :	a bitmap `gtk.gdk.Pixmap` or `None`

The set_from_pixmap() method sets the image data from pixmap using mask.

gtk.Image.set_from_image

    def set_from_image(gdk_image, mask)

`gdk_image` :	a `gtk.gdk.Image` or `None`
`mask` :	a bitmap `gtk.gdk.Pixmap` or `None`

The set_from_image() method sets the image data from image using mask. A gtk.gdk.Image is a client-side image buffer in the pixel format of the current display. If image is None the current image data will be removed.

gtk.Image.set_from_file

    def set_from_file(filename)

filename :

a filename or None

The set_from_file() method sets the image data from the contents of the file named filename. If the file isn't found or can't be loaded, the resulting gtk.Image will display a "broken image" icon. This function never returns None, it always returns a valid gtk.Image widget. If the file contains an animation, the image will contain an animation. If filename is None the current image data will be removed.

If you need to detect failures to load the file, use gtk.gdk.pixbuf_new_from_file() to load the file yourself, then create the gtk.Image from the pixbuf. (Or for animations, use the gtk.gdk.PixbufAnimation() constructor.

gtk.Image.set_from_pixbuf

    def set_from_pixbuf(pixbuf)

pixbuf :

a gtk.gdk.Pixbuf or None

The set_from_pixbuf() method sets the image data using pixbuf. Note that this function just creates an gtk.Image from pixbuf. The gtk.Image created will not react to state changes. Should you want that, you should use the set_from_icon_set() method If pixbuf is None the current image data will be removed.

gtk.Image.set_from_stock

    def set_from_stock(stock_id, size)

`stock_id` :	a stock icon name
`size` :	a stock icon size

The set_from_stock() method sets the image data from the stock item identified by stock_id. Sample stock icon names are gtk.STOCK_OPEN and gtk.STOCK_OK. Stock icon sizes are gtk.ICON_SIZE_MENU, gtk.ICON_SIZE_SMALL_TOOLBAR, gtk.ICON_SIZE_LARGE_TOOLBAR, gtk.ICON_SIZE_BUTTON, gtk.ICON_SIZE_DND and gtk.ICON_SIZE_DIALOG. If the stock icon name isn't known, a "broken image" icon will be displayed instead. You can register your own stock icon names, see the gtk.IconFactory.add_default() and gtk.IconFactory.add() methods.

The stock icons are described in the Stock Items reference.

gtk.Image.set_from_icon_set

    def set_from_icon_set(icon_set, size)

`icon_set` :	a `gtk.IconSet`
`size` :	a stock icon size

The set_from_icon_set() method sets the image data from icon_set with the size specified by size. Stock icon sizes are gtk.ICON_SIZE_MENU, gtk.ICON_SIZE_SMALL_TOOLBAR, gtk.ICON_SIZE_LARGE_TOOLBAR, gtk.ICON_SIZE_BUTTON, gtk.ICON_SIZE_DND and gtk.ICON_SIZE_DIALOG.

gtk.Image.set_from_animation

    def set_from_animation(animation)

animation :

the gtk.gdk.PixbufAnimation

The set_from_animation() method sets the image data from animation.

gtk.Image.get_storage_type

    def get_storage_type()

Returns :

the type of the image representation being used

The get_storage_type() method gets the type of representation being used by the gtk.Image to store image data. If the gtk.Image has no image data, the return value will be gtk.IMAGE_EMPTY. The image type is one of: gtk.IMAGE_EMPTY, gtk.IMAGE_PIXMAP, gtk.IMAGE_IMAGE, gtk.IMAGE_PIXBUF, gtk.IMAGE_STOCK, gtk.IMAGE_ICON_SET or gtk.IMAGE_ANIMATION.

gtk.Image.get_pixmap

    def get_pixmap()

Returns :

a tuple containing the pixmap (or None) and the mask (or None)

The get_pixmap() method returns a tuple containing the pixmap and mask being displayed by the gtk.Image. Either or both the pixmap and mask may be None. If the storage type of the image is not either gtk.IMAGE_EMPTY or gtk.IMAGE_PIXMAP the ValueError exception will be raised.

gtk.Image.get_image

    def get_image()

Returns :

a tuple containing a gtk.gdk.Image and a mask bitmap

The get_image() method returns a tuple containing the gtk.gdk.Image and mask being displayed by the gtk.Image. One or both of the gtk.gdk.Image and mask may be None. If the storage type of the image is not either of gtk.IMAGE_EMPTY or gtk.IMAGE_IMAGE the ValueError exception will be raised.

gtk.Image.get_pixbuf

    def get_pixbuf()

Returns :

the displayed pixbuf, or None if the image is empty

The get_pixbuf() method gets the gtk.gdk.Pixbuf being displayed by the gtk.Image. The return value may be None if no image data is set. If the storage type of the image is not either gtk.IMAGE_EMPTY or gtk.IMAGE_PIXBUF the ValueError exception will be raised.

gtk.Image.get_stock

    def get_stock()

Returns :

a tuple containing the stock icon name and the stock icon size of the image data

The get_stock() method returns a tuple containing the stock icon identifier (may be None) and size being displayed by the gtk.Image. The size will 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 or gtk.ICON_SIZE_DIALOG. If the storage type of the image is not either gtk.IMAGE_EMPTY or gtk.IMAGE_STOCK the ValueError exception will be raised.

gtk.Image.get_icon_set

    def get_icon_set()

Returns :

a tuple containing a gtk.IconSet and a stock icon size

The get_icon_set() method returns a tuple containing the icon set (may be None) and size being displayed by the gtk.Image. The size will 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 or gtk.ICON_SIZE_DIALOG. If the storage type of the image is not either gtk.IMAGE_EMPTY or gtk.IMAGE_ICON_SET the ValueError exception will be raised.

gtk.Image.get_animation

    def get_animation()

Returns :

the displayed animation, or None if the image is empty

The get_animation() method gets the gtk.gdk.PixbufAnimation (may be None if there is no image data) being displayed by the gtk.Image. If the storage type of the image is not either gtk.IMAGE_EMPTY or gtk.IMAGE_ANIMATION the ValueError exception will be raised.

gtk.Image.get_icon_name

    def get_icon_name()

Returns :

a 2-tuple containing the name and size of the displayed icon.

Note

This method is available in PyGTK 2.6 and above.

The get_icon_name() method returns a 2-tuple containing the values of the "icon-name" and "icon-size" properties respectively if the "icon-name" property is not None. If the "icon-name" property is None the 2-tuple returned will be:

  (None, <enum GTK_ICON_SIZE_INVALID of type GtkIconSize>)

gtk.Image.set_from_icon_name

    def set_from_icon_name(icon_name, size)

`icon_name` :	an icon name
`size` :	a stock icon size

Note

This method is available in PyGTK 2.6 and above.

The set_from_icon_name() method sets the "icon-name" and "icon-size" properties to the values of icon_name and size respectively. icon_name should be the name of an icon in the current icon theme. If icon_name isn't known, a "broken image" icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.

gtk.Image.set_pixel_size

    def set_pixel_size(pixel_size)

pixel_size :

the new pixel size to be used for named icons

Note

This method is available in PyGTK 2.6 and above.

The set_pixel_size() method sets the "pixel-size" property to the value specified by pixel_size. If the pixel size is set to a value != -1 the "pixel-size" property is used instead of the icon size set by the set_from_icon_name() method.

gtk.Image.get_pixel_size

    def get_pixel_size()

Returns :

the pixel size used for named icons.

Note

This method is available in PyGTK 2.6 and above.

The get_pixel_size() method returns the value of the "pixel-size" property which specifies the pixel size to be used for named icons.

gtk.Image.clear

    def clear()

Note

This method is available in PyGTK 2.8 and above.

The clear() method removes the current image, if any, and resets the "storage-type", "mask" and "icon-size" properties. One of the "file", "icon-name", "icon-set", "image", "pixbuf", "pixbuf-animation", "pixmap" or "stock" will be reset if there was an existing image.

gtk.Image.set_from_gicon

    def set_from_gicon(icon, size)

`icon` :	an icon
`size` :	an icon size

Note

This method is available in PyGTK 2.14 and above.

For the set_from_gicon() method see gtk.image_new_from_gicon() for details.

Functions

gtk.image_new_from_stock

    def gtk.image_new_from_stock(stock_id, size)

`stock_id` :	a stock icon name
`size` :	an integer representing an icon size
Returns :	a new `gtk.Image` displaying the stock icon

The gtk.image_new_from_stock() function returns a new gtk.Image displaying the stock icon specified by stock_id with the specified size. Sample stock icon names are gtk.STOCK_OPEN, gtk.STOCK_OK - see the set_from_stock() method for detailed information on the PyGTK stock icons. . Sample stock sizes are gtk.ICON_SIZE_MENU, gtk.ICON_SIZE_SMALL_TOOLBAR - see the gtk.icon_size_lookup() function for more detail. If the stock icon name isn't known, a "broken image" icon will be displayed instead. You can register your own stock icon names, see the gtk.IconFactory.add_default() and gtk.IconFactory.add() methods.

gtk.image_new_from_icon_set

    def gtk.image_new_from_icon_set(icon_set, size)

`icon_set` :	a `gtk.IconSet` object
`size` :	an integer representing an icon size
Returns :	a new `gtk.Image` object

The gtk.image_new_from_icon_set() function returns a new gtk.Image created from the gtk.IconSet specified by icon_set with the specified size. Sample stock sizes are gtk.ICON_SIZE_MENU, gtk.ICON_SIZE_SMALL_TOOLBAR - see the gtk.icon_size_lookup() function for more detail. Instead of using this function, usually it's better to create a gtk.IconFactory, put your icon sets in the icon factory, add the icon factory to the list of default factories with the add_default() method, and then use the gtk.image_new_from_stock() function. This will allow themes to override the icon you ship with your application.

gtk.image_new_from_animation

    def gtk.image_new_from_animation(animation)

`animation` :	a `gtk.gdk.PixbufAnimation` object
Returns :	a new `gtk.Image` object

The gtk.image_new_from_animation() function returns a new gtk.Image object containing the gtk.gdk.PixbufAnimation specified by animation.

gtk.image_new_from_icon_name

    def gtk.image_new_from_icon_name(icon_name, size)

`icon_name` :	an icon name
`size` :	a stock icon size
Returns :	a new `gtk.Image` widget.

Note

This function is available in PyGTK 2.6 and above.

The gtk.image_new_from_icon_name() function returns a new gtk.Image object displaying the named theme icon specified by icon_name with the icon size specified by size. If the icon name isn't known, a "broken image" icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. The "icon-name" and "icon-size" properties are also set by this function.

gtk.image_new_from_pixmap

    def gtk.image_new_from_pixmap(pixmap, mask)

`pixmap` :	a `gtk.gdk.Pixmap`
`mask` :	the bitmap that is the transparency mask.
Returns :	a new `gtk.Image` widget.

Note

This function is available in PyGTK 2.12 and above.

The gtk.image_new_from_pixmap() function returns a new gtk.Image object displaying pixmap with a mask. A gtk.gdk.Pixmap is a server-side image buffer in the pixel format of the current display.

gtk.image_new_from_image

    def gtk.image_new_from_image(image, mask)

`image` :	a `gtk.gdk.Image`
`mask` :	the bitmap that is the transparency mask.
Returns :	a new `gtk.Image` widget.

Note

This function is available in PyGTK 2.12 and above.

The gtk.image_new_from_image() function returns a new gtk.Image object displaying an image with a mask. A gtk.gdk.Image is a client-side image buffer in the pixel format of the current display.

gtk.image_new_from_file

    def gtk.image_new_from_file(filename)

`filename` :	a filename
Returns :	a new `gtk.Image` widget.

Note

This function is available in PyGTK 2.12 and above.

The gtk.image_new_from_file() function returns a new gtk.Image object displaying the file filename. If the file isn't found or can't be loaded, the resulting gtk.Image will display a "broken image" icon. This function never returns None, it always returns a valid gtk.Image widget.

If the file contains an animation, the image will contain an animation.

If you need to detect failures to load the file, use gtk.gdk.pixbuf_new_from_file to load the file yourself, then create the gtk.Image from the pixbuf. (Or for animations, use gtk.gdk.PixbufAnimation. The storage type (get_storage_type) of the returned image is not defined, it will be whatever is appropriate for displaying the file.

gtk.image_new_from_pixbuf

    def gtk.image_new_from_pixbuf(pixbuf)

`pixbuf` :	a `gtk.gdk.Pixbuf`
Returns :	a new `gtk.Image` widget.

Note

This function is available in PyGTK 2.12 and above.

The gtk.image_new_from_pixbuf() function returns a new gtk.Image object displaying pixbuf

Note that this function just creates a gtk.Image from the pixbuf. The gtk.Image created will not react to state changes. Should you want that, you should use gtk.image_new_from_icon_set

gtk.image_new_from_gicon

    def gtk.image_new_from_gicon(gicon, size)

`gicon` :	a `gio.Icon`
`size` :	a stock icon size.
Returns :	a new `gtk.Image` displaying the themed icon.

Note

This function is available in PyGTK 2.14 and above.

The gtk.image_new_from_pixbuf() function returns a new gtk.Image displaying an icon from the current icon theme. If the icon name isn't known, a "broken image" icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.

Prev	Up	Next
gtk.IconView	Home	gtk.ImageMenuItem