Gtk.Picture¶

class — extends Widget, Accessible, Buildable, ConstraintTarget

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 and image loading framework such as libglycin, then create the GtkPicture with 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, Picture.new_for_resource and Picture.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 Picture.content-fit. See ContentFit for details. 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 Widget.halign and 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 AccessibleRole.img role.

Constructors¶

new¶

@classmethod
def new(cls) -> Widget

Creates a new empty GtkPicture widget.

new_for_file¶

@classmethod
def new_for_file(cls, file: Gio.File | 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 an image loading framework such as libglycin to load the file yourself, then create the GtkPicture from the texture.

Parameters:

file — a GFile

new_for_filename¶

@classmethod
def new_for_filename(cls, filename: str | bytes | os.PathLike[str] | os.PathLike[bytes] | None = ...) -> Widget

Creates a new GtkPicture displaying the file filename.

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

Parameters:

filename — a filename

new_for_paintable¶

@classmethod
def new_for_paintable(cls, paintable: Gdk.Paintable | 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

new_for_pixbuf¶

@classmethod
def new_for_pixbuf(cls, pixbuf: GdkPixbuf.Pixbuf | None = ...) -> Widget

:::warning Deprecated since 4.12 This API is deprecated. :::

Creates a new GtkPicture displaying pixbuf.

This is a utility function that calls 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

new_for_resource¶

@classmethod
def new_for_resource(cls, resource_path: str | None = ...) -> Widget

Creates a new GtkPicture displaying the resource at resource_path.

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

Parameters:

resource_path — resource path to play back

Methods¶

get_alternative_text¶

def get_alternative_text(self) -> 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¶

def get_can_shrink(self) -> bool

Returns whether the GtkPicture respects its contents size.

get_content_fit¶

def get_content_fit(self) -> ContentFit

Returns the fit mode for the content of the GtkPicture.

See ContentFit for details.

get_file¶

def get_file(self) -> Gio.File | None

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

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

get_isolate_contents¶

def get_isolate_contents(self) -> bool

Returns whether the contents are isolated.

get_keep_aspect_ratio¶

def get_keep_aspect_ratio(self) -> bool

:::warning Deprecated since 4.8 This API is deprecated. :::

Returns whether the GtkPicture preserves its contents aspect ratio.

get_paintable¶

def get_paintable(self) -> Gdk.Paintable | None

Gets the GdkPaintable being displayed by the GtkPicture.

set_alternative_text¶

def set_alternative_text(self, alternative_text: str | 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¶

def set_can_shrink(self, can_shrink: bool) -> None

If set to True, then 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 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 Widget.set_halign and Widget.set_valign.

Parameters:

can_shrink — if self can be made smaller than its contents

set_content_fit¶

def set_content_fit(self, content_fit: ContentFit | int) -> None

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

See ContentFit for details.

Parameters:

content_fit — the content fit mode

set_file¶

def set_file(self, file: Gio.File | None = ...) -> None

Makes self load and display file.

See Picture.new_for_file for details.

::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a GdkTexture, and then use Image.set_from_paintable.

Parameters:

file — a GFile

set_filename¶

def set_filename(self, filename: str | bytes | os.PathLike[str] | os.PathLike[bytes] | None = ...) -> None

Makes self load and display the given filename.

This is a utility function that calls Picture.set_file.

::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a GdkTexture, and then use Image.set_from_paintable.

Parameters:

filename — the filename to play

set_isolate_contents¶

def set_isolate_contents(self, isolate_contents: bool) -> None

If set to true, then the contents will be rendered individually.

If set to false they will be able to erase or otherwise mix with the background.

GTK supports finer grained isolation, in rare cases where you need this, you can use Snapshot.push_isolation yourself to achieve this.

By default contents are isolated.

Parameters:

isolate_contents — if contents are rendered separately

set_keep_aspect_ratio¶

def set_keep_aspect_ratio(self, keep_aspect_ratio: bool) -> None

:::warning Deprecated since 4.8 This API is deprecated. :::

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:

keep_aspect_ratio — whether to keep aspect ratio

set_paintable¶

def set_paintable(self, paintable: Gdk.Paintable | None = ...) -> None

Makes self display the given paintable.

If paintable is NULL, nothing will be displayed.

See Picture.new_for_paintable for details.

Parameters:

paintable — a GdkPaintable

set_pixbuf¶

def set_pixbuf(self, pixbuf: GdkPixbuf.Pixbuf | None = ...) -> None

:::warning Deprecated since 4.12 This API is deprecated. :::

Sets a GtkPicture to show a GdkPixbuf.

See Picture.new_for_pixbuf for details.

This is a utility function that calls Picture.set_paintable.

Parameters:

pixbuf — a GdkPixbuf

set_resource¶

def set_resource(self, resource_path: str | None = ...) -> None

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

This is a utility function that calls Picture.set_file.

Parameters:

resource_path — the resource to set

Properties¶

alternative_text¶

alternative_text: str  # read/write

The alternative textual description for the picture.

can_shrink¶

can_shrink: bool  # read/write

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

content_fit¶

content_fit: ContentFit | int  # read/write

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

file¶

file: Gio.File  # read/write

The GFile that is displayed or None if none.

isolate_contents¶

isolate_contents: bool  # read/write

If the rendering of the contents is isolated from the rest of the widget tree.

keep_aspect_ratio¶

keep_aspect_ratio: bool  # read/write

:::warning Deprecated since 4.8 This API is deprecated. :::

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

paintable¶

paintable: Gdk.Paintable  # read/write

The GdkPaintable to be displayed by this GtkPicture.