gtk.Image
Prev | The gtk Class Reference | Next

## gtk.Image

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()

    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)

## 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`
"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.

## 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

Prev | Up | Next
gtk.IconView | Home | gtk.ImageMenuItem