gtk4/auto/
image.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
6use crate::{
7    ffi, Accessible, AccessibleRole, Align, Buildable, ConstraintTarget, IconSize, ImageType,
8    LayoutManager, Overflow, Widget,
9};
10use glib::{
11    prelude::*,
12    signal::{connect_raw, SignalHandlerId},
13    translate::*,
14};
15use std::boxed::Box as Box_;
16
17glib::wrapper! {
18    /// Displays an image.
19    ///
20    /// picture>
21    ///   <source srcset="image-dark.png" media="(prefers-color-scheme: dark)">
22    ///   <img alt="An example GtkImage" src="image.png">
23    /// </picture>
24    ///
25    /// Various kinds of object can be displayed as an image; most typically,
26    /// you would load a [`gdk::Texture`][crate::gdk::Texture] from a file, using the convenience function
27    /// [`from_file()`][Self::from_file()], for instance:
28    ///
29    /// **⚠️ The following code is in c ⚠️**
30    ///
31    /// ```c
32    /// GtkWidget *image = gtk_image_new_from_file ("myfile.png");
33    /// ```
34    ///
35    /// If the file isn’t loaded successfully, the image will contain a
36    /// “broken image” icon similar to that used in many web browsers.
37    ///
38    /// If you want to handle errors in loading the file yourself, for example
39    /// by displaying an error message, then load the image with an image
40    /// loading framework such as libglycin, then create the [`Image`][crate::Image] with
41    /// [`from_paintable()`][Self::from_paintable()].
42    ///
43    /// Sometimes an application will want to avoid depending on external data
44    /// files, such as image files. See the documentation of `GResource` inside
45    /// GIO, for details. In this case, [`resource`][struct@crate::Image#resource],
46    /// [`from_resource()`][Self::from_resource()], and [`set_resource()`][Self::set_resource()]
47    /// should be used.
48    ///
49    /// [`Image`][crate::Image] displays its image as an icon, with a size that is determined
50    /// by the application. See [`Picture`][crate::Picture] if you want to show an image
51    /// at is actual size.
52    ///
53    /// ## CSS nodes
54    ///
55    /// [`Image`][crate::Image] has a single CSS node with the name `image`. The style classes
56    /// `.normal-icons` or `.large-icons` may appear, depending on the
57    /// [`icon-size`][struct@crate::Image#icon-size] property.
58    ///
59    /// ## Accessibility
60    ///
61    /// [`Image`][crate::Image] uses the [enum@Gtk.AccessibleRole.img] role.
62    ///
63    /// ## Properties
64    ///
65    ///
66    /// #### `file`
67    ///  A path to the file to display.
68    ///
69    /// Readable | Writeable
70    ///
71    ///
72    /// #### `gicon`
73    ///  The `GIcon` displayed in the GtkImage.
74    ///
75    /// For themed icons, If the icon theme is changed, the image will be updated
76    /// automatically.
77    ///
78    /// Readable | Writeable
79    ///
80    ///
81    /// #### `icon-name`
82    ///  The name of the icon in the icon theme.
83    ///
84    /// If the icon theme is changed, the image will be updated automatically.
85    ///
86    /// Readable | Writeable
87    ///
88    ///
89    /// #### `icon-size`
90    ///  The symbolic size to display icons at.
91    ///
92    /// Readable | Writeable
93    ///
94    ///
95    /// #### `paintable`
96    ///  The [`gdk::Paintable`][crate::gdk::Paintable] to display.
97    ///
98    /// Readable | Writeable
99    ///
100    ///
101    /// #### `pixel-size`
102    ///  The size in pixels to display icons at.
103    ///
104    /// If set to a value != -1, this property overrides the
105    /// [`icon-size`][struct@crate::Image#icon-size] property for images of type
106    /// `GTK_IMAGE_ICON_NAME`.
107    ///
108    /// Readable | Writeable
109    ///
110    ///
111    /// #### `resource`
112    ///  A path to a resource file to display.
113    ///
114    /// Readable | Writeable
115    ///
116    ///
117    /// #### `storage-type`
118    ///  The representation being used for image data.
119    ///
120    /// Readable
121    ///
122    ///
123    /// #### `use-fallback`
124    ///  Whether the icon displayed in the [`Image`][crate::Image] will use
125    /// standard icon names fallback.
126    ///
127    /// The value of this property is only relevant for images of type
128    /// [`ImageType::IconName`][crate::ImageType::IconName] and [`ImageType::Gicon`][crate::ImageType::Gicon].
129    ///
130    /// Readable | Writeable
131    /// <details><summary><h4>Widget</h4></summary>
132    ///
133    ///
134    /// #### `can-focus`
135    ///  Whether the widget or any of its descendents can accept
136    /// the input focus.
137    ///
138    /// This property is meant to be set by widget implementations,
139    /// typically in their instance init function.
140    ///
141    /// Readable | Writeable
142    ///
143    ///
144    /// #### `can-target`
145    ///  Whether the widget can receive pointer events.
146    ///
147    /// Readable | Writeable
148    ///
149    ///
150    /// #### `css-classes`
151    ///  A list of css classes applied to this widget.
152    ///
153    /// Readable | Writeable
154    ///
155    ///
156    /// #### `css-name`
157    ///  The name of this widget in the CSS tree.
158    ///
159    /// This property is meant to be set by widget implementations,
160    /// typically in their instance init function.
161    ///
162    /// Readable | Writeable | Construct Only
163    ///
164    ///
165    /// #### `cursor`
166    ///  The cursor used by @widget.
167    ///
168    /// Readable | Writeable
169    ///
170    ///
171    /// #### `focus-on-click`
172    ///  Whether the widget should grab focus when it is clicked with the mouse.
173    ///
174    /// This property is only relevant for widgets that can take focus.
175    ///
176    /// Readable | Writeable
177    ///
178    ///
179    /// #### `focusable`
180    ///  Whether this widget itself will accept the input focus.
181    ///
182    /// Readable | Writeable
183    ///
184    ///
185    /// #### `halign`
186    ///  How to distribute horizontal space if widget gets extra space.
187    ///
188    /// Readable | Writeable
189    ///
190    ///
191    /// #### `has-default`
192    ///  Whether the widget is the default widget.
193    ///
194    /// Readable
195    ///
196    ///
197    /// #### `has-focus`
198    ///  Whether the widget has the input focus.
199    ///
200    /// Readable
201    ///
202    ///
203    /// #### `has-tooltip`
204    ///  Enables or disables the emission of the [`query-tooltip`][struct@crate::Widget#query-tooltip]
205    /// signal on @widget.
206    ///
207    /// A true value indicates that @widget can have a tooltip, in this case
208    /// the widget will be queried using [`query-tooltip`][struct@crate::Widget#query-tooltip] to
209    /// determine whether it will provide a tooltip or not.
210    ///
211    /// Readable | Writeable
212    ///
213    ///
214    /// #### `height-request`
215    ///  Overrides for height request of the widget.
216    ///
217    /// If this is -1, the natural request will be used.
218    ///
219    /// Readable | Writeable
220    ///
221    ///
222    /// #### `hexpand`
223    ///  Whether to expand horizontally.
224    ///
225    /// Readable | Writeable
226    ///
227    ///
228    /// #### `hexpand-set`
229    ///  Whether to use the `hexpand` property.
230    ///
231    /// Readable | Writeable
232    ///
233    ///
234    /// #### `layout-manager`
235    ///  The [`LayoutManager`][crate::LayoutManager] instance to use to compute
236    /// the preferred size of the widget, and allocate its children.
237    ///
238    /// This property is meant to be set by widget implementations,
239    /// typically in their instance init function.
240    ///
241    /// Readable | Writeable
242    ///
243    ///
244    /// #### `limit-events`
245    ///  Makes this widget act like a modal dialog, with respect to
246    /// event delivery.
247    ///
248    /// Global event controllers will not handle events with targets
249    /// inside the widget, unless they are set up to ignore propagation
250    /// limits. See [`EventControllerExt::set_propagation_limit()`][crate::prelude::EventControllerExt::set_propagation_limit()].
251    ///
252    /// Readable | Writeable
253    ///
254    ///
255    /// #### `margin-bottom`
256    ///  Margin on bottom side of widget.
257    ///
258    /// This property adds margin outside of the widget's normal size
259    /// request, the margin will be added in addition to the size from
260    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
261    ///
262    /// Readable | Writeable
263    ///
264    ///
265    /// #### `margin-end`
266    ///  Margin on end of widget, horizontally.
267    ///
268    /// This property supports left-to-right and right-to-left text
269    /// directions.
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    /// #### `margin-start`
279    ///  Margin on start of widget, horizontally.
280    ///
281    /// This property supports left-to-right and right-to-left text
282    /// directions.
283    ///
284    /// This property adds margin outside of the widget's normal size
285    /// request, the margin will be added in addition to the size from
286    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
287    ///
288    /// Readable | Writeable
289    ///
290    ///
291    /// #### `margin-top`
292    ///  Margin on top side of widget.
293    ///
294    /// This property adds margin outside of the widget's normal size
295    /// request, the margin will be added in addition to the size from
296    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
297    ///
298    /// Readable | Writeable
299    ///
300    ///
301    /// #### `name`
302    ///  The name of the widget.
303    ///
304    /// Readable | Writeable
305    ///
306    ///
307    /// #### `opacity`
308    ///  The requested opacity of the widget.
309    ///
310    /// Readable | Writeable
311    ///
312    ///
313    /// #### `overflow`
314    ///  How content outside the widget's content area is treated.
315    ///
316    /// This property is meant to be set by widget implementations,
317    /// typically in their instance init function.
318    ///
319    /// Readable | Writeable
320    ///
321    ///
322    /// #### `parent`
323    ///  The parent widget of this widget.
324    ///
325    /// Readable
326    ///
327    ///
328    /// #### `receives-default`
329    ///  Whether the widget will receive the default action when it is focused.
330    ///
331    /// Readable | Writeable
332    ///
333    ///
334    /// #### `root`
335    ///  The [`Root`][crate::Root] widget of the widget tree containing this widget.
336    ///
337    /// This will be `NULL` if the widget is not contained in a root widget.
338    ///
339    /// Readable
340    ///
341    ///
342    /// #### `scale-factor`
343    ///  The scale factor of the widget.
344    ///
345    /// Readable
346    ///
347    ///
348    /// #### `sensitive`
349    ///  Whether the widget responds to input.
350    ///
351    /// Readable | Writeable
352    ///
353    ///
354    /// #### `tooltip-markup`
355    ///  Sets the text of tooltip to be the given string, which is marked up
356    /// with Pango markup.
357    ///
358    /// Also see [`Tooltip::set_markup()`][crate::Tooltip::set_markup()].
359    ///
360    /// This is a convenience property which will take care of getting the
361    /// tooltip shown if the given string is not `NULL`:
362    /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
363    /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
364    /// the default signal handler.
365    ///
366    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
367    /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
368    ///
369    /// Readable | Writeable
370    ///
371    ///
372    /// #### `tooltip-text`
373    ///  Sets the text of tooltip to be the given string.
374    ///
375    /// Also see [`Tooltip::set_text()`][crate::Tooltip::set_text()].
376    ///
377    /// This is a convenience property which will take care of getting the
378    /// tooltip shown if the given string is not `NULL`:
379    /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
380    /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
381    /// the default signal handler.
382    ///
383    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
384    /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
385    ///
386    /// Readable | Writeable
387    ///
388    ///
389    /// #### `valign`
390    ///  How to distribute vertical space if widget gets extra space.
391    ///
392    /// Readable | Writeable
393    ///
394    ///
395    /// #### `vexpand`
396    ///  Whether to expand vertically.
397    ///
398    /// Readable | Writeable
399    ///
400    ///
401    /// #### `vexpand-set`
402    ///  Whether to use the `vexpand` property.
403    ///
404    /// Readable | Writeable
405    ///
406    ///
407    /// #### `visible`
408    ///  Whether the widget is visible.
409    ///
410    /// Readable | Writeable
411    ///
412    ///
413    /// #### `width-request`
414    ///  Overrides for width request of the widget.
415    ///
416    /// If this is -1, the natural request will be used.
417    ///
418    /// Readable | Writeable
419    /// </details>
420    /// <details><summary><h4>Accessible</h4></summary>
421    ///
422    ///
423    /// #### `accessible-role`
424    ///  The accessible role of the given [`Accessible`][crate::Accessible] implementation.
425    ///
426    /// The accessible role cannot be changed once set.
427    ///
428    /// Readable | Writeable
429    /// </details>
430    ///
431    /// # Implements
432    ///
433    /// [`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]
434    #[doc(alias = "GtkImage")]
435    pub struct Image(Object<ffi::GtkImage>) @extends Widget, @implements Accessible, Buildable, ConstraintTarget;
436
437    match fn {
438        type_ => || ffi::gtk_image_get_type(),
439    }
440}
441
442impl Image {
443    /// Creates a new empty [`Image`][crate::Image] widget.
444    ///
445    /// # Returns
446    ///
447    /// a newly created [`Image`][crate::Image] widget.
448    #[doc(alias = "gtk_image_new")]
449    pub fn new() -> Image {
450        assert_initialized_main_thread!();
451        unsafe { Widget::from_glib_none(ffi::gtk_image_new()).unsafe_cast() }
452    }
453
454    /// Creates a new [`Image`][crate::Image] displaying the file @filename.
455    ///
456    /// If the file isn’t found or can’t be loaded, the resulting [`Image`][crate::Image]
457    /// will display a “broken image” icon. This function never returns [`None`],
458    /// it always returns a valid [`Image`][crate::Image] widget.
459    ///
460    /// If you need to detect failures to load the file, use an
461    /// image loading framework such as libglycin to load the file
462    /// yourself, then create the [`Image`][crate::Image] from the texture.
463    ///
464    /// The storage type (see [`storage_type()`][Self::storage_type()])
465    /// of the returned image is not defined, it will be whatever
466    /// is appropriate for displaying the file.
467    /// ## `filename`
468    /// a filename
469    ///
470    /// # Returns
471    ///
472    /// a new [`Image`][crate::Image]
473    #[doc(alias = "gtk_image_new_from_file")]
474    #[doc(alias = "new_from_file")]
475    pub fn from_file(filename: impl AsRef<std::path::Path>) -> Image {
476        assert_initialized_main_thread!();
477        unsafe {
478            Widget::from_glib_none(ffi::gtk_image_new_from_file(
479                filename.as_ref().to_glib_none().0,
480            ))
481            .unsafe_cast()
482        }
483    }
484
485    /// Creates a [`Image`][crate::Image] displaying an icon from the current icon theme.
486    ///
487    /// If the icon name isn’t known, a “broken image” icon will be
488    /// displayed instead. If the current icon theme is changed, the icon
489    /// will be updated appropriately.
490    /// ## `icon`
491    /// an icon
492    ///
493    /// # Returns
494    ///
495    /// a new [`Image`][crate::Image] displaying the themed icon
496    #[doc(alias = "gtk_image_new_from_gicon")]
497    #[doc(alias = "new_from_gicon")]
498    pub fn from_gicon(icon: &impl IsA<gio::Icon>) -> Image {
499        assert_initialized_main_thread!();
500        unsafe {
501            Widget::from_glib_none(ffi::gtk_image_new_from_gicon(
502                icon.as_ref().to_glib_none().0,
503            ))
504            .unsafe_cast()
505        }
506    }
507
508    /// Creates a [`Image`][crate::Image] displaying an icon from the current icon theme.
509    ///
510    /// If the icon name isn’t known, a “broken image” icon will be
511    /// displayed instead. If the current icon theme is changed, the icon
512    /// will be updated appropriately.
513    /// ## `icon_name`
514    /// an icon name
515    ///
516    /// # Returns
517    ///
518    /// a new [`Image`][crate::Image] displaying the themed icon
519    #[doc(alias = "gtk_image_new_from_icon_name")]
520    #[doc(alias = "new_from_icon_name")]
521    pub fn from_icon_name(icon_name: &str) -> Image {
522        assert_initialized_main_thread!();
523        unsafe {
524            Widget::from_glib_none(ffi::gtk_image_new_from_icon_name(
525                icon_name.to_glib_none().0,
526            ))
527            .unsafe_cast()
528        }
529    }
530
531    /// Creates a new [`Image`][crate::Image] displaying @paintable.
532    ///
533    /// The [`Image`][crate::Image] does not assume a reference to the paintable; you still
534    /// need to unref it if you own references. [`Image`][crate::Image] will add its own
535    /// reference rather than adopting yours.
536    ///
537    /// The [`Image`][crate::Image] will track changes to the @paintable and update
538    /// its size and contents in response to it.
539    ///
540    /// Note that paintables are still subject to the icon size that is
541    /// set on the image. If you want to display a paintable at its intrinsic
542    /// size, use [`Picture`][crate::Picture] instead.
543    ///
544    /// If @paintable is a [`SymbolicPaintable`][crate::SymbolicPaintable], then it will be
545    /// recolored with the symbolic palette from the theme.
546    /// ## `paintable`
547    /// a [`gdk::Paintable`][crate::gdk::Paintable]
548    ///
549    /// # Returns
550    ///
551    /// a new [`Image`][crate::Image]
552    #[doc(alias = "gtk_image_new_from_paintable")]
553    #[doc(alias = "new_from_paintable")]
554    pub fn from_paintable(paintable: Option<&impl IsA<gdk::Paintable>>) -> Image {
555        assert_initialized_main_thread!();
556        unsafe {
557            Widget::from_glib_none(ffi::gtk_image_new_from_paintable(
558                paintable.map(|p| p.as_ref()).to_glib_none().0,
559            ))
560            .unsafe_cast()
561        }
562    }
563
564    /// Creates a new [`Image`][crate::Image] displaying @pixbuf.
565    ///
566    /// The [`Image`][crate::Image] does not assume a reference to the pixbuf; you still
567    /// need to unref it if you own references. [`Image`][crate::Image] will add its own
568    /// reference rather than adopting yours.
569    ///
570    /// This is a helper for [`from_paintable()`][Self::from_paintable()], and you can't
571    /// get back the exact pixbuf once this is called, only a texture.
572    ///
573    /// Note that this function just creates an [`Image`][crate::Image] from the pixbuf.
574    /// The [`Image`][crate::Image] created will not react to state changes. Should you
575    /// want that, you should use [`from_icon_name()`][Self::from_icon_name()].
576    ///
577    /// # Deprecated since 4.12
578    ///
579    /// Use [`from_paintable()`][Self::from_paintable()] and
580    ///   [`gdk::Texture::for_pixbuf()`][crate::gdk::Texture::for_pixbuf()] instead
581    /// ## `pixbuf`
582    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf]
583    ///
584    /// # Returns
585    ///
586    /// a new [`Image`][crate::Image]
587    #[cfg_attr(feature = "v4_12", deprecated = "Since 4.12")]
588    #[allow(deprecated)]
589    #[doc(alias = "gtk_image_new_from_pixbuf")]
590    #[doc(alias = "new_from_pixbuf")]
591    pub fn from_pixbuf(pixbuf: Option<&gdk_pixbuf::Pixbuf>) -> Image {
592        assert_initialized_main_thread!();
593        unsafe {
594            Widget::from_glib_none(ffi::gtk_image_new_from_pixbuf(pixbuf.to_glib_none().0))
595                .unsafe_cast()
596        }
597    }
598
599    /// Creates a new [`Image`][crate::Image] displaying the resource file @resource_path.
600    ///
601    /// If the file isn’t found or can’t be loaded, the resulting [`Image`][crate::Image] will
602    /// display a “broken image” icon. This function never returns [`None`],
603    /// it always returns a valid [`Image`][crate::Image] widget.
604    ///
605    /// If you need to detect failures to load the file, use an
606    /// image loading framework such as libglycin to load the file
607    /// yourself, then create the [`Image`][crate::Image] from the texture.
608    ///
609    /// The storage type (see [`storage_type()`][Self::storage_type()]) of
610    /// the returned image is not defined, it will be whatever is
611    /// appropriate for displaying the file.
612    /// ## `resource_path`
613    /// a resource path
614    ///
615    /// # Returns
616    ///
617    /// a new [`Image`][crate::Image]
618    #[doc(alias = "gtk_image_new_from_resource")]
619    #[doc(alias = "new_from_resource")]
620    pub fn from_resource(resource_path: &str) -> Image {
621        assert_initialized_main_thread!();
622        unsafe {
623            Widget::from_glib_none(ffi::gtk_image_new_from_resource(
624                resource_path.to_glib_none().0,
625            ))
626            .unsafe_cast()
627        }
628    }
629
630    // rustdoc-stripper-ignore-next
631    /// Creates a new builder-pattern struct instance to construct [`Image`] objects.
632    ///
633    /// This method returns an instance of [`ImageBuilder`](crate::builders::ImageBuilder) which can be used to create [`Image`] objects.
634    pub fn builder() -> ImageBuilder {
635        ImageBuilder::new()
636    }
637
638    /// Resets the image to be empty.
639    #[doc(alias = "gtk_image_clear")]
640    pub fn clear(&self) {
641        unsafe {
642            ffi::gtk_image_clear(self.to_glib_none().0);
643        }
644    }
645
646    /// Gets the `GIcon` being displayed by the [`Image`][crate::Image].
647    ///
648    /// The storage type of the image must be [`ImageType::Empty`][crate::ImageType::Empty] or
649    /// [`ImageType::Gicon`][crate::ImageType::Gicon] (see [`storage_type()`][Self::storage_type()]).
650    /// The caller of this function does not own a reference to the
651    /// returned `GIcon`.
652    ///
653    /// # Returns
654    ///
655    /// a `GIcon`
656    #[doc(alias = "gtk_image_get_gicon")]
657    #[doc(alias = "get_gicon")]
658    pub fn gicon(&self) -> Option<gio::Icon> {
659        unsafe { from_glib_none(ffi::gtk_image_get_gicon(self.to_glib_none().0)) }
660    }
661
662    /// Gets the icon name and size being displayed by the [`Image`][crate::Image].
663    ///
664    /// The storage type of the image must be [`ImageType::Empty`][crate::ImageType::Empty] or
665    /// [`ImageType::IconName`][crate::ImageType::IconName] (see [`storage_type()`][Self::storage_type()]).
666    /// The returned string is owned by the [`Image`][crate::Image] and should not
667    /// be freed.
668    ///
669    /// # Returns
670    ///
671    /// the icon name
672    #[doc(alias = "gtk_image_get_icon_name")]
673    #[doc(alias = "get_icon_name")]
674    #[doc(alias = "icon-name")]
675    pub fn icon_name(&self) -> Option<glib::GString> {
676        unsafe { from_glib_none(ffi::gtk_image_get_icon_name(self.to_glib_none().0)) }
677    }
678
679    /// Gets the icon size used by the @self when rendering icons.
680    ///
681    /// # Returns
682    ///
683    /// the image size used by icons
684    #[doc(alias = "gtk_image_get_icon_size")]
685    #[doc(alias = "get_icon_size")]
686    #[doc(alias = "icon-size")]
687    pub fn icon_size(&self) -> IconSize {
688        unsafe { from_glib(ffi::gtk_image_get_icon_size(self.to_glib_none().0)) }
689    }
690
691    /// Gets the image [`gdk::Paintable`][crate::gdk::Paintable] being displayed by the [`Image`][crate::Image].
692    ///
693    /// The storage type of the image must be [`ImageType::Empty`][crate::ImageType::Empty] or
694    /// [`ImageType::Paintable`][crate::ImageType::Paintable] (see [`storage_type()`][Self::storage_type()]).
695    /// The caller of this function does not own a reference to the
696    /// returned paintable.
697    ///
698    /// # Returns
699    ///
700    /// the displayed paintable
701    #[doc(alias = "gtk_image_get_paintable")]
702    #[doc(alias = "get_paintable")]
703    pub fn paintable(&self) -> Option<gdk::Paintable> {
704        unsafe { from_glib_none(ffi::gtk_image_get_paintable(self.to_glib_none().0)) }
705    }
706
707    /// Gets the pixel size used for named icons.
708    ///
709    /// # Returns
710    ///
711    /// the pixel size used for named icons.
712    #[doc(alias = "gtk_image_get_pixel_size")]
713    #[doc(alias = "get_pixel_size")]
714    #[doc(alias = "pixel-size")]
715    pub fn pixel_size(&self) -> i32 {
716        unsafe { ffi::gtk_image_get_pixel_size(self.to_glib_none().0) }
717    }
718
719    /// Gets the type of representation being used by the [`Image`][crate::Image]
720    /// to store image data.
721    ///
722    /// If the [`Image`][crate::Image] has no image data, the return value will
723    /// be [`ImageType::Empty`][crate::ImageType::Empty].
724    ///
725    /// # Returns
726    ///
727    /// image representation being used
728    #[doc(alias = "gtk_image_get_storage_type")]
729    #[doc(alias = "get_storage_type")]
730    #[doc(alias = "storage-type")]
731    pub fn storage_type(&self) -> ImageType {
732        unsafe { from_glib(ffi::gtk_image_get_storage_type(self.to_glib_none().0)) }
733    }
734
735    /// Sets a [`Image`][crate::Image] to show a file.
736    ///
737    /// See [`from_file()`][Self::from_file()] for details.
738    ///
739    /// ::: warning
740    ///     Note that this function should not be used with untrusted data.
741    ///     Use a proper image loading framework such as libglycin, which can
742    ///     load many image formats into a [`gdk::Texture`][crate::gdk::Texture], and then use
743    ///     [`set_paintable()`][Self::set_paintable()].
744    /// ## `filename`
745    /// a filename
746    #[doc(alias = "gtk_image_set_from_file")]
747    #[doc(alias = "file")]
748    pub fn set_from_file(&self, filename: Option<impl AsRef<std::path::Path>>) {
749        unsafe {
750            ffi::gtk_image_set_from_file(
751                self.to_glib_none().0,
752                filename.as_ref().map(|p| p.as_ref()).to_glib_none().0,
753            );
754        }
755    }
756
757    /// Sets a [`Image`][crate::Image] to show a `GIcon`.
758    ///
759    /// See [`from_gicon()`][Self::from_gicon()] for details.
760    /// ## `icon`
761    /// an icon
762    #[doc(alias = "gtk_image_set_from_gicon")]
763    #[doc(alias = "gicon")]
764    pub fn set_from_gicon(&self, icon: &impl IsA<gio::Icon>) {
765        unsafe {
766            ffi::gtk_image_set_from_gicon(self.to_glib_none().0, icon.as_ref().to_glib_none().0);
767        }
768    }
769
770    /// Sets a [`Image`][crate::Image] to show a named icon.
771    ///
772    /// See [`from_icon_name()`][Self::from_icon_name()] for details.
773    /// ## `icon_name`
774    /// an icon name
775    #[doc(alias = "gtk_image_set_from_icon_name")]
776    #[doc(alias = "set_from_icon_name")]
777    #[doc(alias = "icon-name")]
778    pub fn set_icon_name(&self, icon_name: Option<&str>) {
779        unsafe {
780            ffi::gtk_image_set_from_icon_name(self.to_glib_none().0, icon_name.to_glib_none().0);
781        }
782    }
783
784    /// Sets a [`Image`][crate::Image] to show a [`gdk::Paintable`][crate::gdk::Paintable].
785    ///
786    /// See [`from_paintable()`][Self::from_paintable()] for details.
787    /// ## `paintable`
788    /// a [`gdk::Paintable`][crate::gdk::Paintable]
789    #[doc(alias = "gtk_image_set_from_paintable")]
790    #[doc(alias = "set_from_paintable")]
791    #[doc(alias = "paintable")]
792    pub fn set_paintable(&self, paintable: Option<&impl IsA<gdk::Paintable>>) {
793        unsafe {
794            ffi::gtk_image_set_from_paintable(
795                self.to_glib_none().0,
796                paintable.map(|p| p.as_ref()).to_glib_none().0,
797            );
798        }
799    }
800
801    /// Sets a [`Image`][crate::Image] to show a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf].
802    ///
803    /// See [`from_pixbuf()`][Self::from_pixbuf()] for details.
804    ///
805    /// Note: This is a helper for [`set_paintable()`][Self::set_paintable()],
806    /// and you can't get back the exact pixbuf once this is called,
807    /// only a paintable.
808    ///
809    /// # Deprecated since 4.12
810    ///
811    /// Use [`set_paintable()`][Self::set_paintable()] instead
812    /// ## `pixbuf`
813    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] or `NULL`
814    #[cfg_attr(feature = "v4_12", deprecated = "Since 4.12")]
815    #[allow(deprecated)]
816    #[doc(alias = "gtk_image_set_from_pixbuf")]
817    pub fn set_from_pixbuf(&self, pixbuf: Option<&gdk_pixbuf::Pixbuf>) {
818        unsafe {
819            ffi::gtk_image_set_from_pixbuf(self.to_glib_none().0, pixbuf.to_glib_none().0);
820        }
821    }
822
823    /// Sets a [`Image`][crate::Image] to show a resource.
824    ///
825    /// See [`from_resource()`][Self::from_resource()] for details.
826    /// ## `resource_path`
827    /// a resource path
828    #[doc(alias = "gtk_image_set_from_resource")]
829    #[doc(alias = "set_from_resource")]
830    #[doc(alias = "resource")]
831    pub fn set_resource(&self, resource_path: Option<&str>) {
832        unsafe {
833            ffi::gtk_image_set_from_resource(self.to_glib_none().0, resource_path.to_glib_none().0);
834        }
835    }
836
837    /// Suggests an icon size to the theme for named icons.
838    /// ## `icon_size`
839    /// the new icon size
840    #[doc(alias = "gtk_image_set_icon_size")]
841    #[doc(alias = "icon-size")]
842    pub fn set_icon_size(&self, icon_size: IconSize) {
843        unsafe {
844            ffi::gtk_image_set_icon_size(self.to_glib_none().0, icon_size.into_glib());
845        }
846    }
847
848    /// Sets the pixel size to use for named icons.
849    ///
850    /// If the pixel size is set to a value != -1, it is used instead
851    /// of the icon size set by [`set_icon_name()`][Self::set_icon_name()].
852    /// ## `pixel_size`
853    /// the new pixel size
854    #[doc(alias = "gtk_image_set_pixel_size")]
855    #[doc(alias = "pixel-size")]
856    pub fn set_pixel_size(&self, pixel_size: i32) {
857        unsafe {
858            ffi::gtk_image_set_pixel_size(self.to_glib_none().0, pixel_size);
859        }
860    }
861
862    /// A path to the file to display.
863    pub fn file(&self) -> Option<glib::GString> {
864        ObjectExt::property(self, "file")
865    }
866
867    /// A path to a resource file to display.
868    pub fn resource(&self) -> Option<glib::GString> {
869        ObjectExt::property(self, "resource")
870    }
871
872    /// Whether the icon displayed in the [`Image`][crate::Image] will use
873    /// standard icon names fallback.
874    ///
875    /// The value of this property is only relevant for images of type
876    /// [`ImageType::IconName`][crate::ImageType::IconName] and [`ImageType::Gicon`][crate::ImageType::Gicon].
877    #[doc(alias = "use-fallback")]
878    pub fn uses_fallback(&self) -> bool {
879        ObjectExt::property(self, "use-fallback")
880    }
881
882    /// Whether the icon displayed in the [`Image`][crate::Image] will use
883    /// standard icon names fallback.
884    ///
885    /// The value of this property is only relevant for images of type
886    /// [`ImageType::IconName`][crate::ImageType::IconName] and [`ImageType::Gicon`][crate::ImageType::Gicon].
887    #[doc(alias = "use-fallback")]
888    pub fn set_use_fallback(&self, use_fallback: bool) {
889        ObjectExt::set_property(self, "use-fallback", use_fallback)
890    }
891
892    #[doc(alias = "file")]
893    pub fn connect_file_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
894        unsafe extern "C" fn notify_file_trampoline<F: Fn(&Image) + 'static>(
895            this: *mut ffi::GtkImage,
896            _param_spec: glib::ffi::gpointer,
897            f: glib::ffi::gpointer,
898        ) {
899            let f: &F = &*(f as *const F);
900            f(&from_glib_borrow(this))
901        }
902        unsafe {
903            let f: Box_<F> = Box_::new(f);
904            connect_raw(
905                self.as_ptr() as *mut _,
906                c"notify::file".as_ptr() as *const _,
907                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
908                    notify_file_trampoline::<F> as *const (),
909                )),
910                Box_::into_raw(f),
911            )
912        }
913    }
914
915    #[doc(alias = "gicon")]
916    pub fn connect_gicon_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
917        unsafe extern "C" fn notify_gicon_trampoline<F: Fn(&Image) + 'static>(
918            this: *mut ffi::GtkImage,
919            _param_spec: glib::ffi::gpointer,
920            f: glib::ffi::gpointer,
921        ) {
922            let f: &F = &*(f as *const F);
923            f(&from_glib_borrow(this))
924        }
925        unsafe {
926            let f: Box_<F> = Box_::new(f);
927            connect_raw(
928                self.as_ptr() as *mut _,
929                c"notify::gicon".as_ptr() as *const _,
930                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
931                    notify_gicon_trampoline::<F> as *const (),
932                )),
933                Box_::into_raw(f),
934            )
935        }
936    }
937
938    #[doc(alias = "icon-name")]
939    pub fn connect_icon_name_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
940        unsafe extern "C" fn notify_icon_name_trampoline<F: Fn(&Image) + 'static>(
941            this: *mut ffi::GtkImage,
942            _param_spec: glib::ffi::gpointer,
943            f: glib::ffi::gpointer,
944        ) {
945            let f: &F = &*(f as *const F);
946            f(&from_glib_borrow(this))
947        }
948        unsafe {
949            let f: Box_<F> = Box_::new(f);
950            connect_raw(
951                self.as_ptr() as *mut _,
952                c"notify::icon-name".as_ptr() as *const _,
953                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
954                    notify_icon_name_trampoline::<F> as *const (),
955                )),
956                Box_::into_raw(f),
957            )
958        }
959    }
960
961    #[doc(alias = "icon-size")]
962    pub fn connect_icon_size_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
963        unsafe extern "C" fn notify_icon_size_trampoline<F: Fn(&Image) + 'static>(
964            this: *mut ffi::GtkImage,
965            _param_spec: glib::ffi::gpointer,
966            f: glib::ffi::gpointer,
967        ) {
968            let f: &F = &*(f as *const F);
969            f(&from_glib_borrow(this))
970        }
971        unsafe {
972            let f: Box_<F> = Box_::new(f);
973            connect_raw(
974                self.as_ptr() as *mut _,
975                c"notify::icon-size".as_ptr() as *const _,
976                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
977                    notify_icon_size_trampoline::<F> as *const (),
978                )),
979                Box_::into_raw(f),
980            )
981        }
982    }
983
984    #[doc(alias = "paintable")]
985    pub fn connect_paintable_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
986        unsafe extern "C" fn notify_paintable_trampoline<F: Fn(&Image) + 'static>(
987            this: *mut ffi::GtkImage,
988            _param_spec: glib::ffi::gpointer,
989            f: glib::ffi::gpointer,
990        ) {
991            let f: &F = &*(f as *const F);
992            f(&from_glib_borrow(this))
993        }
994        unsafe {
995            let f: Box_<F> = Box_::new(f);
996            connect_raw(
997                self.as_ptr() as *mut _,
998                c"notify::paintable".as_ptr() as *const _,
999                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1000                    notify_paintable_trampoline::<F> as *const (),
1001                )),
1002                Box_::into_raw(f),
1003            )
1004        }
1005    }
1006
1007    #[doc(alias = "pixel-size")]
1008    pub fn connect_pixel_size_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1009        unsafe extern "C" fn notify_pixel_size_trampoline<F: Fn(&Image) + 'static>(
1010            this: *mut ffi::GtkImage,
1011            _param_spec: glib::ffi::gpointer,
1012            f: glib::ffi::gpointer,
1013        ) {
1014            let f: &F = &*(f as *const F);
1015            f(&from_glib_borrow(this))
1016        }
1017        unsafe {
1018            let f: Box_<F> = Box_::new(f);
1019            connect_raw(
1020                self.as_ptr() as *mut _,
1021                c"notify::pixel-size".as_ptr() as *const _,
1022                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1023                    notify_pixel_size_trampoline::<F> as *const (),
1024                )),
1025                Box_::into_raw(f),
1026            )
1027        }
1028    }
1029
1030    #[doc(alias = "resource")]
1031    pub fn connect_resource_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1032        unsafe extern "C" fn notify_resource_trampoline<F: Fn(&Image) + 'static>(
1033            this: *mut ffi::GtkImage,
1034            _param_spec: glib::ffi::gpointer,
1035            f: glib::ffi::gpointer,
1036        ) {
1037            let f: &F = &*(f as *const F);
1038            f(&from_glib_borrow(this))
1039        }
1040        unsafe {
1041            let f: Box_<F> = Box_::new(f);
1042            connect_raw(
1043                self.as_ptr() as *mut _,
1044                c"notify::resource".as_ptr() as *const _,
1045                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1046                    notify_resource_trampoline::<F> as *const (),
1047                )),
1048                Box_::into_raw(f),
1049            )
1050        }
1051    }
1052
1053    #[doc(alias = "storage-type")]
1054    pub fn connect_storage_type_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1055        unsafe extern "C" fn notify_storage_type_trampoline<F: Fn(&Image) + 'static>(
1056            this: *mut ffi::GtkImage,
1057            _param_spec: glib::ffi::gpointer,
1058            f: glib::ffi::gpointer,
1059        ) {
1060            let f: &F = &*(f as *const F);
1061            f(&from_glib_borrow(this))
1062        }
1063        unsafe {
1064            let f: Box_<F> = Box_::new(f);
1065            connect_raw(
1066                self.as_ptr() as *mut _,
1067                c"notify::storage-type".as_ptr() as *const _,
1068                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1069                    notify_storage_type_trampoline::<F> as *const (),
1070                )),
1071                Box_::into_raw(f),
1072            )
1073        }
1074    }
1075
1076    #[doc(alias = "use-fallback")]
1077    pub fn connect_use_fallback_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1078        unsafe extern "C" fn notify_use_fallback_trampoline<F: Fn(&Image) + 'static>(
1079            this: *mut ffi::GtkImage,
1080            _param_spec: glib::ffi::gpointer,
1081            f: glib::ffi::gpointer,
1082        ) {
1083            let f: &F = &*(f as *const F);
1084            f(&from_glib_borrow(this))
1085        }
1086        unsafe {
1087            let f: Box_<F> = Box_::new(f);
1088            connect_raw(
1089                self.as_ptr() as *mut _,
1090                c"notify::use-fallback".as_ptr() as *const _,
1091                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1092                    notify_use_fallback_trampoline::<F> as *const (),
1093                )),
1094                Box_::into_raw(f),
1095            )
1096        }
1097    }
1098}
1099
1100impl Default for Image {
1101    fn default() -> Self {
1102        Self::new()
1103    }
1104}
1105
1106// rustdoc-stripper-ignore-next
1107/// A [builder-pattern] type to construct [`Image`] objects.
1108///
1109/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
1110#[must_use = "The builder must be built to be used"]
1111pub struct ImageBuilder {
1112    builder: glib::object::ObjectBuilder<'static, Image>,
1113}
1114
1115impl ImageBuilder {
1116    fn new() -> Self {
1117        Self {
1118            builder: glib::object::Object::builder(),
1119        }
1120    }
1121
1122    /// A path to the file to display.
1123    pub fn file(self, file: impl Into<glib::GString>) -> Self {
1124        Self {
1125            builder: self.builder.property("file", file.into()),
1126        }
1127    }
1128
1129    /// The `GIcon` displayed in the GtkImage.
1130    ///
1131    /// For themed icons, If the icon theme is changed, the image will be updated
1132    /// automatically.
1133    pub fn gicon(self, gicon: &impl IsA<gio::Icon>) -> Self {
1134        Self {
1135            builder: self.builder.property("gicon", gicon.clone().upcast()),
1136        }
1137    }
1138
1139    /// The name of the icon in the icon theme.
1140    ///
1141    /// If the icon theme is changed, the image will be updated automatically.
1142    pub fn icon_name(self, icon_name: impl Into<glib::GString>) -> Self {
1143        Self {
1144            builder: self.builder.property("icon-name", icon_name.into()),
1145        }
1146    }
1147
1148    /// The symbolic size to display icons at.
1149    pub fn icon_size(self, icon_size: IconSize) -> Self {
1150        Self {
1151            builder: self.builder.property("icon-size", icon_size),
1152        }
1153    }
1154
1155    /// The [`gdk::Paintable`][crate::gdk::Paintable] to display.
1156    pub fn paintable(self, paintable: &impl IsA<gdk::Paintable>) -> Self {
1157        Self {
1158            builder: self
1159                .builder
1160                .property("paintable", paintable.clone().upcast()),
1161        }
1162    }
1163
1164    /// The size in pixels to display icons at.
1165    ///
1166    /// If set to a value != -1, this property overrides the
1167    /// [`icon-size`][struct@crate::Image#icon-size] property for images of type
1168    /// `GTK_IMAGE_ICON_NAME`.
1169    pub fn pixel_size(self, pixel_size: i32) -> Self {
1170        Self {
1171            builder: self.builder.property("pixel-size", pixel_size),
1172        }
1173    }
1174
1175    /// A path to a resource file to display.
1176    pub fn resource(self, resource: impl Into<glib::GString>) -> Self {
1177        Self {
1178            builder: self.builder.property("resource", resource.into()),
1179        }
1180    }
1181
1182    /// Whether the icon displayed in the [`Image`][crate::Image] will use
1183    /// standard icon names fallback.
1184    ///
1185    /// The value of this property is only relevant for images of type
1186    /// [`ImageType::IconName`][crate::ImageType::IconName] and [`ImageType::Gicon`][crate::ImageType::Gicon].
1187    pub fn use_fallback(self, use_fallback: bool) -> Self {
1188        Self {
1189            builder: self.builder.property("use-fallback", use_fallback),
1190        }
1191    }
1192
1193    /// Whether the widget or any of its descendents can accept
1194    /// the input focus.
1195    ///
1196    /// This property is meant to be set by widget implementations,
1197    /// typically in their instance init function.
1198    pub fn can_focus(self, can_focus: bool) -> Self {
1199        Self {
1200            builder: self.builder.property("can-focus", can_focus),
1201        }
1202    }
1203
1204    /// Whether the widget can receive pointer events.
1205    pub fn can_target(self, can_target: bool) -> Self {
1206        Self {
1207            builder: self.builder.property("can-target", can_target),
1208        }
1209    }
1210
1211    /// A list of css classes applied to this widget.
1212    pub fn css_classes(self, css_classes: impl Into<glib::StrV>) -> Self {
1213        Self {
1214            builder: self.builder.property("css-classes", css_classes.into()),
1215        }
1216    }
1217
1218    /// The name of this widget in the CSS tree.
1219    ///
1220    /// This property is meant to be set by widget implementations,
1221    /// typically in their instance init function.
1222    pub fn css_name(self, css_name: impl Into<glib::GString>) -> Self {
1223        Self {
1224            builder: self.builder.property("css-name", css_name.into()),
1225        }
1226    }
1227
1228    /// The cursor used by @widget.
1229    pub fn cursor(self, cursor: &gdk::Cursor) -> Self {
1230        Self {
1231            builder: self.builder.property("cursor", cursor.clone()),
1232        }
1233    }
1234
1235    /// Whether the widget should grab focus when it is clicked with the mouse.
1236    ///
1237    /// This property is only relevant for widgets that can take focus.
1238    pub fn focus_on_click(self, focus_on_click: bool) -> Self {
1239        Self {
1240            builder: self.builder.property("focus-on-click", focus_on_click),
1241        }
1242    }
1243
1244    /// Whether this widget itself will accept the input focus.
1245    pub fn focusable(self, focusable: bool) -> Self {
1246        Self {
1247            builder: self.builder.property("focusable", focusable),
1248        }
1249    }
1250
1251    /// How to distribute horizontal space if widget gets extra space.
1252    pub fn halign(self, halign: Align) -> Self {
1253        Self {
1254            builder: self.builder.property("halign", halign),
1255        }
1256    }
1257
1258    /// Enables or disables the emission of the [`query-tooltip`][struct@crate::Widget#query-tooltip]
1259    /// signal on @widget.
1260    ///
1261    /// A true value indicates that @widget can have a tooltip, in this case
1262    /// the widget will be queried using [`query-tooltip`][struct@crate::Widget#query-tooltip] to
1263    /// determine whether it will provide a tooltip or not.
1264    pub fn has_tooltip(self, has_tooltip: bool) -> Self {
1265        Self {
1266            builder: self.builder.property("has-tooltip", has_tooltip),
1267        }
1268    }
1269
1270    /// Overrides for height request of the widget.
1271    ///
1272    /// If this is -1, the natural request will be used.
1273    pub fn height_request(self, height_request: i32) -> Self {
1274        Self {
1275            builder: self.builder.property("height-request", height_request),
1276        }
1277    }
1278
1279    /// Whether to expand horizontally.
1280    pub fn hexpand(self, hexpand: bool) -> Self {
1281        Self {
1282            builder: self.builder.property("hexpand", hexpand),
1283        }
1284    }
1285
1286    /// Whether to use the `hexpand` property.
1287    pub fn hexpand_set(self, hexpand_set: bool) -> Self {
1288        Self {
1289            builder: self.builder.property("hexpand-set", hexpand_set),
1290        }
1291    }
1292
1293    /// The [`LayoutManager`][crate::LayoutManager] instance to use to compute
1294    /// the preferred size of the widget, and allocate its children.
1295    ///
1296    /// This property is meant to be set by widget implementations,
1297    /// typically in their instance init function.
1298    pub fn layout_manager(self, layout_manager: &impl IsA<LayoutManager>) -> Self {
1299        Self {
1300            builder: self
1301                .builder
1302                .property("layout-manager", layout_manager.clone().upcast()),
1303        }
1304    }
1305
1306    /// Makes this widget act like a modal dialog, with respect to
1307    /// event delivery.
1308    ///
1309    /// Global event controllers will not handle events with targets
1310    /// inside the widget, unless they are set up to ignore propagation
1311    /// limits. See [`EventControllerExt::set_propagation_limit()`][crate::prelude::EventControllerExt::set_propagation_limit()].
1312    #[cfg(feature = "v4_18")]
1313    #[cfg_attr(docsrs, doc(cfg(feature = "v4_18")))]
1314    pub fn limit_events(self, limit_events: bool) -> Self {
1315        Self {
1316            builder: self.builder.property("limit-events", limit_events),
1317        }
1318    }
1319
1320    /// Margin on bottom side of widget.
1321    ///
1322    /// This property adds margin outside of the widget's normal size
1323    /// request, the margin will be added in addition to the size from
1324    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
1325    pub fn margin_bottom(self, margin_bottom: i32) -> Self {
1326        Self {
1327            builder: self.builder.property("margin-bottom", margin_bottom),
1328        }
1329    }
1330
1331    /// Margin on end of widget, horizontally.
1332    ///
1333    /// This property supports left-to-right and right-to-left text
1334    /// directions.
1335    ///
1336    /// This property adds margin outside of the widget's normal size
1337    /// request, the margin will be added in addition to the size from
1338    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
1339    pub fn margin_end(self, margin_end: i32) -> Self {
1340        Self {
1341            builder: self.builder.property("margin-end", margin_end),
1342        }
1343    }
1344
1345    /// Margin on start of widget, horizontally.
1346    ///
1347    /// This property supports left-to-right and right-to-left text
1348    /// directions.
1349    ///
1350    /// This property adds margin outside of the widget's normal size
1351    /// request, the margin will be added in addition to the size from
1352    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
1353    pub fn margin_start(self, margin_start: i32) -> Self {
1354        Self {
1355            builder: self.builder.property("margin-start", margin_start),
1356        }
1357    }
1358
1359    /// Margin on top side of widget.
1360    ///
1361    /// This property adds margin outside of the widget's normal size
1362    /// request, the margin will be added in addition to the size from
1363    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
1364    pub fn margin_top(self, margin_top: i32) -> Self {
1365        Self {
1366            builder: self.builder.property("margin-top", margin_top),
1367        }
1368    }
1369
1370    /// The name of the widget.
1371    pub fn name(self, name: impl Into<glib::GString>) -> Self {
1372        Self {
1373            builder: self.builder.property("name", name.into()),
1374        }
1375    }
1376
1377    /// The requested opacity of the widget.
1378    pub fn opacity(self, opacity: f64) -> Self {
1379        Self {
1380            builder: self.builder.property("opacity", opacity),
1381        }
1382    }
1383
1384    /// How content outside the widget's content area is treated.
1385    ///
1386    /// This property is meant to be set by widget implementations,
1387    /// typically in their instance init function.
1388    pub fn overflow(self, overflow: Overflow) -> Self {
1389        Self {
1390            builder: self.builder.property("overflow", overflow),
1391        }
1392    }
1393
1394    /// Whether the widget will receive the default action when it is focused.
1395    pub fn receives_default(self, receives_default: bool) -> Self {
1396        Self {
1397            builder: self.builder.property("receives-default", receives_default),
1398        }
1399    }
1400
1401    /// Whether the widget responds to input.
1402    pub fn sensitive(self, sensitive: bool) -> Self {
1403        Self {
1404            builder: self.builder.property("sensitive", sensitive),
1405        }
1406    }
1407
1408    /// Sets the text of tooltip to be the given string, which is marked up
1409    /// with Pango markup.
1410    ///
1411    /// Also see [`Tooltip::set_markup()`][crate::Tooltip::set_markup()].
1412    ///
1413    /// This is a convenience property which will take care of getting the
1414    /// tooltip shown if the given string is not `NULL`:
1415    /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
1416    /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
1417    /// the default signal handler.
1418    ///
1419    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
1420    /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
1421    pub fn tooltip_markup(self, tooltip_markup: impl Into<glib::GString>) -> Self {
1422        Self {
1423            builder: self
1424                .builder
1425                .property("tooltip-markup", tooltip_markup.into()),
1426        }
1427    }
1428
1429    /// Sets the text of tooltip to be the given string.
1430    ///
1431    /// Also see [`Tooltip::set_text()`][crate::Tooltip::set_text()].
1432    ///
1433    /// This is a convenience property which will take care of getting the
1434    /// tooltip shown if the given string is not `NULL`:
1435    /// [`has-tooltip`][struct@crate::Widget#has-tooltip] will automatically be set to true
1436    /// and there will be taken care of [`query-tooltip`][struct@crate::Widget#query-tooltip] in
1437    /// the default signal handler.
1438    ///
1439    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and
1440    /// [`tooltip-markup`][struct@crate::Widget#tooltip-markup] are set, the last one wins.
1441    pub fn tooltip_text(self, tooltip_text: impl Into<glib::GString>) -> Self {
1442        Self {
1443            builder: self.builder.property("tooltip-text", tooltip_text.into()),
1444        }
1445    }
1446
1447    /// How to distribute vertical space if widget gets extra space.
1448    pub fn valign(self, valign: Align) -> Self {
1449        Self {
1450            builder: self.builder.property("valign", valign),
1451        }
1452    }
1453
1454    /// Whether to expand vertically.
1455    pub fn vexpand(self, vexpand: bool) -> Self {
1456        Self {
1457            builder: self.builder.property("vexpand", vexpand),
1458        }
1459    }
1460
1461    /// Whether to use the `vexpand` property.
1462    pub fn vexpand_set(self, vexpand_set: bool) -> Self {
1463        Self {
1464            builder: self.builder.property("vexpand-set", vexpand_set),
1465        }
1466    }
1467
1468    /// Whether the widget is visible.
1469    pub fn visible(self, visible: bool) -> Self {
1470        Self {
1471            builder: self.builder.property("visible", visible),
1472        }
1473    }
1474
1475    /// Overrides for width request of the widget.
1476    ///
1477    /// If this is -1, the natural request will be used.
1478    pub fn width_request(self, width_request: i32) -> Self {
1479        Self {
1480            builder: self.builder.property("width-request", width_request),
1481        }
1482    }
1483
1484    /// The accessible role of the given [`Accessible`][crate::Accessible] implementation.
1485    ///
1486    /// The accessible role cannot be changed once set.
1487    pub fn accessible_role(self, accessible_role: AccessibleRole) -> Self {
1488        Self {
1489            builder: self.builder.property("accessible-role", accessible_role),
1490        }
1491    }
1492
1493    // rustdoc-stripper-ignore-next
1494    /// Build the [`Image`].
1495    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
1496    pub fn build(self) -> Image {
1497        assert_initialized_main_thread!();
1498        self.builder.build()
1499    }
1500}