Gtk.Picture¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (183), GObject.Object (37), Gtk.Accessible (17), Gtk.Buildable (1)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
class	`new_for_file` (file)
class	`new_for_filename` (filename)
class	`new_for_paintable` (paintable)
class	`new_for_pixbuf` (pixbuf)
class	`new_for_resource` (resource_path)
	`get_alternative_text` ()
	`get_can_shrink` ()
	`get_content_fit` ()
	`get_file` ()
	`get_keep_aspect_ratio` ()
	`get_paintable` ()
	`set_alternative_text` (alternative_text)
	`set_can_shrink` (can_shrink)
	`set_content_fit` (content_fit)
	`set_file` (file)
	`set_filename` (filename)
	`set_keep_aspect_ratio` (keep_aspect_ratio)
	`set_paintable` (paintable)
	`set_pixbuf` (pixbuf)
	`set_resource` (resource_path)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9)

Properties¶

Inherited:: Gtk.Widget (35), Gtk.Accessible (1)

Name	Type	Flags	Short Description
`alternative-text`	`str`	r/w/en
`can-shrink`	`bool`	r/w/en
`content-fit`	`Gtk.ContentFit`	r/w/en
`file`	`Gio.File`	r/w/en
`keep-aspect-ratio`	`bool`	d/r/w/en	`deprecated`
`paintable`	`Gdk.Paintable`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Class Details¶

class Gtk.Picture(**kwargs)¶

Bases:: Gtk.Widget
Abstract:: No
Structure:: Gtk.PictureClass

Displays a GdkPaintable.

picture> <source srcset=”picture-dark.png” media=”(prefers-color-scheme: dark)”> <img alt=”An example Gtk.Picture" src=”picture.png”> </picture>

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:

``c 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 [ctor`Gdk`.Texture.new_from_file], then create the GtkPicture with [ctor`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, [ctor`Gtk`.Picture.new_for_resource] and [method`Gtk`.Picture.set_resource] should be used.

GtkPicture displays an image at its natural size. See [class`Gtk`.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 [property`Gtk`.Picture:content-fit]. See [enum`Gtk`.ContentFit] for details. [property`Gtk`.Picture: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 [property`Gtk`.Widget:halign] and [property`Gtk`.Widget: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 [enum`Gtk`.AccessibleRole.img] role.

classmethod new()[source]¶

Returns:: a newly created GtkPicture widget.
Return type:: Gtk.Widget

Creates a new empty GtkPicture widget.

classmethod new_for_file(file)[source]¶

Parameters:: file (Gio.File or None) – a GFile
Returns:: a new GtkPicture
Return type:: Gtk.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 [ctor`Gdk`.Texture.new_from_file] to load the file yourself, then create the GtkPicture from the texture.

classmethod new_for_filename(filename)[source]¶

Parameters:: filename (str or None) – a filename
Returns:: a new GtkPicture
Return type:: Gtk.Widget

Creates a new GtkPicture displaying the file filename.

This is a utility function that calls [ctor`Gtk`.Picture.new_for_file]. See that function for details.

classmethod new_for_paintable(paintable)[source]¶

Parameters:: paintable (Gdk.Paintable or None) – a GdkPaintable
Returns:: a new GtkPicture
Return type:: Gtk.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.

classmethod new_for_pixbuf(pixbuf)[source]¶

Parameters:: pixbuf (GdkPixbuf.Pixbuf or None) – a GdkPixbuf
Returns:: a new GtkPicture
Return type:: Gtk.Widget

Creates a new GtkPicture displaying pixbuf.

This is a utility function that calls [ctor`Gtk`.Picture.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 [ctor`Gtk`.Picture.new_for_paintable] and [ctor`Gdk`.Texture.new_for_pixbuf] instead

classmethod new_for_resource(resource_path)[source]¶

Parameters:: resource_path (str or None) – resource path to play back
Returns:: a new GtkPicture
Return type:: Gtk.Widget

Creates a new GtkPicture displaying the resource at resource_path.

This is a utility function that calls [ctor`Gtk`.Picture.new_for_file]. See that function for details.

get_alternative_text()[source]¶

Returns:: the alternative textual description of self.
Return type:: str or 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()[source]¶

Returns:: True if the picture can be made smaller than its contents
Return type:: bool

Returns whether the GtkPicture respects its contents size.

get_content_fit()[source]¶

Returns:: the content fit mode
Return type:: Gtk.ContentFit

Returns the fit mode for the content of the GtkPicture.

See [enum`Gtk`.ContentFit] for details.

New in version 4.8.

get_file()[source]¶

Returns:: The GFile displayed by self.
Return type:: Gio.File or None

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

If self is not displaying a file, for example when [method`Gtk`.Picture.set_paintable] was used, then None is returned.

get_keep_aspect_ratio()[source]¶

Returns:: True if the self tries to keep the contents’ aspect ratio
Return type:: bool

Returns whether the GtkPicture preserves its contents aspect ratio.

Deprecated since version 4.8: Use [method`Gtk`.Picture.get_content_fit] instead. This will now return FALSE only if [property`Gtk`.Picture:content-fit] is GTK_CONTENT_FIT_FILL. Returns TRUE otherwise.

get_paintable()[source]¶

Returns:: the displayed paintable
Return type:: Gdk.Paintable or None

Gets the GdkPaintable being displayed by the GtkPicture.

set_alternative_text(alternative_text)[source]¶

Parameters:: alternative_text (str or None) – a textual description of the contents

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.

set_can_shrink(can_shrink)[source]¶

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

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 [method`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 [method`Gtk`.Widget.set_halign] and [method`Gtk`.Widget.set_valign].

set_content_fit(content_fit)[source]¶

Parameters:: content_fit (Gtk.ContentFit) – the content fit mode

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

See [enum`Gtk`.ContentFit] for details.

New in version 4.8.

set_file(file)[source]¶

Parameters:: file (Gio.File or None) – a GFile

Makes self load and display file.

See [ctor`Gtk`.Picture.new_for_file] for details.

set_filename(filename)[source]¶

Parameters:: filename (str or None) – the filename to play

Makes self load and display the given filename.

This is a utility function that calls [method`Gtk`.Picture.set_file].

set_keep_aspect_ratio(keep_aspect_ratio)[source]¶

Parameters:: keep_aspect_ratio (bool) – whether to 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.

Deprecated since version 4.8: Use [method`Gtk`.Picture.set_content_fit] instead. If still used, this method will always set the [property`Gtk`.Picture:content-fit] property to GTK_CONTENT_FIT_CONTAIN if keep_aspect_ratio is true, otherwise it will set it to GTK_CONTENT_FIT_FILL.

set_paintable(paintable)[source]¶

Parameters:: paintable (Gdk.Paintable or None) – a GdkPaintable

Makes self display the given paintable.

If paintable is None, nothing will be displayed.

See [ctor`Gtk`.Picture.new_for_paintable] for details.

set_pixbuf(pixbuf)[source]¶

Parameters:: pixbuf (GdkPixbuf.Pixbuf or None) – a GdkPixbuf

Sets a GtkPicture to show a GdkPixbuf.

See [ctor`Gtk`.Picture.new_for_pixbuf] for details.

This is a utility function that calls [method`Gtk`.Picture.set_paintable].

Deprecated since version 4.12: Use [method`Gtk`.Picture.set_paintable] instead

set_resource(resource_path)[source]¶

Parameters:: resource_path (str or None) – the resource to set

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

This is a utility function that calls [method`Gtk`.Picture.set_file].

Property Details¶

Gtk.Picture.props.alternative_text¶

Name:: alternative-text
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The alternative textual description for the picture.

Gtk.Picture.props.can_shrink¶

Name:: can-shrink
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

If the GtkPicture can be made smaller than the natural size of its contents.

Gtk.Picture.props.content_fit¶

Name:: content-fit
Type:: Gtk.ContentFit
Default Value:: Gtk.ContentFit.CONTAIN
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

How the content should be resized to fit inside the GtkPicture.

New in version 4.8.

Gtk.Picture.props.file¶

Name:: file
Type:: Gio.File
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The GFile that is displayed or None if none.

Gtk.Picture.props.keep_aspect_ratio¶

Name:: keep-aspect-ratio
Type:: bool
Default Value:: True
Flags:: DEPRECATED, READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the Gtk.Picture will render its contents trying to preserve the aspect ratio.

Deprecated since version 4.8: Use [property`Gtk`.Picture:content-fit] instead.

Gtk.Picture.props.paintable¶

Name:: paintable
Type:: Gdk.Paintable
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The GdkPaintable to be displayed by this GtkPicture.