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.

gtk_image_new ()

GtkWidget *
gtk_image_new (void);

Creates a new empty GtkImage widget.

gtk_image_new_from_file ()

GtkWidget *
gtk_image_new_from_file (const char *filename);

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 NULL, it always returns a valid GtkImage widget.

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

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

gtk_image_new_from_resource ()

GtkWidget *
gtk_image_new_from_resource (const char *resource_path);

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 NULL, it always returns a valid GtkImage widget.

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

The storage type (gtk_image_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 ()

GtkWidget *
gtk_image_new_from_pixbuf (GdkPixbuf *pixbuf);

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 gtk_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 gtk_image_new_from_icon_name().

gtk_image_new_from_paintable ()

GtkWidget *
gtk_image_new_from_paintable (GdkPaintable *paintable);

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.

gtk_image_new_from_icon_name ()

GtkWidget *
gtk_image_new_from_icon_name (const char *icon_name);

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.

Note: Before 3.94, this function was taking an extra icon size argument. See gtk_image_set_icon_size() for another way to set the icon size.

gtk_image_new_from_gicon ()

GtkWidget *
gtk_image_new_from_gicon (GIcon *icon);

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.

Note: Before 3.94, this function was taking an extra icon size argument. See gtk_image_set_icon_size() for another way to set the icon size.

gtk_image_clear ()

void
gtk_image_clear (GtkImage *image);

Resets the image to be empty.

gtk_image_set_from_file ()

void
gtk_image_set_from_file (GtkImage *image,
                         const char *filename);

See gtk_image_new_from_file() for details.

gtk_image_set_from_resource ()

void
gtk_image_set_from_resource (GtkImage *image,
                             const char *resource_path);

See gtk_image_new_from_resource() for details.

gtk_image_set_from_pixbuf ()

void
gtk_image_set_from_pixbuf (GtkImage *image,
                           GdkPixbuf *pixbuf);

See gtk_image_new_from_pixbuf() for details.

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

gtk_image_set_from_paintable ()

void
gtk_image_set_from_paintable (GtkImage *image,
                              GdkPaintable *paintable);

See gtk_image_new_from_paintable() for details.

gtk_image_set_from_icon_name ()

void
gtk_image_set_from_icon_name (GtkImage *image,
                              const char *icon_name);

See gtk_image_new_from_icon_name() for details.

Note: Before 3.94, this function was taking an extra icon size argument. See gtk_image_set_icon_size() for another way to set the icon size.

gtk_image_set_from_gicon ()

void
gtk_image_set_from_gicon (GtkImage *image,
                          GIcon *icon);

See gtk_image_new_from_gicon() for details.

Note: Before 3.94, this function was taking an extra icon size argument. See gtk_image_set_icon_size() for another way to set the icon size.

gtk_image_get_storage_type ()

GtkImageType
gtk_image_get_storage_type (GtkImage *image);

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 GTK_IMAGE_EMPTY.

gtk_image_get_paintable ()

GdkPaintable *
gtk_image_get_paintable (GtkImage *image);

Gets the image GdkPaintable being displayed by the GtkImage. The storage type of the image must be GTK_IMAGE_EMPTY or GTK_IMAGE_PAINTABLE (see gtk_image_get_storage_type()). The caller of this function does not own a reference to the returned paintable.

gtk_image_get_icon_name ()

const char *
gtk_image_get_icon_name (GtkImage *image);

Gets the icon name and size being displayed by the GtkImage. The storage type of the image must be GTK_IMAGE_EMPTY or GTK_IMAGE_ICON_NAME (see gtk_image_get_storage_type()). The returned string is owned by the GtkImage and should not be freed.

Note: This function was changed in 3.94 not to use out parameters anymore, but return the icon name directly. See gtk_image_get_icon_size() for a way to get the icon size.

gtk_image_get_gicon ()

GIcon *
gtk_image_get_gicon (GtkImage *image);

Gets the GIcon and size being displayed by the GtkImage. The storage type of the image must be GTK_IMAGE_EMPTY or GTK_IMAGE_GICON (see gtk_image_get_storage_type()). The caller of this function does not own a reference to the returned GIcon.

Note: This function was changed in 3.94 not to use out parameters anymore, but return the GIcon directly. See gtk_image_get_icon_size() for a way to get the icon size.

gtk_image_set_pixel_size ()

void
gtk_image_set_pixel_size (GtkImage *image,
                          int pixel_size);

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

gtk_image_get_pixel_size ()

int
gtk_image_get_pixel_size (GtkImage *image);

Gets the pixel size used for named icons.

gtk_image_set_icon_size ()

void
gtk_image_set_icon_size (GtkImage *image,
                         GtkIconSize icon_size);

Suggests an icon size to the theme for named icons.

gtk_image_get_icon_size ()

GtkIconSize
gtk_image_get_icon_size (GtkImage *image);

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

GtkImage

typedef struct _GtkImage GtkImage;

enum GtkImageType

Describes the image data representation used by a GtkImage. If you want to get the image from the widget, you can only get the currently-stored representation. e.g. if the gtk_image_get_storage_type() returns GTK_IMAGE_PAINTABLE, then you can call gtk_image_get_paintable(). For empty images, you can request any storage type (call any of the "get" functions), but they will all return NULL values.

The “file” property

  “file”                     char *

Filename to load and display.

Owner: GtkImage

Flags: Read / Write

Default value: NULL

The “gicon” property

  “gicon”                    GIcon *

The GIcon displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically.

Owner: GtkImage

Flags: Read / Write

The “icon-name” property

  “icon-name”                char *

The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically.

Owner: GtkImage

Flags: Read / Write

Default value: NULL

The “icon-size” property

  “icon-size”                GtkIconSize

Symbolic size to use for icon set or named icon.

Owner: GtkImage

Flags: Read / Write

Default value: GTK_ICON_SIZE_INHERIT

The “paintable” property

  “paintable”                GdkPaintable *

A GdkPaintable to display.

Owner: GtkImage

Flags: Read / Write

The “pixel-size” property

  “pixel-size”               int

The "pixel-size" property can be used to specify a fixed size overriding the “icon-size” property for images of type GTK_IMAGE_ICON_NAME.

Owner: GtkImage

Flags: Read / Write

Allowed values: >= -1

Default value: -1

The “resource” property

  “resource”                 char *

A path to a resource file to display.

Owner: GtkImage

Flags: Read / Write

Default value: NULL

The “storage-type” property

  “storage-type”             GtkImageType

The representation being used for image data.

Owner: GtkImage

Flags: Read

Default value: GTK_IMAGE_EMPTY

The “use-fallback” property

  “use-fallback”             gboolean

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 GTK_IMAGE_ICON_NAME and GTK_IMAGE_GICON.

Owner: GtkImage

Flags: Read / Write

Default value: FALSE