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 {}