Picture#

class Picture(**properties: Any)#

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget

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 it, there’s a convenience function to do this:

GtkWidget *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 new_from_file, then create the GtkPicture with 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, new_for_resource and set_resource should be used.

GtkPicture displays an image at its natural size. See Image 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 changing content_fit. See ContentFit for details. 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.

Constructors#

class Picture

classmethod new() → Widget#: Creates a new empty GtkPicture widget.

classmethod new_for_file(file: File | None = None) → Widget#

Creates a new GtkPicture displaying the given file.

If the file isn’t found or can’t be loaded, the resulting GtkPicture is empty.

If you need to detect failures to load the file, use new_from_file to load the file yourself, then create the GtkPicture from the texture.

Parameters:: file – a GFile

classmethod new_for_filename(filename: str | None = None) → Widget#

Creates a new GtkPicture displaying the file filename.

This is a utility function that calls new_for_file. See that function for details.

Parameters:: filename – a filename

classmethod new_for_paintable(paintable: Paintable | None = None) → Widget#

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

classmethod new_for_pixbuf(pixbuf: Pixbuf | None = None) → Widget#

Creates a new GtkPicture displaying pixbuf.

This is a utility function that calls new_for_paintable, See that function for details.

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

Deprecated since version 4.12: Use new_for_paintable and new_for_pixbuf instead

Parameters:: pixbuf – a GdkPixbuf

classmethod new_for_resource(resource_path: str | None = None) → Widget#

Creates a new GtkPicture displaying the resource at resource_path.

This is a utility function that calls new_for_file. See that function for details.

Parameters:: resource_path – resource path to play back

Methods#

class Picture

get_alternative_text() → str | None#

Gets the alternative textual description of the picture.

The returned string will be None if the picture cannot be described textually.

get_can_shrink() → bool#: Returns whether the GtkPicture respects its contents size.

get_content_fit() → ContentFit#

Returns the fit mode for the content of the GtkPicture.

See ContentFit for details.

Added in version 4.8.

get_file() → File | None#

Gets the GFile currently displayed if self is displaying a file.

If self is not displaying a file, for example when set_paintable was used, then None is returned.

get_keep_aspect_ratio() → bool#: Returns whether the GtkPicture preserves its contents aspect ratio.

Deprecated since version 4.8: Use get_content_fit instead. This will now return FALSE only if content_fit is GTK_CONTENT_FIT_FILL. Returns TRUE otherwise.

get_paintable() → Paintable | None#: Gets the GdkPaintable being displayed by the GtkPicture.

set_alternative_text(alternative_text: str | None = None) → None#

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

Parameters:: alternative_text – a textual description of the contents

set_can_shrink(can_shrink: bool) → None#

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

Also of note is that a similar function for growing does not exist because the grow behavior can be controlled via set_halign and set_valign.

Parameters:: can_shrink – if self can be made smaller than its contents

set_content_fit(content_fit: ContentFit) → None#

Sets how the content should be resized to fit the GtkPicture.

See ContentFit for details.

Added in version 4.8.

Parameters:: content_fit – the content fit mode

set_file(file: File | None = None) → None#

Makes self load and display file.

See new_for_file for details.

Parameters:: file – a GFile

set_filename(filename: str | None = None) → None#

Makes self load and display the given filename.

This is a utility function that calls set_file.

Parameters:: filename – the filename to play

set_keep_aspect_ratio(keep_aspect_ratio: bool) → None#

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.

Deprecated since version 4.8: Use set_content_fit instead. If still used, this method will always set the content_fit property to GTK_CONTENT_FIT_CONTAIN if keep_aspect_ratio is true, otherwise it will set it to GTK_CONTENT_FIT_FILL.

Parameters:: keep_aspect_ratio – whether to keep aspect ratio

set_paintable(paintable: Paintable | None = None) → None#

Makes self display the given paintable.

If paintable is None, nothing will be displayed.

See new_for_paintable for details.

Parameters:: paintable – a GdkPaintable

set_pixbuf(pixbuf: Pixbuf | None = None) → None#

Sets a GtkPicture to show a GdkPixbuf.

See new_for_pixbuf for details.

This is a utility function that calls set_paintable.

Deprecated since version 4.12: Use set_paintable instead

Parameters:: pixbuf – a GdkPixbuf

set_resource(resource_path: str | None = None) → None#

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

This is a utility function that calls set_file.

Parameters:: resource_path – the resource to set

Properties#

class Picture

props.alternative_text: str#: The type of the None singleton.

props.can_shrink: bool#: The type of the None singleton.

props.content_fit: ContentFit#: The type of the None singleton.

Added in version 4.8.

props.file: File#: The type of the None singleton.

props.keep_aspect_ratio: bool#: The type of the None singleton.

Deprecated since version 4.8: Use content_fit instead.

props.paintable: Paintable#: The type of the None singleton.