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#: The type of the None singleton.

props.gicon: Icon#: The type of the None singleton.

props.icon_name: str#: The type of the None singleton.

props.icon_size: IconSize#: The type of the None singleton.

props.paintable: Paintable#: The type of the None singleton.

props.pixel_size: int#: The type of the None singleton.

props.resource: str#: The type of the None singleton.

props.storage_type: ImageType#: The type of the None singleton.

props.use_fallback: bool#: The type of the None singleton.