gdk_pixbuf/auto/

pixbuf_animation.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};
use glib::{prelude::*, translate::*};
use std::{boxed::Box as Box_, pin::Pin};

glib::wrapper! {
    /// An opaque object representing an animation.
    ///
    /// The GdkPixBuf library provides a simple mechanism to load and
    /// represent animations. An animation is conceptually a series of
    /// frames to be displayed over time.
    ///
    /// The animation may not be represented as a series of frames
    /// internally; for example, it may be stored as a sprite and
    /// instructions for moving the sprite around a background.
    ///
    /// To display an animation you don't need to understand its
    /// representation, however; you just ask [`Pixbuf`][crate::Pixbuf] what should
    /// be displayed at a given point in time.
    ///
    /// # Implements
    ///
    /// [`PixbufAnimationExt`][trait@crate::prelude::PixbufAnimationExt], [`PixbufAnimationExtManual`][trait@crate::prelude::PixbufAnimationExtManual]
    #[doc(alias = "GdkPixbufAnimation")]
    pub struct PixbufAnimation(Object<ffi::GdkPixbufAnimation, ffi::GdkPixbufAnimationClass>);

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

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

    /// Creates a new animation by loading it from a file.
    ///
    /// The file format is detected automatically.
    ///
    /// If the file's format does not support multi-frame images, then an animation
    /// with a single frame will be created.
    ///
    /// Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains.
    /// ## `filename`
    /// Name of file to load, in the GLib file
    ///   name encoding
    ///
    /// # Returns
    ///
    /// A newly-created animation
    #[doc(alias = "gdk_pixbuf_animation_new_from_file")]
    #[doc(alias = "new_from_file")]
    pub fn from_file(
        filename: impl AsRef<std::path::Path>,
    ) -> Result<PixbufAnimation, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gdk_pixbuf_animation_new_from_file(
                filename.as_ref().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 animation by loading an image from an resource.
    ///
    /// The file format is detected automatically. If `NULL` is returned, then
    /// @error will be set.
    /// ## `resource_path`
    /// the path of the resource file
    ///
    /// # Returns
    ///
    /// A newly-created animation
    #[doc(alias = "gdk_pixbuf_animation_new_from_resource")]
    #[doc(alias = "new_from_resource")]
    pub fn from_resource(resource_path: &str) -> Result<PixbufAnimation, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gdk_pixbuf_animation_new_from_resource(
                resource_path.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Creates a new animation by loading it from an input stream.
    ///
    /// The file format is detected automatically.
    ///
    /// If `NULL` is returned, then @error will be set.
    ///
    /// The @cancellable can be used to abort the operation from another thread.
    /// If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be
    /// returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and
    /// `G_IO_ERROR` domains.
    ///
    /// The stream is not closed.
    /// ## `stream`
    /// a `GInputStream` to load the pixbuf from
    /// ## `cancellable`
    /// optional `GCancellable` object
    ///
    /// # Returns
    ///
    /// A newly-created animation
    #[doc(alias = "gdk_pixbuf_animation_new_from_stream")]
    #[doc(alias = "new_from_stream")]
    pub fn from_stream(
        stream: &impl IsA<gio::InputStream>,
        cancellable: Option<&impl IsA<gio::Cancellable>>,
    ) -> Result<PixbufAnimation, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gdk_pixbuf_animation_new_from_stream(
                stream.as_ref().to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Creates a new animation by asynchronously loading an image from an input stream.
    ///
    /// For more details see gdk_pixbuf_new_from_stream(), which is the synchronous
    /// version of this function.
    ///
    /// When the operation is finished, `callback` will be called in the main thread.
    /// You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the
    /// result of the operation.
    /// ## `stream`
    /// a #GInputStream from which to load the animation
    /// ## `cancellable`
    /// optional #GCancellable object
    /// ## `callback`
    /// a `GAsyncReadyCallback` to call when the pixbuf is loaded
    #[doc(alias = "gdk_pixbuf_animation_new_from_stream_async")]
    #[doc(alias = "new_from_stream_async")]
    pub fn from_stream_async<P: FnOnce(Result<PixbufAnimation, glib::Error>) + 'static>(
        stream: &impl IsA<gio::InputStream>,
        cancellable: Option<&impl IsA<gio::Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn from_stream_async_trampoline<
            P: FnOnce(Result<PixbufAnimation, glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut gio::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gdk_pixbuf_animation_new_from_stream_finish(res, &mut error);
            let result = if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            };
            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                Box_::from_raw(user_data as *mut _);
            let callback: P = callback.into_inner();
            callback(result);
        }
        let callback = from_stream_async_trampoline::<P>;
        unsafe {
            ffi::gdk_pixbuf_animation_new_from_stream_async(
                stream.as_ref().to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    pub fn from_stream_future(
        stream: &(impl IsA<gio::InputStream> + Clone + 'static),
    ) -> Pin<Box_<dyn std::future::Future<Output = Result<PixbufAnimation, glib::Error>> + 'static>>
    {
        let stream = stream.clone();
        Box_::pin(gio::GioFuture::new(&(), move |_obj, cancellable, send| {
            Self::from_stream_async(&stream, Some(cancellable), move |res| {
                send.resolve(res);
            });
        }))
    }
}

/// Trait containing all [`struct@PixbufAnimation`] methods.
///
/// # Implementors
///
/// [`PixbufAnimation`][struct@crate::PixbufAnimation], [`PixbufNonAnim`][struct@crate::PixbufNonAnim], [`PixbufSimpleAnim`][struct@crate::PixbufSimpleAnim]
pub trait PixbufAnimationExt: IsA<PixbufAnimation> + 'static {
    /// Queries the height of the bounding box of a pixbuf animation.
    ///
    /// # Returns
    ///
    /// Height of the bounding box of the animation.
    #[doc(alias = "gdk_pixbuf_animation_get_height")]
    #[doc(alias = "get_height")]
    fn height(&self) -> i32 {
        unsafe { ffi::gdk_pixbuf_animation_get_height(self.as_ref().to_glib_none().0) }
    }

    /// Retrieves a static image for the animation.
    ///
    /// If an animation is really just a plain image (has only one frame),
    /// this function returns that image.
    ///
    /// If the animation is an animation, this function returns a reasonable
    /// image to use as a static unanimated image, which might be the first
    /// frame, or something more sophisticated depending on the file format.
    ///
    /// If an animation hasn't loaded any frames yet, this function will
    /// return `NULL`.
    ///
    /// # Returns
    ///
    /// unanimated image representing the animation
    #[doc(alias = "gdk_pixbuf_animation_get_static_image")]
    #[doc(alias = "get_static_image")]
    fn static_image(&self) -> Option<Pixbuf> {
        unsafe {
            from_glib_none(ffi::gdk_pixbuf_animation_get_static_image(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Queries the width of the bounding box of a pixbuf animation.
    ///
    /// # Returns
    ///
    /// Width of the bounding box of the animation.
    #[doc(alias = "gdk_pixbuf_animation_get_width")]
    #[doc(alias = "get_width")]
    fn width(&self) -> i32 {
        unsafe { ffi::gdk_pixbuf_animation_get_width(self.as_ref().to_glib_none().0) }
    }

    /// Checks whether the animation is a static image.
    ///
    /// If you load a file with gdk_pixbuf_animation_new_from_file() and it
    /// turns out to be a plain, unanimated image, then this function will
    /// return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve
    /// the image.
    ///
    /// # Returns
    ///
    /// `TRUE` if the "animation" was really just an image
    #[doc(alias = "gdk_pixbuf_animation_is_static_image")]
    fn is_static_image(&self) -> bool {
        unsafe {
            from_glib(ffi::gdk_pixbuf_animation_is_static_image(
                self.as_ref().to_glib_none().0,
            ))
        }
    }
}

impl<O: IsA<PixbufAnimation>> PixbufAnimationExt for O {}