gdk_pixbuf/pixbuf_animation.rs
1// Take a look at the license at the top of the repository in the LICENSE file.
2
3use std::{ptr, time::SystemTime};
4
5use glib::{prelude::*, translate::*};
6
7use crate::{ffi, PixbufAnimation, PixbufAnimationIter};
8
9mod sealed {
10 pub trait Sealed {}
11 impl<T: super::IsA<super::PixbufAnimation>> Sealed for T {}
12}
13
14pub trait PixbufAnimationExtManual: sealed::Sealed + IsA<PixbufAnimation> + 'static {
15 /// Get an iterator for displaying an animation.
16 ///
17 /// The iterator provides the frames that should be displayed at a
18 /// given time.
19 ///
20 /// @start_time would normally come from g_get_current_time(), and marks
21 /// the beginning of animation playback. After creating an iterator, you
22 /// should immediately display the pixbuf returned by
23 /// gdk_pixbuf_animation_iter_get_pixbuf(). Then, you should install
24 /// a timeout (with g_timeout_add()) or by some other mechanism ensure
25 /// that you'll update the image after
26 /// gdk_pixbuf_animation_iter_get_delay_time() milliseconds. Each time
27 /// the image is updated, you should reinstall the timeout with the new,
28 /// possibly-changed delay time.
29 ///
30 /// As a shortcut, if @start_time is `NULL`, the result of
31 /// g_get_current_time() will be used automatically.
32 ///
33 /// To update the image (i.e. possibly change the result of
34 /// gdk_pixbuf_animation_iter_get_pixbuf() to a new frame of the animation),
35 /// call gdk_pixbuf_animation_iter_advance().
36 ///
37 /// If you're using #GdkPixbufLoader, in addition to updating the image
38 /// after the delay time, you should also update it whenever you
39 /// receive the area_updated signal and
40 /// gdk_pixbuf_animation_iter_on_currently_loading_frame() returns
41 /// `TRUE`. In this case, the frame currently being fed into the loader
42 /// has received new data, so needs to be refreshed. The delay time for
43 /// a frame may also be modified after an area_updated signal, for
44 /// example if the delay time for a frame is encoded in the data after
45 /// the frame itself. So your timeout should be reinstalled after any
46 /// area_updated signal.
47 ///
48 /// A delay time of -1 is possible, indicating "infinite".
49 /// ## `start_time`
50 /// time when the animation starts playing
51 ///
52 /// # Returns
53 ///
54 /// an iterator to move over the animation
55 #[doc(alias = "gdk_pixbuf_animation_get_iter")]
56 #[doc(alias = "get_iter")]
57 fn iter(&self, start_time: Option<SystemTime>) -> PixbufAnimationIter {
58 let start_time = start_time.map(|s| {
59 let diff = s
60 .duration_since(SystemTime::UNIX_EPOCH)
61 .expect("failed to convert time");
62 glib::ffi::GTimeVal {
63 tv_sec: diff.as_secs() as _,
64 tv_usec: diff.subsec_micros() as _,
65 }
66 });
67
68 unsafe {
69 from_glib_full(ffi::gdk_pixbuf_animation_get_iter(
70 self.as_ref().to_glib_none().0,
71 start_time
72 .as_ref()
73 .map(|t| t as *const glib::ffi::GTimeVal)
74 .unwrap_or(ptr::null()),
75 ))
76 }
77 }
78}
79
80impl<O: IsA<PixbufAnimation>> PixbufAnimationExtManual for O {}