gtk4/auto/
picture.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4#![allow(deprecated)]
5
6#[cfg(feature = "v4_8")]
7#[cfg_attr(docsrs, doc(cfg(feature = "v4_8")))]
8use crate::ContentFit;
9use crate::{
10    ffi, Accessible, AccessibleRole, Align, Buildable, ConstraintTarget, LayoutManager, Overflow,
11    Widget,
12};
13use glib::{
14    prelude::*,
15    signal::{connect_raw, SignalHandlerId},
16    translate::*,
17};
18use std::boxed::Box as Box_;
19
20glib::wrapper! {
21    /// The [`Picture`][crate::Picture] widget displays a [`gdk::Paintable`][crate::gdk::Paintable].
22    ///
23    /// ![An example GtkPicture](picture.png)
24    ///
25    /// Many convenience functions are provided to make pictures simple to use.
26    /// For example, if you want to load an image from a file, and then display
27    /// it, there’s a convenience function to do this:
28    ///
29    /// **⚠️ The following code is in c ⚠️**
30    ///
31    /// ```c
32    /// GtkWidget *widget = gtk_picture_new_for_filename ("myfile.png");
33    /// ```
34    ///
35    /// If the file isn’t loaded successfully, the picture will contain a
36    /// “broken image” icon similar to that used in many web browsers.
37    /// If you want to handle errors in loading the file yourself,
38    /// for example by displaying an error message, then load the image with
39    /// [`gdk::Texture::from_file()`][crate::gdk::Texture::from_file()], then create the [`Picture`][crate::Picture] with
40    /// [`for_paintable()`][Self::for_paintable()].
41    ///
42    /// Sometimes an application will want to avoid depending on external data
43    /// files, such as image files. See the documentation of `GResource` for details.
44    /// In this case, [`for_resource()`][Self::for_resource()] and
45    /// [`set_resource()`][Self::set_resource()] should be used.
46    ///
47    /// [`Picture`][crate::Picture] displays an image at its natural size. See [`Image`][crate::Image]
48    /// if you want to display a fixed-size image, such as an icon.
49    ///
50    /// ## Sizing the paintable
51    ///
52    /// You can influence how the paintable is displayed inside the [`Picture`][crate::Picture]
53    /// by changing [`content-fit`][struct@crate::Picture#content-fit]. See [`ContentFit`][crate::ContentFit]
54    /// for details. [`can-shrink`][struct@crate::Picture#can-shrink] can be unset to make sure
55    /// that paintables are never made smaller than their ideal size - but
56    /// be careful if you do not know the size of the paintable in use (like
57    /// when displaying user-loaded images). This can easily cause the picture to
58    /// grow larger than the screen. And [`halign`][struct@crate::Widget#halign] and
59    /// [`valign`][struct@crate::Widget#valign] can be used to make sure the paintable doesn't
60    /// fill all available space but is instead displayed at its original size.
61    ///
62    /// ## CSS nodes
63    ///
64    /// [`Picture`][crate::Picture] has a single CSS node with the name `picture`.
65    ///
66    /// ## Accessibility
67    ///
68    /// [`Picture`][crate::Picture] uses the `GTK_ACCESSIBLE_ROLE_IMG` role.
69    ///
70    /// ## Properties
71    ///
72    ///
73    /// #### `alternative-text`
74    ///  The alternative textual description for the picture.
75    ///
76    /// Readable | Writeable
77    ///
78    ///
79    /// #### `can-shrink`
80    ///  If the [`Picture`][crate::Picture] can be made smaller than the natural size of its contents.
81    ///
82    /// Readable | Writeable
83    ///
84    ///
85    /// #### `content-fit`
86    ///  How the content should be resized to fit inside the [`Picture`][crate::Picture].
87    ///
88    /// Readable | Writeable
89    ///
90    ///
91    /// #### `file`
92    ///  The `GFile` that is displayed or [`None`] if none.
93    ///
94    /// Readable | Writeable
95    ///
96    ///
97    /// #### `keep-aspect-ratio`
98    ///  Whether the GtkPicture will render its contents trying to preserve the aspect
99    /// ratio.
100    ///
101    /// Readable | Writeable
102    ///
103    ///
104    /// #### `paintable`
105    ///  The [`gdk::Paintable`][crate::gdk::Paintable] to be displayed by this [`Picture`][crate::Picture].
106    ///
107    /// Readable | Writeable
108    /// <details><summary><h4>Widget</h4></summary>
109    ///
110    ///
111    /// #### `can-focus`
112    ///  Whether the widget or any of its descendents can accept
113    /// the input focus.
114    ///
115    /// This property is meant to be set by widget implementations,
116    /// typically in their instance init function.
117    ///
118    /// Readable | Writeable
119    ///
120    ///
121    /// #### `can-target`
122    ///  Whether the widget can receive pointer events.
123    ///
124    /// Readable | Writeable
125    ///
126    ///
127    /// #### `css-classes`
128    ///  A list of css classes applied to this widget.
129    ///
130    /// Readable | Writeable
131    ///
132    ///
133    /// #### `css-name`
134    ///  The name of this widget in the CSS tree.
135    ///
136    /// This property is meant to be set by widget implementations,
137    /// typically in their instance init function.
138    ///
139    /// Readable | Writeable | Construct Only
140    ///
141    ///
142    /// #### `cursor`
143    ///  The cursor used by @widget.
144    ///
145    /// Readable | Writeable
146    ///
147    ///
148    /// #### `focus-on-click`
149    ///  Whether the widget should grab focus when it is clicked with the mouse.
150    ///
151    /// This property is only relevant for widgets that can take focus.
152    ///
153    /// Readable | Writeable
154    ///
155    ///
156    /// #### `focusable`
157    ///  Whether this widget itself will accept the input focus.
158    ///
159    /// Readable | Writeable
160    ///
161    ///
162    /// #### `halign`
163    ///  How to distribute horizontal space if widget gets extra space.
164    ///
165    /// Readable | Writeable
166    ///
167    ///
168    /// #### `has-default`
169    ///  Whether the widget is the default widget.
170    ///
171    /// Readable
172    ///
173    ///
174    /// #### `has-focus`
175    ///  Whether the widget has the input focus.
176    ///
177    /// Readable
178    ///
179    ///
180    /// #### `has-tooltip`
181    ///  Enables or disables the emission of the [`query-tooltip`][struct@crate::Widget#query-tooltip]
182    /// signal on @widget.
183    ///
184    /// A true value indicates that @widget can have a tooltip, in this case
185    /// the widget will be queried using [`query-tooltip`][struct@crate::Widget#query-tooltip] to
186    /// determine whether it will provide a tooltip or not.
187    ///
188    /// Readable | Writeable
189    ///
190    ///
191    /// #### `height-request`
192    ///  Overrides for height request of the widget.
193    ///
194    /// If this is -1, the natural request will be used.
195    ///
196    /// Readable | Writeable
197    ///
198    ///
199    /// #### `hexpand`
200    ///  Whether to expand horizontally.
201    ///
202    /// Readable | Writeable
203    ///
204    ///
205    /// #### `hexpand-set`
206    ///  Whether to use the `hexpand` property.
207    ///
208    /// Readable | Writeable
209    ///
210    ///
211    /// #### `layout-manager`
212    ///  The [`LayoutManager`][crate::LayoutManager] instance to use to compute
213    /// the preferred size of the widget, and allocate its children.
214    ///
215    /// This property is meant to be set by widget implementations,
216    /// typically in their instance init function.
217    ///
218    /// Readable | Writeable
219    ///
220    ///
221    /// #### `limit-events`
222    ///  Makes this widget act like a modal dialog, with respect to
223    /// event delivery.
224    ///
225    /// Global event controllers will not handle events with targets
226    /// inside the widget, unless they are set up to ignore propagation
227    /// limits. See [`EventControllerExt::set_propagation_limit()`][crate::prelude::EventControllerExt::set_propagation_limit()].
228    ///
229    /// Readable | Writeable
230    ///
231    ///
232    /// #### `margin-bottom`
233    ///  Margin on bottom side of widget.
234    ///
235    /// This property adds margin outside of the widget's normal size
236    /// request, the margin will be added in addition to the size from
237    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
238    ///
239    /// Readable | Writeable
240    ///
241    ///
242    /// #### `margin-end`
243    ///  Margin on end of widget, horizontally.
244    ///
245    /// This property supports left-to-right and right-to-left text
246    /// directions.
247    ///
248    /// This property adds margin outside of the widget's normal size
249    /// request, the margin will be added in addition to the size from
250    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
251    ///
252    /// Readable | Writeable
253    ///
254    ///
255    /// #### `margin-start`
256    ///  Margin on start of widget, horizontally.
257    ///
258    /// This property supports left-to-right and right-to-left text
259    /// directions.
260    ///
261    /// This property adds margin outside of the widget's normal size
262    /// request, the margin will be added in addition to the size from
263    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
264    ///
265    /// Readable | Writeable
266    ///
267    ///
268    /// #### `margin-top`
269    ///  Margin on top side of widget.
270    ///
271    /// This property adds margin outside of the widget's normal size
272    /// request, the margin will be added in addition to the size from
273    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
274    ///
275    /// Readable | Writeable
276    ///
277    ///
278    /// #### `name`
279    ///  The name of the widget.
280    ///
281    /// Readable | Writeable
282    ///
283    ///
284    /// #### `opacity`
285    ///  The requested opacity of the widget.
286    ///
287    /// Readable | Writeable
288    ///
289    ///
290    /// #### `overflow`
291    ///  How content outside the widget's content area is treated.
292    ///
293    /// This property is meant to be set by widget implementations,
294    /// typically in their instance init function.
295    ///
296    /// Readable | Writeable
297    ///
298    ///
299    /// #### `parent`
300    ///  The parent widget of this widget.
301    ///
302    /// Readable
303    ///
304    ///
305    /// #### `receives-default`
306    ///  Whether the widget will receive the default action when it is focused.
307    ///
308    /// Readable | Writeable
309    ///
310    ///
311    /// #### `root`
312    ///  The [`Root`][crate::Root] widget of the widget tree containing this widget.
313    ///
314    /// This will be `NULL` if the widget is not contained in a root widget.
315    ///
316    /// Readable
317    ///
318    ///
319    /// #### `scale-factor`
320    ///  The scale factor of the widget.
321    ///
322    /// Readable
323    ///
324    ///
325    /// #### `sensitive`
326    ///  Whether the widget responds to input.
327    ///
328    /// Readable | Writeable
329    ///
330    ///
331    /// #### `tooltip-markup`
332    ///  Sets the text of tooltip to be the given string, which is marked up
333    /// with Pango markup.
334    ///
335    /// Also see [`Tooltip::set_markup()`][crate::Tooltip::set_markup()].
336    ///
337    /// This is a convenience property which will take care of getting the
338    /// tooltip shown if the given string is not `NULL`:
339    /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
340    /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
341    /// the default signal handler.
342    ///
343    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
344    /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
345    ///
346    /// Readable | Writeable
347    ///
348    ///
349    /// #### `tooltip-text`
350    ///  Sets the text of tooltip to be the given string.
351    ///
352    /// Also see [`Tooltip::set_text()`][crate::Tooltip::set_text()].
353    ///
354    /// This is a convenience property which will take care of getting the
355    /// tooltip shown if the given string is not `NULL`:
356    /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
357    /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
358    /// the default signal handler.
359    ///
360    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
361    /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
362    ///
363    /// Readable | Writeable
364    ///
365    ///
366    /// #### `valign`
367    ///  How to distribute vertical space if widget gets extra space.
368    ///
369    /// Readable | Writeable
370    ///
371    ///
372    /// #### `vexpand`
373    ///  Whether to expand vertically.
374    ///
375    /// Readable | Writeable
376    ///
377    ///
378    /// #### `vexpand-set`
379    ///  Whether to use the `vexpand` property.
380    ///
381    /// Readable | Writeable
382    ///
383    ///
384    /// #### `visible`
385    ///  Whether the widget is visible.
386    ///
387    /// Readable | Writeable
388    ///
389    ///
390    /// #### `width-request`
391    ///  Overrides for width request of the widget.
392    ///
393    /// If this is -1, the natural request will be used.
394    ///
395    /// Readable | Writeable
396    /// </details>
397    /// <details><summary><h4>Accessible</h4></summary>
398    ///
399    ///
400    /// #### `accessible-role`
401    ///  The accessible role of the given [`Accessible`][crate::Accessible] implementation.
402    ///
403    /// The accessible role cannot be changed once set.
404    ///
405    /// Readable | Writeable
406    /// </details>
407    ///
408    /// # Implements
409    ///
410    /// [`WidgetExt`][trait@crate::prelude::WidgetExt], [`trait@glib::ObjectExt`], [`AccessibleExt`][trait@crate::prelude::AccessibleExt], [`BuildableExt`][trait@crate::prelude::BuildableExt], [`ConstraintTargetExt`][trait@crate::prelude::ConstraintTargetExt], [`WidgetExtManual`][trait@crate::prelude::WidgetExtManual], [`AccessibleExtManual`][trait@crate::prelude::AccessibleExtManual]
411    #[doc(alias = "GtkPicture")]
412    pub struct Picture(Object<ffi::GtkPicture, ffi::GtkPictureClass>) @extends Widget, @implements Accessible, Buildable, ConstraintTarget;
413
414    match fn {
415        type_ => || ffi::gtk_picture_get_type(),
416    }
417}
418
419impl Picture {
420    /// Creates a new empty [`Picture`][crate::Picture] widget.
421    ///
422    /// # Returns
423    ///
424    /// a newly created [`Picture`][crate::Picture] widget.
425    #[doc(alias = "gtk_picture_new")]
426    pub fn new() -> Picture {
427        assert_initialized_main_thread!();
428        unsafe { Widget::from_glib_none(ffi::gtk_picture_new()).unsafe_cast() }
429    }
430
431    /// Creates a new [`Picture`][crate::Picture] displaying the given @file.
432    ///
433    /// If the file isn’t found or can’t be loaded, the resulting
434    /// [`Picture`][crate::Picture] is empty.
435    ///
436    /// If you need to detect failures to load the file, use
437    /// [`gdk::Texture::from_file()`][crate::gdk::Texture::from_file()] to load the file yourself,
438    /// then create the [`Picture`][crate::Picture] from the texture.
439    /// ## `file`
440    /// a `GFile`
441    ///
442    /// # Returns
443    ///
444    /// a new [`Picture`][crate::Picture]
445    #[doc(alias = "gtk_picture_new_for_file")]
446    #[doc(alias = "new_for_file")]
447    pub fn for_file(file: &impl IsA<gio::File>) -> Picture {
448        assert_initialized_main_thread!();
449        unsafe {
450            Widget::from_glib_none(ffi::gtk_picture_new_for_file(
451                file.as_ref().to_glib_none().0,
452            ))
453            .unsafe_cast()
454        }
455    }
456
457    /// Creates a new [`Picture`][crate::Picture] displaying the file @filename.
458    ///
459    /// This is a utility function that calls [`for_file()`][Self::for_file()].
460    /// See that function for details.
461    /// ## `filename`
462    /// a filename
463    ///
464    /// # Returns
465    ///
466    /// a new [`Picture`][crate::Picture]
467    #[doc(alias = "gtk_picture_new_for_filename")]
468    #[doc(alias = "new_for_filename")]
469    pub fn for_filename(filename: impl AsRef<std::path::Path>) -> Picture {
470        assert_initialized_main_thread!();
471        unsafe {
472            Widget::from_glib_none(ffi::gtk_picture_new_for_filename(
473                filename.as_ref().to_glib_none().0,
474            ))
475            .unsafe_cast()
476        }
477    }
478
479    /// Creates a new [`Picture`][crate::Picture] displaying @paintable.
480    ///
481    /// The [`Picture`][crate::Picture] will track changes to the @paintable and update
482    /// its size and contents in response to it.
483    /// ## `paintable`
484    /// a [`gdk::Paintable`][crate::gdk::Paintable]
485    ///
486    /// # Returns
487    ///
488    /// a new [`Picture`][crate::Picture]
489    #[doc(alias = "gtk_picture_new_for_paintable")]
490    #[doc(alias = "new_for_paintable")]
491    pub fn for_paintable(paintable: &impl IsA<gdk::Paintable>) -> Picture {
492        assert_initialized_main_thread!();
493        unsafe {
494            Widget::from_glib_none(ffi::gtk_picture_new_for_paintable(
495                paintable.as_ref().to_glib_none().0,
496            ))
497            .unsafe_cast()
498        }
499    }
500
501    /// Creates a new [`Picture`][crate::Picture] displaying @pixbuf.
502    ///
503    /// This is a utility function that calls [`for_paintable()`][Self::for_paintable()],
504    /// See that function for details.
505    ///
506    /// The pixbuf must not be modified after passing it to this function.
507    ///
508    /// # Deprecated since 4.12
509    ///
510    /// Use [`for_paintable()`][Self::for_paintable()] and
511    ///   [`gdk::Texture::for_pixbuf()`][crate::gdk::Texture::for_pixbuf()] instead
512    /// ## `pixbuf`
513    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf]
514    ///
515    /// # Returns
516    ///
517    /// a new [`Picture`][crate::Picture]
518    #[cfg_attr(feature = "v4_12", deprecated = "Since 4.12")]
519    #[allow(deprecated)]
520    #[doc(alias = "gtk_picture_new_for_pixbuf")]
521    #[doc(alias = "new_for_pixbuf")]
522    pub fn for_pixbuf(pixbuf: &gdk_pixbuf::Pixbuf) -> Picture {
523        assert_initialized_main_thread!();
524        unsafe {
525            Widget::from_glib_none(ffi::gtk_picture_new_for_pixbuf(pixbuf.to_glib_none().0))
526                .unsafe_cast()
527        }
528    }
529
530    /// Creates a new [`Picture`][crate::Picture] displaying the resource at @resource_path.
531    ///
532    /// This is a utility function that calls [`for_file()`][Self::for_file()].
533    /// See that function for details.
534    /// ## `resource_path`
535    /// resource path to play back
536    ///
537    /// # Returns
538    ///
539    /// a new [`Picture`][crate::Picture]
540    #[doc(alias = "gtk_picture_new_for_resource")]
541    #[doc(alias = "new_for_resource")]
542    pub fn for_resource(resource_path: &str) -> Picture {
543        assert_initialized_main_thread!();
544        unsafe {
545            Widget::from_glib_none(ffi::gtk_picture_new_for_resource(
546                resource_path.to_glib_none().0,
547            ))
548            .unsafe_cast()
549        }
550    }
551
552    // rustdoc-stripper-ignore-next
553    /// Creates a new builder-pattern struct instance to construct [`Picture`] objects.
554    ///
555    /// This method returns an instance of [`PictureBuilder`](crate::builders::PictureBuilder) which can be used to create [`Picture`] objects.
556    pub fn builder() -> PictureBuilder {
557        PictureBuilder::new()
558    }
559
560    /// Gets the alternative textual description of the picture.
561    ///
562    /// The returned string will be [`None`] if the picture cannot be described textually.
563    ///
564    /// # Returns
565    ///
566    /// the alternative textual description of @self.
567    #[doc(alias = "gtk_picture_get_alternative_text")]
568    #[doc(alias = "get_alternative_text")]
569    #[doc(alias = "alternative-text")]
570    pub fn alternative_text(&self) -> Option<glib::GString> {
571        unsafe { from_glib_none(ffi::gtk_picture_get_alternative_text(self.to_glib_none().0)) }
572    }
573
574    /// Returns whether the [`Picture`][crate::Picture] respects its contents size.
575    ///
576    /// # Returns
577    ///
578    /// [`true`] if the picture can be made smaller than its contents
579    #[doc(alias = "gtk_picture_get_can_shrink")]
580    #[doc(alias = "get_can_shrink")]
581    #[doc(alias = "can-shrink")]
582    pub fn can_shrink(&self) -> bool {
583        unsafe { from_glib(ffi::gtk_picture_get_can_shrink(self.to_glib_none().0)) }
584    }
585
586    /// Returns the fit mode for the content of the [`Picture`][crate::Picture].
587    ///
588    /// See [`ContentFit`][crate::ContentFit] for details.
589    ///
590    /// # Returns
591    ///
592    /// the content fit mode
593    #[cfg(feature = "v4_8")]
594    #[cfg_attr(docsrs, doc(cfg(feature = "v4_8")))]
595    #[doc(alias = "gtk_picture_get_content_fit")]
596    #[doc(alias = "get_content_fit")]
597    #[doc(alias = "content-fit")]
598    pub fn content_fit(&self) -> ContentFit {
599        unsafe { from_glib(ffi::gtk_picture_get_content_fit(self.to_glib_none().0)) }
600    }
601
602    /// Gets the `GFile` currently displayed if @self is displaying a file.
603    ///
604    /// If @self is not displaying a file, for example when
605    /// [`set_paintable()`][Self::set_paintable()] was used, then [`None`] is returned.
606    ///
607    /// # Returns
608    ///
609    /// The `GFile` displayed by @self.
610    #[doc(alias = "gtk_picture_get_file")]
611    #[doc(alias = "get_file")]
612    pub fn file(&self) -> Option<gio::File> {
613        unsafe { from_glib_none(ffi::gtk_picture_get_file(self.to_glib_none().0)) }
614    }
615
616    /// Returns whether the [`Picture`][crate::Picture] preserves its contents aspect ratio.
617    ///
618    /// # Deprecated since 4.8
619    ///
620    /// Use [`content_fit()`][Self::content_fit()] instead. This will
621    ///   now return `FALSE` only if [`content-fit`][struct@crate::Picture#content-fit] is
622    ///   `GTK_CONTENT_FIT_FILL`. Returns `TRUE` otherwise.
623    ///
624    /// # Returns
625    ///
626    /// [`true`] if the self tries to keep the contents' aspect ratio
627    #[cfg_attr(feature = "v4_8", deprecated = "Since 4.8")]
628    #[allow(deprecated)]
629    #[doc(alias = "gtk_picture_get_keep_aspect_ratio")]
630    #[doc(alias = "get_keep_aspect_ratio")]
631    #[doc(alias = "keep-aspect-ratio")]
632    pub fn is_keep_aspect_ratio(&self) -> bool {
633        unsafe {
634            from_glib(ffi::gtk_picture_get_keep_aspect_ratio(
635                self.to_glib_none().0,
636            ))
637        }
638    }
639
640    /// Gets the [`gdk::Paintable`][crate::gdk::Paintable] being displayed by the [`Picture`][crate::Picture].
641    ///
642    /// # Returns
643    ///
644    /// the displayed paintable
645    #[doc(alias = "gtk_picture_get_paintable")]
646    #[doc(alias = "get_paintable")]
647    pub fn paintable(&self) -> Option<gdk::Paintable> {
648        unsafe { from_glib_none(ffi::gtk_picture_get_paintable(self.to_glib_none().0)) }
649    }
650
651    /// Sets an alternative textual description for the picture contents.
652    ///
653    /// It is equivalent to the "alt" attribute for images on websites.
654    ///
655    /// This text will be made available to accessibility tools.
656    ///
657    /// If the picture cannot be described textually, set this property to [`None`].
658    /// ## `alternative_text`
659    /// a textual description of the contents
660    #[doc(alias = "gtk_picture_set_alternative_text")]
661    #[doc(alias = "alternative-text")]
662    pub fn set_alternative_text(&self, alternative_text: Option<&str>) {
663        unsafe {
664            ffi::gtk_picture_set_alternative_text(
665                self.to_glib_none().0,
666                alternative_text.to_glib_none().0,
667            );
668        }
669    }
670
671    /// If set to [`true`], the @self can be made smaller than its contents.
672    ///
673    /// The contents will then be scaled down when rendering.
674    ///
675    /// If you want to still force a minimum size manually, consider using
676    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()].
677    ///
678    /// Also of note is that a similar function for growing does not exist
679    /// because the grow behavior can be controlled via
680    /// [`WidgetExt::set_halign()`][crate::prelude::WidgetExt::set_halign()] and [`WidgetExt::set_valign()`][crate::prelude::WidgetExt::set_valign()].
681    /// ## `can_shrink`
682    /// if @self can be made smaller than its contents
683    #[doc(alias = "gtk_picture_set_can_shrink")]
684    #[doc(alias = "can-shrink")]
685    pub fn set_can_shrink(&self, can_shrink: bool) {
686        unsafe {
687            ffi::gtk_picture_set_can_shrink(self.to_glib_none().0, can_shrink.into_glib());
688        }
689    }
690
691    /// Sets how the content should be resized to fit the [`Picture`][crate::Picture].
692    ///
693    /// See [`ContentFit`][crate::ContentFit] for details.
694    /// ## `content_fit`
695    /// the content fit mode
696    #[cfg(feature = "v4_8")]
697    #[cfg_attr(docsrs, doc(cfg(feature = "v4_8")))]
698    #[doc(alias = "gtk_picture_set_content_fit")]
699    #[doc(alias = "content-fit")]
700    pub fn set_content_fit(&self, content_fit: ContentFit) {
701        unsafe {
702            ffi::gtk_picture_set_content_fit(self.to_glib_none().0, content_fit.into_glib());
703        }
704    }
705
706    /// Makes @self load and display @file.
707    ///
708    /// See [`for_file()`][Self::for_file()] for details.
709    /// ## `file`
710    /// a `GFile`
711    #[doc(alias = "gtk_picture_set_file")]
712    #[doc(alias = "file")]
713    pub fn set_file(&self, file: Option<&impl IsA<gio::File>>) {
714        unsafe {
715            ffi::gtk_picture_set_file(
716                self.to_glib_none().0,
717                file.map(|p| p.as_ref()).to_glib_none().0,
718            );
719        }
720    }
721
722    /// Makes @self load and display the given @filename.
723    ///
724    /// This is a utility function that calls [`set_file()`][Self::set_file()].
725    /// ## `filename`
726    /// the filename to play
727    #[doc(alias = "gtk_picture_set_filename")]
728    pub fn set_filename(&self, filename: Option<impl AsRef<std::path::Path>>) {
729        unsafe {
730            ffi::gtk_picture_set_filename(
731                self.to_glib_none().0,
732                filename.as_ref().map(|p| p.as_ref()).to_glib_none().0,
733            );
734        }
735    }
736
737    /// If set to [`true`], the @self will render its contents according to
738    /// their aspect ratio.
739    ///
740    /// That means that empty space may show up at the top/bottom or
741    /// left/right of @self.
742    ///
743    /// If set to [`false`] or if the contents provide no aspect ratio,
744    /// the contents will be stretched over the picture's whole area.
745    ///
746    /// # Deprecated since 4.8
747    ///
748    /// Use [`set_content_fit()`][Self::set_content_fit()] instead. If still
749    ///   used, this method will always set the [`content-fit`][struct@crate::Picture#content-fit]
750    ///   property to `GTK_CONTENT_FIT_CONTAIN` if @keep_aspect_ratio is true,
751    ///   otherwise it will set it to `GTK_CONTENT_FIT_FILL`.
752    /// ## `keep_aspect_ratio`
753    /// whether to keep aspect ratio
754    #[cfg_attr(feature = "v4_8", deprecated = "Since 4.8")]
755    #[allow(deprecated)]
756    #[doc(alias = "gtk_picture_set_keep_aspect_ratio")]
757    #[doc(alias = "keep-aspect-ratio")]
758    pub fn set_keep_aspect_ratio(&self, keep_aspect_ratio: bool) {
759        unsafe {
760            ffi::gtk_picture_set_keep_aspect_ratio(
761                self.to_glib_none().0,
762                keep_aspect_ratio.into_glib(),
763            );
764        }
765    }
766
767    /// Makes @self display the given @paintable.
768    ///
769    /// If @paintable is [`None`], nothing will be displayed.
770    ///
771    /// See [`for_paintable()`][Self::for_paintable()] for details.
772    /// ## `paintable`
773    /// a [`gdk::Paintable`][crate::gdk::Paintable]
774    #[doc(alias = "gtk_picture_set_paintable")]
775    #[doc(alias = "paintable")]
776    pub fn set_paintable(&self, paintable: Option<&impl IsA<gdk::Paintable>>) {
777        unsafe {
778            ffi::gtk_picture_set_paintable(
779                self.to_glib_none().0,
780                paintable.map(|p| p.as_ref()).to_glib_none().0,
781            );
782        }
783    }
784
785    /// Sets a [`Picture`][crate::Picture] to show a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf].
786    ///
787    /// See [`for_pixbuf()`][Self::for_pixbuf()] for details.
788    ///
789    /// This is a utility function that calls [`set_paintable()`][Self::set_paintable()].
790    ///
791    /// # Deprecated since 4.12
792    ///
793    /// Use [`set_paintable()`][Self::set_paintable()] instead
794    /// ## `pixbuf`
795    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf]
796    #[cfg_attr(feature = "v4_12", deprecated = "Since 4.12")]
797    #[allow(deprecated)]
798    #[doc(alias = "gtk_picture_set_pixbuf")]
799    pub fn set_pixbuf(&self, pixbuf: Option<&gdk_pixbuf::Pixbuf>) {
800        unsafe {
801            ffi::gtk_picture_set_pixbuf(self.to_glib_none().0, pixbuf.to_glib_none().0);
802        }
803    }
804
805    /// Makes @self load and display the resource at the given
806    /// @resource_path.
807    ///
808    /// This is a utility function that calls [`set_file()`][Self::set_file()].
809    /// ## `resource_path`
810    /// the resource to set
811    #[doc(alias = "gtk_picture_set_resource")]
812    pub fn set_resource(&self, resource_path: Option<&str>) {
813        unsafe {
814            ffi::gtk_picture_set_resource(self.to_glib_none().0, resource_path.to_glib_none().0);
815        }
816    }
817
818    #[doc(alias = "alternative-text")]
819    pub fn connect_alternative_text_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
820        unsafe extern "C" fn notify_alternative_text_trampoline<F: Fn(&Picture) + 'static>(
821            this: *mut ffi::GtkPicture,
822            _param_spec: glib::ffi::gpointer,
823            f: glib::ffi::gpointer,
824        ) {
825            let f: &F = &*(f as *const F);
826            f(&from_glib_borrow(this))
827        }
828        unsafe {
829            let f: Box_<F> = Box_::new(f);
830            connect_raw(
831                self.as_ptr() as *mut _,
832                b"notify::alternative-text\0".as_ptr() as *const _,
833                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
834                    notify_alternative_text_trampoline::<F> as *const (),
835                )),
836                Box_::into_raw(f),
837            )
838        }
839    }
840
841    #[doc(alias = "can-shrink")]
842    pub fn connect_can_shrink_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
843        unsafe extern "C" fn notify_can_shrink_trampoline<F: Fn(&Picture) + 'static>(
844            this: *mut ffi::GtkPicture,
845            _param_spec: glib::ffi::gpointer,
846            f: glib::ffi::gpointer,
847        ) {
848            let f: &F = &*(f as *const F);
849            f(&from_glib_borrow(this))
850        }
851        unsafe {
852            let f: Box_<F> = Box_::new(f);
853            connect_raw(
854                self.as_ptr() as *mut _,
855                b"notify::can-shrink\0".as_ptr() as *const _,
856                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
857                    notify_can_shrink_trampoline::<F> as *const (),
858                )),
859                Box_::into_raw(f),
860            )
861        }
862    }
863
864    #[cfg(feature = "v4_8")]
865    #[cfg_attr(docsrs, doc(cfg(feature = "v4_8")))]
866    #[doc(alias = "content-fit")]
867    pub fn connect_content_fit_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
868        unsafe extern "C" fn notify_content_fit_trampoline<F: Fn(&Picture) + 'static>(
869            this: *mut ffi::GtkPicture,
870            _param_spec: glib::ffi::gpointer,
871            f: glib::ffi::gpointer,
872        ) {
873            let f: &F = &*(f as *const F);
874            f(&from_glib_borrow(this))
875        }
876        unsafe {
877            let f: Box_<F> = Box_::new(f);
878            connect_raw(
879                self.as_ptr() as *mut _,
880                b"notify::content-fit\0".as_ptr() as *const _,
881                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
882                    notify_content_fit_trampoline::<F> as *const (),
883                )),
884                Box_::into_raw(f),
885            )
886        }
887    }
888
889    #[doc(alias = "file")]
890    pub fn connect_file_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
891        unsafe extern "C" fn notify_file_trampoline<F: Fn(&Picture) + 'static>(
892            this: *mut ffi::GtkPicture,
893            _param_spec: glib::ffi::gpointer,
894            f: glib::ffi::gpointer,
895        ) {
896            let f: &F = &*(f as *const F);
897            f(&from_glib_borrow(this))
898        }
899        unsafe {
900            let f: Box_<F> = Box_::new(f);
901            connect_raw(
902                self.as_ptr() as *mut _,
903                b"notify::file\0".as_ptr() as *const _,
904                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
905                    notify_file_trampoline::<F> as *const (),
906                )),
907                Box_::into_raw(f),
908            )
909        }
910    }
911
912    #[cfg_attr(feature = "v4_8", deprecated = "Since 4.8")]
913    #[doc(alias = "keep-aspect-ratio")]
914    pub fn connect_keep_aspect_ratio_notify<F: Fn(&Self) + 'static>(
915        &self,
916        f: F,
917    ) -> SignalHandlerId {
918        unsafe extern "C" fn notify_keep_aspect_ratio_trampoline<F: Fn(&Picture) + 'static>(
919            this: *mut ffi::GtkPicture,
920            _param_spec: glib::ffi::gpointer,
921            f: glib::ffi::gpointer,
922        ) {
923            let f: &F = &*(f as *const F);
924            f(&from_glib_borrow(this))
925        }
926        unsafe {
927            let f: Box_<F> = Box_::new(f);
928            connect_raw(
929                self.as_ptr() as *mut _,
930                b"notify::keep-aspect-ratio\0".as_ptr() as *const _,
931                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
932                    notify_keep_aspect_ratio_trampoline::<F> as *const (),
933                )),
934                Box_::into_raw(f),
935            )
936        }
937    }
938
939    #[doc(alias = "paintable")]
940    pub fn connect_paintable_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
941        unsafe extern "C" fn notify_paintable_trampoline<F: Fn(&Picture) + 'static>(
942            this: *mut ffi::GtkPicture,
943            _param_spec: glib::ffi::gpointer,
944            f: glib::ffi::gpointer,
945        ) {
946            let f: &F = &*(f as *const F);
947            f(&from_glib_borrow(this))
948        }
949        unsafe {
950            let f: Box_<F> = Box_::new(f);
951            connect_raw(
952                self.as_ptr() as *mut _,
953                b"notify::paintable\0".as_ptr() as *const _,
954                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
955                    notify_paintable_trampoline::<F> as *const (),
956                )),
957                Box_::into_raw(f),
958            )
959        }
960    }
961}
962
963impl Default for Picture {
964    fn default() -> Self {
965        Self::new()
966    }
967}
968
969// rustdoc-stripper-ignore-next
970/// A [builder-pattern] type to construct [`Picture`] objects.
971///
972/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
973#[must_use = "The builder must be built to be used"]
974pub struct PictureBuilder {
975    builder: glib::object::ObjectBuilder<'static, Picture>,
976}
977
978impl PictureBuilder {
979    fn new() -> Self {
980        Self {
981            builder: glib::object::Object::builder(),
982        }
983    }
984
985    /// The alternative textual description for the picture.
986    pub fn alternative_text(self, alternative_text: impl Into<glib::GString>) -> Self {
987        Self {
988            builder: self
989                .builder
990                .property("alternative-text", alternative_text.into()),
991        }
992    }
993
994    /// If the [`Picture`][crate::Picture] can be made smaller than the natural size of its contents.
995    pub fn can_shrink(self, can_shrink: bool) -> Self {
996        Self {
997            builder: self.builder.property("can-shrink", can_shrink),
998        }
999    }
1000
1001    /// How the content should be resized to fit inside the [`Picture`][crate::Picture].
1002    #[cfg(feature = "v4_8")]
1003    #[cfg_attr(docsrs, doc(cfg(feature = "v4_8")))]
1004    pub fn content_fit(self, content_fit: ContentFit) -> Self {
1005        Self {
1006            builder: self.builder.property("content-fit", content_fit),
1007        }
1008    }
1009
1010    /// The `GFile` that is displayed or [`None`] if none.
1011    pub fn file(self, file: &impl IsA<gio::File>) -> Self {
1012        Self {
1013            builder: self.builder.property("file", file.clone().upcast()),
1014        }
1015    }
1016
1017    /// Whether the GtkPicture will render its contents trying to preserve the aspect
1018    /// ratio.
1019    /// Use [`content-fit`][struct@crate::Picture#content-fit] instead.
1020    #[cfg_attr(feature = "v4_8", deprecated = "Since 4.8")]
1021    pub fn keep_aspect_ratio(self, keep_aspect_ratio: bool) -> Self {
1022        Self {
1023            builder: self
1024                .builder
1025                .property("keep-aspect-ratio", keep_aspect_ratio),
1026        }
1027    }
1028
1029    /// The [`gdk::Paintable`][crate::gdk::Paintable] to be displayed by this [`Picture`][crate::Picture].
1030    pub fn paintable(self, paintable: &impl IsA<gdk::Paintable>) -> Self {
1031        Self {
1032            builder: self
1033                .builder
1034                .property("paintable", paintable.clone().upcast()),
1035        }
1036    }
1037
1038    /// Whether the widget or any of its descendents can accept
1039    /// the input focus.
1040    ///
1041    /// This property is meant to be set by widget implementations,
1042    /// typically in their instance init function.
1043    pub fn can_focus(self, can_focus: bool) -> Self {
1044        Self {
1045            builder: self.builder.property("can-focus", can_focus),
1046        }
1047    }
1048
1049    /// Whether the widget can receive pointer events.
1050    pub fn can_target(self, can_target: bool) -> Self {
1051        Self {
1052            builder: self.builder.property("can-target", can_target),
1053        }
1054    }
1055
1056    /// A list of css classes applied to this widget.
1057    pub fn css_classes(self, css_classes: impl Into<glib::StrV>) -> Self {
1058        Self {
1059            builder: self.builder.property("css-classes", css_classes.into()),
1060        }
1061    }
1062
1063    /// The name of this widget in the CSS tree.
1064    ///
1065    /// This property is meant to be set by widget implementations,
1066    /// typically in their instance init function.
1067    pub fn css_name(self, css_name: impl Into<glib::GString>) -> Self {
1068        Self {
1069            builder: self.builder.property("css-name", css_name.into()),
1070        }
1071    }
1072
1073    /// The cursor used by @widget.
1074    pub fn cursor(self, cursor: &gdk::Cursor) -> Self {
1075        Self {
1076            builder: self.builder.property("cursor", cursor.clone()),
1077        }
1078    }
1079
1080    /// Whether the widget should grab focus when it is clicked with the mouse.
1081    ///
1082    /// This property is only relevant for widgets that can take focus.
1083    pub fn focus_on_click(self, focus_on_click: bool) -> Self {
1084        Self {
1085            builder: self.builder.property("focus-on-click", focus_on_click),
1086        }
1087    }
1088
1089    /// Whether this widget itself will accept the input focus.
1090    pub fn focusable(self, focusable: bool) -> Self {
1091        Self {
1092            builder: self.builder.property("focusable", focusable),
1093        }
1094    }
1095
1096    /// How to distribute horizontal space if widget gets extra space.
1097    pub fn halign(self, halign: Align) -> Self {
1098        Self {
1099            builder: self.builder.property("halign", halign),
1100        }
1101    }
1102
1103    /// Enables or disables the emission of the [`query-tooltip`][struct@crate::Widget#query-tooltip]
1104    /// signal on @widget.
1105    ///
1106    /// A true value indicates that @widget can have a tooltip, in this case
1107    /// the widget will be queried using [`query-tooltip`][struct@crate::Widget#query-tooltip] to
1108    /// determine whether it will provide a tooltip or not.
1109    pub fn has_tooltip(self, has_tooltip: bool) -> Self {
1110        Self {
1111            builder: self.builder.property("has-tooltip", has_tooltip),
1112        }
1113    }
1114
1115    /// Overrides for height request of the widget.
1116    ///
1117    /// If this is -1, the natural request will be used.
1118    pub fn height_request(self, height_request: i32) -> Self {
1119        Self {
1120            builder: self.builder.property("height-request", height_request),
1121        }
1122    }
1123
1124    /// Whether to expand horizontally.
1125    pub fn hexpand(self, hexpand: bool) -> Self {
1126        Self {
1127            builder: self.builder.property("hexpand", hexpand),
1128        }
1129    }
1130
1131    /// Whether to use the `hexpand` property.
1132    pub fn hexpand_set(self, hexpand_set: bool) -> Self {
1133        Self {
1134            builder: self.builder.property("hexpand-set", hexpand_set),
1135        }
1136    }
1137
1138    /// The [`LayoutManager`][crate::LayoutManager] instance to use to compute
1139    /// the preferred size of the widget, and allocate its children.
1140    ///
1141    /// This property is meant to be set by widget implementations,
1142    /// typically in their instance init function.
1143    pub fn layout_manager(self, layout_manager: &impl IsA<LayoutManager>) -> Self {
1144        Self {
1145            builder: self
1146                .builder
1147                .property("layout-manager", layout_manager.clone().upcast()),
1148        }
1149    }
1150
1151    /// Makes this widget act like a modal dialog, with respect to
1152    /// event delivery.
1153    ///
1154    /// Global event controllers will not handle events with targets
1155    /// inside the widget, unless they are set up to ignore propagation
1156    /// limits. See [`EventControllerExt::set_propagation_limit()`][crate::prelude::EventControllerExt::set_propagation_limit()].
1157    #[cfg(feature = "v4_18")]
1158    #[cfg_attr(docsrs, doc(cfg(feature = "v4_18")))]
1159    pub fn limit_events(self, limit_events: bool) -> Self {
1160        Self {
1161            builder: self.builder.property("limit-events", limit_events),
1162        }
1163    }
1164
1165    /// Margin on bottom side of widget.
1166    ///
1167    /// This property adds margin outside of the widget's normal size
1168    /// request, the margin will be added in addition to the size from
1169    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
1170    pub fn margin_bottom(self, margin_bottom: i32) -> Self {
1171        Self {
1172            builder: self.builder.property("margin-bottom", margin_bottom),
1173        }
1174    }
1175
1176    /// Margin on end of widget, horizontally.
1177    ///
1178    /// This property supports left-to-right and right-to-left text
1179    /// directions.
1180    ///
1181    /// This property adds margin outside of the widget's normal size
1182    /// request, the margin will be added in addition to the size from
1183    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
1184    pub fn margin_end(self, margin_end: i32) -> Self {
1185        Self {
1186            builder: self.builder.property("margin-end", margin_end),
1187        }
1188    }
1189
1190    /// Margin on start of widget, horizontally.
1191    ///
1192    /// This property supports left-to-right and right-to-left text
1193    /// directions.
1194    ///
1195    /// This property adds margin outside of the widget's normal size
1196    /// request, the margin will be added in addition to the size from
1197    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
1198    pub fn margin_start(self, margin_start: i32) -> Self {
1199        Self {
1200            builder: self.builder.property("margin-start", margin_start),
1201        }
1202    }
1203
1204    /// Margin on top side of widget.
1205    ///
1206    /// This property adds margin outside of the widget's normal size
1207    /// request, the margin will be added in addition to the size from
1208    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
1209    pub fn margin_top(self, margin_top: i32) -> Self {
1210        Self {
1211            builder: self.builder.property("margin-top", margin_top),
1212        }
1213    }
1214
1215    /// The name of the widget.
1216    pub fn name(self, name: impl Into<glib::GString>) -> Self {
1217        Self {
1218            builder: self.builder.property("name", name.into()),
1219        }
1220    }
1221
1222    /// The requested opacity of the widget.
1223    pub fn opacity(self, opacity: f64) -> Self {
1224        Self {
1225            builder: self.builder.property("opacity", opacity),
1226        }
1227    }
1228
1229    /// How content outside the widget's content area is treated.
1230    ///
1231    /// This property is meant to be set by widget implementations,
1232    /// typically in their instance init function.
1233    pub fn overflow(self, overflow: Overflow) -> Self {
1234        Self {
1235            builder: self.builder.property("overflow", overflow),
1236        }
1237    }
1238
1239    /// Whether the widget will receive the default action when it is focused.
1240    pub fn receives_default(self, receives_default: bool) -> Self {
1241        Self {
1242            builder: self.builder.property("receives-default", receives_default),
1243        }
1244    }
1245
1246    /// Whether the widget responds to input.
1247    pub fn sensitive(self, sensitive: bool) -> Self {
1248        Self {
1249            builder: self.builder.property("sensitive", sensitive),
1250        }
1251    }
1252
1253    /// Sets the text of tooltip to be the given string, which is marked up
1254    /// with Pango markup.
1255    ///
1256    /// Also see [`Tooltip::set_markup()`][crate::Tooltip::set_markup()].
1257    ///
1258    /// This is a convenience property which will take care of getting the
1259    /// tooltip shown if the given string is not `NULL`:
1260    /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
1261    /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
1262    /// the default signal handler.
1263    ///
1264    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
1265    /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
1266    pub fn tooltip_markup(self, tooltip_markup: impl Into<glib::GString>) -> Self {
1267        Self {
1268            builder: self
1269                .builder
1270                .property("tooltip-markup", tooltip_markup.into()),
1271        }
1272    }
1273
1274    /// Sets the text of tooltip to be the given string.
1275    ///
1276    /// Also see [`Tooltip::set_text()`][crate::Tooltip::set_text()].
1277    ///
1278    /// This is a convenience property which will take care of getting the
1279    /// tooltip shown if the given string is not `NULL`:
1280    /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
1281    /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
1282    /// the default signal handler.
1283    ///
1284    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
1285    /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
1286    pub fn tooltip_text(self, tooltip_text: impl Into<glib::GString>) -> Self {
1287        Self {
1288            builder: self.builder.property("tooltip-text", tooltip_text.into()),
1289        }
1290    }
1291
1292    /// How to distribute vertical space if widget gets extra space.
1293    pub fn valign(self, valign: Align) -> Self {
1294        Self {
1295            builder: self.builder.property("valign", valign),
1296        }
1297    }
1298
1299    /// Whether to expand vertically.
1300    pub fn vexpand(self, vexpand: bool) -> Self {
1301        Self {
1302            builder: self.builder.property("vexpand", vexpand),
1303        }
1304    }
1305
1306    /// Whether to use the `vexpand` property.
1307    pub fn vexpand_set(self, vexpand_set: bool) -> Self {
1308        Self {
1309            builder: self.builder.property("vexpand-set", vexpand_set),
1310        }
1311    }
1312
1313    /// Whether the widget is visible.
1314    pub fn visible(self, visible: bool) -> Self {
1315        Self {
1316            builder: self.builder.property("visible", visible),
1317        }
1318    }
1319
1320    /// Overrides for width request of the widget.
1321    ///
1322    /// If this is -1, the natural request will be used.
1323    pub fn width_request(self, width_request: i32) -> Self {
1324        Self {
1325            builder: self.builder.property("width-request", width_request),
1326        }
1327    }
1328
1329    /// The accessible role of the given [`Accessible`][crate::Accessible] implementation.
1330    ///
1331    /// The accessible role cannot be changed once set.
1332    pub fn accessible_role(self, accessible_role: AccessibleRole) -> Self {
1333        Self {
1334            builder: self.builder.property("accessible-role", accessible_role),
1335        }
1336    }
1337
1338    // rustdoc-stripper-ignore-next
1339    /// Build the [`Picture`].
1340    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
1341    pub fn build(self) -> Picture {
1342        assert_initialized_main_thread!();
1343        self.builder.build()
1344    }
1345}