gdk4/auto/

draw_context.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
#![allow(deprecated)]

use crate::{ffi, Display, Surface};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// Base class for objects implementing different rendering methods.
    ///
    /// [`DrawContext`][crate::DrawContext] is the base object used by contexts implementing different
    /// rendering methods, such as [`CairoContext`][crate::CairoContext] or [`GLContext`][crate::GLContext].
    /// It provides shared functionality between those contexts.
    ///
    /// You will always interact with one of those subclasses.
    ///
    /// A [`DrawContext`][crate::DrawContext] is always associated with a single toplevel surface.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `display`
    ///  The [`Display`][crate::Display] used to create the [`DrawContext`][crate::DrawContext].
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `surface`
    ///  The [`Surface`][crate::Surface] the context is bound to.
    ///
    /// Readable | Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`DrawContextExt`][trait@crate::prelude::DrawContextExt], [`DrawContextExtManual`][trait@crate::prelude::DrawContextExtManual]
    #[doc(alias = "GdkDrawContext")]
    pub struct DrawContext(Object<ffi::GdkDrawContext>);

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

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

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::DrawContext>> Sealed for T {}
}

/// Trait containing all [`struct@DrawContext`] methods.
///
/// # Implementors
///
/// [`CairoContext`][struct@crate::CairoContext], [`DrawContext`][struct@crate::DrawContext], [`GLContext`][struct@crate::GLContext], [`VulkanContext`][struct@crate::VulkanContext]
pub trait DrawContextExt: IsA<DrawContext> + sealed::Sealed + 'static {
    /// Indicates that you are beginning the process of redrawing @region
    /// on the @self's surface.
    ///
    /// Calling this function begins a drawing operation using @self on the
    /// surface that @self was created from. The actual requirements and
    /// guarantees for the drawing operation vary for different implementations
    /// of drawing, so a [`CairoContext`][crate::CairoContext] and a [`GLContext`][crate::GLContext]
    /// need to be treated differently.
    ///
    /// A call to this function is a requirement for drawing and must be
    /// followed by a call to [`end_frame()`][Self::end_frame()], which will
    /// complete the drawing operation and ensure the contents become visible
    /// on screen.
    ///
    /// Note that the @region passed to this function is the minimum region that
    /// needs to be drawn and depending on implementation, windowing system and
    /// hardware in use, it might be necessary to draw a larger region. Drawing
    /// implementation must use [`DrawContextExtManual::frame_region()`][crate::prelude::DrawContextExtManual::frame_region()] to
    /// query the region that must be drawn.
    ///
    /// When using GTK, the widget system automatically places calls to
    /// gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the
    /// use of [GskRenderer](../gsk4/class.Renderer.html)s, so application code
    /// does not need to call these functions explicitly.
    ///
    /// # Deprecated since 4.16
    ///
    /// Drawing directly to the surface is no longer recommended.
    ///   Use `GskRenderNode` and `GskRenderer`.
    /// ## `region`
    /// minimum region that should be drawn
    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
    #[allow(deprecated)]
    #[doc(alias = "gdk_draw_context_begin_frame")]
    fn begin_frame(&self, region: &cairo::Region) {
        unsafe {
            ffi::gdk_draw_context_begin_frame(
                self.as_ref().to_glib_none().0,
                region.to_glib_none().0,
            );
        }
    }

    /// Ends a drawing operation started with gdk_draw_context_begin_frame().
    ///
    /// This makes the drawing available on screen.
    /// See [`begin_frame()`][Self::begin_frame()] for more details about drawing.
    ///
    /// When using a [`GLContext`][crate::GLContext], this function may call `glFlush()`
    /// implicitly before returning; it is not recommended to call `glFlush()`
    /// explicitly before calling this function.
    ///
    /// # Deprecated since 4.16
    ///
    /// Drawing directly to the surface is no longer recommended.
    ///   Use `GskRenderNode` and `GskRenderer`.
    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
    #[allow(deprecated)]
    #[doc(alias = "gdk_draw_context_end_frame")]
    fn end_frame(&self) {
        unsafe {
            ffi::gdk_draw_context_end_frame(self.as_ref().to_glib_none().0);
        }
    }

    /// Retrieves the [`Display`][crate::Display] the @self is created for
    ///
    /// # Returns
    ///
    /// the [`Display`][crate::Display]
    #[doc(alias = "gdk_draw_context_get_display")]
    #[doc(alias = "get_display")]
    fn display(&self) -> Option<Display> {
        unsafe {
            from_glib_none(ffi::gdk_draw_context_get_display(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Retrieves the surface that @self is bound to.
    ///
    /// # Returns
    ///
    /// a [`Surface`][crate::Surface]
    #[doc(alias = "gdk_draw_context_get_surface")]
    #[doc(alias = "get_surface")]
    fn surface(&self) -> Option<Surface> {
        unsafe {
            from_glib_none(ffi::gdk_draw_context_get_surface(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Returns [`true`] if @self is in the process of drawing to its surface.
    ///
    /// This is the case between calls to [`begin_frame()`][Self::begin_frame()]
    /// and [`end_frame()`][Self::end_frame()]. In this situation, drawing commands
    /// may be effecting the contents of the @self's surface.
    ///
    /// # Deprecated since 4.16
    ///
    /// Drawing directly to the surface is no longer recommended.
    ///   Use `GskRenderNode` and `GskRenderer`.
    ///
    /// # Returns
    ///
    /// [`true`] if the context is between [`begin_frame()`][Self::begin_frame()]
    ///   and [`end_frame()`][Self::end_frame()] calls.
    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
    #[allow(deprecated)]
    #[doc(alias = "gdk_draw_context_is_in_frame")]
    fn is_in_frame(&self) -> bool {
        unsafe {
            from_glib(ffi::gdk_draw_context_is_in_frame(
                self.as_ref().to_glib_none().0,
            ))
        }
    }
}

impl<O: IsA<DrawContext>> DrawContextExt for O {}