## GtkPicture GtkPicture — A widget displaying a GdkPaintable |

## Functions

GtkWidget * | gtk_picture_new ()
GtkWidget * | gtk_picture_new_for_paintable ()
GtkWidget * | gtk_picture_new_for_pixbuf ()
GtkWidget * | gtk_picture_new_for_file ()
GtkWidget * | gtk_picture_new_for_filename ()
GtkWidget * | gtk_picture_new_for_resource ()
void | gtk_picture_set_paintable ()
GdkPaintable * | gtk_picture_get_paintable ()
void | gtk_picture_set_pixbuf ()
void | gtk_picture_set_file ()
GFile * | gtk_picture_get_file ()
void | gtk_picture_set_filename ()
void | gtk_picture_set_resource ()
void | gtk_picture_set_keep_aspect_ratio ()
gboolean | gtk_picture_get_keep_aspect_ratio ()
void | gtk_picture_set_can_shrink ()
gboolean | gtk_picture_get_can_shrink ()
void | gtk_picture_set_alternative_text ()
const char * | gtk_picture_get_alternative_text ()

## Properties

gchar * | alternative-text | Read / Write
gboolean | can-shrink | Read / Write
GFile * | file | Read / Write
gboolean | keep-aspect-ratio | Read / Write
GdkPaintable * | paintable | Read / Write

## Types and Values

| GtkPicture

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkPicture

## Implemented Interfaces

GtkPicture implements AtkImplementorIface, GtkBuildable and GtkConstraintTarget.

## Includes

    #include <gtk/gtk.h>

## Description

The GtkPicture widget displays a GdkPaintable. Many convenience functions are provided to make pictures simple to use. For example, if you want to load an image from a file, and then display that, there’s a convenience function to do this:

    1
    2
    GtkWidget *widget;
    widget = gtk_picture_new_for_filename ("myfile.png");

If the file isn’t loaded successfully, the picture 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 GtkPicture with `gtk_picture_new_for_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, `gtk_picture_new_for_resource()` and `gtk_picture_set_resource()` should be used.

### CSS nodes

GtkPicture has a single CSS node with the name picture.

## Functions

### gtk_picture_new ()

    GtkWidget *
    gtk_picture_new (void);

Creates a new empty GtkPicture widget.

#### Returns

a newly created GtkPicture widget.

### gtk_picture_new_for_paintable ()

    GtkWidget *
    gtk_picture_new_for_paintable (GdkPaintable *paintable);

Creates a new GtkPicture displaying `paintable` .

The GtkPicture will track changes to the `paintable` and update its size and contents in response to it.

#### Parameters

paintable | a GdkPaintable, or `NULL`. | [nullable]

#### Returns

a new GtkPicture

### gtk_picture_new_for_pixbuf ()

    GtkWidget *
    gtk_picture_new_for_pixbuf (GdkPixbuf *pixbuf);

Creates a new GtkPicture displaying `pixbuf` .

This is a utility function that calls `gtk_picture_new_for_paintable()`, See that function for details.

The pixbuf must not be modified after passing it to this function.

#### Parameters

pixbuf | a GdkPixbuf, or `NULL`. | [nullable]

#### Returns

a new GtkPicture

### gtk_picture_new_for_file ()

    GtkWidget *
    gtk_picture_new_for_file (GFile *file);

Creates a new GtkPicture displaying the given `file` . If the file isn’t found or can’t be loaded, the resulting GtkPicture be empty.

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

#### Parameters

file | a GFile. | [nullable]

#### Returns

a new GtkPicture

### gtk_picture_new_for_filename ()

    GtkWidget *
    gtk_picture_new_for_filename (const gchar *filename);

Creates a new GtkPicture displaying the file `filename` .

This is a utility function that calls `gtk_picture_new_for_file()`. See that function for details.

#### Parameters

filename | a filename. | [type filename][nullable]

#### Returns

a new GtkPicture

### gtk_picture_new_for_resource ()

    GtkWidget *
    gtk_picture_new_for_resource (const gchar *resource_path);

Creates a new GtkPicture displaying the file `filename` .

This is a utility function that calls `gtk_picture_new_for_file()`. See that function for details.

#### Parameters

resource_path | resource path to play back. | [nullable]

#### Returns

a new GtkPicture

### gtk_picture_set_paintable ()

    void
    gtk_picture_set_paintable (GtkPicture *self,
                               GdkPaintable *paintable);

Makes `self` display the given `paintable` . If `paintable` is `NULL`, nothing will be displayed.

See `gtk_picture_new_for_paintable()` for details.

#### Parameters

self | a GtkPicture |
paintable | a GdkPaintable or `NULL`. | [nullable]

### gtk_picture_get_paintable ()

    GdkPaintable *
    gtk_picture_get_paintable (GtkPicture *self);

Gets the GdkPaintable being displayed by the GtkPicture.

#### Parameters

self | a GtkPicture |

#### Returns

the displayed paintable, or `NULL` if the picture is empty.

[nullable][transfer none]

### gtk_picture_set_pixbuf ()

    void
    gtk_picture_set_pixbuf (GtkPicture *self,
                            GdkPixbuf *pixbuf);

See `gtk_picture_new_for_pixbuf()` for details.

This is a utility function that calls `gtk_picture_set_paintable()`,

#### Parameters

self | a GtkPicture |
pixbuf | a GdkPixbuf or `NULL`. | [nullable]

### gtk_picture_set_file ()

    void
    gtk_picture_set_file (GtkPicture *self,
                          GFile *file);

Makes `self` load and display `file` .

See `gtk_picture_new_for_file()` for details.

#### Parameters

self | a GtkPicture |
file | a `GFile` or `NULL`. | [nullable]

### gtk_picture_get_file ()

    GFile *
    gtk_picture_get_file (GtkPicture *self);

Gets the GFile currently displayed if `self` is displaying a file. If `self` is not displaying a file, for example when `gtk_picture_set_paintable()` was used, then `NULL` is returned.

#### Parameters

self | a GtkPicture |

#### Returns

The GFile displayed by `self` .

[nullable][transfer none]

### gtk_picture_set_filename ()

    void
    gtk_picture_set_filename (GtkPicture *self,
                              const gchar *filename);

Makes `self` load and display the given `filename` .

This is a utility function that calls `gtk_picture_set_file()`.

#### Parameters

self | a GtkPicture |
filename | the filename to play. | [nullable]

### gtk_picture_set_resource ()

    void
    gtk_picture_set_resource (GtkPicture *self,
                              const gchar *resource_path);

Makes `self` load and display the resource at the given `resource_path` .

This is a utility function that calls `gtk_picture_set_file()`,

#### Parameters

self | a GtkPicture |
resource_path | the resource to set. | [nullable]

### gtk_picture_set_keep_aspect_ratio ()

    void
    gtk_picture_set_keep_aspect_ratio (GtkPicture *self,
                                       gboolean keep_aspect_ratio);

If set to `TRUE`, the `self` will render its contents according to their aspect ratio. That means that empty space may show up at the top/bottom or left/right of `self` .

If set to `FALSE` or if the contents provide no aspect ratio, the contents will be stretched over the picture's whole area.

#### Parameters

self | a GtkPicture |
keep_aspect_ratio | whether to keep aspect ratio |

### gtk_picture_get_keep_aspect_ratio ()

    gboolean
    gtk_picture_get_keep_aspect_ratio (GtkPicture *self);

Gets the value set via `gtk_picture_set_keep_aspect_ratio()`.

#### Parameters

self | a GtkPicture |

#### Returns

`TRUE` if the self tries to keep the contents' aspect ratio

### gtk_picture_set_can_shrink ()

    void
    gtk_picture_set_can_shrink (GtkPicture *self,
                                gboolean can_shrink);

If set to `TRUE`, the `self` can be made smaller than its contents. The contents will then be scaled down when rendering.

If you want to still force a minimum size manually, consider using `gtk_widget_set_size_request()`.

Also of note is that a similar function for growing does not exist because the grow behavior can be controlled via `gtk_widget_set_halign()` and `gtk_widget_set_valign()`.

#### Parameters

self | a GtkPicture |
can_shrink | if `self` can be made smaller than its contents |

### gtk_picture_get_can_shrink ()

    gboolean
    gtk_picture_get_can_shrink (GtkPicture *self);

Gets the value set via `gtk_picture_set_can_shrink()`.

#### Parameters

self | a GtkPicture |

#### Returns

`TRUE` if the picture can be made smaller than its contents

### gtk_picture_set_alternative_text ()

    void
    gtk_picture_set_alternative_text (GtkPicture *self,
                                      const char *alternative_text);

Sets an alternative textual description for the picture contents. It is equivalent to the "alt" attribute for images on websites.

This text will be made available to accessibility tools.

If the picture cannot be described textually, set this property to `NULL`.

#### Parameters

self | a GtkPicture |
alternative_text | a textual description of the contents. | [nullable]

### gtk_picture_get_alternative_text ()

    const char *
    gtk_picture_get_alternative_text (GtkPicture *self);

Gets the alternative textual description of the picture or returns `NULL` if the picture cannot be described textually.

#### Parameters

self | a GtkPicture |

#### Returns

the alternative textual description of `self` .

[nullable][transfer none]

## Types and Values

### GtkPicture

    typedef struct _GtkPicture GtkPicture;

## Property Details

### The `“alternative-text”` property

      “alternative-text”         gchar *

The alternative textual description for the picture.

Owner: GtkPicture

Flags: Read / Write

Default value: NULL

### The `“can-shrink”` property

      “can-shrink”               gboolean

If the GtkPicture can be made smaller than the self it contains.

Owner: GtkPicture

Flags: Read / Write

Default value: TRUE

### The `“file”` property

      “file”                     GFile *

The GFile that is displayed or `NULL` if none.

Owner: GtkPicture

Flags: Read / Write

### The `“keep-aspect-ratio”` property

      “keep-aspect-ratio”        gboolean

Whether the GtkPicture will render its contents trying to preserve the aspect ratio of the contents.

Owner: GtkPicture

Flags: Read / Write

Default value: TRUE

### The `“paintable”` property

      “paintable”                GdkPaintable *

The GdkPaintable to be displayed by this GtkPicture.

Owner: GtkPicture

Flags: Read / Write