gtk4/
widget.rs

Help
1// Take a look at the license at the top of the repository in the LICENSE file.
2
3use glib::{translate::*, ControlFlow, WeakRef};
4
5use crate::{ffi, prelude::*, Widget};
6
7// rustdoc-stripper-ignore-next
8/// Trait containing manually implemented methods of [`Widget`](crate::Widget).
9pub trait WidgetExtManual: IsA<Widget> + 'static {
10    /// Queues an animation frame update and adds a callback to be called
11    /// before each frame.
12    ///
13    /// Until the tick callback is removed, it will be called frequently
14    /// (usually at the frame rate of the output device or as quickly as
15    /// the application can be repainted, whichever is slower). For this
16    /// reason, is most suitable for handling graphics that change every
17    /// frame or every few frames.
18    ///
19    /// The tick callback does not automatically imply a relayout or repaint.
20    /// If you want a repaint or relayout, and aren’t changing widget properties
21    /// that would trigger that (for example, changing the text of a label),
22    /// then you will have to call [`WidgetExt::queue_resize()`][crate::prelude::WidgetExt::queue_resize()] or
23    /// [`WidgetExt::queue_draw()`][crate::prelude::WidgetExt::queue_draw()] yourself.
24    ///
25    /// [`FrameClock::frame_time()`][crate::gdk::FrameClock::frame_time()] should generally be used
26    /// for timing continuous animations and
27    /// `Gdk::FrameTimings::get_predicted_presentation_time()` should be
28    /// used if you are trying to display isolated frames at particular times.
29    ///
30    /// This is a more convenient alternative to connecting directly to the
31    /// [`update`][struct@crate::gdk::FrameClock#update] signal of the frame clock, since you
32    /// don't have to worry about when a frame clock is assigned to a widget.
33    ///
34    /// To remove a tick callback, pass the ID that is returned by this function
35    /// to [`WidgetExtManual::remove()`][crate::prelude::WidgetExtManual::remove()].
36    /// ## `callback`
37    /// function
38    ///   to call for updating animations
39    ///
40    /// # Returns
41    ///
42    /// an ID for this callback
43    #[doc(alias = "gtk_widget_add_tick_callback")]
44    fn add_tick_callback<P: Fn(&Self, &gdk::FrameClock) -> ControlFlow + 'static>(
45        &self,
46        callback: P,
47    ) -> TickCallbackId {
48        let callback_data: Box<P> = Box::new(callback);
49
50        unsafe extern "C" fn callback_func<
51            O: IsA<Widget>,
52            P: Fn(&O, &gdk::FrameClock) -> ControlFlow + 'static,
53        >(
54            widget: *mut ffi::GtkWidget,
55            frame_clock: *mut gdk::ffi::GdkFrameClock,
56            user_data: glib::ffi::gpointer,
57        ) -> glib::ffi::gboolean {
58            let widget: Borrowed<Widget> = from_glib_borrow(widget);
59            let frame_clock = from_glib_borrow(frame_clock);
60            let callback: &P = &*(user_data as *mut _);
61            let res = (*callback)(widget.unsafe_cast_ref(), &frame_clock);
62            res.into_glib()
63        }
64        let callback = Some(callback_func::<Self, P> as _);
65
66        unsafe extern "C" fn notify_func<
67            O: IsA<Widget>,
68            P: Fn(&O, &gdk::FrameClock) -> ControlFlow + 'static,
69        >(
70            data: glib::ffi::gpointer,
71        ) {
72            let _callback: Box<P> = Box::from_raw(data as *mut _);
73        }
74        let destroy_call = Some(notify_func::<Self, P> as _);
75
76        let id = unsafe {
77            ffi::gtk_widget_add_tick_callback(
78                self.as_ref().to_glib_none().0,
79                callback,
80                Box::into_raw(callback_data) as *mut _,
81                destroy_call,
82            )
83        };
84        TickCallbackId {
85            id,
86            widget: self.upcast_ref().downgrade(),
87        }
88    }
89}
90
91impl<O: IsA<Widget>> WidgetExtManual for O {}
92
93#[derive(Debug)]
94pub struct TickCallbackId {
95    id: u32,
96    widget: WeakRef<Widget>,
97}
98
99impl PartialEq for TickCallbackId {
100    #[inline]
101    fn eq(&self, other: &Self) -> bool {
102        self.id == other.id
103    }
104}
105
106impl TickCallbackId {
107    /// Removes a tick callback previously registered with
108    /// [`WidgetExtManual::add_tick_callback()`][crate::prelude::WidgetExtManual::add_tick_callback()].
109    /// ## `id`
110    /// an ID returned by [`WidgetExtManual::add_tick_callback()`][crate::prelude::WidgetExtManual::add_tick_callback()]
111    #[doc(alias = "gtk_widget_remove_tick_callback")]
112    #[doc(alias = "remove_tick_callback")]
113    pub fn remove(self) {
114        if let Some(widget) = self.widget.upgrade() {
115            unsafe {
116                ffi::gtk_widget_remove_tick_callback(widget.to_glib_none().0, self.id);
117            }
118        }
119    }
120}
gtk4/widget.rs

gtk4/
widget.rs
