gtk/auto/

image.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{Buildable, IconSize, ImageType, Misc, Widget};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::{boxed::Box as Box_, fmt, mem, mem::transmute, ptr};

glib::wrapper! {
    /// The [`Image`][crate::Image] widget displays an image. Various kinds of object
    /// can be displayed as an image; most typically, you would load a
    /// [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] ("pixel buffer") from a file, and then display that.
    /// There’s a convenience function to do this, [`from_file()`][Self::from_file()],
    /// used as follows:
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    ///   GtkWidget *image;
    ///   image = gtk_image_new_from_file ("myfile.png");
    /// ```
    /// If the file isn’t loaded successfully, the image will contain a
    /// “broken image” icon similar to that used in many web browsers.
    /// If you want to handle errors in loading the file yourself,
    /// for example by displaying an error message, then load the image with
    /// [`gdk_pixbuf::Pixbuf::from_file()`][crate::gdk_pixbuf::Pixbuf::from_file()], then create the [`Image`][crate::Image] with
    /// [`from_pixbuf()`][Self::from_pixbuf()].
    ///
    /// The image file may contain an animation, if so the [`Image`][crate::Image] will
    /// display an animation ([`gdk_pixbuf::PixbufAnimation`][crate::gdk_pixbuf::PixbufAnimation]) instead of a static image.
    ///
    /// [`Image`][crate::Image] is a subclass of [`Misc`][crate::Misc], which implies that you can
    /// align it (center, left, right) and add padding to it, using
    /// [`Misc`][crate::Misc] methods.
    ///
    /// [`Image`][crate::Image] is a “no window” widget (has no [`gdk::Window`][crate::gdk::Window] of its own),
    /// so by default does not receive events. If you want to receive events
    /// on the image, such as button clicks, place the image inside a
    /// [`EventBox`][crate::EventBox], then connect to the event signals on the event box.
    ///
    /// ## Handling button press events on a [`Image`][crate::Image].
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    ///   static gboolean
    ///   button_press_callback (GtkWidget      *event_box,
    ///                          GdkEventButton *event,
    ///                          gpointer        data)
    ///   {
    ///     g_print ("Event box clicked at coordinates %f,%f\n",
    ///              event->x, event->y);
    ///
    ///     // Returning TRUE means we handled the event, so the signal
    ///     // emission should be stopped (don’t call any further callbacks
    ///     // that may be connected). Return FALSE to continue invoking callbacks.
    ///     return TRUE;
    ///   }
    ///
    ///   static GtkWidget*
    ///   create_image (void)
    ///   {
    ///     GtkWidget *image;
    ///     GtkWidget *event_box;
    ///
    ///     image = gtk_image_new_from_file ("myfile.png");
    ///
    ///     event_box = gtk_event_box_new ();
    ///
    ///     gtk_container_add (GTK_CONTAINER (event_box), image);
    ///
    ///     g_signal_connect (G_OBJECT (event_box),
    ///                       "button_press_event",
    ///                       G_CALLBACK (button_press_callback),
    ///                       image);
    ///
    ///     return image;
    ///   }
    /// ```
    ///
    /// When handling events on the event box, keep in mind that coordinates
    /// in the image may be different from event box coordinates due to
    /// the alignment and padding settings on the image (see [`Misc`][crate::Misc]).
    /// The simplest way to solve this is to set the alignment to 0.0
    /// (left/top), and set the padding to zero. Then the origin of
    /// the image will be the same as the origin of the event box.
    ///
    /// Sometimes an application will want to avoid depending on external data
    /// files, such as image files. GTK+ comes with a program to avoid this,
    /// called “gdk-pixbuf-csource”. This library
    /// allows you to convert an image into a C variable declaration, which
    /// can then be loaded into a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] using
    /// `gdk_pixbuf_new_from_inline()`.
    ///
    /// # CSS nodes
    ///
    /// GtkImage has a single CSS node with the name image. The style classes
    /// may appear on image CSS nodes: .icon-dropshadow, .lowres-icon.
    ///
    /// ## Properties
    ///
    ///
    /// #### `file`
    ///  Readable | Writeable
    ///
    ///
    /// #### `gicon`
    ///  The GIcon displayed in the GtkImage. For themed icons,
    /// If the icon theme is changed, the image will be updated
    /// automatically.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `icon-name`
    ///  The name of the icon in the icon theme. If the icon theme is
    /// changed, the image will be updated automatically.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `icon-set`
    ///  Readable | Writeable
    ///
    ///
    /// #### `icon-size`
    ///  Readable | Writeable
    ///
    ///
    /// #### `pixbuf`
    ///  Readable | Writeable
    ///
    ///
    /// #### `pixbuf-animation`
    ///  Readable | Writeable
    ///
    ///
    /// #### `pixel-size`
    ///  The "pixel-size" property can be used to specify a fixed size
    /// overriding the [`icon-size`][struct@crate::Image#icon-size] property for images of type
    /// [`ImageType::IconName`][crate::ImageType::IconName].
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `resource`
    ///  A path to a resource file to display.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `stock`
    ///  Readable | Writeable
    ///
    ///
    /// #### `storage-type`
    ///  Readable
    ///
    ///
    /// #### `surface`
    ///  Readable | Writeable
    ///
    ///
    /// #### `use-fallback`
    ///  Whether the icon displayed in the GtkImage will use
    /// standard icon names fallback. The value of this property
    /// is only relevant for images of type [`ImageType::IconName`][crate::ImageType::IconName]
    /// and [`ImageType::Gicon`][crate::ImageType::Gicon].
    ///
    /// Readable | Writeable
    /// <details><summary><h4>Misc</h4></summary>
    ///
    ///
    /// #### `xalign`
    ///  The horizontal alignment. A value of 0.0 means left alignment (or right
    /// on RTL locales); a value of 1.0 means right alignment (or left on RTL
    /// locales).
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `xpad`
    ///  The amount of space to add on the left and right of the widget, in
    /// pixels.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `yalign`
    ///  The vertical alignment. A value of 0.0 means top alignment;
    /// a value of 1.0 means bottom alignment.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `ypad`
    ///  The amount of space to add on the top and bottom of the widget, in
    /// pixels.
    ///
    /// Readable | Writeable
    /// </details>
    /// <details><summary><h4>Widget</h4></summary>
    ///
    ///
    /// #### `app-paintable`
    ///  Readable | Writeable
    ///
    ///
    /// #### `can-default`
    ///  Readable | Writeable
    ///
    ///
    /// #### `can-focus`
    ///  Readable | Writeable
    ///
    ///
    /// #### `composite-child`
    ///  Readable
    ///
    ///
    /// #### `double-buffered`
    ///  Whether the widget is double buffered.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `events`
    ///  Readable | Writeable
    ///
    ///
    /// #### `expand`
    ///  Whether to expand in both directions. Setting this sets both [`hexpand`][struct@crate::Widget#hexpand] and [`vexpand`][struct@crate::Widget#vexpand]
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `focus-on-click`
    ///  Whether the widget should grab focus when it is clicked with the mouse.
    ///
    /// This property is only relevant for widgets that can take focus.
    ///
    /// Before 3.20, several widgets (GtkButton, GtkFileChooserButton,
    /// GtkComboBox) implemented this property individually.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `halign`
    ///  How to distribute horizontal space if widget gets extra space, see [`Align`][crate::Align]
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `has-default`
    ///  Readable | Writeable
    ///
    ///
    /// #### `has-focus`
    ///  Readable | Writeable
    ///
    ///
    /// #### `has-tooltip`
    ///  Enables or disables the emission of [`query-tooltip`][struct@crate::Widget#query-tooltip] on `widget`.
    /// A value of [`true`] indicates that `widget` can have a tooltip, in this case
    /// the widget will be queried using [`query-tooltip`][struct@crate::Widget#query-tooltip] to determine
    /// whether it will provide a tooltip or not.
    ///
    /// Note that setting this property to [`true`] for the first time will change
    /// the event masks of the GdkWindows of this widget to include leave-notify
    /// and motion-notify events. This cannot and will not be undone when the
    /// property is set to [`false`] again.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `height-request`
    ///  Readable | Writeable
    ///
    ///
    /// #### `hexpand`
    ///  Whether to expand horizontally. See [`WidgetExt::set_hexpand()`][crate::prelude::WidgetExt::set_hexpand()].
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `hexpand-set`
    ///  Whether to use the [`hexpand`][struct@crate::Widget#hexpand] property. See [`WidgetExt::is_hexpand_set()`][crate::prelude::WidgetExt::is_hexpand_set()].
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `is-focus`
    ///  Readable | Writeable
    ///
    ///
    /// #### `margin`
    ///  Sets all four sides' margin at once. If read, returns max
    /// margin on any side.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `margin-bottom`
    ///  Margin on bottom side of widget.
    ///
    /// This property adds margin outside of the widget's normal size
    /// request, the margin will be added in addition to the size from
    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `margin-end`
    ///  Margin on end of widget, horizontally. This property supports
    /// left-to-right and right-to-left text directions.
    ///
    /// This property adds margin outside of the widget's normal size
    /// request, the margin will be added in addition to the size from
    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `margin-left`
    ///  Margin on left side of widget.
    ///
    /// This property adds margin outside of the widget's normal size
    /// request, the margin will be added in addition to the size from
    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `margin-right`
    ///  Margin on right side of widget.
    ///
    /// This property adds margin outside of the widget's normal size
    /// request, the margin will be added in addition to the size from
    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `margin-start`
    ///  Margin on start of widget, horizontally. This property supports
    /// left-to-right and right-to-left text directions.
    ///
    /// This property adds margin outside of the widget's normal size
    /// request, the margin will be added in addition to the size from
    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `margin-top`
    ///  Margin on top side of widget.
    ///
    /// This property adds margin outside of the widget's normal size
    /// request, the margin will be added in addition to the size from
    /// [`WidgetExt::set_size_request()`][crate::prelude::WidgetExt::set_size_request()] for example.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `name`
    ///  Readable | Writeable
    ///
    ///
    /// #### `no-show-all`
    ///  Readable | Writeable
    ///
    ///
    /// #### `opacity`
    ///  The requested opacity of the widget. See [`WidgetExt::set_opacity()`][crate::prelude::WidgetExt::set_opacity()] for
    /// more details about window opacity.
    ///
    /// Before 3.8 this was only available in GtkWindow
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `parent`
    ///  Readable | Writeable
    ///
    ///
    /// #### `receives-default`
    ///  Readable | Writeable
    ///
    ///
    /// #### `scale-factor`
    ///  The scale factor of the widget. See [`WidgetExt::scale_factor()`][crate::prelude::WidgetExt::scale_factor()] for
    /// more details about widget scaling.
    ///
    /// Readable
    ///
    ///
    /// #### `sensitive`
    ///  Readable | Writeable
    ///
    ///
    /// #### `style`
    ///  The style of the widget, which contains information about how it will look (colors, etc).
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `tooltip-markup`
    ///  Sets the text of tooltip to be the given string, which is marked up
    /// with the [Pango text markup language][PangoMarkupFormat].
    /// Also see [`Tooltip::set_markup()`][crate::Tooltip::set_markup()].
    ///
    /// This is a convenience property which will take care of getting the
    /// tooltip shown if the given string is not [`None`]: [`has-tooltip`][struct@crate::Widget#has-tooltip]
    /// will automatically be set to [`true`] and there will be taken care of
    /// [`query-tooltip`][struct@crate::Widget#query-tooltip] in the default signal handler.
    ///
    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and [`tooltip-markup`][struct@crate::Widget#tooltip-markup]
    /// are set, the last one wins.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `tooltip-text`
    ///  Sets the text of tooltip to be the given string.
    ///
    /// Also see [`Tooltip::set_text()`][crate::Tooltip::set_text()].
    ///
    /// This is a convenience property which will take care of getting the
    /// tooltip shown if the given string is not [`None`]: [`has-tooltip`][struct@crate::Widget#has-tooltip]
    /// will automatically be set to [`true`] and there will be taken care of
    /// [`query-tooltip`][struct@crate::Widget#query-tooltip] in the default signal handler.
    ///
    /// Note that if both [`tooltip-text`][struct@crate::Widget#tooltip-text] and [`tooltip-markup`][struct@crate::Widget#tooltip-markup]
    /// are set, the last one wins.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `valign`
    ///  How to distribute vertical space if widget gets extra space, see [`Align`][crate::Align]
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `vexpand`
    ///  Whether to expand vertically. See [`WidgetExt::set_vexpand()`][crate::prelude::WidgetExt::set_vexpand()].
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `vexpand-set`
    ///  Whether to use the [`vexpand`][struct@crate::Widget#vexpand] property. See [`WidgetExt::is_vexpand_set()`][crate::prelude::WidgetExt::is_vexpand_set()].
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `visible`
    ///  Readable | Writeable
    ///
    ///
    /// #### `width-request`
    ///  Readable | Writeable
    ///
    ///
    /// #### `window`
    ///  The widget's window if it is realized, [`None`] otherwise.
    ///
    /// Readable
    /// </details>
    ///
    /// # Implements
    ///
    /// [`ImageExt`][trait@crate::prelude::ImageExt], [`MiscExt`][trait@crate::prelude::MiscExt], [`WidgetExt`][trait@crate::prelude::WidgetExt], [`trait@glib::ObjectExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt], [`ImageExtManual`][trait@crate::prelude::ImageExtManual], [`WidgetExtManual`][trait@crate::prelude::WidgetExtManual], [`BuildableExtManual`][trait@crate::prelude::BuildableExtManual]
    #[doc(alias = "GtkImage")]
    pub struct Image(Object<ffi::GtkImage, ffi::GtkImageClass>) @extends Misc, Widget, @implements Buildable;

    match fn {
        type_ => || ffi::gtk_image_get_type(),
    }
}

impl Image {
    pub const NONE: Option<&'static Image> = None;

    /// Creates a new empty [`Image`][crate::Image] widget.
    ///
    /// # Returns
    ///
    /// a newly created [`Image`][crate::Image] widget.
    #[doc(alias = "gtk_image_new")]
    pub fn new() -> Image {
        assert_initialized_main_thread!();
        unsafe { Widget::from_glib_none(ffi::gtk_image_new()).unsafe_cast() }
    }

    /// Creates a [`Image`][crate::Image] displaying the given animation.
    /// The [`Image`][crate::Image] does not assume a reference to the
    /// animation; you still need to unref it if you own references.
    /// [`Image`][crate::Image] will add its own reference rather than adopting yours.
    ///
    /// Note that the animation frames are shown using a timeout with
    /// `G_PRIORITY_DEFAULT`. When using animations to indicate busyness,
    /// keep in mind that the animation will only be shown if the main loop
    /// is not busy with something that has a higher priority.
    /// ## `animation`
    /// an animation
    ///
    /// # Returns
    ///
    /// a new [`Image`][crate::Image] widget
    #[doc(alias = "gtk_image_new_from_animation")]
    #[doc(alias = "new_from_animation")]
    pub fn from_animation(animation: &impl IsA<gdk_pixbuf::PixbufAnimation>) -> Image {
        assert_initialized_main_thread!();
        unsafe {
            Widget::from_glib_none(ffi::gtk_image_new_from_animation(
                animation.as_ref().to_glib_none().0,
            ))
            .unsafe_cast()
        }
    }

    /// Creates a new [`Image`][crate::Image] displaying the file `filename`. If the file
    /// isn’t found or can’t be loaded, the resulting [`Image`][crate::Image] will
    /// display a “broken image” icon. This function never returns [`None`],
    /// it always returns a valid [`Image`][crate::Image] widget.
    ///
    /// If the file contains an animation, the image will contain an
    /// animation.
    ///
    /// If you need to detect failures to load the file, use
    /// [`gdk_pixbuf::Pixbuf::from_file()`][crate::gdk_pixbuf::Pixbuf::from_file()] to load the file yourself, then create
    /// the [`Image`][crate::Image] from the pixbuf. (Or for animations, use
    /// [`gdk_pixbuf::PixbufAnimation::from_file()`][crate::gdk_pixbuf::PixbufAnimation::from_file()]).
    ///
    /// The storage type ([`ImageExt::storage_type()`][crate::prelude::ImageExt::storage_type()]) of the returned
    /// image is not defined, it will be whatever is appropriate for
    /// displaying the file.
    /// ## `filename`
    /// a filename
    ///
    /// # Returns
    ///
    /// a new [`Image`][crate::Image]
    #[doc(alias = "gtk_image_new_from_file")]
    #[doc(alias = "new_from_file")]
    pub fn from_file(filename: impl AsRef<std::path::Path>) -> Image {
        assert_initialized_main_thread!();
        unsafe {
            Widget::from_glib_none(ffi::gtk_image_new_from_file(
                filename.as_ref().to_glib_none().0,
            ))
            .unsafe_cast()
        }
    }

    /// Creates a [`Image`][crate::Image] displaying an icon from the current icon theme.
    /// If the icon name isn’t known, a “broken image” icon will be
    /// displayed instead. If the current icon theme is changed, the icon
    /// will be updated appropriately.
    /// ## `icon`
    /// an icon
    /// ## `size`
    /// a stock icon size ([`IconSize`][crate::IconSize])
    ///
    /// # Returns
    ///
    /// a new [`Image`][crate::Image] displaying the themed icon
    #[doc(alias = "gtk_image_new_from_gicon")]
    #[doc(alias = "new_from_gicon")]
    pub fn from_gicon(icon: &impl IsA<gio::Icon>, size: IconSize) -> Image {
        assert_initialized_main_thread!();
        unsafe {
            Widget::from_glib_none(ffi::gtk_image_new_from_gicon(
                icon.as_ref().to_glib_none().0,
                size.into_glib(),
            ))
            .unsafe_cast()
        }
    }

    /// Creates a [`Image`][crate::Image] displaying an icon from the current icon theme.
    /// If the icon name isn’t known, a “broken image” icon will be
    /// displayed instead. If the current icon theme is changed, the icon
    /// will be updated appropriately.
    /// ## `icon_name`
    /// an icon name or [`None`]
    /// ## `size`
    /// a stock icon size ([`IconSize`][crate::IconSize])
    ///
    /// # Returns
    ///
    /// a new [`Image`][crate::Image] displaying the themed icon
    #[doc(alias = "gtk_image_new_from_icon_name")]
    #[doc(alias = "new_from_icon_name")]
    pub fn from_icon_name(icon_name: Option<&str>, size: IconSize) -> Image {
        assert_initialized_main_thread!();
        unsafe {
            Widget::from_glib_none(ffi::gtk_image_new_from_icon_name(
                icon_name.to_glib_none().0,
                size.into_glib(),
            ))
            .unsafe_cast()
        }
    }

    /// Creates a new [`Image`][crate::Image] displaying `pixbuf`.
    /// The [`Image`][crate::Image] does not assume a reference to the
    /// pixbuf; you still need to unref it if you own references.
    /// [`Image`][crate::Image] will add its own reference rather than adopting yours.
    ///
    /// Note that this function just creates an [`Image`][crate::Image] from the pixbuf. The
    /// [`Image`][crate::Image] created will not react to state changes. Should you want that,
    /// you should use [`from_icon_name()`][Self::from_icon_name()].
    /// ## `pixbuf`
    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf], or [`None`]
    ///
    /// # Returns
    ///
    /// a new [`Image`][crate::Image]
    #[doc(alias = "gtk_image_new_from_pixbuf")]
    #[doc(alias = "new_from_pixbuf")]
    pub fn from_pixbuf(pixbuf: Option<&gdk_pixbuf::Pixbuf>) -> Image {
        assert_initialized_main_thread!();
        unsafe {
            Widget::from_glib_none(ffi::gtk_image_new_from_pixbuf(pixbuf.to_glib_none().0))
                .unsafe_cast()
        }
    }

    /// Creates a new [`Image`][crate::Image] displaying the resource file `resource_path`. If the file
    /// isn’t found or can’t be loaded, the resulting [`Image`][crate::Image] will
    /// display a “broken image” icon. This function never returns [`None`],
    /// it always returns a valid [`Image`][crate::Image] widget.
    ///
    /// If the file contains an animation, the image will contain an
    /// animation.
    ///
    /// If you need to detect failures to load the file, use
    /// [`gdk_pixbuf::Pixbuf::from_file()`][crate::gdk_pixbuf::Pixbuf::from_file()] to load the file yourself, then create
    /// the [`Image`][crate::Image] from the pixbuf. (Or for animations, use
    /// [`gdk_pixbuf::PixbufAnimation::from_file()`][crate::gdk_pixbuf::PixbufAnimation::from_file()]).
    ///
    /// The storage type ([`ImageExt::storage_type()`][crate::prelude::ImageExt::storage_type()]) of the returned
    /// image is not defined, it will be whatever is appropriate for
    /// displaying the file.
    /// ## `resource_path`
    /// a resource path
    ///
    /// # Returns
    ///
    /// a new [`Image`][crate::Image]
    #[doc(alias = "gtk_image_new_from_resource")]
    #[doc(alias = "new_from_resource")]
    pub fn from_resource(resource_path: &str) -> Image {
        assert_initialized_main_thread!();
        unsafe {
            Widget::from_glib_none(ffi::gtk_image_new_from_resource(
                resource_path.to_glib_none().0,
            ))
            .unsafe_cast()
        }
    }

    /// Creates a new [`Image`][crate::Image] displaying `surface`.
    /// The [`Image`][crate::Image] does not assume a reference to the
    /// surface; you still need to unref it if you own references.
    /// [`Image`][crate::Image] will add its own reference rather than adopting yours.
    /// ## `surface`
    /// a [`cairo::Surface`][crate::cairo::Surface], or [`None`]
    ///
    /// # Returns
    ///
    /// a new [`Image`][crate::Image]
    #[doc(alias = "gtk_image_new_from_surface")]
    #[doc(alias = "new_from_surface")]
    pub fn from_surface(surface: Option<&cairo::Surface>) -> Image {
        assert_initialized_main_thread!();
        unsafe {
            Widget::from_glib_none(ffi::gtk_image_new_from_surface(mut_override(
                surface.to_glib_none().0,
            )))
            .unsafe_cast()
        }
    }
}

impl Default for Image {
    fn default() -> Self {
        Self::new()
    }
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::Image>> Sealed for T {}
}

/// Trait containing all [`struct@Image`] methods.
///
/// # Implementors
///
/// [`Image`][struct@crate::Image]
pub trait ImageExt: IsA<Image> + sealed::Sealed + 'static {
    /// Resets the image to be empty.
    #[doc(alias = "gtk_image_clear")]
    fn clear(&self) {
        unsafe {
            ffi::gtk_image_clear(self.as_ref().to_glib_none().0);
        }
    }

    /// Gets the [`gdk_pixbuf::PixbufAnimation`][crate::gdk_pixbuf::PixbufAnimation] being displayed by the [`Image`][crate::Image].
    /// The storage type of the image must be [`ImageType::Empty`][crate::ImageType::Empty] or
    /// [`ImageType::Animation`][crate::ImageType::Animation] (see [`storage_type()`][Self::storage_type()]).
    /// The caller of this function does not own a reference to the
    /// returned animation.
    ///
    /// # Returns
    ///
    /// the displayed animation, or [`None`] if
    /// the image is empty
    #[doc(alias = "gtk_image_get_animation")]
    #[doc(alias = "get_animation")]
    fn animation(&self) -> Option<gdk_pixbuf::PixbufAnimation> {
        unsafe { from_glib_none(ffi::gtk_image_get_animation(self.as_ref().to_glib_none().0)) }
    }

    /// Gets the [`gio::Icon`][crate::gio::Icon] and size being displayed by the [`Image`][crate::Image].
    /// The storage type of the image must be [`ImageType::Empty`][crate::ImageType::Empty] or
    /// [`ImageType::Gicon`][crate::ImageType::Gicon] (see [`storage_type()`][Self::storage_type()]).
    /// The caller of this function does not own a reference to the
    /// returned [`gio::Icon`][crate::gio::Icon].
    ///
    /// # Returns
    ///
    ///
    /// ## `gicon`
    /// place to store a
    ///  [`gio::Icon`][crate::gio::Icon], or [`None`]
    ///
    /// ## `size`
    /// place to store an icon size
    ///  ([`IconSize`][crate::IconSize]), or [`None`]
    #[doc(alias = "gtk_image_get_gicon")]
    #[doc(alias = "get_gicon")]
    fn gicon(&self) -> (gio::Icon, IconSize) {
        unsafe {
            let mut gicon = ptr::null_mut();
            let mut size = mem::MaybeUninit::uninit();
            ffi::gtk_image_get_gicon(
                self.as_ref().to_glib_none().0,
                &mut gicon,
                size.as_mut_ptr(),
            );
            (from_glib_none(gicon), from_glib(size.assume_init()))
        }
    }

    /// Gets the [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] being displayed by the [`Image`][crate::Image].
    /// The storage type of the image must be [`ImageType::Empty`][crate::ImageType::Empty] or
    /// [`ImageType::Pixbuf`][crate::ImageType::Pixbuf] (see [`storage_type()`][Self::storage_type()]).
    /// The caller of this function does not own a reference to the
    /// returned pixbuf.
    ///
    /// # Returns
    ///
    /// the displayed pixbuf, or [`None`] if
    /// the image is empty
    #[doc(alias = "gtk_image_get_pixbuf")]
    #[doc(alias = "get_pixbuf")]
    fn pixbuf(&self) -> Option<gdk_pixbuf::Pixbuf> {
        unsafe { from_glib_none(ffi::gtk_image_get_pixbuf(self.as_ref().to_glib_none().0)) }
    }

    /// Gets the pixel size used for named icons.
    ///
    /// # Returns
    ///
    /// the pixel size used for named icons.
    #[doc(alias = "gtk_image_get_pixel_size")]
    #[doc(alias = "get_pixel_size")]
    fn pixel_size(&self) -> i32 {
        unsafe { ffi::gtk_image_get_pixel_size(self.as_ref().to_glib_none().0) }
    }

    /// Gets the type of representation being used by the [`Image`][crate::Image]
    /// to store image data. If the [`Image`][crate::Image] has no image data,
    /// the return value will be [`ImageType::Empty`][crate::ImageType::Empty].
    ///
    /// # Returns
    ///
    /// image representation being used
    #[doc(alias = "gtk_image_get_storage_type")]
    #[doc(alias = "get_storage_type")]
    fn storage_type(&self) -> ImageType {
        unsafe {
            from_glib(ffi::gtk_image_get_storage_type(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Causes the [`Image`][crate::Image] to display the given animation (or display
    /// nothing, if you set the animation to [`None`]).
    /// ## `animation`
    /// the [`gdk_pixbuf::PixbufAnimation`][crate::gdk_pixbuf::PixbufAnimation]
    #[doc(alias = "gtk_image_set_from_animation")]
    fn set_from_animation(&self, animation: &impl IsA<gdk_pixbuf::PixbufAnimation>) {
        unsafe {
            ffi::gtk_image_set_from_animation(
                self.as_ref().to_glib_none().0,
                animation.as_ref().to_glib_none().0,
            );
        }
    }

    /// See [`Image::from_file()`][crate::Image::from_file()] for details.
    /// ## `filename`
    /// a filename or [`None`]
    #[doc(alias = "gtk_image_set_from_file")]
    fn set_from_file(&self, filename: Option<impl AsRef<std::path::Path>>) {
        unsafe {
            ffi::gtk_image_set_from_file(
                self.as_ref().to_glib_none().0,
                filename.as_ref().map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// See [`Image::from_gicon()`][crate::Image::from_gicon()] for details.
    /// ## `icon`
    /// an icon
    /// ## `size`
    /// an icon size ([`IconSize`][crate::IconSize])
    #[doc(alias = "gtk_image_set_from_gicon")]
    fn set_from_gicon(&self, icon: &impl IsA<gio::Icon>, size: IconSize) {
        unsafe {
            ffi::gtk_image_set_from_gicon(
                self.as_ref().to_glib_none().0,
                icon.as_ref().to_glib_none().0,
                size.into_glib(),
            );
        }
    }

    /// See [`Image::from_icon_name()`][crate::Image::from_icon_name()] for details.
    /// ## `icon_name`
    /// an icon name or [`None`]
    /// ## `size`
    /// an icon size ([`IconSize`][crate::IconSize])
    #[doc(alias = "gtk_image_set_from_icon_name")]
    fn set_from_icon_name(&self, icon_name: Option<&str>, size: IconSize) {
        unsafe {
            ffi::gtk_image_set_from_icon_name(
                self.as_ref().to_glib_none().0,
                icon_name.to_glib_none().0,
                size.into_glib(),
            );
        }
    }

    /// See [`Image::from_pixbuf()`][crate::Image::from_pixbuf()] for details.
    /// ## `pixbuf`
    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] or [`None`]
    #[doc(alias = "gtk_image_set_from_pixbuf")]
    fn set_from_pixbuf(&self, pixbuf: Option<&gdk_pixbuf::Pixbuf>) {
        unsafe {
            ffi::gtk_image_set_from_pixbuf(self.as_ref().to_glib_none().0, pixbuf.to_glib_none().0);
        }
    }

    /// See [`Image::from_resource()`][crate::Image::from_resource()] for details.
    /// ## `resource_path`
    /// a resource path or [`None`]
    #[doc(alias = "gtk_image_set_from_resource")]
    fn set_from_resource(&self, resource_path: Option<&str>) {
        unsafe {
            ffi::gtk_image_set_from_resource(
                self.as_ref().to_glib_none().0,
                resource_path.to_glib_none().0,
            );
        }
    }

    /// See [`Image::from_surface()`][crate::Image::from_surface()] for details.
    /// ## `surface`
    /// a cairo_surface_t or [`None`]
    #[doc(alias = "gtk_image_set_from_surface")]
    fn set_from_surface(&self, surface: Option<&cairo::Surface>) {
        unsafe {
            ffi::gtk_image_set_from_surface(
                self.as_ref().to_glib_none().0,
                mut_override(surface.to_glib_none().0),
            );
        }
    }

    /// Sets the pixel size to use for named icons. If the pixel size is set
    /// to a value != -1, it is used instead of the icon size set by
    /// [`set_from_icon_name()`][Self::set_from_icon_name()].
    /// ## `pixel_size`
    /// the new pixel size
    #[doc(alias = "gtk_image_set_pixel_size")]
    fn set_pixel_size(&self, pixel_size: i32) {
        unsafe {
            ffi::gtk_image_set_pixel_size(self.as_ref().to_glib_none().0, pixel_size);
        }
    }

    fn file(&self) -> Option<glib::GString> {
        ObjectExt::property(self.as_ref(), "file")
    }

    fn set_file(&self, file: Option<&str>) {
        ObjectExt::set_property(self.as_ref(), "file", file)
    }

    /// The GIcon displayed in the GtkImage. For themed icons,
    /// If the icon theme is changed, the image will be updated
    /// automatically.
    fn set_gicon<P: IsA<gio::Icon>>(&self, gicon: Option<&P>) {
        ObjectExt::set_property(self.as_ref(), "gicon", gicon)
    }

    /// The name of the icon in the icon theme. If the icon theme is
    /// changed, the image will be updated automatically.
    #[doc(alias = "icon-name")]
    fn icon_name(&self) -> Option<glib::GString> {
        ObjectExt::property(self.as_ref(), "icon-name")
    }

    /// The name of the icon in the icon theme. If the icon theme is
    /// changed, the image will be updated automatically.
    #[doc(alias = "icon-name")]
    fn set_icon_name(&self, icon_name: Option<&str>) {
        ObjectExt::set_property(self.as_ref(), "icon-name", icon_name)
    }

    fn set_pixbuf(&self, pixbuf: Option<&gdk_pixbuf::Pixbuf>) {
        ObjectExt::set_property(self.as_ref(), "pixbuf", pixbuf)
    }

    #[doc(alias = "pixbuf-animation")]
    fn pixbuf_animation(&self) -> Option<gdk_pixbuf::PixbufAnimation> {
        ObjectExt::property(self.as_ref(), "pixbuf-animation")
    }

    #[doc(alias = "pixbuf-animation")]
    fn set_pixbuf_animation<P: IsA<gdk_pixbuf::PixbufAnimation>>(
        &self,
        pixbuf_animation: Option<&P>,
    ) {
        ObjectExt::set_property(self.as_ref(), "pixbuf-animation", pixbuf_animation)
    }

    /// A path to a resource file to display.
    fn resource(&self) -> Option<glib::GString> {
        ObjectExt::property(self.as_ref(), "resource")
    }

    /// A path to a resource file to display.
    fn set_resource(&self, resource: Option<&str>) {
        ObjectExt::set_property(self.as_ref(), "resource", resource)
    }

    fn surface(&self) -> Option<cairo::Surface> {
        ObjectExt::property(self.as_ref(), "surface")
    }

    fn set_surface(&self, surface: Option<&cairo::Surface>) {
        ObjectExt::set_property(self.as_ref(), "surface", surface)
    }

    /// Whether the icon displayed in the GtkImage will use
    /// standard icon names fallback. The value of this property
    /// is only relevant for images of type [`ImageType::IconName`][crate::ImageType::IconName]
    /// and [`ImageType::Gicon`][crate::ImageType::Gicon].
    #[doc(alias = "use-fallback")]
    fn uses_fallback(&self) -> bool {
        ObjectExt::property(self.as_ref(), "use-fallback")
    }

    /// Whether the icon displayed in the GtkImage will use
    /// standard icon names fallback. The value of this property
    /// is only relevant for images of type [`ImageType::IconName`][crate::ImageType::IconName]
    /// and [`ImageType::Gicon`][crate::ImageType::Gicon].
    #[doc(alias = "use-fallback")]
    fn set_use_fallback(&self, use_fallback: bool) {
        ObjectExt::set_property(self.as_ref(), "use-fallback", use_fallback)
    }

    #[doc(alias = "file")]
    fn connect_file_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_file_trampoline<P: IsA<Image>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::file\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_file_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "gicon")]
    fn connect_gicon_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_gicon_trampoline<P: IsA<Image>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::gicon\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_gicon_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "icon-name")]
    fn connect_icon_name_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_icon_name_trampoline<P: IsA<Image>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::icon-name\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_icon_name_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "pixbuf")]
    fn connect_pixbuf_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_pixbuf_trampoline<P: IsA<Image>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::pixbuf\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_pixbuf_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "pixbuf-animation")]
    fn connect_pixbuf_animation_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_pixbuf_animation_trampoline<
            P: IsA<Image>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::pixbuf-animation\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_pixbuf_animation_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "pixel-size")]
    fn connect_pixel_size_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_pixel_size_trampoline<P: IsA<Image>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::pixel-size\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_pixel_size_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "resource")]
    fn connect_resource_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_resource_trampoline<P: IsA<Image>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::resource\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_resource_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "storage-type")]
    fn connect_storage_type_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_storage_type_trampoline<P: IsA<Image>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::storage-type\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_storage_type_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "surface")]
    fn connect_surface_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_surface_trampoline<P: IsA<Image>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::surface\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_surface_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "use-fallback")]
    fn connect_use_fallback_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_use_fallback_trampoline<P: IsA<Image>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkImage,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Image::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::use-fallback\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_use_fallback_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Image>> ImageExt for O {}

impl fmt::Display for Image {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("Image")
    }
}