GtkImage

GtkImage — A widget displaying an image

Properties

gchar * file Read / Write
GIcon * gicon Read / Write
gchar * icon-name Read / Write
GtkIconSize icon-size Read / Write
GdkPaintable * paintable Read / Write
gint pixel-size Read / Write
gchar * resource Read / Write
GtkImageType storage-type Read
gboolean use-fallback Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkImage

Implemented Interfaces

GtkImage implements AtkImplementorIface, GtkBuildable and GtkConstraintTarget.

Includes

#include <gtk/gtk.h>

Description

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, and then display that. There’s a convenience function to do this, gtk_image_new_from_file(), used as follows:

1
2
GtkWidget *image;
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 gdk_texture_new_from_file(), then create the GtkImage with gtk_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 for details. In this case, the “resource”, gtk_image_new_from_resource() and gtk_image_set_from_resource() should be used.

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.

Functions

gtk_image_new ()

GtkWidget *
gtk_image_new (void);

Creates a new empty GtkImage widget.

Returns

a newly created GtkImage widget.


gtk_image_new_from_file ()

GtkWidget *
gtk_image_new_from_file (const gchar *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.

Parameters

filename

a filename.

[type filename]

Returns

a new GtkImage


gtk_image_new_from_resource ()

GtkWidget *
gtk_image_new_from_resource (const gchar *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.

Parameters

resource_path

a resource path

 

Returns

a new GtkImage


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

Parameters

pixbuf

a GdkPixbuf, or NULL.

[allow-none]

Returns

a new GtkImage


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.

Parameters

paintable

a GdkPaintable, or NULL.

[allow-none]

Returns

a new GtkImage


gtk_image_new_from_icon_name ()

GtkWidget *
gtk_image_new_from_icon_name (const gchar *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.

Parameters

icon_name

an icon name or NULL.

[nullable]

Returns

a new GtkImage displaying the themed icon


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.

Parameters

icon

an icon

 

Returns

a new GtkImage displaying the themed icon


gtk_image_clear ()

void
gtk_image_clear (GtkImage *image);

Resets the image to be empty.

Parameters

image

a GtkImage

 

gtk_image_set_from_file ()

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

See gtk_image_new_from_file() for details.

Parameters

image

a GtkImage

 

filename

a filename or NULL.

[type filename][allow-none]

gtk_image_set_from_resource ()

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

See gtk_image_new_from_resource() for details.

Parameters

image

a GtkImage

 

resource_path

a resource path or NULL.

[allow-none]

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.

Parameters

image

a GtkImage

 

pixbuf

a GdkPixbuf or NULL.

[allow-none]

gtk_image_set_from_paintable ()

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

See gtk_image_new_from_paintable() for details.

Parameters

image

a GtkImage

 

paintable

a GdkPaintable or NULL.

[nullable]

gtk_image_set_from_icon_name ()

void
gtk_image_set_from_icon_name (GtkImage *image,
                              const gchar *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.

Parameters

image

a GtkImage

 

icon_name

an icon name or NULL.

[nullable]

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.

Parameters

image

a GtkImage

 

icon

an icon

 

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.

Parameters

image

a GtkImage

 

Returns

image representation being used


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.

Parameters

image

a GtkImage

 

Returns

the displayed paintable, or NULL if the image is empty.

[nullable][transfer none]


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.

Parameters

image

a GtkImage

 

Returns

the icon name, or NULL.

[transfer none][allow-none]


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.

Parameters

image

a GtkImage

 

Returns

a GIcon, or NULL.

[transfer none][allow-none]


gtk_image_set_pixel_size ()

void
gtk_image_set_pixel_size (GtkImage *image,
                          gint 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().

Parameters

image

a GtkImage

 

pixel_size

the new pixel size

 

gtk_image_get_pixel_size ()

gint
gtk_image_get_pixel_size (GtkImage *image);

Gets the pixel size used for named icons.

Parameters

image

a GtkImage

 

Returns

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.

Parameters

image

a GtkImage

 

icon_size

the new icon size

 

gtk_image_get_icon_size ()

GtkIconSize
gtk_image_get_icon_size (GtkImage *image);

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

Parameters

image

a GtkImage

 

Returns

the image size used by icons

Types and Values

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.

Members

GTK_IMAGE_EMPTY

there is no image displayed by the widget

 

GTK_IMAGE_ICON_NAME

the widget contains a named icon. This image type was added in GTK+ 2.6

 

GTK_IMAGE_GICON

the widget contains a GIcon. This image type was added in GTK+ 2.14

 

GTK_IMAGE_PAINTABLE

the widget contains a GdkPaintable. This image type was added in GTK+ 3.96

 

Property Details

The “file” property

  “file”                     gchar *

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”                gchar *

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”               gint

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”                 gchar *

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