gdk_pixbuf/auto/
pixbuf_animation.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
5use crate::{ffi, Pixbuf};
6use glib::{prelude::*, translate::*};
7use std::{boxed::Box as Box_, pin::Pin};
8
9glib::wrapper! {
10    /// An opaque object representing an animation.
11    ///
12    /// The GdkPixBuf library provides a simple mechanism to load and
13    /// represent animations. An animation is conceptually a series of
14    /// frames to be displayed over time.
15    ///
16    /// The animation may not be represented as a series of frames
17    /// internally; for example, it may be stored as a sprite and
18    /// instructions for moving the sprite around a background.
19    ///
20    /// To display an animation you don't need to understand its
21    /// representation, however; you just ask [`Pixbuf`][crate::Pixbuf] what should
22    /// be displayed at a given point in time.
23    ///
24    /// # Implements
25    ///
26    /// [`PixbufAnimationExt`][trait@crate::prelude::PixbufAnimationExt], [`PixbufAnimationExtManual`][trait@crate::prelude::PixbufAnimationExtManual]
27    #[doc(alias = "GdkPixbufAnimation")]
28    pub struct PixbufAnimation(Object<ffi::GdkPixbufAnimation, ffi::GdkPixbufAnimationClass>);
29
30    match fn {
31        type_ => || ffi::gdk_pixbuf_animation_get_type(),
32    }
33}
34
35impl PixbufAnimation {
36    pub const NONE: Option<&'static PixbufAnimation> = None;
37
38    /// Creates a new animation by loading it from a file.
39    ///
40    /// The file format is detected automatically.
41    ///
42    /// If the file's format does not support multi-frame images, then an animation
43    /// with a single frame will be created.
44    ///
45    /// Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains.
46    /// ## `filename`
47    /// Name of file to load, in the GLib file
48    ///   name encoding
49    ///
50    /// # Returns
51    ///
52    /// A newly-created animation
53    #[doc(alias = "gdk_pixbuf_animation_new_from_file")]
54    #[doc(alias = "new_from_file")]
55    pub fn from_file(
56        filename: impl AsRef<std::path::Path>,
57    ) -> Result<PixbufAnimation, glib::Error> {
58        unsafe {
59            let mut error = std::ptr::null_mut();
60            let ret = ffi::gdk_pixbuf_animation_new_from_file(
61                filename.as_ref().to_glib_none().0,
62                &mut error,
63            );
64            if error.is_null() {
65                Ok(from_glib_full(ret))
66            } else {
67                Err(from_glib_full(error))
68            }
69        }
70    }
71
72    /// Creates a new pixbuf animation by loading an image from an resource.
73    ///
74    /// The file format is detected automatically. If `NULL` is returned, then
75    /// @error will be set.
76    /// ## `resource_path`
77    /// the path of the resource file
78    ///
79    /// # Returns
80    ///
81    /// A newly-created animation
82    #[doc(alias = "gdk_pixbuf_animation_new_from_resource")]
83    #[doc(alias = "new_from_resource")]
84    pub fn from_resource(resource_path: &str) -> Result<PixbufAnimation, glib::Error> {
85        unsafe {
86            let mut error = std::ptr::null_mut();
87            let ret = ffi::gdk_pixbuf_animation_new_from_resource(
88                resource_path.to_glib_none().0,
89                &mut error,
90            );
91            if error.is_null() {
92                Ok(from_glib_full(ret))
93            } else {
94                Err(from_glib_full(error))
95            }
96        }
97    }
98
99    /// Creates a new animation by loading it from an input stream.
100    ///
101    /// The file format is detected automatically.
102    ///
103    /// If `NULL` is returned, then @error will be set.
104    ///
105    /// The @cancellable can be used to abort the operation from another thread.
106    /// If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be
107    /// returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and
108    /// `G_IO_ERROR` domains.
109    ///
110    /// The stream is not closed.
111    /// ## `stream`
112    /// a `GInputStream` to load the pixbuf from
113    /// ## `cancellable`
114    /// optional `GCancellable` object
115    ///
116    /// # Returns
117    ///
118    /// A newly-created animation
119    #[doc(alias = "gdk_pixbuf_animation_new_from_stream")]
120    #[doc(alias = "new_from_stream")]
121    pub fn from_stream(
122        stream: &impl IsA<gio::InputStream>,
123        cancellable: Option<&impl IsA<gio::Cancellable>>,
124    ) -> Result<PixbufAnimation, glib::Error> {
125        unsafe {
126            let mut error = std::ptr::null_mut();
127            let ret = ffi::gdk_pixbuf_animation_new_from_stream(
128                stream.as_ref().to_glib_none().0,
129                cancellable.map(|p| p.as_ref()).to_glib_none().0,
130                &mut error,
131            );
132            if error.is_null() {
133                Ok(from_glib_full(ret))
134            } else {
135                Err(from_glib_full(error))
136            }
137        }
138    }
139
140    /// Creates a new animation by asynchronously loading an image from an input stream.
141    ///
142    /// For more details see gdk_pixbuf_new_from_stream(), which is the synchronous
143    /// version of this function.
144    ///
145    /// When the operation is finished, `callback` will be called in the main thread.
146    /// You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the
147    /// result of the operation.
148    /// ## `stream`
149    /// a #GInputStream from which to load the animation
150    /// ## `cancellable`
151    /// optional #GCancellable object
152    /// ## `callback`
153    /// a `GAsyncReadyCallback` to call when the pixbuf is loaded
154    #[doc(alias = "gdk_pixbuf_animation_new_from_stream_async")]
155    #[doc(alias = "new_from_stream_async")]
156    pub fn from_stream_async<P: FnOnce(Result<PixbufAnimation, glib::Error>) + 'static>(
157        stream: &impl IsA<gio::InputStream>,
158        cancellable: Option<&impl IsA<gio::Cancellable>>,
159        callback: P,
160    ) {
161        let main_context = glib::MainContext::ref_thread_default();
162        let is_main_context_owner = main_context.is_owner();
163        let has_acquired_main_context = (!is_main_context_owner)
164            .then(|| main_context.acquire().ok())
165            .flatten();
166        assert!(
167            is_main_context_owner || has_acquired_main_context.is_some(),
168            "Async operations only allowed if the thread is owning the MainContext"
169        );
170
171        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
172            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
173        unsafe extern "C" fn from_stream_async_trampoline<
174            P: FnOnce(Result<PixbufAnimation, glib::Error>) + 'static,
175        >(
176            _source_object: *mut glib::gobject_ffi::GObject,
177            res: *mut gio::ffi::GAsyncResult,
178            user_data: glib::ffi::gpointer,
179        ) {
180            let mut error = std::ptr::null_mut();
181            let ret = ffi::gdk_pixbuf_animation_new_from_stream_finish(res, &mut error);
182            let result = if error.is_null() {
183                Ok(from_glib_full(ret))
184            } else {
185                Err(from_glib_full(error))
186            };
187            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
188                Box_::from_raw(user_data as *mut _);
189            let callback: P = callback.into_inner();
190            callback(result);
191        }
192        let callback = from_stream_async_trampoline::<P>;
193        unsafe {
194            ffi::gdk_pixbuf_animation_new_from_stream_async(
195                stream.as_ref().to_glib_none().0,
196                cancellable.map(|p| p.as_ref()).to_glib_none().0,
197                Some(callback),
198                Box_::into_raw(user_data) as *mut _,
199            );
200        }
201    }
202
203    pub fn from_stream_future(
204        stream: &(impl IsA<gio::InputStream> + Clone + 'static),
205    ) -> Pin<Box_<dyn std::future::Future<Output = Result<PixbufAnimation, glib::Error>> + 'static>>
206    {
207        let stream = stream.clone();
208        Box_::pin(gio::GioFuture::new(&(), move |_obj, cancellable, send| {
209            Self::from_stream_async(&stream, Some(cancellable), move |res| {
210                send.resolve(res);
211            });
212        }))
213    }
214}
215
216mod sealed {
217    pub trait Sealed {}
218    impl<T: super::IsA<super::PixbufAnimation>> Sealed for T {}
219}
220
221/// Trait containing all [`struct@PixbufAnimation`] methods.
222///
223/// # Implementors
224///
225/// [`PixbufAnimation`][struct@crate::PixbufAnimation], [`PixbufNonAnim`][struct@crate::PixbufNonAnim], [`PixbufSimpleAnim`][struct@crate::PixbufSimpleAnim]
226pub trait PixbufAnimationExt: IsA<PixbufAnimation> + sealed::Sealed + 'static {
227    /// Queries the height of the bounding box of a pixbuf animation.
228    ///
229    /// # Returns
230    ///
231    /// Height of the bounding box of the animation.
232    #[doc(alias = "gdk_pixbuf_animation_get_height")]
233    #[doc(alias = "get_height")]
234    fn height(&self) -> i32 {
235        unsafe { ffi::gdk_pixbuf_animation_get_height(self.as_ref().to_glib_none().0) }
236    }
237
238    /// Retrieves a static image for the animation.
239    ///
240    /// If an animation is really just a plain image (has only one frame),
241    /// this function returns that image.
242    ///
243    /// If the animation is an animation, this function returns a reasonable
244    /// image to use as a static unanimated image, which might be the first
245    /// frame, or something more sophisticated depending on the file format.
246    ///
247    /// If an animation hasn't loaded any frames yet, this function will
248    /// return `NULL`.
249    ///
250    /// # Returns
251    ///
252    /// unanimated image representing the animation
253    #[doc(alias = "gdk_pixbuf_animation_get_static_image")]
254    #[doc(alias = "get_static_image")]
255    fn static_image(&self) -> Option<Pixbuf> {
256        unsafe {
257            from_glib_none(ffi::gdk_pixbuf_animation_get_static_image(
258                self.as_ref().to_glib_none().0,
259            ))
260        }
261    }
262
263    /// Queries the width of the bounding box of a pixbuf animation.
264    ///
265    /// # Returns
266    ///
267    /// Width of the bounding box of the animation.
268    #[doc(alias = "gdk_pixbuf_animation_get_width")]
269    #[doc(alias = "get_width")]
270    fn width(&self) -> i32 {
271        unsafe { ffi::gdk_pixbuf_animation_get_width(self.as_ref().to_glib_none().0) }
272    }
273
274    /// Checks whether the animation is a static image.
275    ///
276    /// If you load a file with gdk_pixbuf_animation_new_from_file() and it
277    /// turns out to be a plain, unanimated image, then this function will
278    /// return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve
279    /// the image.
280    ///
281    /// # Returns
282    ///
283    /// `TRUE` if the "animation" was really just an image
284    #[doc(alias = "gdk_pixbuf_animation_is_static_image")]
285    fn is_static_image(&self) -> bool {
286        unsafe {
287            from_glib(ffi::gdk_pixbuf_animation_is_static_image(
288                self.as_ref().to_glib_none().0,
289            ))
290        }
291    }
292}
293
294impl<O: IsA<PixbufAnimation>> PixbufAnimationExt for O {}