gtk4/auto/
gesture_stylus.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, EventController, Gesture, GestureSingle, PropagationLimit, PropagationPhase};
6use glib::{
7    object::ObjectType as _,
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// [`GestureStylus`][crate::GestureStylus] is a [`Gesture`][crate::Gesture] specific to stylus input.
16    ///
17    /// The provided signals just relay the basic information of the
18    /// stylus events.
19    ///
20    /// ## Properties
21    ///
22    ///
23    /// #### `stylus-only`
24    ///  If this gesture should exclusively react to stylus input devices.
25    ///
26    /// Readable | Writeable | Construct
27    /// <details><summary><h4>GestureSingle</h4></summary>
28    ///
29    ///
30    /// #### `button`
31    ///  Mouse button number to listen to, or 0 to listen for any button.
32    ///
33    /// Readable | Writeable
34    ///
35    ///
36    /// #### `exclusive`
37    ///  Whether the gesture is exclusive.
38    ///
39    /// Exclusive gestures only listen to pointer and pointer emulated events.
40    ///
41    /// Readable | Writeable
42    ///
43    ///
44    /// #### `touch-only`
45    ///  Whether the gesture handles only touch events.
46    ///
47    /// Readable | Writeable
48    /// </details>
49    /// <details><summary><h4>Gesture</h4></summary>
50    ///
51    ///
52    /// #### `n-points`
53    ///  The number of touch points that trigger
54    /// recognition on this gesture.
55    ///
56    /// Readable | Writeable | Construct Only
57    /// </details>
58    /// <details><summary><h4>EventController</h4></summary>
59    ///
60    ///
61    /// #### `name`
62    ///  The name for this controller, typically used for debugging purposes.
63    ///
64    /// Readable | Writeable
65    ///
66    ///
67    /// #### `propagation-limit`
68    ///  The limit for which events this controller will handle.
69    ///
70    /// Readable | Writeable
71    ///
72    ///
73    /// #### `propagation-phase`
74    ///  The propagation phase at which this controller will handle events.
75    ///
76    /// Readable | Writeable
77    ///
78    ///
79    /// #### `widget`
80    ///  The widget receiving the `GdkEvents` that the controller will handle.
81    ///
82    /// Readable
83    /// </details>
84    ///
85    /// ## Signals
86    ///
87    ///
88    /// #### `down`
89    ///  Emitted when the stylus touches the device.
90    ///
91    ///
92    ///
93    ///
94    /// #### `motion`
95    ///  Emitted when the stylus moves while touching the device.
96    ///
97    ///
98    ///
99    ///
100    /// #### `proximity`
101    ///  Emitted when the stylus is in proximity of the device.
102    ///
103    ///
104    ///
105    ///
106    /// #### `up`
107    ///  Emitted when the stylus no longer touches the device.
108    ///
109    ///
110    /// <details><summary><h4>Gesture</h4></summary>
111    ///
112    ///
113    /// #### `begin`
114    ///  Emitted when the gesture is recognized.
115    ///
116    /// This means the number of touch sequences matches
117    /// [`n-points`][struct@crate::Gesture#n-points].
118    ///
119    /// Note: These conditions may also happen when an extra touch
120    /// (eg. a third touch on a 2-touches gesture) is lifted, in that
121    /// situation @sequence won't pertain to the current set of active
122    /// touches, so don't rely on this being true.
123    ///
124    ///
125    ///
126    ///
127    /// #### `cancel`
128    ///  Emitted whenever a sequence is cancelled.
129    ///
130    /// This usually happens on active touches when
131    /// [`EventControllerExt::reset()`][crate::prelude::EventControllerExt::reset()] is called on @gesture
132    /// (manually, due to grabs...), or the individual @sequence
133    /// was claimed by parent widgets' controllers (see
134    /// [`GestureExt::set_sequence_state()`][crate::prelude::GestureExt::set_sequence_state()]).
135    ///
136    /// @gesture must forget everything about @sequence as in
137    /// response to this signal.
138    ///
139    ///
140    ///
141    ///
142    /// #### `end`
143    ///  Emitted when @gesture either stopped recognizing the event
144    /// sequences as something to be handled, or the number of touch
145    /// sequences became higher or lower than [`n-points`][struct@crate::Gesture#n-points].
146    ///
147    /// Note: @sequence might not pertain to the group of sequences that
148    /// were previously triggering recognition on @gesture (ie. a just
149    /// pressed touch sequence that exceeds [`n-points`][struct@crate::Gesture#n-points]).
150    /// This situation may be detected by checking through
151    /// [`GestureExt::handles_sequence()`][crate::prelude::GestureExt::handles_sequence()].
152    ///
153    ///
154    ///
155    ///
156    /// #### `sequence-state-changed`
157    ///  Emitted whenever a sequence state changes.
158    ///
159    /// See [`GestureExt::set_sequence_state()`][crate::prelude::GestureExt::set_sequence_state()] to know
160    /// more about the expectable sequence lifetimes.
161    ///
162    ///
163    ///
164    ///
165    /// #### `update`
166    ///  Emitted whenever an event is handled while the gesture is recognized.
167    ///
168    /// @sequence is guaranteed to pertain to the set of active touches.
169    ///
170    ///
171    /// </details>
172    ///
173    /// # Implements
174    ///
175    /// [`GestureSingleExt`][trait@crate::prelude::GestureSingleExt], [`GestureExt`][trait@crate::prelude::GestureExt], [`EventControllerExt`][trait@crate::prelude::EventControllerExt], [`trait@glib::ObjectExt`]
176    #[doc(alias = "GtkGestureStylus")]
177    pub struct GestureStylus(Object<ffi::GtkGestureStylus, ffi::GtkGestureStylusClass>) @extends GestureSingle, Gesture, EventController;
178
179    match fn {
180        type_ => || ffi::gtk_gesture_stylus_get_type(),
181    }
182}
183
184impl GestureStylus {
185    /// Creates a new [`GestureStylus`][crate::GestureStylus].
186    ///
187    /// # Returns
188    ///
189    /// a newly created stylus gesture
190    #[doc(alias = "gtk_gesture_stylus_new")]
191    pub fn new() -> GestureStylus {
192        assert_initialized_main_thread!();
193        unsafe { Gesture::from_glib_full(ffi::gtk_gesture_stylus_new()).unsafe_cast() }
194    }
195
196    // rustdoc-stripper-ignore-next
197    /// Creates a new builder-pattern struct instance to construct [`GestureStylus`] objects.
198    ///
199    /// This method returns an instance of [`GestureStylusBuilder`](crate::builders::GestureStylusBuilder) which can be used to create [`GestureStylus`] objects.
200    pub fn builder() -> GestureStylusBuilder {
201        GestureStylusBuilder::new()
202    }
203
204    /// Returns the current value for the requested @axis.
205    ///
206    /// This function must be called from the handler of one of the
207    /// [`down`][struct@crate::GestureStylus#down], [`motion`][struct@crate::GestureStylus#motion],
208    /// [`up`][struct@crate::GestureStylus#up] or [`proximity`][struct@crate::GestureStylus#proximity]
209    /// signals.
210    /// ## `axis`
211    /// requested device axis
212    ///
213    /// # Returns
214    ///
215    /// [`true`] if there is a current value for the axis
216    ///
217    /// ## `value`
218    /// return location for the axis value
219    #[doc(alias = "gtk_gesture_stylus_get_axis")]
220    #[doc(alias = "get_axis")]
221    pub fn axis(&self, axis: gdk::AxisUse) -> Option<f64> {
222        unsafe {
223            let mut value = std::mem::MaybeUninit::uninit();
224            let ret = from_glib(ffi::gtk_gesture_stylus_get_axis(
225                self.to_glib_none().0,
226                axis.into_glib(),
227                value.as_mut_ptr(),
228            ));
229            if ret {
230                Some(value.assume_init())
231            } else {
232                None
233            }
234        }
235    }
236
237    /// Returns the accumulated backlog of tracking information.
238    ///
239    /// By default, GTK will limit rate of input events. On stylus input
240    /// where accuracy of strokes is paramount, this function returns the
241    /// accumulated coordinate/timing state before the emission of the
242    /// current [Gtk.GestureStylus::motion] signal.
243    ///
244    /// This function may only be called within a [`motion`][struct@crate::GestureStylus#motion]
245    /// signal handler, the state given in this signal and obtainable through
246    /// [`axis()`][Self::axis()] express the latest (most up-to-date)
247    /// state in motion history.
248    ///
249    /// The @backlog is provided in chronological order.
250    ///
251    /// # Returns
252    ///
253    /// [`true`] if there is a backlog to unfold in the current state.
254    ///
255    /// ## `backlog`
256    /// coordinates and times for the backlog events
257    #[doc(alias = "gtk_gesture_stylus_get_backlog")]
258    #[doc(alias = "get_backlog")]
259    pub fn backlog(&self) -> Option<Vec<gdk::TimeCoord>> {
260        unsafe {
261            let mut backlog = std::ptr::null_mut();
262            let mut n_elems = std::mem::MaybeUninit::uninit();
263            let ret = from_glib(ffi::gtk_gesture_stylus_get_backlog(
264                self.to_glib_none().0,
265                &mut backlog,
266                n_elems.as_mut_ptr(),
267            ));
268            if ret {
269                Some(FromGlibContainer::from_glib_full_num(
270                    backlog,
271                    n_elems.assume_init() as _,
272                ))
273            } else {
274                None
275            }
276        }
277    }
278
279    /// Returns the [`gdk::DeviceTool`][crate::gdk::DeviceTool] currently driving input through this gesture.
280    ///
281    /// This function must be called from the handler of one of the
282    /// [`down`][struct@crate::GestureStylus#down], [`motion`][struct@crate::GestureStylus#motion],
283    /// [`up`][struct@crate::GestureStylus#up] or [`proximity`][struct@crate::GestureStylus#proximity]
284    /// signals.
285    ///
286    /// # Returns
287    ///
288    /// The current stylus tool
289    #[doc(alias = "gtk_gesture_stylus_get_device_tool")]
290    #[doc(alias = "get_device_tool")]
291    pub fn device_tool(&self) -> Option<gdk::DeviceTool> {
292        unsafe {
293            from_glib_none(ffi::gtk_gesture_stylus_get_device_tool(
294                self.to_glib_none().0,
295            ))
296        }
297    }
298
299    /// Checks whether the gesture is for styluses only.
300    ///
301    /// Stylus-only gestures will signal events exclusively from stylus
302    /// input devices.
303    ///
304    /// # Returns
305    ///
306    /// [`true`] if the gesture is only for stylus events
307    #[cfg(feature = "v4_10")]
308    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
309    #[doc(alias = "gtk_gesture_stylus_get_stylus_only")]
310    #[doc(alias = "get_stylus_only")]
311    #[doc(alias = "stylus-only")]
312    pub fn is_stylus_only(&self) -> bool {
313        unsafe {
314            from_glib(ffi::gtk_gesture_stylus_get_stylus_only(
315                self.to_glib_none().0,
316            ))
317        }
318    }
319
320    /// Sets the state of stylus-only
321    ///
322    /// If true, the gesture will exclusively handle events from stylus input devices,
323    /// otherwise it'll handle events from any pointing device.
324    /// ## `stylus_only`
325    /// whether the gesture is used exclusively for stylus events
326    #[cfg(feature = "v4_10")]
327    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
328    #[doc(alias = "gtk_gesture_stylus_set_stylus_only")]
329    #[doc(alias = "stylus-only")]
330    pub fn set_stylus_only(&self, stylus_only: bool) {
331        unsafe {
332            ffi::gtk_gesture_stylus_set_stylus_only(self.to_glib_none().0, stylus_only.into_glib());
333        }
334    }
335
336    /// Emitted when the stylus touches the device.
337    /// ## `x`
338    /// the X coordinate of the stylus event
339    /// ## `y`
340    /// the Y coordinate of the stylus event
341    #[doc(alias = "down")]
342    pub fn connect_down<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
343        unsafe extern "C" fn down_trampoline<F: Fn(&GestureStylus, f64, f64) + 'static>(
344            this: *mut ffi::GtkGestureStylus,
345            x: std::ffi::c_double,
346            y: std::ffi::c_double,
347            f: glib::ffi::gpointer,
348        ) {
349            let f: &F = &*(f as *const F);
350            f(&from_glib_borrow(this), x, y)
351        }
352        unsafe {
353            let f: Box_<F> = Box_::new(f);
354            connect_raw(
355                self.as_ptr() as *mut _,
356                b"down\0".as_ptr() as *const _,
357                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
358                    down_trampoline::<F> as *const (),
359                )),
360                Box_::into_raw(f),
361            )
362        }
363    }
364
365    /// Emitted when the stylus moves while touching the device.
366    /// ## `x`
367    /// the X coordinate of the stylus event
368    /// ## `y`
369    /// the Y coordinate of the stylus event
370    #[doc(alias = "motion")]
371    pub fn connect_motion<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
372        unsafe extern "C" fn motion_trampoline<F: Fn(&GestureStylus, f64, f64) + 'static>(
373            this: *mut ffi::GtkGestureStylus,
374            x: std::ffi::c_double,
375            y: std::ffi::c_double,
376            f: glib::ffi::gpointer,
377        ) {
378            let f: &F = &*(f as *const F);
379            f(&from_glib_borrow(this), x, y)
380        }
381        unsafe {
382            let f: Box_<F> = Box_::new(f);
383            connect_raw(
384                self.as_ptr() as *mut _,
385                b"motion\0".as_ptr() as *const _,
386                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
387                    motion_trampoline::<F> as *const (),
388                )),
389                Box_::into_raw(f),
390            )
391        }
392    }
393
394    /// Emitted when the stylus is in proximity of the device.
395    /// ## `x`
396    /// the X coordinate of the stylus event
397    /// ## `y`
398    /// the Y coordinate of the stylus event
399    #[doc(alias = "proximity")]
400    pub fn connect_proximity<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
401        unsafe extern "C" fn proximity_trampoline<F: Fn(&GestureStylus, f64, f64) + 'static>(
402            this: *mut ffi::GtkGestureStylus,
403            x: std::ffi::c_double,
404            y: std::ffi::c_double,
405            f: glib::ffi::gpointer,
406        ) {
407            let f: &F = &*(f as *const F);
408            f(&from_glib_borrow(this), x, y)
409        }
410        unsafe {
411            let f: Box_<F> = Box_::new(f);
412            connect_raw(
413                self.as_ptr() as *mut _,
414                b"proximity\0".as_ptr() as *const _,
415                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
416                    proximity_trampoline::<F> as *const (),
417                )),
418                Box_::into_raw(f),
419            )
420        }
421    }
422
423    /// Emitted when the stylus no longer touches the device.
424    /// ## `x`
425    /// the X coordinate of the stylus event
426    /// ## `y`
427    /// the Y coordinate of the stylus event
428    #[doc(alias = "up")]
429    pub fn connect_up<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
430        unsafe extern "C" fn up_trampoline<F: Fn(&GestureStylus, f64, f64) + 'static>(
431            this: *mut ffi::GtkGestureStylus,
432            x: std::ffi::c_double,
433            y: std::ffi::c_double,
434            f: glib::ffi::gpointer,
435        ) {
436            let f: &F = &*(f as *const F);
437            f(&from_glib_borrow(this), x, y)
438        }
439        unsafe {
440            let f: Box_<F> = Box_::new(f);
441            connect_raw(
442                self.as_ptr() as *mut _,
443                b"up\0".as_ptr() as *const _,
444                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
445                    up_trampoline::<F> as *const (),
446                )),
447                Box_::into_raw(f),
448            )
449        }
450    }
451
452    #[cfg(feature = "v4_10")]
453    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
454    #[doc(alias = "stylus-only")]
455    pub fn connect_stylus_only_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
456        unsafe extern "C" fn notify_stylus_only_trampoline<F: Fn(&GestureStylus) + 'static>(
457            this: *mut ffi::GtkGestureStylus,
458            _param_spec: glib::ffi::gpointer,
459            f: glib::ffi::gpointer,
460        ) {
461            let f: &F = &*(f as *const F);
462            f(&from_glib_borrow(this))
463        }
464        unsafe {
465            let f: Box_<F> = Box_::new(f);
466            connect_raw(
467                self.as_ptr() as *mut _,
468                b"notify::stylus-only\0".as_ptr() as *const _,
469                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
470                    notify_stylus_only_trampoline::<F> as *const (),
471                )),
472                Box_::into_raw(f),
473            )
474        }
475    }
476}
477
478impl Default for GestureStylus {
479    fn default() -> Self {
480        Self::new()
481    }
482}
483
484// rustdoc-stripper-ignore-next
485/// A [builder-pattern] type to construct [`GestureStylus`] objects.
486///
487/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
488#[must_use = "The builder must be built to be used"]
489pub struct GestureStylusBuilder {
490    builder: glib::object::ObjectBuilder<'static, GestureStylus>,
491}
492
493impl GestureStylusBuilder {
494    fn new() -> Self {
495        Self {
496            builder: glib::object::Object::builder(),
497        }
498    }
499
500    /// If this gesture should exclusively react to stylus input devices.
501    #[cfg(feature = "v4_10")]
502    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
503    pub fn stylus_only(self, stylus_only: bool) -> Self {
504        Self {
505            builder: self.builder.property("stylus-only", stylus_only),
506        }
507    }
508
509    /// Mouse button number to listen to, or 0 to listen for any button.
510    pub fn button(self, button: u32) -> Self {
511        Self {
512            builder: self.builder.property("button", button),
513        }
514    }
515
516    /// Whether the gesture is exclusive.
517    ///
518    /// Exclusive gestures only listen to pointer and pointer emulated events.
519    pub fn exclusive(self, exclusive: bool) -> Self {
520        Self {
521            builder: self.builder.property("exclusive", exclusive),
522        }
523    }
524
525    /// Whether the gesture handles only touch events.
526    pub fn touch_only(self, touch_only: bool) -> Self {
527        Self {
528            builder: self.builder.property("touch-only", touch_only),
529        }
530    }
531
532    /// The number of touch points that trigger
533    /// recognition on this gesture.
534    pub fn n_points(self, n_points: u32) -> Self {
535        Self {
536            builder: self.builder.property("n-points", n_points),
537        }
538    }
539
540    /// The name for this controller, typically used for debugging purposes.
541    pub fn name(self, name: impl Into<glib::GString>) -> Self {
542        Self {
543            builder: self.builder.property("name", name.into()),
544        }
545    }
546
547    /// The limit for which events this controller will handle.
548    pub fn propagation_limit(self, propagation_limit: PropagationLimit) -> Self {
549        Self {
550            builder: self
551                .builder
552                .property("propagation-limit", propagation_limit),
553        }
554    }
555
556    /// The propagation phase at which this controller will handle events.
557    pub fn propagation_phase(self, propagation_phase: PropagationPhase) -> Self {
558        Self {
559            builder: self
560                .builder
561                .property("propagation-phase", propagation_phase),
562        }
563    }
564
565    // rustdoc-stripper-ignore-next
566    /// Build the [`GestureStylus`].
567    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
568    pub fn build(self) -> GestureStylus {
569        assert_initialized_main_thread!();
570        self.builder.build()
571    }
572}