gdk4/auto/

paintable.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::{ffi, PaintableFlags, Snapshot};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// An interface for content that can be painted.
    ///
    /// The content of a [`Paintable`][crate::Paintable] can be painted anywhere at any size
    /// without requiring any sort of layout. The interface is inspired by
    /// similar concepts elsewhere, such as
    /// [ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html),
    /// [HTML/CSS Paint Sources](https://www.w3.org/TR/css-images-4/#paint-source),
    /// or [SVG Paint Servers](https://www.w3.org/TR/SVG2/pservers.html).
    ///
    /// A [`Paintable`][crate::Paintable] can be snapshot at any time and size using
    /// [`PaintableExt::snapshot()`][crate::prelude::PaintableExt::snapshot()]. How the paintable interprets that size and
    /// if it scales or centers itself into the given rectangle is implementation
    /// defined, though if you are implementing a [`Paintable`][crate::Paintable] and don't know what
    /// to do, it is suggested that you scale your paintable ignoring any potential
    /// aspect ratio.
    ///
    /// The contents that a [`Paintable`][crate::Paintable] produces may depend on the [`Snapshot`][crate::Snapshot]
    /// passed to it. For example, paintables may decide to use more detailed images
    /// on higher resolution screens or when OpenGL is available. A [`Paintable`][crate::Paintable]
    /// will however always produce the same output for the same snapshot.
    ///
    /// A [`Paintable`][crate::Paintable] may change its contents, meaning that it will now produce
    /// a different output with the same snapshot. Once that happens, it will call
    /// [`PaintableExt::invalidate_contents()`][crate::prelude::PaintableExt::invalidate_contents()] which will emit the
    /// [`invalidate-contents`][struct@crate::Paintable#invalidate-contents] signal. If a paintable is known
    /// to never change its contents, it will set the [`PaintableFlags::CONTENTS`][crate::PaintableFlags::CONTENTS]
    /// flag. If a consumer cannot deal with changing contents, it may call
    /// [`PaintableExt::current_image()`][crate::prelude::PaintableExt::current_image()] which will return a static
    /// paintable and use that.
    ///
    /// A paintable can report an intrinsic (or preferred) size or aspect ratio it
    /// wishes to be rendered at, though it doesn't have to. Consumers of the interface
    /// can use this information to layout thepaintable appropriately. Just like the
    /// contents, the size of a paintable can change. A paintable will indicate this
    /// by calling [`PaintableExt::invalidate_size()`][crate::prelude::PaintableExt::invalidate_size()] which will emit the
    /// [`invalidate-size`][struct@crate::Paintable#invalidate-size] signal. And just like for contents,
    /// if a paintable is known to never change its size, it will set the
    /// [`PaintableFlags::SIZE`][crate::PaintableFlags::SIZE] flag.
    ///
    /// Besides API for applications, there are some functions that are only
    /// useful for implementing subclasses and should not be used by applications:
    /// [`PaintableExt::invalidate_contents()`][crate::prelude::PaintableExt::invalidate_contents()],
    /// [`PaintableExt::invalidate_size()`][crate::prelude::PaintableExt::invalidate_size()],
    /// [`new_empty()`][Self::new_empty()].
    ///
    /// ## Signals
    ///
    ///
    /// #### `invalidate-contents`
    ///  Emitted when the contents of the @paintable change.
    ///
    /// Examples for such an event would be videos changing to the next frame or
    /// the icon theme for an icon changing.
    ///
    ///
    ///
    ///
    /// #### `invalidate-size`
    ///  Emitted when the intrinsic size of the @paintable changes.
    ///
    /// This means the values reported by at least one of
    /// [`PaintableExt::intrinsic_width()`][crate::prelude::PaintableExt::intrinsic_width()],
    /// [`PaintableExt::intrinsic_height()`][crate::prelude::PaintableExt::intrinsic_height()] or
    /// [`PaintableExt::intrinsic_aspect_ratio()`][crate::prelude::PaintableExt::intrinsic_aspect_ratio()]
    /// has changed.
    ///
    /// Examples for such an event would be a paintable displaying
    /// the contents of a toplevel surface being resized.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`PaintableExt`][trait@crate::prelude::PaintableExt]
    #[doc(alias = "GdkPaintable")]
    pub struct Paintable(Interface<ffi::GdkPaintable, ffi::GdkPaintableInterface>);

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

impl Paintable {
    pub const NONE: Option<&'static Paintable> = None;

    /// Returns a paintable that has the given intrinsic size and draws nothing.
    ///
    /// This is often useful for implementing the
    /// `vfunc::Gdk::Paintable::get_current_image` virtual function
    /// when the paintable is in an incomplete state (like a
    /// [GtkMediaStream](../gtk4/class.MediaStream.html) before receiving
    /// the first frame).
    /// ## `intrinsic_width`
    /// The intrinsic width to report. Can be 0 for no width.
    /// ## `intrinsic_height`
    /// The intrinsic height to report. Can be 0 for no height.
    ///
    /// # Returns
    ///
    /// a [`Paintable`][crate::Paintable]
    #[doc(alias = "gdk_paintable_new_empty")]
    pub fn new_empty(intrinsic_width: i32, intrinsic_height: i32) -> Paintable {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gdk_paintable_new_empty(
                intrinsic_width,
                intrinsic_height,
            ))
        }
    }
}

/// Trait containing all [`struct@Paintable`] methods.
///
/// # Implementors
///
/// [`DmabufTexture`][struct@crate::DmabufTexture], [`GLTexture`][struct@crate::GLTexture], [`MemoryTexture`][struct@crate::MemoryTexture], [`Paintable`][struct@crate::Paintable], [`Texture`][struct@crate::Texture]
pub trait PaintableExt: IsA<Paintable> + 'static {
    /// Compute a concrete size for the [`Paintable`][crate::Paintable].
    ///
    /// Applies the sizing algorithm outlined in the
    /// [CSS Image spec](https://drafts.csswg.org/css-images-3/#default-sizing)
    /// to the given @self. See that link for more details.
    ///
    /// It is not necessary to call this function when both @specified_width
    /// and @specified_height are known, but it is useful to call this
    /// function in GtkWidget:measure implementations to compute the
    /// other dimension when only one dimension is given.
    /// ## `specified_width`
    /// the width @self could be drawn into or
    ///   0.0 if unknown
    /// ## `specified_height`
    /// the height @self could be drawn into or
    ///   0.0 if unknown
    /// ## `default_width`
    /// the width @self would be drawn into if
    ///   no other constraints were given
    /// ## `default_height`
    /// the height @self would be drawn into if
    ///   no other constraints were given
    ///
    /// # Returns
    ///
    ///
    /// ## `concrete_width`
    /// will be set to the concrete width computed
    ///
    /// ## `concrete_height`
    /// will be set to the concrete height computed
    #[doc(alias = "gdk_paintable_compute_concrete_size")]
    fn compute_concrete_size(
        &self,
        specified_width: f64,
        specified_height: f64,
        default_width: f64,
        default_height: f64,
    ) -> (f64, f64) {
        unsafe {
            let mut concrete_width = std::mem::MaybeUninit::uninit();
            let mut concrete_height = std::mem::MaybeUninit::uninit();
            ffi::gdk_paintable_compute_concrete_size(
                self.as_ref().to_glib_none().0,
                specified_width,
                specified_height,
                default_width,
                default_height,
                concrete_width.as_mut_ptr(),
                concrete_height.as_mut_ptr(),
            );
            (concrete_width.assume_init(), concrete_height.assume_init())
        }
    }

    /// Gets an immutable paintable for the current contents displayed by @self.
    ///
    /// This is useful when you want to retain the current state of an animation,
    /// for example to take a screenshot of a running animation.
    ///
    /// If the @self is already immutable, it will return itself.
    ///
    /// # Returns
    ///
    /// An immutable paintable for the current
    ///   contents of @self
    #[doc(alias = "gdk_paintable_get_current_image")]
    #[doc(alias = "get_current_image")]
    #[must_use]
    fn current_image(&self) -> Paintable {
        unsafe {
            from_glib_full(ffi::gdk_paintable_get_current_image(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Get flags for the paintable.
    ///
    /// This is oftentimes useful for optimizations.
    ///
    /// See [`PaintableFlags`][crate::PaintableFlags] for the flags and what they mean.
    ///
    /// # Returns
    ///
    /// The [`PaintableFlags`][crate::PaintableFlags] for this paintable
    #[doc(alias = "gdk_paintable_get_flags")]
    #[doc(alias = "get_flags")]
    fn flags(&self) -> PaintableFlags {
        unsafe { from_glib(ffi::gdk_paintable_get_flags(self.as_ref().to_glib_none().0)) }
    }

    /// Gets the preferred aspect ratio the @self would like to be displayed at.
    ///
    /// The aspect ratio is the width divided by the height, so a value of 0.5
    /// means that the @self prefers to be displayed twice as high as it
    /// is wide. Consumers of this interface can use this to preserve aspect
    /// ratio when displaying the paintable.
    ///
    /// This is a purely informational value and does not in any way limit the
    /// values that may be passed to [`snapshot()`][Self::snapshot()].
    ///
    /// Usually when a @self returns nonzero values from
    /// [`intrinsic_width()`][Self::intrinsic_width()] and
    /// [`intrinsic_height()`][Self::intrinsic_height()] the aspect ratio
    /// should conform to those values, though that is not required.
    ///
    /// If the @self does not have a preferred aspect ratio,
    /// it returns 0. Negative values are never returned.
    ///
    /// # Returns
    ///
    /// the intrinsic aspect ratio of @self or 0 if none.
    #[doc(alias = "gdk_paintable_get_intrinsic_aspect_ratio")]
    #[doc(alias = "get_intrinsic_aspect_ratio")]
    fn intrinsic_aspect_ratio(&self) -> f64 {
        unsafe { ffi::gdk_paintable_get_intrinsic_aspect_ratio(self.as_ref().to_glib_none().0) }
    }

    /// Gets the preferred height the @self would like to be displayed at.
    ///
    /// Consumers of this interface can use this to reserve enough space to draw
    /// the paintable.
    ///
    /// This is a purely informational value and does not in any way limit the
    /// values that may be passed to [`snapshot()`][Self::snapshot()].
    ///
    /// If the @self does not have a preferred height, it returns 0.
    /// Negative values are never returned.
    ///
    /// # Returns
    ///
    /// the intrinsic height of @self or 0 if none.
    #[doc(alias = "gdk_paintable_get_intrinsic_height")]
    #[doc(alias = "get_intrinsic_height")]
    fn intrinsic_height(&self) -> i32 {
        unsafe { ffi::gdk_paintable_get_intrinsic_height(self.as_ref().to_glib_none().0) }
    }

    /// Gets the preferred width the @self would like to be displayed at.
    ///
    /// Consumers of this interface can use this to reserve enough space to draw
    /// the paintable.
    ///
    /// This is a purely informational value and does not in any way limit the
    /// values that may be passed to [`snapshot()`][Self::snapshot()].
    ///
    /// If the @self does not have a preferred width, it returns 0.
    /// Negative values are never returned.
    ///
    /// # Returns
    ///
    /// the intrinsic width of @self or 0 if none.
    #[doc(alias = "gdk_paintable_get_intrinsic_width")]
    #[doc(alias = "get_intrinsic_width")]
    fn intrinsic_width(&self) -> i32 {
        unsafe { ffi::gdk_paintable_get_intrinsic_width(self.as_ref().to_glib_none().0) }
    }

    /// Called by implementations of [`Paintable`][crate::Paintable] to invalidate their contents.
    ///
    /// Unless the contents are invalidated, implementations must guarantee that
    /// multiple calls of [`snapshot()`][Self::snapshot()] produce the same output.
    ///
    /// This function will emit the [`invalidate-contents`][struct@crate::Paintable#invalidate-contents]
    /// signal.
    ///
    /// If a @self reports the [`PaintableFlags::CONTENTS`][crate::PaintableFlags::CONTENTS] flag,
    /// it must not call this function.
    #[doc(alias = "gdk_paintable_invalidate_contents")]
    fn invalidate_contents(&self) {
        unsafe {
            ffi::gdk_paintable_invalidate_contents(self.as_ref().to_glib_none().0);
        }
    }

    /// Called by implementations of [`Paintable`][crate::Paintable] to invalidate their size.
    ///
    /// As long as the size is not invalidated, @self must return the same
    /// values for its intrinsic width, height and aspect ratio.
    ///
    /// This function will emit the [`invalidate-size`][struct@crate::Paintable#invalidate-size]
    /// signal.
    ///
    /// If a @self reports the [`PaintableFlags::SIZE`][crate::PaintableFlags::SIZE] flag,
    /// it must not call this function.
    #[doc(alias = "gdk_paintable_invalidate_size")]
    fn invalidate_size(&self) {
        unsafe {
            ffi::gdk_paintable_invalidate_size(self.as_ref().to_glib_none().0);
        }
    }

    /// Snapshots the given paintable with the given @width and @height.
    ///
    /// The paintable is drawn at the current (0,0) offset of the @snapshot.
    /// If @width and @height are not larger than zero, this function will
    /// do nothing.
    /// ## `snapshot`
    /// a [`Snapshot`][crate::Snapshot] to snapshot to
    /// ## `width`
    /// width to snapshot in
    /// ## `height`
    /// height to snapshot in
    #[doc(alias = "gdk_paintable_snapshot")]
    fn snapshot(&self, snapshot: &impl IsA<Snapshot>, width: f64, height: f64) {
        unsafe {
            ffi::gdk_paintable_snapshot(
                self.as_ref().to_glib_none().0,
                snapshot.as_ref().to_glib_none().0,
                width,
                height,
            );
        }
    }

    /// Emitted when the contents of the @paintable change.
    ///
    /// Examples for such an event would be videos changing to the next frame or
    /// the icon theme for an icon changing.
    #[doc(alias = "invalidate-contents")]
    fn connect_invalidate_contents<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn invalidate_contents_trampoline<
            P: IsA<Paintable>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GdkPaintable,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Paintable::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"invalidate-contents".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    invalidate_contents_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted when the intrinsic size of the @paintable changes.
    ///
    /// This means the values reported by at least one of
    /// [`intrinsic_width()`][Self::intrinsic_width()],
    /// [`intrinsic_height()`][Self::intrinsic_height()] or
    /// [`intrinsic_aspect_ratio()`][Self::intrinsic_aspect_ratio()]
    /// has changed.
    ///
    /// Examples for such an event would be a paintable displaying
    /// the contents of a toplevel surface being resized.
    #[doc(alias = "invalidate-size")]
    fn connect_invalidate_size<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn invalidate_size_trampoline<P: IsA<Paintable>, F: Fn(&P) + 'static>(
            this: *mut ffi::GdkPaintable,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Paintable::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"invalidate-size".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    invalidate_size_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Paintable>> PaintableExt for O {}