Image

class Image(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget

The GtkImage widget displays an image.

Various kinds of object can be displayed as an image; most typically, you would load a GdkTexture from a file, using the convenience function new_from_file, for instance:

GtkWidget *image = gtk_image_new_from_file ("myfile.png");

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 new_from_file, then create the GtkImage with new_from_paintable.

Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of GResource inside GIO, for details. In this case, resource, new_from_resource, and set_from_resource should be used.

GtkImage displays its image as an icon, with a size that is determined by the application. See Picture if you want to show an image at is actual size.

CSS nodes

GtkImage has a single CSS node with the name image. The style classes .normal-icons or .large-icons may appear, depending on the icon_size property.

Accessibility

GtkImage uses the GTK_ACCESSIBLE_ROLE_IMG role.

Constructors

class Image

classmethod new() → Widget

Creates a new empty GtkImage widget.

classmethod new_from_file(filename: str) → Widget

Creates a new GtkImage displaying the file filename.

If the file isn’t found or can’t be loaded, the resulting GtkImage will display a “broken image” icon. This function never returns None, it always returns a valid GtkImage widget.

If you need to detect failures to load the file, use new_from_file to load the file yourself, then create the GtkImage from the texture.

The storage type (see get_storage_type) of the returned image is not defined, it will be whatever is appropriate for displaying the file.

Parameters:

filename – a filename

classmethod new_from_gicon(icon: Icon) → Widget

Creates a GtkImage 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.

Parameters:

icon – an icon

classmethod new_from_icon_name(icon_name: str | None = None) → Widget

Creates a GtkImage 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.

Parameters:

icon_name – an icon name

classmethod new_from_paintable(paintable: Paintable | None = None) → Widget

Creates a new GtkImage displaying paintable.

The GtkImage does not assume a reference to the paintable; you still need to unref it if you own references. GtkImage will add its own reference rather than adopting yours.

The GtkImage will track changes to the paintable and update its size and contents in response to it.

Parameters:

paintable – a GdkPaintable

classmethod new_from_pixbuf(pixbuf: Pixbuf | None = None) → Widget

Creates a new GtkImage displaying pixbuf.

The GtkImage does not assume a reference to the pixbuf; you still need to unref it if you own references. GtkImage will add its own reference rather than adopting yours.

This is a helper for new_from_paintable, and you can’t get back the exact pixbuf once this is called, only a texture.

Note that this function just creates an GtkImage from the pixbuf. The GtkImage created will not react to state changes. Should you want that, you should use new_from_icon_name.

Deprecated since version 4.12: Use new_from_paintable and new_for_pixbuf instead

Parameters:

pixbuf – a GdkPixbuf

classmethod new_from_resource(resource_path: str) → Widget

Creates a new GtkImage displaying the resource file resource_path.

If the file isn’t found or can’t be loaded, the resulting GtkImage will display a “broken image” icon. This function never returns None, it always returns a valid GtkImage widget.

If you need to detect failures to load the file, use new_from_file to load the file yourself, then create the GtkImage from the pixbuf.

The storage type (see get_storage_type) of the returned image is not defined, it will be whatever is appropriate for displaying the file.

Parameters:

resource_path – a resource path

Methods

class Image

clear() → None

Resets the image to be empty.

get_gicon() → Icon | None

Gets the GIcon being displayed by the GtkImage.

The storage type of the image must be EMPTY or GICON (see get_storage_type). The caller of this function does not own a reference to the returned GIcon.

get_icon_name() → str | None

Gets the icon name and size being displayed by the GtkImage.

The storage type of the image must be EMPTY or ICON_NAME (see get_storage_type). The returned string is owned by the GtkImage and should not be freed.

get_icon_size() → IconSize

Gets the icon size used by the image when rendering icons.

get_paintable() → Paintable | None

Gets the image GdkPaintable being displayed by the GtkImage.

The storage type of the image must be EMPTY or PAINTABLE (see get_storage_type). The caller of this function does not own a reference to the returned paintable.

get_pixel_size() → int

Gets the pixel size used for named icons.

get_storage_type() → ImageType

Gets the type of representation being used by the GtkImage to store image data.

If the GtkImage has no image data, the return value will be EMPTY.

set_from_file(filename: str | None = None) → None

Sets a GtkImage to show a file.

See new_from_file for details.

Parameters:

filename – a filename

set_from_gicon(icon: Icon) → None

Sets a GtkImage to show a GIcon.

See new_from_gicon for details.

Parameters:

icon – an icon

set_from_icon_name(icon_name: str | None = None) → None

Sets a GtkImage to show a named icon.

See new_from_icon_name for details.

Parameters:

icon_name – an icon name

set_from_paintable(paintable: Paintable | None = None) → None

Sets a GtkImage to show a GdkPaintable.

See new_from_paintable for details.

Parameters:

paintable – a GdkPaintable

set_from_pixbuf(pixbuf: Pixbuf | None = None) → None

Sets a GtkImage to show a GdkPixbuf.

See new_from_pixbuf for details.

Note: This is a helper for set_from_paintable, and you can’t get back the exact pixbuf once this is called, only a paintable.

Deprecated since version 4.12: Use set_from_paintable instead

Parameters:

pixbuf – a GdkPixbuf or NULL

set_from_resource(resource_path: str | None = None) → None

Sets a GtkImage to show a resource.

See new_from_resource for details.

Parameters:

resource_path – a resource path

set_icon_size(icon_size: IconSize) → None

Suggests an icon size to the theme for named icons.

Parameters:

icon_size – the new icon size

set_pixel_size(pixel_size: int) → None

Sets the pixel size to use for named icons.

If the pixel size is set to a value != -1, it is used instead of the icon size set by set_from_icon_name.

Parameters:

pixel_size – the new pixel size

Properties

class Image

props.file: str

A path to the file to display.

props.gicon: Icon

The GIcon displayed in the GtkImage.

For themed icons, If the icon theme is changed, the image will be updated automatically.

props.icon_name: str

The name of the icon in the icon theme.

If the icon theme is changed, the image will be updated automatically.

props.icon_size: IconSize

The symbolic size to display icons at.

props.paintable: Paintable

The GdkPaintable to display.

props.pixel_size: int

The size in pixels to display icons at.

If set to a value != -1, this property overrides the icon_size property for images of type GTK_IMAGE_ICON_NAME.

props.resource: str

A path to a resource file to display.

props.storage_type: ImageType

The representation being used for image data.

props.use_fallback: bool

Whether the icon displayed in the GtkImage will use standard icon names fallback.

The value of this property is only relevant for images of type ICON_NAME and GICON.