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 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][struct@crate::GtkWidget#halign] and [valign][struct@crate::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.

Properties

alternative-text

The alternative textual description for the picture.

Readable | Writeable

can-shrink

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

Readable | Writeable

content-fit

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

Readable | Writeable

file

The GFile that is displayed or None if none.

Readable | Writeable

keep-aspect-ratio

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

Readable | Writeable

paintable

The gdk::Paintable to be displayed by this Picture.

Readable | Writeable

Widget

can-focus

Whether the widget or any of its descendents can accept the input focus.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

can-target

Whether the widget can receive pointer events.

Readable | Writeable

css-classes

A list of css classes applied to this widget.

Readable | Writeable

css-name

The name of this widget in the CSS tree.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable | Construct Only

cursor

The cursor used by @widget.

Readable | Writeable

focus-on-click

Whether the widget should grab focus when it is clicked with the mouse.

This property is only relevant for widgets that can take focus.

Readable | Writeable

focusable

Whether this widget itself will accept the input focus.

Readable | Writeable

halign

How to distribute horizontal space if widget gets extra space.

Readable | Writeable

has-default

Whether the widget is the default widget.

Readable

has-focus

Whether the widget has the input focus.

Readable

has-tooltip

Enables or disables the emission of the ::query-tooltip signal on @widget.

A value of true indicates that @widget can have a tooltip, in this case the widget will be queried using query-tooltip to determine whether it will provide a tooltip or not.

Readable | Writeable

height-request

Override for height request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

hexpand

Whether to expand horizontally.

Readable | Writeable

hexpand-set

Whether to use the hexpand property.

Readable | Writeable

layout-manager

The LayoutManager instance to use to compute the preferred size of the widget, and allocate its children.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

margin-bottom

Margin on bottom side of widget.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

margin-end

Margin on end of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

margin-start

Margin on start of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

margin-top

Margin on top side of widget.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

name

The name of the widget.

Readable | Writeable

opacity

The requested opacity of the widget.

Readable | Writeable

overflow

How content outside the widget’s content area is treated.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

parent

The parent widget of this widget.

Readable

receives-default

Whether the widget will receive the default action when it is focused.

Readable | Writeable

root

The Root widget of the widget tree containing this widget.

This will be None if the widget is not contained in a root widget.

Readable

scale-factor

The scale factor of the widget.

Readable

sensitive

Whether the widget responds to input.

Readable | Writeable

tooltip-markup

Sets the text of tooltip to be the given string, which is marked up with Pango markup.

Also see Tooltip::set_markup().

This is a convenience property which will take care of getting the tooltip shown if the given string is not None: has-tooltip will automatically be set to true and there will be taken care of query-tooltip in the default signal handler.

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

tooltip-text

Sets the text of tooltip to be the given string.

Also see Tooltip::set_text().

This is a convenience property which will take care of getting the tooltip shown if the given string is not None: has-tooltip will automatically be set to true and there will be taken care of query-tooltip in the default signal handler.

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

valign

How to distribute vertical space if widget gets extra space.

Readable | Writeable

vexpand

Whether to expand vertically.

Readable | Writeable

vexpand-set

Whether to use the vexpand property.

Readable | Writeable

visible

Whether the widget is visible.

Readable | Writeable

width-request

Override for width request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

Accessible

accessible-role

The accessible role of the given Accessible implementation.

The accessible role cannot be changed once set.

Readable | Writeable

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 content_fit(&self) -> ContentFit

Available on crate feature v4_8 only.

Returns the fit mode for the content of the Picture.

See ContentFit for details.

Returns

the content fit mode

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.

Deprecated since 4.8

Use content_fit() instead. This will now return FALSE only if content-fit is GTK_CONTENT_FIT_FILL. Returns TRUE otherwise.

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_content_fit(&self, content_fit: ContentFit)

Available on crate feature v4_8 only.

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

See ContentFit for details.

content_fit

the content fit mode

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.

Deprecated since 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.

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_content_fit_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

Available on crate feature v4_8 only.

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 HasParamSpec for Picture

type ParamSpec = ParamSpecObject

type SetValue = Picture

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, Picture>

fn param_spec_builder() -> Self::BuilderFn

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