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 {}