gdk_pixbuf/auto/

pixbuf_loader.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::{ffi, Pixbuf, PixbufAnimation, PixbufFormat};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// Incremental image loader.
    ///
    /// [`PixbufLoader`][crate::PixbufLoader] provides a way for applications to drive the
    /// process of loading an image, by letting them send the image data
    /// directly to the loader instead of having the loader read the data
    /// from a file. Applications can use this functionality instead of
    /// `gdk_pixbuf_new_from_file()` or `gdk_pixbuf_animation_new_from_file()`
    /// when they need to parse image data in small chunks. For example,
    /// it should be used when reading an image from a (potentially) slow
    /// network connection, or when loading an extremely large file.
    ///
    /// To use [`PixbufLoader`][crate::PixbufLoader] to load an image, create a new instance,
    /// and call [`PixbufLoaderExt::write()`][crate::prelude::PixbufLoaderExt::write()] to send the data
    /// to it. When done, [`PixbufLoaderExt::close()`][crate::prelude::PixbufLoaderExt::close()] should be
    /// called to end the stream and finalize everything.
    ///
    /// The loader will emit three important signals throughout the process:
    ///
    ///  - [`size-prepared`][struct@crate::PixbufLoader#size-prepared] will be emitted as
    ///    soon as the image has enough information to determine the size of
    ///    the image to be used. If you want to scale the image while loading
    ///    it, you can call [`PixbufLoaderExt::set_size()`][crate::prelude::PixbufLoaderExt::set_size()] in
    ///    response to this signal.
    ///  - [`area-prepared`][struct@crate::PixbufLoader#area-prepared] will be emitted as
    ///    soon as the pixbuf of the desired has been allocated. You can obtain
    ///    the [`Pixbuf`][crate::Pixbuf] instance by calling [`PixbufLoaderExt::pixbuf()`][crate::prelude::PixbufLoaderExt::pixbuf()].
    ///    If you want to use it, simply acquire a reference to it. You can
    ///    also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same
    ///    pixbuf.
    ///  - [`area-updated`][struct@crate::PixbufLoader#area-updated] will be emitted every
    ///    time a region is updated. This way you can update a partially
    ///    completed image. Note that you do not know anything about the
    ///    completeness of an image from the updated area. For example, in an
    ///    interlaced image you will need to make several passes before the
    ///    image is done loading.
    ///
    /// ## Loading an animation
    ///
    /// Loading an animation is almost as easy as loading an image. Once the
    /// first [`area-prepared`][struct@crate::PixbufLoader#area-prepared] signal has been
    /// emitted, you can call [`PixbufLoaderExt::animation()`][crate::prelude::PixbufLoaderExt::animation()] to
    /// get the [`PixbufAnimation`][crate::PixbufAnimation] instance, and then call
    /// and [`PixbufAnimationExtManual::iter()`][crate::prelude::PixbufAnimationExtManual::iter()] to get a
    /// [`PixbufAnimationIter`][crate::PixbufAnimationIter] to retrieve the pixbuf for the
    /// desired time stamp.
    ///
    /// ## Signals
    ///
    ///
    /// #### `area-prepared`
    ///  This signal is emitted when the pixbuf loader has allocated the
    /// pixbuf in the desired size.
    ///
    /// After this signal is emitted, applications can call
    /// gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded
    /// pixbuf.
    ///
    ///
    ///
    ///
    /// #### `area-updated`
    ///  This signal is emitted when a significant area of the image being
    /// loaded has been updated.
    ///
    /// Normally it means that a complete scanline has been read in, but
    /// it could be a different area as well.
    ///
    /// Applications can use this signal to know when to repaint
    /// areas of an image that is being loaded.
    ///
    ///
    ///
    ///
    /// #### `closed`
    ///  This signal is emitted when gdk_pixbuf_loader_close() is called.
    ///
    /// It can be used by different parts of an application to receive
    /// notification when an image loader is closed by the code that
    /// drives it.
    ///
    ///
    ///
    ///
    /// #### `size-prepared`
    ///  This signal is emitted when the pixbuf loader has been fed the
    /// initial amount of data that is required to figure out the size
    /// of the image that it will create.
    ///
    /// Applications can call gdk_pixbuf_loader_set_size() in response
    /// to this signal to set the desired size to which the image
    /// should be scaled.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`PixbufLoaderExt`][trait@crate::prelude::PixbufLoaderExt]
    #[doc(alias = "GdkPixbufLoader")]
    pub struct PixbufLoader(Object<ffi::GdkPixbufLoader, ffi::GdkPixbufLoaderClass>);

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

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

    /// Creates a new pixbuf loader object.
    ///
    /// # Returns
    ///
    /// A newly-created pixbuf loader.
    #[doc(alias = "gdk_pixbuf_loader_new")]
    pub fn new() -> PixbufLoader {
        unsafe { from_glib_full(ffi::gdk_pixbuf_loader_new()) }
    }

    /// Creates a new pixbuf loader object that always attempts to parse
    /// image data as if it were an image of MIME type @mime_type, instead of
    /// identifying the type automatically.
    ///
    /// This function is useful if you want an error if the image isn't the
    /// expected MIME type; for loading image formats that can't be reliably
    /// identified by looking at the data; or if the user manually forces a
    /// specific MIME type.
    ///
    /// The list of supported mime types depends on what image loaders
    /// are installed, but typically "image/png", "image/jpeg", "image/gif",
    /// "image/tiff" and "image/x-xpixmap" are among the supported mime types.
    /// To obtain the full list of supported mime types, call
    /// gdk_pixbuf_format_get_mime_types() on each of the #GdkPixbufFormat
    /// structs returned by gdk_pixbuf_get_formats().
    /// ## `mime_type`
    /// the mime type to be loaded
    ///
    /// # Returns
    ///
    /// A newly-created pixbuf loader.
    #[doc(alias = "gdk_pixbuf_loader_new_with_mime_type")]
    #[doc(alias = "new_with_mime_type")]
    pub fn with_mime_type(mime_type: &str) -> Result<PixbufLoader, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret =
                ffi::gdk_pixbuf_loader_new_with_mime_type(mime_type.to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Creates a new pixbuf loader object that always attempts to parse
    /// image data as if it were an image of type @image_type, instead of
    /// identifying the type automatically.
    ///
    /// This function is useful if you want an error if the image isn't the
    /// expected type; for loading image formats that can't be reliably
    /// identified by looking at the data; or if the user manually forces
    /// a specific type.
    ///
    /// The list of supported image formats depends on what image loaders
    /// are installed, but typically "png", "jpeg", "gif", "tiff" and
    /// "xpm" are among the supported formats. To obtain the full list of
    /// supported image formats, call gdk_pixbuf_format_get_name() on each
    /// of the #GdkPixbufFormat structs returned by gdk_pixbuf_get_formats().
    /// ## `image_type`
    /// name of the image format to be loaded with the image
    ///
    /// # Returns
    ///
    /// A newly-created pixbuf loader.
    #[doc(alias = "gdk_pixbuf_loader_new_with_type")]
    #[doc(alias = "new_with_type")]
    pub fn with_type(image_type: &str) -> Result<PixbufLoader, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gdk_pixbuf_loader_new_with_type(image_type.to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

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

/// Trait containing all [`struct@PixbufLoader`] methods.
///
/// # Implementors
///
/// [`PixbufLoader`][struct@crate::PixbufLoader]
pub trait PixbufLoaderExt: IsA<PixbufLoader> + 'static {
    /// Informs a pixbuf loader that no further writes with
    /// gdk_pixbuf_loader_write() will occur, so that it can free its
    /// internal loading structures.
    ///
    /// This function also tries to parse any data that hasn't yet been parsed;
    /// if the remaining data is partial or corrupt, an error will be returned.
    ///
    /// If `FALSE` is returned, `error` will be set to an error from the
    /// `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains.
    ///
    /// If you're just cancelling a load rather than expecting it to be finished,
    /// passing `NULL` for `error` to ignore it is reasonable.
    ///
    /// Remember that this function does not release a reference on the loader, so
    /// you will need to explicitly release any reference you hold.
    ///
    /// # Returns
    ///
    /// `TRUE` if all image data written so far was successfully
    ///   passed out via the update_area signal
    #[doc(alias = "gdk_pixbuf_loader_close")]
    fn close(&self) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::gdk_pixbuf_loader_close(self.as_ref().to_glib_none().0, &mut error);
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating.
    ///
    /// In general it only makes sense to call this function after the
    /// [`area-prepared`][struct@crate::PixbufLoader#area-prepared] signal has been emitted by
    /// the loader.
    ///
    /// If the loader doesn't have enough bytes yet, and hasn't emitted the `area-prepared`
    /// signal, this function will return `NULL`.
    ///
    /// # Returns
    ///
    /// The animation that the loader is
    ///   currently loading
    #[doc(alias = "gdk_pixbuf_loader_get_animation")]
    #[doc(alias = "get_animation")]
    fn animation(&self) -> Option<PixbufAnimation> {
        unsafe {
            from_glib_none(ffi::gdk_pixbuf_loader_get_animation(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Obtains the available information about the format of the
    /// currently loading image file.
    ///
    /// # Returns
    ///
    /// A #GdkPixbufFormat
    #[doc(alias = "gdk_pixbuf_loader_get_format")]
    #[doc(alias = "get_format")]
    fn format(&self) -> Option<PixbufFormat> {
        unsafe {
            from_glib_none(ffi::gdk_pixbuf_loader_get_format(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Queries the #GdkPixbuf that a pixbuf loader is currently creating.
    ///
    /// In general it only makes sense to call this function after the
    /// [`area-prepared`][struct@crate::PixbufLoader#area-prepared] signal has been
    /// emitted by the loader; this means that enough data has been read
    /// to know the size of the image that will be allocated.
    ///
    /// If the loader has not received enough data via gdk_pixbuf_loader_write(),
    /// then this function returns `NULL`.
    ///
    /// The returned pixbuf will be the same in all future calls to the loader,
    /// so if you want to keep using it, you should acquire a reference to it.
    ///
    /// Additionally, if the loader is an animation, it will return the "static
    /// image" of the animation (see gdk_pixbuf_animation_get_static_image()).
    ///
    /// # Returns
    ///
    /// The pixbuf that the loader is
    ///   creating
    #[doc(alias = "gdk_pixbuf_loader_get_pixbuf")]
    #[doc(alias = "get_pixbuf")]
    fn pixbuf(&self) -> Option<Pixbuf> {
        unsafe {
            from_glib_none(ffi::gdk_pixbuf_loader_get_pixbuf(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Causes the image to be scaled while it is loaded.
    ///
    /// The desired image size can be determined relative to the original
    /// size of the image by calling gdk_pixbuf_loader_set_size() from a
    /// signal handler for the ::size-prepared signal.
    ///
    /// Attempts to set the desired image size  are ignored after the
    /// emission of the ::size-prepared signal.
    /// ## `width`
    /// The desired width of the image being loaded.
    /// ## `height`
    /// The desired height of the image being loaded.
    #[doc(alias = "gdk_pixbuf_loader_set_size")]
    fn set_size(&self, width: i32, height: i32) {
        unsafe {
            ffi::gdk_pixbuf_loader_set_size(self.as_ref().to_glib_none().0, width, height);
        }
    }

    /// Parses the next `count` bytes in the given image buffer.
    /// ## `buf`
    /// Pointer to image data.
    ///
    /// # Returns
    ///
    /// `TRUE` if the write was successful, or
    ///   `FALSE` if the loader cannot parse the buffer
    #[doc(alias = "gdk_pixbuf_loader_write")]
    fn write(&self, buf: &[u8]) -> Result<(), glib::Error> {
        let count = buf.len() as _;
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::gdk_pixbuf_loader_write(
                self.as_ref().to_glib_none().0,
                buf.to_glib_none().0,
                count,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses the next contents of the given image buffer.
    /// ## `buffer`
    /// The image data as a `GBytes` buffer.
    ///
    /// # Returns
    ///
    /// `TRUE` if the write was successful, or `FALSE` if
    ///   the loader cannot parse the buffer
    #[doc(alias = "gdk_pixbuf_loader_write_bytes")]
    fn write_bytes(&self, buffer: &glib::Bytes) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::gdk_pixbuf_loader_write_bytes(
                self.as_ref().to_glib_none().0,
                buffer.to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// This signal is emitted when the pixbuf loader has allocated the
    /// pixbuf in the desired size.
    ///
    /// After this signal is emitted, applications can call
    /// gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded
    /// pixbuf.
    #[doc(alias = "area-prepared")]
    fn connect_area_prepared<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn area_prepared_trampoline<P: IsA<PixbufLoader>, F: Fn(&P) + 'static>(
            this: *mut ffi::GdkPixbufLoader,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(PixbufLoader::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"area-prepared".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    area_prepared_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal is emitted when a significant area of the image being
    /// loaded has been updated.
    ///
    /// Normally it means that a complete scanline has been read in, but
    /// it could be a different area as well.
    ///
    /// Applications can use this signal to know when to repaint
    /// areas of an image that is being loaded.
    /// ## `x`
    /// X offset of upper-left corner of the updated area.
    /// ## `y`
    /// Y offset of upper-left corner of the updated area.
    /// ## `width`
    /// Width of updated area.
    /// ## `height`
    /// Height of updated area.
    #[doc(alias = "area-updated")]
    fn connect_area_updated<F: Fn(&Self, i32, i32, i32, i32) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn area_updated_trampoline<
            P: IsA<PixbufLoader>,
            F: Fn(&P, i32, i32, i32, i32) + 'static,
        >(
            this: *mut ffi::GdkPixbufLoader,
            x: std::ffi::c_int,
            y: std::ffi::c_int,
            width: std::ffi::c_int,
            height: std::ffi::c_int,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                PixbufLoader::from_glib_borrow(this).unsafe_cast_ref(),
                x,
                y,
                width,
                height,
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"area-updated".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    area_updated_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal is emitted when gdk_pixbuf_loader_close() is called.
    ///
    /// It can be used by different parts of an application to receive
    /// notification when an image loader is closed by the code that
    /// drives it.
    #[doc(alias = "closed")]
    fn connect_closed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn closed_trampoline<P: IsA<PixbufLoader>, F: Fn(&P) + 'static>(
            this: *mut ffi::GdkPixbufLoader,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(PixbufLoader::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"closed".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    closed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal is emitted when the pixbuf loader has been fed the
    /// initial amount of data that is required to figure out the size
    /// of the image that it will create.
    ///
    /// Applications can call gdk_pixbuf_loader_set_size() in response
    /// to this signal to set the desired size to which the image
    /// should be scaled.
    /// ## `width`
    /// the original width of the image
    /// ## `height`
    /// the original height of the image
    #[doc(alias = "size-prepared")]
    fn connect_size_prepared<F: Fn(&Self, i32, i32) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn size_prepared_trampoline<
            P: IsA<PixbufLoader>,
            F: Fn(&P, i32, i32) + 'static,
        >(
            this: *mut ffi::GdkPixbufLoader,
            width: std::ffi::c_int,
            height: std::ffi::c_int,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                PixbufLoader::from_glib_borrow(this).unsafe_cast_ref(),
                width,
                height,
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"size-prepared".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    size_prepared_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<PixbufLoader>> PixbufLoaderExt for O {}