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}