## GtkImage GtkImage — A widget displaying an image |

## Functions

GtkWidget * | gtk_image_new ()
GtkWidget * | gtk_image_new_from_file ()
GtkWidget * | gtk_image_new_from_resource ()
GtkWidget * | gtk_image_new_from_pixbuf ()
GtkWidget * | gtk_image_new_from_paintable ()
GtkWidget * | gtk_image_new_from_icon_name ()
GtkWidget * | gtk_image_new_from_gicon ()
void | gtk_image_clear ()
void | gtk_image_set_from_file ()
void | gtk_image_set_from_resource ()
void | gtk_image_set_from_pixbuf ()
void | gtk_image_set_from_paintable ()
void | gtk_image_set_from_icon_name ()
void | gtk_image_set_from_gicon ()
GtkImageType | gtk_image_get_storage_type ()
GdkPaintable * | gtk_image_get_paintable ()
const char * | gtk_image_get_icon_name ()
GIcon * | gtk_image_get_gicon ()
void | gtk_image_set_pixel_size ()
gint | gtk_image_get_pixel_size ()
void | gtk_image_set_icon_size ()
GtkIconSize | gtk_image_get_icon_size ()

## 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

| GtkImage
enum | GtkImageType

## 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