gdk4/auto/
draw_context.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4#![allow(deprecated)]
5
6use crate::{ffi, Display, Surface};
7use glib::{prelude::*, translate::*};
8
9glib::wrapper! {
10    /// Base class for objects implementing different rendering methods.
11    ///
12    /// [`DrawContext`][crate::DrawContext] is the base object used by contexts implementing different
13    /// rendering methods, such as [`CairoContext`][crate::CairoContext] or [`GLContext`][crate::GLContext].
14    /// It provides shared functionality between those contexts.
15    ///
16    /// You will always interact with one of those subclasses.
17    ///
18    /// A [`DrawContext`][crate::DrawContext] is always associated with a single toplevel surface.
19    ///
20    /// This is an Abstract Base Class, you cannot instantiate it.
21    ///
22    /// ## Properties
23    ///
24    ///
25    /// #### `display`
26    ///  The [`Display`][crate::Display] used to create the [`DrawContext`][crate::DrawContext].
27    ///
28    /// Readable | Writeable | Construct Only
29    ///
30    ///
31    /// #### `surface`
32    ///  The [`Surface`][crate::Surface] the context is bound to.
33    ///
34    /// Readable | Writeable | Construct Only
35    ///
36    /// # Implements
37    ///
38    /// [`DrawContextExt`][trait@crate::prelude::DrawContextExt], [`DrawContextExtManual`][trait@crate::prelude::DrawContextExtManual]
39    #[doc(alias = "GdkDrawContext")]
40    pub struct DrawContext(Object<ffi::GdkDrawContext>);
41
42    match fn {
43        type_ => || ffi::gdk_draw_context_get_type(),
44    }
45}
46
47impl DrawContext {
48    pub const NONE: Option<&'static DrawContext> = None;
49}
50
51mod sealed {
52    pub trait Sealed {}
53    impl<T: super::IsA<super::DrawContext>> Sealed for T {}
54}
55
56/// Trait containing all [`struct@DrawContext`] methods.
57///
58/// # Implementors
59///
60/// [`CairoContext`][struct@crate::CairoContext], [`DrawContext`][struct@crate::DrawContext], [`GLContext`][struct@crate::GLContext], [`VulkanContext`][struct@crate::VulkanContext]
61pub trait DrawContextExt: IsA<DrawContext> + sealed::Sealed + 'static {
62    /// Indicates that you are beginning the process of redrawing @region
63    /// on the @self's surface.
64    ///
65    /// Calling this function begins a drawing operation using @self on the
66    /// surface that @self was created from. The actual requirements and
67    /// guarantees for the drawing operation vary for different implementations
68    /// of drawing, so a [`CairoContext`][crate::CairoContext] and a [`GLContext`][crate::GLContext]
69    /// need to be treated differently.
70    ///
71    /// A call to this function is a requirement for drawing and must be
72    /// followed by a call to [`end_frame()`][Self::end_frame()], which will
73    /// complete the drawing operation and ensure the contents become visible
74    /// on screen.
75    ///
76    /// Note that the @region passed to this function is the minimum region that
77    /// needs to be drawn and depending on implementation, windowing system and
78    /// hardware in use, it might be necessary to draw a larger region. Drawing
79    /// implementation must use [`DrawContextExtManual::frame_region()`][crate::prelude::DrawContextExtManual::frame_region()] to
80    /// query the region that must be drawn.
81    ///
82    /// When using GTK, the widget system automatically places calls to
83    /// gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the
84    /// use of [GskRenderer](../gsk4/class.Renderer.html)s, so application code
85    /// does not need to call these functions explicitly.
86    ///
87    /// # Deprecated since 4.16
88    ///
89    /// Drawing directly to the surface is no longer recommended.
90    ///   Use `GskRenderNode` and `GskRenderer`.
91    /// ## `region`
92    /// minimum region that should be drawn
93    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
94    #[allow(deprecated)]
95    #[doc(alias = "gdk_draw_context_begin_frame")]
96    fn begin_frame(&self, region: &cairo::Region) {
97        unsafe {
98            ffi::gdk_draw_context_begin_frame(
99                self.as_ref().to_glib_none().0,
100                region.to_glib_none().0,
101            );
102        }
103    }
104
105    /// Ends a drawing operation started with gdk_draw_context_begin_frame().
106    ///
107    /// This makes the drawing available on screen.
108    /// See [`begin_frame()`][Self::begin_frame()] for more details about drawing.
109    ///
110    /// When using a [`GLContext`][crate::GLContext], this function may call `glFlush()`
111    /// implicitly before returning; it is not recommended to call `glFlush()`
112    /// explicitly before calling this function.
113    ///
114    /// # Deprecated since 4.16
115    ///
116    /// Drawing directly to the surface is no longer recommended.
117    ///   Use `GskRenderNode` and `GskRenderer`.
118    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
119    #[allow(deprecated)]
120    #[doc(alias = "gdk_draw_context_end_frame")]
121    fn end_frame(&self) {
122        unsafe {
123            ffi::gdk_draw_context_end_frame(self.as_ref().to_glib_none().0);
124        }
125    }
126
127    /// Retrieves the [`Display`][crate::Display] the @self is created for
128    ///
129    /// # Returns
130    ///
131    /// the [`Display`][crate::Display]
132    #[doc(alias = "gdk_draw_context_get_display")]
133    #[doc(alias = "get_display")]
134    fn display(&self) -> Option<Display> {
135        unsafe {
136            from_glib_none(ffi::gdk_draw_context_get_display(
137                self.as_ref().to_glib_none().0,
138            ))
139        }
140    }
141
142    /// Retrieves the surface that @self is bound to.
143    ///
144    /// # Returns
145    ///
146    /// a [`Surface`][crate::Surface]
147    #[doc(alias = "gdk_draw_context_get_surface")]
148    #[doc(alias = "get_surface")]
149    fn surface(&self) -> Option<Surface> {
150        unsafe {
151            from_glib_none(ffi::gdk_draw_context_get_surface(
152                self.as_ref().to_glib_none().0,
153            ))
154        }
155    }
156
157    /// Returns [`true`] if @self is in the process of drawing to its surface.
158    ///
159    /// This is the case between calls to [`begin_frame()`][Self::begin_frame()]
160    /// and [`end_frame()`][Self::end_frame()]. In this situation, drawing commands
161    /// may be effecting the contents of the @self's surface.
162    ///
163    /// # Deprecated since 4.16
164    ///
165    /// Drawing directly to the surface is no longer recommended.
166    ///   Use `GskRenderNode` and `GskRenderer`.
167    ///
168    /// # Returns
169    ///
170    /// [`true`] if the context is between [`begin_frame()`][Self::begin_frame()]
171    ///   and [`end_frame()`][Self::end_frame()] calls.
172    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
173    #[allow(deprecated)]
174    #[doc(alias = "gdk_draw_context_is_in_frame")]
175    fn is_in_frame(&self) -> bool {
176        unsafe {
177            from_glib(ffi::gdk_draw_context_is_in_frame(
178                self.as_ref().to_glib_none().0,
179            ))
180        }
181    }
182}
183
184impl<O: IsA<DrawContext>> DrawContextExt for O {}