Gtk.Image¶

class — extends Widget, Accessible, Buildable, ConstraintTarget

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 Image.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 an image loading framework such as libglycin, then create the GtkImage with Image.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, Image.resource, Image.new_from_resource, and Image.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 Image.icon-size property.

Accessibility¶

GtkImage uses the AccessibleRole.img role.

Constructors¶

new¶

@classmethod
def new(cls) -> Widget

Creates a new empty GtkImage widget.

new_from_file¶

@classmethod
def new_from_file(cls, filename: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> 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 an image loading framework such as libglycin to load the file yourself, then create the GtkImage from the texture.

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

Parameters:

filename — a filename

new_from_gicon¶

@classmethod
def new_from_gicon(cls, icon: Gio.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

new_from_icon_name¶

@classmethod
def new_from_icon_name(cls, icon_name: str | 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

new_from_paintable¶

@classmethod
def new_from_paintable(cls, paintable: Gdk.Paintable | 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.

Note that paintables are still subject to the icon size that is set on the image. If you want to display a paintable at its intrinsic size, use Picture instead.

If paintable is a SymbolicPaintable, then it will be recolored with the symbolic palette from the theme.

Parameters:

paintable — a GdkPaintable

new_from_pixbuf¶

@classmethod
def new_from_pixbuf(cls, pixbuf: GdkPixbuf.Pixbuf | None = ...) -> Widget

:::warning Deprecated since 4.12 This API is deprecated. :::

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 Image.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 Image.new_from_icon_name.

Parameters:

pixbuf — a GdkPixbuf

new_from_resource¶

@classmethod
def new_from_resource(cls, 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 an image loading framework such as libglycin to load the file yourself, then create the GtkImage from the texture.

The storage type (see Image.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¶

clear¶

def clear(self) -> None

Resets the image to be empty.

get_gicon¶

def get_gicon(self) -> Gio.Icon | None

Gets the GIcon being displayed by the GtkImage.

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

get_icon_name¶

def get_icon_name(self) -> str | None

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

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

get_icon_size¶

def get_icon_size(self) -> IconSize

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

get_paintable¶

def get_paintable(self) -> Gdk.Paintable | None

Gets the image GdkPaintable being displayed by the GtkImage.

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

get_pixel_size¶

def get_pixel_size(self) -> int

Gets the pixel size used for named icons.

get_storage_type¶

def get_storage_type(self) -> 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 ImageType.EMPTY.

set_from_file¶

def set_from_file(self, filename: str | bytes | os.PathLike[str] | os.PathLike[bytes] | None = ...) -> None

Sets a GtkImage to show a file.

See Image.new_from_file for details.

::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a GdkTexture, and then use Image.set_from_paintable.

Parameters:

filename — a filename

set_from_gicon¶

def set_from_gicon(self, icon: Gio.Icon) -> None

Sets a GtkImage to show a GIcon.

See Image.new_from_gicon for details.

Parameters:

icon — an icon

set_from_icon_name¶

def set_from_icon_name(self, icon_name: str | None = ...) -> None

Sets a GtkImage to show a named icon.

See Image.new_from_icon_name for details.

Parameters:

icon_name — an icon name

set_from_paintable¶

def set_from_paintable(self, paintable: Gdk.Paintable | None = ...) -> None

Sets a GtkImage to show a GdkPaintable.

See Image.new_from_paintable for details.

Parameters:

paintable — a GdkPaintable

set_from_pixbuf¶

def set_from_pixbuf(self, pixbuf: GdkPixbuf.Pixbuf | None = ...) -> None

:::warning Deprecated since 4.12 This API is deprecated. :::

Sets a GtkImage to show a GdkPixbuf.

See Image.new_from_pixbuf for details.

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

Parameters:

pixbuf — a GdkPixbuf or NULL

set_from_resource¶

def set_from_resource(self, resource_path: str | None = ...) -> None

Sets a GtkImage to show a resource.

See Image.new_from_resource for details.

Parameters:

resource_path — a resource path

set_icon_size¶

def set_icon_size(self, icon_size: IconSize | int) -> None

Suggests an icon size to the theme for named icons.

Parameters:

icon_size — the new icon size

set_pixel_size¶

def set_pixel_size(self, 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 Image.set_icon_size.

Parameters:

pixel_size — the new pixel size

Properties¶

file¶

file: str  # read/write

A path to the file to display.

gicon¶

gicon: Gio.Icon  # read/write

The GIcon displayed in the GtkImage.

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

icon_name¶

icon_name: str  # read/write

The name of the icon in the icon theme.

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

icon_size¶

icon_size: IconSize | int  # read/write

The symbolic size to display icons at.

paintable¶

paintable: Gdk.Paintable  # read/write

The GdkPaintable to display.

pixel_size¶

pixel_size: int  # read/write

The size in pixels to display icons at.

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

resource¶

resource: str  # read/write

A path to a resource file to display.

storage_type¶

storage_type: ImageType | int  # read-only

The representation being used for image data.

use_fallback¶

use_fallback: bool  # read/write

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 ImageType.ICON_NAME and ImageType.GICON.