gdk_pixbuf/auto/
pixbuf_loader.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, PixbufAnimation, PixbufFormat};
6use glib::{
7    object::ObjectType as _,
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// Incremental image loader.
16    ///
17    /// [`PixbufLoader`][crate::PixbufLoader] provides a way for applications to drive the
18    /// process of loading an image, by letting them send the image data
19    /// directly to the loader instead of having the loader read the data
20    /// from a file. Applications can use this functionality instead of
21    /// `gdk_pixbuf_new_from_file()` or `gdk_pixbuf_animation_new_from_file()`
22    /// when they need to parse image data in small chunks. For example,
23    /// it should be used when reading an image from a (potentially) slow
24    /// network connection, or when loading an extremely large file.
25    ///
26    /// To use [`PixbufLoader`][crate::PixbufLoader] to load an image, create a new instance,
27    /// and call [`PixbufLoaderExt::write()`][crate::prelude::PixbufLoaderExt::write()] to send the data
28    /// to it. When done, [`PixbufLoaderExt::close()`][crate::prelude::PixbufLoaderExt::close()] should be
29    /// called to end the stream and finalize everything.
30    ///
31    /// The loader will emit three important signals throughout the process:
32    ///
33    ///  - [`size-prepared`][struct@crate::PixbufLoader#size-prepared] will be emitted as
34    ///    soon as the image has enough information to determine the size of
35    ///    the image to be used. If you want to scale the image while loading
36    ///    it, you can call [`PixbufLoaderExt::set_size()`][crate::prelude::PixbufLoaderExt::set_size()] in
37    ///    response to this signal.
38    ///  - [`area-prepared`][struct@crate::PixbufLoader#area-prepared] will be emitted as
39    ///    soon as the pixbuf of the desired has been allocated. You can obtain
40    ///    the [`Pixbuf`][crate::Pixbuf] instance by calling [`PixbufLoaderExt::pixbuf()`][crate::prelude::PixbufLoaderExt::pixbuf()].
41    ///    If you want to use it, simply acquire a reference to it. You can
42    ///    also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same
43    ///    pixbuf.
44    ///  - [`area-updated`][struct@crate::PixbufLoader#area-updated] will be emitted every
45    ///    time a region is updated. This way you can update a partially
46    ///    completed image. Note that you do not know anything about the
47    ///    completeness of an image from the updated area. For example, in an
48    ///    interlaced image you will need to make several passes before the
49    ///    image is done loading.
50    ///
51    /// ## Loading an animation
52    ///
53    /// Loading an animation is almost as easy as loading an image. Once the
54    /// first [`area-prepared`][struct@crate::PixbufLoader#area-prepared] signal has been
55    /// emitted, you can call [`PixbufLoaderExt::animation()`][crate::prelude::PixbufLoaderExt::animation()] to
56    /// get the [`PixbufAnimation`][crate::PixbufAnimation] instance, and then call
57    /// and [`PixbufAnimationExtManual::iter()`][crate::prelude::PixbufAnimationExtManual::iter()] to get a
58    /// [`PixbufAnimationIter`][crate::PixbufAnimationIter] to retrieve the pixbuf for the
59    /// desired time stamp.
60    ///
61    /// ## Signals
62    ///
63    ///
64    /// #### `area-prepared`
65    ///  This signal is emitted when the pixbuf loader has allocated the
66    /// pixbuf in the desired size.
67    ///
68    /// After this signal is emitted, applications can call
69    /// gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded
70    /// pixbuf.
71    ///
72    ///
73    ///
74    ///
75    /// #### `area-updated`
76    ///  This signal is emitted when a significant area of the image being
77    /// loaded has been updated.
78    ///
79    /// Normally it means that a complete scanline has been read in, but
80    /// it could be a different area as well.
81    ///
82    /// Applications can use this signal to know when to repaint
83    /// areas of an image that is being loaded.
84    ///
85    ///
86    ///
87    ///
88    /// #### `closed`
89    ///  This signal is emitted when gdk_pixbuf_loader_close() is called.
90    ///
91    /// It can be used by different parts of an application to receive
92    /// notification when an image loader is closed by the code that
93    /// drives it.
94    ///
95    ///
96    ///
97    ///
98    /// #### `size-prepared`
99    ///  This signal is emitted when the pixbuf loader has been fed the
100    /// initial amount of data that is required to figure out the size
101    /// of the image that it will create.
102    ///
103    /// Applications can call gdk_pixbuf_loader_set_size() in response
104    /// to this signal to set the desired size to which the image
105    /// should be scaled.
106    ///
107    ///
108    ///
109    /// # Implements
110    ///
111    /// [`PixbufLoaderExt`][trait@crate::prelude::PixbufLoaderExt]
112    #[doc(alias = "GdkPixbufLoader")]
113    pub struct PixbufLoader(Object<ffi::GdkPixbufLoader, ffi::GdkPixbufLoaderClass>);
114
115    match fn {
116        type_ => || ffi::gdk_pixbuf_loader_get_type(),
117    }
118}
119
120impl PixbufLoader {
121    pub const NONE: Option<&'static PixbufLoader> = None;
122
123    /// Creates a new pixbuf loader object.
124    ///
125    /// # Returns
126    ///
127    /// A newly-created pixbuf loader.
128    #[doc(alias = "gdk_pixbuf_loader_new")]
129    pub fn new() -> PixbufLoader {
130        unsafe { from_glib_full(ffi::gdk_pixbuf_loader_new()) }
131    }
132
133    /// Creates a new pixbuf loader object that always attempts to parse
134    /// image data as if it were an image of MIME type @mime_type, instead of
135    /// identifying the type automatically.
136    ///
137    /// This function is useful if you want an error if the image isn't the
138    /// expected MIME type; for loading image formats that can't be reliably
139    /// identified by looking at the data; or if the user manually forces a
140    /// specific MIME type.
141    ///
142    /// The list of supported mime types depends on what image loaders
143    /// are installed, but typically "image/png", "image/jpeg", "image/gif",
144    /// "image/tiff" and "image/x-xpixmap" are among the supported mime types.
145    /// To obtain the full list of supported mime types, call
146    /// gdk_pixbuf_format_get_mime_types() on each of the #GdkPixbufFormat
147    /// structs returned by gdk_pixbuf_get_formats().
148    /// ## `mime_type`
149    /// the mime type to be loaded
150    ///
151    /// # Returns
152    ///
153    /// A newly-created pixbuf loader.
154    #[doc(alias = "gdk_pixbuf_loader_new_with_mime_type")]
155    #[doc(alias = "new_with_mime_type")]
156    pub fn with_mime_type(mime_type: &str) -> Result<PixbufLoader, glib::Error> {
157        unsafe {
158            let mut error = std::ptr::null_mut();
159            let ret =
160                ffi::gdk_pixbuf_loader_new_with_mime_type(mime_type.to_glib_none().0, &mut error);
161            if error.is_null() {
162                Ok(from_glib_full(ret))
163            } else {
164                Err(from_glib_full(error))
165            }
166        }
167    }
168
169    /// Creates a new pixbuf loader object that always attempts to parse
170    /// image data as if it were an image of type @image_type, instead of
171    /// identifying the type automatically.
172    ///
173    /// This function is useful if you want an error if the image isn't the
174    /// expected type; for loading image formats that can't be reliably
175    /// identified by looking at the data; or if the user manually forces
176    /// a specific type.
177    ///
178    /// The list of supported image formats depends on what image loaders
179    /// are installed, but typically "png", "jpeg", "gif", "tiff" and
180    /// "xpm" are among the supported formats. To obtain the full list of
181    /// supported image formats, call gdk_pixbuf_format_get_name() on each
182    /// of the #GdkPixbufFormat structs returned by gdk_pixbuf_get_formats().
183    /// ## `image_type`
184    /// name of the image format to be loaded with the image
185    ///
186    /// # Returns
187    ///
188    /// A newly-created pixbuf loader.
189    #[doc(alias = "gdk_pixbuf_loader_new_with_type")]
190    #[doc(alias = "new_with_type")]
191    pub fn with_type(image_type: &str) -> Result<PixbufLoader, glib::Error> {
192        unsafe {
193            let mut error = std::ptr::null_mut();
194            let ret = ffi::gdk_pixbuf_loader_new_with_type(image_type.to_glib_none().0, &mut error);
195            if error.is_null() {
196                Ok(from_glib_full(ret))
197            } else {
198                Err(from_glib_full(error))
199            }
200        }
201    }
202}
203
204impl Default for PixbufLoader {
205    fn default() -> Self {
206        Self::new()
207    }
208}
209
210mod sealed {
211    pub trait Sealed {}
212    impl<T: super::IsA<super::PixbufLoader>> Sealed for T {}
213}
214
215/// Trait containing all [`struct@PixbufLoader`] methods.
216///
217/// # Implementors
218///
219/// [`PixbufLoader`][struct@crate::PixbufLoader]
220pub trait PixbufLoaderExt: IsA<PixbufLoader> + sealed::Sealed + 'static {
221    /// Informs a pixbuf loader that no further writes with
222    /// gdk_pixbuf_loader_write() will occur, so that it can free its
223    /// internal loading structures.
224    ///
225    /// This function also tries to parse any data that hasn't yet been parsed;
226    /// if the remaining data is partial or corrupt, an error will be returned.
227    ///
228    /// If `FALSE` is returned, `error` will be set to an error from the
229    /// `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains.
230    ///
231    /// If you're just cancelling a load rather than expecting it to be finished,
232    /// passing `NULL` for `error` to ignore it is reasonable.
233    ///
234    /// Remember that this function does not release a reference on the loader, so
235    /// you will need to explicitly release any reference you hold.
236    ///
237    /// # Returns
238    ///
239    /// `TRUE` if all image data written so far was successfully
240    ///   passed out via the update_area signal
241    #[doc(alias = "gdk_pixbuf_loader_close")]
242    fn close(&self) -> Result<(), glib::Error> {
243        unsafe {
244            let mut error = std::ptr::null_mut();
245            let is_ok = ffi::gdk_pixbuf_loader_close(self.as_ref().to_glib_none().0, &mut error);
246            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
247            if error.is_null() {
248                Ok(())
249            } else {
250                Err(from_glib_full(error))
251            }
252        }
253    }
254
255    /// Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating.
256    ///
257    /// In general it only makes sense to call this function after the
258    /// [`area-prepared`][struct@crate::PixbufLoader#area-prepared] signal has been emitted by
259    /// the loader.
260    ///
261    /// If the loader doesn't have enough bytes yet, and hasn't emitted the `area-prepared`
262    /// signal, this function will return `NULL`.
263    ///
264    /// # Returns
265    ///
266    /// The animation that the loader is
267    ///   currently loading
268    #[doc(alias = "gdk_pixbuf_loader_get_animation")]
269    #[doc(alias = "get_animation")]
270    fn animation(&self) -> Option<PixbufAnimation> {
271        unsafe {
272            from_glib_none(ffi::gdk_pixbuf_loader_get_animation(
273                self.as_ref().to_glib_none().0,
274            ))
275        }
276    }
277
278    /// Obtains the available information about the format of the
279    /// currently loading image file.
280    ///
281    /// # Returns
282    ///
283    /// A #GdkPixbufFormat
284    #[doc(alias = "gdk_pixbuf_loader_get_format")]
285    #[doc(alias = "get_format")]
286    fn format(&self) -> Option<PixbufFormat> {
287        unsafe {
288            from_glib_none(ffi::gdk_pixbuf_loader_get_format(
289                self.as_ref().to_glib_none().0,
290            ))
291        }
292    }
293
294    /// Queries the #GdkPixbuf that a pixbuf loader is currently creating.
295    ///
296    /// In general it only makes sense to call this function after the
297    /// [`area-prepared`][struct@crate::PixbufLoader#area-prepared] signal has been
298    /// emitted by the loader; this means that enough data has been read
299    /// to know the size of the image that will be allocated.
300    ///
301    /// If the loader has not received enough data via gdk_pixbuf_loader_write(),
302    /// then this function returns `NULL`.
303    ///
304    /// The returned pixbuf will be the same in all future calls to the loader,
305    /// so if you want to keep using it, you should acquire a reference to it.
306    ///
307    /// Additionally, if the loader is an animation, it will return the "static
308    /// image" of the animation (see gdk_pixbuf_animation_get_static_image()).
309    ///
310    /// # Returns
311    ///
312    /// The pixbuf that the loader is
313    ///   creating
314    #[doc(alias = "gdk_pixbuf_loader_get_pixbuf")]
315    #[doc(alias = "get_pixbuf")]
316    fn pixbuf(&self) -> Option<Pixbuf> {
317        unsafe {
318            from_glib_none(ffi::gdk_pixbuf_loader_get_pixbuf(
319                self.as_ref().to_glib_none().0,
320            ))
321        }
322    }
323
324    /// Causes the image to be scaled while it is loaded.
325    ///
326    /// The desired image size can be determined relative to the original
327    /// size of the image by calling gdk_pixbuf_loader_set_size() from a
328    /// signal handler for the ::size-prepared signal.
329    ///
330    /// Attempts to set the desired image size  are ignored after the
331    /// emission of the ::size-prepared signal.
332    /// ## `width`
333    /// The desired width of the image being loaded.
334    /// ## `height`
335    /// The desired height of the image being loaded.
336    #[doc(alias = "gdk_pixbuf_loader_set_size")]
337    fn set_size(&self, width: i32, height: i32) {
338        unsafe {
339            ffi::gdk_pixbuf_loader_set_size(self.as_ref().to_glib_none().0, width, height);
340        }
341    }
342
343    /// Parses the next `count` bytes in the given image buffer.
344    /// ## `buf`
345    /// Pointer to image data.
346    ///
347    /// # Returns
348    ///
349    /// `TRUE` if the write was successful, or
350    ///   `FALSE` if the loader cannot parse the buffer
351    #[doc(alias = "gdk_pixbuf_loader_write")]
352    fn write(&self, buf: &[u8]) -> Result<(), glib::Error> {
353        let count = buf.len() as _;
354        unsafe {
355            let mut error = std::ptr::null_mut();
356            let is_ok = ffi::gdk_pixbuf_loader_write(
357                self.as_ref().to_glib_none().0,
358                buf.to_glib_none().0,
359                count,
360                &mut error,
361            );
362            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
363            if error.is_null() {
364                Ok(())
365            } else {
366                Err(from_glib_full(error))
367            }
368        }
369    }
370
371    /// Parses the next contents of the given image buffer.
372    /// ## `buffer`
373    /// The image data as a `GBytes` buffer.
374    ///
375    /// # Returns
376    ///
377    /// `TRUE` if the write was successful, or `FALSE` if
378    ///   the loader cannot parse the buffer
379    #[doc(alias = "gdk_pixbuf_loader_write_bytes")]
380    fn write_bytes(&self, buffer: &glib::Bytes) -> Result<(), glib::Error> {
381        unsafe {
382            let mut error = std::ptr::null_mut();
383            let is_ok = ffi::gdk_pixbuf_loader_write_bytes(
384                self.as_ref().to_glib_none().0,
385                buffer.to_glib_none().0,
386                &mut error,
387            );
388            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
389            if error.is_null() {
390                Ok(())
391            } else {
392                Err(from_glib_full(error))
393            }
394        }
395    }
396
397    /// This signal is emitted when the pixbuf loader has allocated the
398    /// pixbuf in the desired size.
399    ///
400    /// After this signal is emitted, applications can call
401    /// gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded
402    /// pixbuf.
403    #[doc(alias = "area-prepared")]
404    fn connect_area_prepared<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
405        unsafe extern "C" fn area_prepared_trampoline<P: IsA<PixbufLoader>, F: Fn(&P) + 'static>(
406            this: *mut ffi::GdkPixbufLoader,
407            f: glib::ffi::gpointer,
408        ) {
409            let f: &F = &*(f as *const F);
410            f(PixbufLoader::from_glib_borrow(this).unsafe_cast_ref())
411        }
412        unsafe {
413            let f: Box_<F> = Box_::new(f);
414            connect_raw(
415                self.as_ptr() as *mut _,
416                b"area-prepared\0".as_ptr() as *const _,
417                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
418                    area_prepared_trampoline::<Self, F> as *const (),
419                )),
420                Box_::into_raw(f),
421            )
422        }
423    }
424
425    /// This signal is emitted when a significant area of the image being
426    /// loaded has been updated.
427    ///
428    /// Normally it means that a complete scanline has been read in, but
429    /// it could be a different area as well.
430    ///
431    /// Applications can use this signal to know when to repaint
432    /// areas of an image that is being loaded.
433    /// ## `x`
434    /// X offset of upper-left corner of the updated area.
435    /// ## `y`
436    /// Y offset of upper-left corner of the updated area.
437    /// ## `width`
438    /// Width of updated area.
439    /// ## `height`
440    /// Height of updated area.
441    #[doc(alias = "area-updated")]
442    fn connect_area_updated<F: Fn(&Self, i32, i32, i32, i32) + 'static>(
443        &self,
444        f: F,
445    ) -> SignalHandlerId {
446        unsafe extern "C" fn area_updated_trampoline<
447            P: IsA<PixbufLoader>,
448            F: Fn(&P, i32, i32, i32, i32) + 'static,
449        >(
450            this: *mut ffi::GdkPixbufLoader,
451            x: std::ffi::c_int,
452            y: std::ffi::c_int,
453            width: std::ffi::c_int,
454            height: std::ffi::c_int,
455            f: glib::ffi::gpointer,
456        ) {
457            let f: &F = &*(f as *const F);
458            f(
459                PixbufLoader::from_glib_borrow(this).unsafe_cast_ref(),
460                x,
461                y,
462                width,
463                height,
464            )
465        }
466        unsafe {
467            let f: Box_<F> = Box_::new(f);
468            connect_raw(
469                self.as_ptr() as *mut _,
470                b"area-updated\0".as_ptr() as *const _,
471                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
472                    area_updated_trampoline::<Self, F> as *const (),
473                )),
474                Box_::into_raw(f),
475            )
476        }
477    }
478
479    /// This signal is emitted when gdk_pixbuf_loader_close() is called.
480    ///
481    /// It can be used by different parts of an application to receive
482    /// notification when an image loader is closed by the code that
483    /// drives it.
484    #[doc(alias = "closed")]
485    fn connect_closed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
486        unsafe extern "C" fn closed_trampoline<P: IsA<PixbufLoader>, F: Fn(&P) + 'static>(
487            this: *mut ffi::GdkPixbufLoader,
488            f: glib::ffi::gpointer,
489        ) {
490            let f: &F = &*(f as *const F);
491            f(PixbufLoader::from_glib_borrow(this).unsafe_cast_ref())
492        }
493        unsafe {
494            let f: Box_<F> = Box_::new(f);
495            connect_raw(
496                self.as_ptr() as *mut _,
497                b"closed\0".as_ptr() as *const _,
498                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
499                    closed_trampoline::<Self, F> as *const (),
500                )),
501                Box_::into_raw(f),
502            )
503        }
504    }
505
506    /// This signal is emitted when the pixbuf loader has been fed the
507    /// initial amount of data that is required to figure out the size
508    /// of the image that it will create.
509    ///
510    /// Applications can call gdk_pixbuf_loader_set_size() in response
511    /// to this signal to set the desired size to which the image
512    /// should be scaled.
513    /// ## `width`
514    /// the original width of the image
515    /// ## `height`
516    /// the original height of the image
517    #[doc(alias = "size-prepared")]
518    fn connect_size_prepared<F: Fn(&Self, i32, i32) + 'static>(&self, f: F) -> SignalHandlerId {
519        unsafe extern "C" fn size_prepared_trampoline<
520            P: IsA<PixbufLoader>,
521            F: Fn(&P, i32, i32) + 'static,
522        >(
523            this: *mut ffi::GdkPixbufLoader,
524            width: std::ffi::c_int,
525            height: std::ffi::c_int,
526            f: glib::ffi::gpointer,
527        ) {
528            let f: &F = &*(f as *const F);
529            f(
530                PixbufLoader::from_glib_borrow(this).unsafe_cast_ref(),
531                width,
532                height,
533            )
534        }
535        unsafe {
536            let f: Box_<F> = Box_::new(f);
537            connect_raw(
538                self.as_ptr() as *mut _,
539                b"size-prepared\0".as_ptr() as *const _,
540                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
541                    size_prepared_trampoline::<Self, F> as *const (),
542                )),
543                Box_::into_raw(f),
544            )
545        }
546    }
547}
548
549impl<O: IsA<PixbufLoader>> PixbufLoaderExt for O {}