Struct gtk4::Picture

#[repr(transparent)]
pub struct Picture { /* private fields */ }

The Picture widget displays a gdk::Paintable.

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:

⚠️ The following code is in 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 gdk::Texture::from_file(), then create the Picture with 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, for_resource() and set_resource() should be used.

Picture 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 Picture. By turning off property::Picture::keep-aspect-ratio you can allow the paintable to get stretched. property::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::GtkWidget::halign and property::GtkWidget::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

Picture has a single CSS node with the name picture.

Accessibility

Picture uses the GTK_ACCESSIBLE_ROLE_IMG role.

Implements

WidgetExt, glib::ObjectExt, AccessibleExt, BuildableExt, ConstraintTargetExt, WidgetExtManual, AccessibleExtManual

Implementations

impl Picture

pub fn new() -> Picture

Creates a new empty Picture widget.

Returns

a newly created Picture widget.

pub fn for_file(file: &impl IsA<File>) -> Picture

Creates a new Picture displaying the given @file.

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

If you need to detect failures to load the file, use gdk::Texture::from_file() to load the file yourself, then create the Picture from the texture.

file

a GFile

Returns

a new Picture

pub fn for_filename(filename: impl AsRef<Path>) -> Picture

Creates a new Picture displaying the file @filename.

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

filename

a filename

Returns

a new Picture

pub fn for_paintable(paintable: &impl IsA<Paintable>) -> Picture

Creates a new Picture displaying @paintable.

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

paintable

a gdk::Paintable

Returns

a new Picture

pub fn for_pixbuf(pixbuf: &Pixbuf) -> Picture

Creates a new Picture displaying @pixbuf.

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

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

pixbuf

a gdk_pixbuf::Pixbuf

Returns

a new Picture

pub fn for_resource(resource_path: &str) -> Picture

Creates a new Picture displaying the resource at @resource_path.

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

resource_path

resource path to play back

Returns

a new Picture

pub fn builder() -> PictureBuilder

Creates a new builder-pattern struct instance to construct Picture objects.

This method returns an instance of PictureBuilder which can be used to create Picture objects.

pub fn alternative_text(&self) -> Option<GString>

Gets the alternative textual description of the picture.

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

Returns

the alternative textual description of @self.

pub fn can_shrink(&self) -> bool

Returns whether the Picture respects its contents size.

Returns

true if the picture can be made smaller than its contents

pub fn file(&self) -> Option<File>

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.

Returns

The GFile displayed by @self.

pub fn is_keep_aspect_ratio(&self) -> bool

Returns whether the Picture preserves its contents aspect ratio.

Returns

true if the self tries to keep the contents’ aspect ratio

pub fn paintable(&self) -> Option<Paintable>

Gets the gdk::Paintable being displayed by the Picture.

Returns

the displayed paintable

pub fn set_alternative_text(&self, alternative_text: Option<&str>)

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.

alternative_text

a textual description of the contents

pub fn set_can_shrink(&self, can_shrink: bool)

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 WidgetExt::set_size_request().

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

can_shrink

if @self can be made smaller than its contents

pub fn set_file(&self, file: Option<&impl IsA<File>>)

Makes @self load and display @file.

See for_file() for details.

file

a GFile

pub fn set_filename(&self, filename: Option<impl AsRef<Path>>)

Makes @self load and display the given @filename.

This is a utility function that calls set_file().

filename

the filename to play

pub fn set_keep_aspect_ratio(&self, keep_aspect_ratio: bool)

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.

keep_aspect_ratio

whether to keep aspect ratio

pub fn set_paintable(&self, paintable: Option<&impl IsA<Paintable>>)

Makes @self display the given @paintable.

If @paintable is None, nothing will be displayed.

See for_paintable() for details.

paintable

a gdk::Paintable

pub fn set_pixbuf(&self, pixbuf: Option<&Pixbuf>)

Sets a Picture to show a gdk_pixbuf::Pixbuf.

See for_pixbuf() for details.

This is a utility function that calls set_paintable().

pixbuf

a gdk_pixbuf::Pixbuf

pub fn set_resource(&self, resource_path: Option<&str>)

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

This is a utility function that calls set_file().

resource_path

the resource to set

pub fn connect_alternative_text_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_can_shrink_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_file_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_keep_aspect_ratio_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_paintable_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

Trait Implementations

impl Clone for Picture

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Picture

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Picture

fn default() -> Self

Returns the “default value” for a type.

impl Display for Picture

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Picture

fn hash<H>(&self, state: &mut H)where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Picture

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl ParentClassIs for Picture

type Parent = Widget

impl<OT: ObjectType> PartialEq<OT> for Picture

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Picture

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Picture

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Picture

impl IsA<Accessible> for Picture

impl IsA<Buildable> for Picture

impl IsA<ConstraintTarget> for Picture

impl IsA<Widget> for Picture