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