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_cursor.png) "default" | ![](help_cursor.png) "help" | ![](pointer_cursor.png) "pointer" |
97    /// | ![](context_menu_cursor.png) "context-menu" | ![](progress_cursor.png) "progress" | ![](wait_cursor.png) "wait" | ![](cell_cursor.png) "cell" |
98    /// | ![](crosshair_cursor.png) "crosshair" | ![](text_cursor.png) "text" | ![](vertical_text_cursor.png) "vertical-text" | ![](alias_cursor.png) "alias" |
99    /// | ![](copy_cursor.png) "copy" | ![](no_drop_cursor.png) "no-drop" | ![](move_cursor.png) "move" | ![](not_allowed_cursor.png) "not-allowed" |
100    /// | ![](grab_cursor.png) "grab" | ![](grabbing_cursor.png) "grabbing" | ![](all_scroll_cursor.png) "all-scroll" | ![](col_resize_cursor.png) "col-resize" |
101    /// | ![](row_resize_cursor.png) "row-resize" | ![](n_resize_cursor.png) "n-resize" | ![](e_resize_cursor.png) "e-resize" | ![](s_resize_cursor.png) "s-resize" |
102    /// | ![](w_resize_cursor.png) "w-resize" | ![](ne_resize_cursor.png) "ne-resize" | ![](nw_resize_cursor.png) "nw-resize" | ![](sw_resize_cursor.png) "sw-resize" |
103    /// | ![](se_resize_cursor.png) "se-resize" | ![](ew_resize_cursor.png) "ew-resize" | ![](ns_resize_cursor.png) "ns-resize" | ![](nesw_resize_cursor.png) "nesw-resize" |
104    /// | ![](nwse_resize_cursor.png) "nwse-resize" | ![](zoom_in_cursor.png) "zoom-in" | ![](zoom_out_cursor.png) "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}