gdk/auto/

frame_clock.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{FrameClockPhase, FrameTimings};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::{boxed::Box as Box_, fmt, mem::transmute};

glib::wrapper! {
    /// A [`FrameClock`][crate::FrameClock] tells the application when to update and repaint a
    /// window. This may be synced to the vertical refresh rate of the
    /// monitor, for example. Even when the frame clock uses a simple timer
    /// rather than a hardware-based vertical sync, the frame clock helps
    /// because it ensures everything paints at the same time (reducing the
    /// total number of frames). The frame clock can also automatically
    /// stop painting when it knows the frames will not be visible, or
    /// scale back animation framerates.
    ///
    /// [`FrameClock`][crate::FrameClock] is designed to be compatible with an OpenGL-based
    /// implementation or with mozRequestAnimationFrame in Firefox,
    /// for example.
    ///
    /// A frame clock is idle until someone requests a frame with
    /// [`request_phase()`][Self::request_phase()]. At some later point that makes
    /// sense for the synchronization being implemented, the clock will
    /// process a frame and emit signals for each phase that has been
    /// requested. (See the signals of the [`FrameClock`][crate::FrameClock] class for
    /// documentation of the phases. [`FrameClockPhase::UPDATE`][crate::FrameClockPhase::UPDATE] and the
    /// [`update`][struct@crate::FrameClock#update] signal are most interesting for application
    /// writers, and are used to update the animations, using the frame time
    /// given by [`frame_time()`][Self::frame_time()].
    ///
    /// The frame time is reported in microseconds and generally in the same
    /// timescale as `g_get_monotonic_time()`, however, it is not the same
    /// as `g_get_monotonic_time()`. The frame time does not advance during
    /// the time a frame is being painted, and outside of a frame, an attempt
    /// is made so that all calls to [`frame_time()`][Self::frame_time()] that
    /// are called at a “similar” time get the same value. This means that
    /// if different animations are timed by looking at the difference in
    /// time between an initial value from [`frame_time()`][Self::frame_time()]
    /// and the value inside the [`update`][struct@crate::FrameClock#update] signal of the clock,
    /// they will stay exactly synchronized.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Signals
    ///
    ///
    /// #### `after-paint`
    ///  This signal ends processing of the frame. Applications
    /// should generally not handle this signal.
    ///
    ///
    ///
    ///
    /// #### `before-paint`
    ///  This signal begins processing of the frame. Applications
    /// should generally not handle this signal.
    ///
    ///
    ///
    ///
    /// #### `flush-events`
    ///  This signal is used to flush pending motion events that
    /// are being batched up and compressed together. Applications
    /// should not handle this signal.
    ///
    ///
    ///
    ///
    /// #### `layout`
    ///  This signal is emitted as the second step of toolkit and
    /// application processing of the frame. Any work to update
    /// sizes and positions of application elements should be
    /// performed. GTK+ normally handles this internally.
    ///
    ///
    ///
    ///
    /// #### `paint`
    ///  This signal is emitted as the third step of toolkit and
    /// application processing of the frame. The frame is
    /// repainted. GDK normally handles this internally and
    /// produces expose events, which are turned into GTK+
    /// `GtkWidget::draw` signals.
    ///
    ///
    ///
    ///
    /// #### `resume-events`
    ///  This signal is emitted after processing of the frame is
    /// finished, and is handled internally by GTK+ to resume normal
    /// event processing. Applications should not handle this signal.
    ///
    ///
    ///
    ///
    /// #### `update`
    ///  This signal is emitted as the first step of toolkit and
    /// application processing of the frame. Animations should
    /// be updated using [`FrameClock::frame_time()`][crate::FrameClock::frame_time()].
    /// Applications can connect directly to this signal, or
    /// use `gtk_widget_add_tick_callback()` as a more convenient
    /// interface.
    ///
    ///
    #[doc(alias = "GdkFrameClock")]
    pub struct FrameClock(Object<ffi::GdkFrameClock, ffi::GdkFrameClockClass>);

    match fn {
        type_ => || ffi::gdk_frame_clock_get_type(),
    }
}

impl FrameClock {
    /// Starts updates for an animation. Until a matching call to
    /// [`end_updating()`][Self::end_updating()] is made, the frame clock will continually
    /// request a new frame with the [`FrameClockPhase::UPDATE`][crate::FrameClockPhase::UPDATE] phase.
    /// This function may be called multiple times and frames will be
    /// requested until [`end_updating()`][Self::end_updating()] is called the same
    /// number of times.
    #[doc(alias = "gdk_frame_clock_begin_updating")]
    pub fn begin_updating(&self) {
        unsafe {
            ffi::gdk_frame_clock_begin_updating(self.to_glib_none().0);
        }
    }

    /// Stops updates for an animation. See the documentation for
    /// [`begin_updating()`][Self::begin_updating()].
    #[doc(alias = "gdk_frame_clock_end_updating")]
    pub fn end_updating(&self) {
        unsafe {
            ffi::gdk_frame_clock_end_updating(self.to_glib_none().0);
        }
    }

    /// Gets the frame timings for the current frame.
    ///
    /// # Returns
    ///
    /// the [`FrameTimings`][crate::FrameTimings] for the
    ///  frame currently being processed, or even no frame is being
    ///  processed, for the previous frame. Before any frames have been
    ///  processed, returns [`None`].
    #[doc(alias = "gdk_frame_clock_get_current_timings")]
    #[doc(alias = "get_current_timings")]
    pub fn current_timings(&self) -> Option<FrameTimings> {
        unsafe {
            from_glib_none(ffi::gdk_frame_clock_get_current_timings(
                self.to_glib_none().0,
            ))
        }
    }

    /// A [`FrameClock`][crate::FrameClock] maintains a 64-bit counter that increments for
    /// each frame drawn.
    ///
    /// # Returns
    ///
    /// inside frame processing, the value of the frame counter
    ///  for the current frame. Outside of frame processing, the frame
    ///  counter for the last frame.
    #[doc(alias = "gdk_frame_clock_get_frame_counter")]
    #[doc(alias = "get_frame_counter")]
    pub fn frame_counter(&self) -> i64 {
        unsafe { ffi::gdk_frame_clock_get_frame_counter(self.to_glib_none().0) }
    }

    /// Gets the time that should currently be used for animations. Inside
    /// the processing of a frame, it’s the time used to compute the
    /// animation position of everything in a frame. Outside of a frame, it's
    /// the time of the conceptual “previous frame,” which may be either
    /// the actual previous frame time, or if that’s too old, an updated
    /// time.
    ///
    /// # Returns
    ///
    /// a timestamp in microseconds, in the timescale of
    ///  of `g_get_monotonic_time()`.
    #[doc(alias = "gdk_frame_clock_get_frame_time")]
    #[doc(alias = "get_frame_time")]
    pub fn frame_time(&self) -> i64 {
        unsafe { ffi::gdk_frame_clock_get_frame_time(self.to_glib_none().0) }
    }

    /// [`FrameClock`][crate::FrameClock] internally keeps a history of [`FrameTimings`][crate::FrameTimings]
    /// objects for recent frames that can be retrieved with
    /// [`timings()`][Self::timings()]. The set of stored frames
    /// is the set from the counter values given by
    /// [`history_start()`][Self::history_start()] and
    /// [`frame_counter()`][Self::frame_counter()], inclusive.
    ///
    /// # Returns
    ///
    /// the frame counter value for the oldest frame
    ///  that is available in the internal frame history of the
    ///  [`FrameClock`][crate::FrameClock].
    #[doc(alias = "gdk_frame_clock_get_history_start")]
    #[doc(alias = "get_history_start")]
    pub fn history_start(&self) -> i64 {
        unsafe { ffi::gdk_frame_clock_get_history_start(self.to_glib_none().0) }
    }

    /// Retrieves a [`FrameTimings`][crate::FrameTimings] object holding timing information
    /// for the current frame or a recent frame. The [`FrameTimings`][crate::FrameTimings]
    /// object may not yet be complete: see [`FrameTimings::is_complete()`][crate::FrameTimings::is_complete()].
    /// ## `frame_counter`
    /// the frame counter value identifying the frame to
    ///  be received.
    ///
    /// # Returns
    ///
    /// the [`FrameTimings`][crate::FrameTimings] object for
    ///  the specified frame, or [`None`] if it is not available. See
    ///  [`history_start()`][Self::history_start()].
    #[doc(alias = "gdk_frame_clock_get_timings")]
    #[doc(alias = "get_timings")]
    pub fn timings(&self, frame_counter: i64) -> Option<FrameTimings> {
        unsafe {
            from_glib_none(ffi::gdk_frame_clock_get_timings(
                self.to_glib_none().0,
                frame_counter,
            ))
        }
    }

    /// Asks the frame clock to run a particular phase. The signal
    /// corresponding the requested phase will be emitted the next
    /// time the frame clock processes. Multiple calls to
    /// [`request_phase()`][Self::request_phase()] will be combined together
    /// and only one frame processed. If you are displaying animated
    /// content and want to continually request the
    /// [`FrameClockPhase::UPDATE`][crate::FrameClockPhase::UPDATE] phase for a period of time,
    /// you should use [`begin_updating()`][Self::begin_updating()] instead, since
    /// this allows GTK+ to adjust system parameters to get maximally
    /// smooth animations.
    /// ## `phase`
    /// the phase that is requested
    #[doc(alias = "gdk_frame_clock_request_phase")]
    pub fn request_phase(&self, phase: FrameClockPhase) {
        unsafe {
            ffi::gdk_frame_clock_request_phase(self.to_glib_none().0, phase.into_glib());
        }
    }

    /// This signal ends processing of the frame. Applications
    /// should generally not handle this signal.
    #[doc(alias = "after-paint")]
    pub fn connect_after_paint<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn after_paint_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"after-paint\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    after_paint_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal begins processing of the frame. Applications
    /// should generally not handle this signal.
    #[doc(alias = "before-paint")]
    pub fn connect_before_paint<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn before_paint_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"before-paint\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    before_paint_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal is used to flush pending motion events that
    /// are being batched up and compressed together. Applications
    /// should not handle this signal.
    #[doc(alias = "flush-events")]
    pub fn connect_flush_events<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn flush_events_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"flush-events\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    flush_events_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal is emitted as the second step of toolkit and
    /// application processing of the frame. Any work to update
    /// sizes and positions of application elements should be
    /// performed. GTK+ normally handles this internally.
    #[doc(alias = "layout")]
    pub fn connect_layout<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn layout_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"layout\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    layout_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal is emitted as the third step of toolkit and
    /// application processing of the frame. The frame is
    /// repainted. GDK normally handles this internally and
    /// produces expose events, which are turned into GTK+
    /// `GtkWidget::draw` signals.
    #[doc(alias = "paint")]
    pub fn connect_paint<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn paint_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"paint\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    paint_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal is emitted after processing of the frame is
    /// finished, and is handled internally by GTK+ to resume normal
    /// event processing. Applications should not handle this signal.
    #[doc(alias = "resume-events")]
    pub fn connect_resume_events<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn resume_events_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"resume-events\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    resume_events_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// This signal is emitted as the first step of toolkit and
    /// application processing of the frame. Animations should
    /// be updated using [`frame_time()`][Self::frame_time()].
    /// Applications can connect directly to this signal, or
    /// use `gtk_widget_add_tick_callback()` as a more convenient
    /// interface.
    #[doc(alias = "update")]
    pub fn connect_update<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn update_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"update\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    update_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl fmt::Display for FrameClock {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("FrameClock")
    }
}