GtkPicture

GtkPicture — A widget displaying a GdkPaintable

Properties

char * 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

Object Hierarchy

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

Implemented Interfaces

GtkPicture implements GtkAccessible, 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.

GtkPicture displays an image at its natural size. See GtkImage if you want to display a fixed-size image, such as an icon.

Sizing the paintable

You can influence how the paintable is displayed inside the GtkPicture. By turning off “keep-aspect-ratio” you can allow the paintable to get stretched. “can-shrink” can be unset to make sure that paintables are never made smaller than their ideal size - but be careful if you do not know the size of the paintable in use (like when displaying user-loaded images). This can easily cause the picture to grow larger than the screen. And “halign” and “valign” can be used to make sure the paintable doesn't fill all available space but is instead displayed at its original size.


CSS nodes

GtkPicture has a single CSS node with the name picture.


Accessibility

GtkPicture uses the GTK_ACCESSIBLE_ROLE_IMG role.

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 char *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 char *resource_path);

Creates a new GtkPicture displaying the resource at resource_path .

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

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