gdk4/auto/cursor.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
5use crate::{ffi, Texture};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9 /// [`Cursor`][crate::Cursor] is used to create and destroy cursors.
10 ///
11 /// Cursors are immutable objects, so once you created them, there is no way
12 /// to modify them later. You should create a new cursor when you want to change
13 /// something about it.
14 ///
15 /// Cursors by themselves are not very interesting: they must be bound to a
16 /// window for users to see them. This is done with [`SurfaceExt::set_cursor()`][crate::prelude::SurfaceExt::set_cursor()]
17 /// or [`SurfaceExt::set_device_cursor()`][crate::prelude::SurfaceExt::set_device_cursor()]. Applications will typically
18 /// use higher-level GTK functions such as [gtk_widget_set_cursor()](../gtk4/method.Widget.set_cursor.html)
19 /// instead.
20 ///
21 /// Cursors are not bound to a given [`Display`][crate::Display], so they can be shared.
22 /// However, the appearance of cursors may vary when used on different
23 /// platforms.
24 ///
25 /// ## Named and texture cursors
26 ///
27 /// There are multiple ways to create cursors. The platform's own cursors
28 /// can be created with [`from_name()`][Self::from_name()]. That function lists
29 /// the commonly available names that are shared with the CSS specification.
30 /// Other names may be available, depending on the platform in use. On some
31 /// platforms, what images are used for named cursors may be influenced by
32 /// the cursor theme.
33 ///
34 /// Another option to create a cursor is to use [`from_texture()`][Self::from_texture()]
35 /// and provide an image to use for the cursor.
36 ///
37 /// To ease work with unsupported cursors, a fallback cursor can be provided.
38 /// If a [`Surface`][crate::Surface] cannot use a cursor because of the reasons mentioned
39 /// above, it will try the fallback cursor. Fallback cursors can themselves have
40 /// fallback cursors again, so it is possible to provide a chain of progressively
41 /// easier to support cursors. If none of the provided cursors can be supported,
42 /// the default cursor will be the ultimate fallback.
43 ///
44 /// ## Properties
45 ///
46 ///
47 /// #### `fallback`
48 /// Cursor to fall back to if this cursor cannot be displayed.
49 ///
50 /// Readable | Writeable | Construct Only
51 ///
52 ///
53 /// #### `hotspot-x`
54 /// X position of the cursor hotspot in the cursor image.
55 ///
56 /// Readable | Writeable | Construct Only
57 ///
58 ///
59 /// #### `hotspot-y`
60 /// Y position of the cursor hotspot in the cursor image.
61 ///
62 /// Readable | Writeable | Construct Only
63 ///
64 ///
65 /// #### `name`
66 /// Name of this this cursor.
67 ///
68 /// The name will be [`None`] if the cursor was created from a texture.
69 ///
70 /// Readable | Writeable | Construct Only
71 ///
72 ///
73 /// #### `texture`
74 /// The texture displayed by this cursor.
75 ///
76 /// The texture will be [`None`] if the cursor was created from a name.
77 ///
78 /// Readable | Writeable | Construct Only
79 #[doc(alias = "GdkCursor")]
80 pub struct Cursor(Object<ffi::GdkCursor>);
81
82 match fn {
83 type_ => || ffi::gdk_cursor_get_type(),
84 }
85}
86
87impl Cursor {
88 /// Creates a new cursor by looking up @name in the current cursor
89 /// theme.
90 ///
91 /// A recommended set of cursor names that will work across different
92 /// platforms can be found in the CSS specification:
93 ///
94 /// | | | | |
95 /// | --- | --- | ---- | --- |
96 /// | "none" |  "default" |  "help" |  "pointer" |
97 /// |  "context-menu" |  "progress" |  "wait" |  "cell" |
98 /// |  "crosshair" |  "text" |  "vertical-text" |  "alias" |
99 /// |  "copy" |  "no-drop" |  "move" |  "not-allowed" |
100 /// |  "grab" |  "grabbing" |  "all-scroll" |  "col-resize" |
101 /// |  "row-resize" |  "n-resize" |  "e-resize" |  "s-resize" |
102 /// |  "w-resize" |  "ne-resize" |  "nw-resize" |  "sw-resize" |
103 /// |  "se-resize" |  "ew-resize" |  "ns-resize" |  "nesw-resize" |
104 /// |  "nwse-resize" |  "zoom-in" |  "zoom-out" | |
105 /// ## `name`
106 /// the name of the cursor
107 /// ## `fallback`
108 /// [`None`] or the [`Cursor`][crate::Cursor] to fall back to when
109 /// this one cannot be supported
110 ///
111 /// # Returns
112 ///
113 /// a new [`Cursor`][crate::Cursor], or [`None`] if there is no
114 /// cursor with the given name
115 #[doc(alias = "gdk_cursor_new_from_name")]
116 #[doc(alias = "new_from_name")]
117 pub fn from_name(name: &str, fallback: Option<&Cursor>) -> Option<Cursor> {
118 assert_initialized_main_thread!();
119 unsafe {
120 from_glib_full(ffi::gdk_cursor_new_from_name(
121 name.to_glib_none().0,
122 fallback.to_glib_none().0,
123 ))
124 }
125 }
126
127 /// Creates a new cursor from a [`Texture`][crate::Texture].
128 /// ## `texture`
129 /// the texture providing the pixel data
130 /// ## `hotspot_x`
131 /// the horizontal offset of the “hotspot” of the cursor
132 /// ## `hotspot_y`
133 /// the vertical offset of the “hotspot” of the cursor
134 /// ## `fallback`
135 /// the [`Cursor`][crate::Cursor] to fall back to when
136 /// this one cannot be supported
137 ///
138 /// # Returns
139 ///
140 /// a new [`Cursor`][crate::Cursor]
141 #[doc(alias = "gdk_cursor_new_from_texture")]
142 #[doc(alias = "new_from_texture")]
143 pub fn from_texture(
144 texture: &impl IsA<Texture>,
145 hotspot_x: i32,
146 hotspot_y: i32,
147 fallback: Option<&Cursor>,
148 ) -> Cursor {
149 skip_assert_initialized!();
150 unsafe {
151 from_glib_full(ffi::gdk_cursor_new_from_texture(
152 texture.as_ref().to_glib_none().0,
153 hotspot_x,
154 hotspot_y,
155 fallback.to_glib_none().0,
156 ))
157 }
158 }
159
160 // rustdoc-stripper-ignore-next
161 /// Creates a new builder-pattern struct instance to construct [`Cursor`] objects.
162 ///
163 /// This method returns an instance of [`CursorBuilder`](crate::builders::CursorBuilder) which can be used to create [`Cursor`] objects.
164 pub fn builder() -> CursorBuilder {
165 CursorBuilder::new()
166 }
167
168 /// Returns the fallback for this @self.
169 ///
170 /// The fallback will be used if this cursor is not available on a given
171 /// [`Display`][crate::Display]. For named cursors, this can happen when using nonstandard
172 /// names or when using an incomplete cursor theme. For textured cursors,
173 /// this can happen when the texture is too large or when the [`Display`][crate::Display]
174 /// it is used on does not support textured cursors.
175 ///
176 /// # Returns
177 ///
178 /// the fallback of the cursor or [`None`]
179 /// to use the default cursor as fallback
180 #[doc(alias = "gdk_cursor_get_fallback")]
181 #[doc(alias = "get_fallback")]
182 #[must_use]
183 pub fn fallback(&self) -> Option<Cursor> {
184 unsafe { from_glib_none(ffi::gdk_cursor_get_fallback(self.to_glib_none().0)) }
185 }
186
187 /// Returns the horizontal offset of the hotspot.
188 ///
189 /// The hotspot indicates the pixel that will be directly above the cursor.
190 ///
191 /// Note that named cursors may have a nonzero hotspot, but this function
192 /// will only return the hotspot position for cursors created with
193 /// [`from_texture()`][Self::from_texture()].
194 ///
195 /// # Returns
196 ///
197 /// the horizontal offset of the hotspot or 0 for named cursors
198 #[doc(alias = "gdk_cursor_get_hotspot_x")]
199 #[doc(alias = "get_hotspot_x")]
200 #[doc(alias = "hotspot-x")]
201 pub fn hotspot_x(&self) -> i32 {
202 unsafe { ffi::gdk_cursor_get_hotspot_x(self.to_glib_none().0) }
203 }
204
205 /// Returns the vertical offset of the hotspot.
206 ///
207 /// The hotspot indicates the pixel that will be directly above the cursor.
208 ///
209 /// Note that named cursors may have a nonzero hotspot, but this function
210 /// will only return the hotspot position for cursors created with
211 /// [`from_texture()`][Self::from_texture()].
212 ///
213 /// # Returns
214 ///
215 /// the vertical offset of the hotspot or 0 for named cursors
216 #[doc(alias = "gdk_cursor_get_hotspot_y")]
217 #[doc(alias = "get_hotspot_y")]
218 #[doc(alias = "hotspot-y")]
219 pub fn hotspot_y(&self) -> i32 {
220 unsafe { ffi::gdk_cursor_get_hotspot_y(self.to_glib_none().0) }
221 }
222
223 /// Returns the name of the cursor.
224 ///
225 /// If the cursor is not a named cursor, [`None`] will be returned.
226 ///
227 /// # Returns
228 ///
229 /// the name of the cursor or [`None`]
230 /// if it is not a named cursor
231 #[doc(alias = "gdk_cursor_get_name")]
232 #[doc(alias = "get_name")]
233 pub fn name(&self) -> Option<glib::GString> {
234 unsafe { from_glib_none(ffi::gdk_cursor_get_name(self.to_glib_none().0)) }
235 }
236
237 /// Returns the texture for the cursor.
238 ///
239 /// If the cursor is a named cursor, [`None`] will be returned.
240 ///
241 /// # Returns
242 ///
243 /// the texture for cursor or [`None`]
244 /// if it is a named cursor
245 #[doc(alias = "gdk_cursor_get_texture")]
246 #[doc(alias = "get_texture")]
247 pub fn texture(&self) -> Option<Texture> {
248 unsafe { from_glib_none(ffi::gdk_cursor_get_texture(self.to_glib_none().0)) }
249 }
250}
251
252// rustdoc-stripper-ignore-next
253/// A [builder-pattern] type to construct [`Cursor`] objects.
254///
255/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
256#[must_use = "The builder must be built to be used"]
257pub struct CursorBuilder {
258 builder: glib::object::ObjectBuilder<'static, Cursor>,
259}
260
261impl CursorBuilder {
262 fn new() -> Self {
263 Self {
264 builder: glib::object::Object::builder(),
265 }
266 }
267
268 /// Cursor to fall back to if this cursor cannot be displayed.
269 pub fn fallback(self, fallback: &Cursor) -> Self {
270 Self {
271 builder: self.builder.property("fallback", fallback.clone()),
272 }
273 }
274
275 /// X position of the cursor hotspot in the cursor image.
276 pub fn hotspot_x(self, hotspot_x: i32) -> Self {
277 Self {
278 builder: self.builder.property("hotspot-x", hotspot_x),
279 }
280 }
281
282 /// Y position of the cursor hotspot in the cursor image.
283 pub fn hotspot_y(self, hotspot_y: i32) -> Self {
284 Self {
285 builder: self.builder.property("hotspot-y", hotspot_y),
286 }
287 }
288
289 /// Name of this this cursor.
290 ///
291 /// The name will be [`None`] if the cursor was created from a texture.
292 pub fn name(self, name: impl Into<glib::GString>) -> Self {
293 Self {
294 builder: self.builder.property("name", name.into()),
295 }
296 }
297
298 /// The texture displayed by this cursor.
299 ///
300 /// The texture will be [`None`] if the cursor was created from a name.
301 pub fn texture(self, texture: &impl IsA<Texture>) -> Self {
302 Self {
303 builder: self.builder.property("texture", texture.clone().upcast()),
304 }
305 }
306
307 // rustdoc-stripper-ignore-next
308 /// Build the [`Cursor`].
309 #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
310 pub fn build(self) -> Cursor {
311 assert_initialized_main_thread!();
312 self.builder.build()
313 }
314}