gtk4/auto/
gesture_drag.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    /// [`GestureDrag`][crate::GestureDrag] is a [`Gesture`][crate::Gesture] implementation for drags.
16    ///
17    /// The drag operation itself can be tracked throughout the
18    /// [`drag-begin`][struct@crate::GestureDrag#drag-begin],
19    /// [`drag-update`][struct@crate::GestureDrag#drag-update] and
20    /// [`drag-end`][struct@crate::GestureDrag#drag-end] signals, and the relevant
21    /// coordinates can be extracted through
22    /// [`GestureDragExt::offset()`][crate::prelude::GestureDragExt::offset()] and
23    /// [`GestureDragExt::start_point()`][crate::prelude::GestureDragExt::start_point()].
24    ///
25    /// ## Signals
26    ///
27    ///
28    /// #### `drag-begin`
29    ///  Emitted whenever dragging starts.
30    ///
31    ///
32    ///
33    ///
34    /// #### `drag-end`
35    ///  Emitted whenever the dragging is finished.
36    ///
37    ///
38    ///
39    ///
40    /// #### `drag-update`
41    ///  Emitted whenever the dragging point moves.
42    ///
43    ///
44    /// <details><summary><h4>Gesture</h4></summary>
45    ///
46    ///
47    /// #### `begin`
48    ///  Emitted when the gesture is recognized.
49    ///
50    /// This means the number of touch sequences matches
51    /// [`n-points`][struct@crate::Gesture#n-points].
52    ///
53    /// Note: These conditions may also happen when an extra touch
54    /// (eg. a third touch on a 2-touches gesture) is lifted, in that
55    /// situation @sequence won't pertain to the current set of active
56    /// touches, so don't rely on this being true.
57    ///
58    ///
59    ///
60    ///
61    /// #### `cancel`
62    ///  Emitted whenever a sequence is cancelled.
63    ///
64    /// This usually happens on active touches when
65    /// [`EventControllerExt::reset()`][crate::prelude::EventControllerExt::reset()] is called on @gesture
66    /// (manually, due to grabs...), or the individual @sequence
67    /// was claimed by parent widgets' controllers (see
68    /// [`GestureExt::set_sequence_state()`][crate::prelude::GestureExt::set_sequence_state()]).
69    ///
70    /// @gesture must forget everything about @sequence as in
71    /// response to this signal.
72    ///
73    ///
74    ///
75    ///
76    /// #### `end`
77    ///  Emitted when @gesture either stopped recognizing the event
78    /// sequences as something to be handled, or the number of touch
79    /// sequences became higher or lower than [`n-points`][struct@crate::Gesture#n-points].
80    ///
81    /// Note: @sequence might not pertain to the group of sequences that
82    /// were previously triggering recognition on @gesture (ie. a just
83    /// pressed touch sequence that exceeds [`n-points`][struct@crate::Gesture#n-points]).
84    /// This situation may be detected by checking through
85    /// [`GestureExt::handles_sequence()`][crate::prelude::GestureExt::handles_sequence()].
86    ///
87    ///
88    ///
89    ///
90    /// #### `sequence-state-changed`
91    ///  Emitted whenever a sequence state changes.
92    ///
93    /// See [`GestureExt::set_sequence_state()`][crate::prelude::GestureExt::set_sequence_state()] to know
94    /// more about the expectable sequence lifetimes.
95    ///
96    ///
97    ///
98    ///
99    /// #### `update`
100    ///  Emitted whenever an event is handled while the gesture is recognized.
101    ///
102    /// @sequence is guaranteed to pertain to the set of active touches.
103    ///
104    ///
105    /// </details>
106    ///
107    /// # Implements
108    ///
109    /// [`GestureDragExt`][trait@crate::prelude::GestureDragExt], [`GestureSingleExt`][trait@crate::prelude::GestureSingleExt], [`GestureExt`][trait@crate::prelude::GestureExt], [`EventControllerExt`][trait@crate::prelude::EventControllerExt], [`trait@glib::ObjectExt`]
110    #[doc(alias = "GtkGestureDrag")]
111    pub struct GestureDrag(Object<ffi::GtkGestureDrag, ffi::GtkGestureDragClass>) @extends GestureSingle, Gesture, EventController;
112
113    match fn {
114        type_ => || ffi::gtk_gesture_drag_get_type(),
115    }
116}
117
118impl GestureDrag {
119    pub const NONE: Option<&'static GestureDrag> = None;
120
121    /// Returns a newly created [`Gesture`][crate::Gesture] that recognizes drags.
122    ///
123    /// # Returns
124    ///
125    /// a newly created [`GestureDrag`][crate::GestureDrag]
126    #[doc(alias = "gtk_gesture_drag_new")]
127    pub fn new() -> GestureDrag {
128        assert_initialized_main_thread!();
129        unsafe { Gesture::from_glib_full(ffi::gtk_gesture_drag_new()).unsafe_cast() }
130    }
131
132    // rustdoc-stripper-ignore-next
133    /// Creates a new builder-pattern struct instance to construct [`GestureDrag`] objects.
134    ///
135    /// This method returns an instance of [`GestureDragBuilder`](crate::builders::GestureDragBuilder) which can be used to create [`GestureDrag`] objects.
136    pub fn builder() -> GestureDragBuilder {
137        GestureDragBuilder::new()
138    }
139}
140
141impl Default for GestureDrag {
142    fn default() -> Self {
143        Self::new()
144    }
145}
146
147// rustdoc-stripper-ignore-next
148/// A [builder-pattern] type to construct [`GestureDrag`] objects.
149///
150/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
151#[must_use = "The builder must be built to be used"]
152pub struct GestureDragBuilder {
153    builder: glib::object::ObjectBuilder<'static, GestureDrag>,
154}
155
156impl GestureDragBuilder {
157    fn new() -> Self {
158        Self {
159            builder: glib::object::Object::builder(),
160        }
161    }
162
163    /// Mouse button number to listen to, or 0 to listen for any button.
164    pub fn button(self, button: u32) -> Self {
165        Self {
166            builder: self.builder.property("button", button),
167        }
168    }
169
170    /// Whether the gesture is exclusive.
171    ///
172    /// Exclusive gestures only listen to pointer and pointer emulated events.
173    pub fn exclusive(self, exclusive: bool) -> Self {
174        Self {
175            builder: self.builder.property("exclusive", exclusive),
176        }
177    }
178
179    /// Whether the gesture handles only touch events.
180    pub fn touch_only(self, touch_only: bool) -> Self {
181        Self {
182            builder: self.builder.property("touch-only", touch_only),
183        }
184    }
185
186    /// The number of touch points that trigger
187    /// recognition on this gesture.
188    pub fn n_points(self, n_points: u32) -> Self {
189        Self {
190            builder: self.builder.property("n-points", n_points),
191        }
192    }
193
194    /// The name for this controller, typically used for debugging purposes.
195    pub fn name(self, name: impl Into<glib::GString>) -> Self {
196        Self {
197            builder: self.builder.property("name", name.into()),
198        }
199    }
200
201    /// The limit for which events this controller will handle.
202    pub fn propagation_limit(self, propagation_limit: PropagationLimit) -> Self {
203        Self {
204            builder: self
205                .builder
206                .property("propagation-limit", propagation_limit),
207        }
208    }
209
210    /// The propagation phase at which this controller will handle events.
211    pub fn propagation_phase(self, propagation_phase: PropagationPhase) -> Self {
212        Self {
213            builder: self
214                .builder
215                .property("propagation-phase", propagation_phase),
216        }
217    }
218
219    // rustdoc-stripper-ignore-next
220    /// Build the [`GestureDrag`].
221    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
222    pub fn build(self) -> GestureDrag {
223        assert_initialized_main_thread!();
224        self.builder.build()
225    }
226}
227
228mod sealed {
229    pub trait Sealed {}
230    impl<T: super::IsA<super::GestureDrag>> Sealed for T {}
231}
232
233/// Trait containing all [`struct@GestureDrag`] methods.
234///
235/// # Implementors
236///
237/// [`GestureDrag`][struct@crate::GestureDrag], [`GesturePan`][struct@crate::GesturePan]
238pub trait GestureDragExt: IsA<GestureDrag> + sealed::Sealed + 'static {
239    /// Gets the offset from the start point.
240    ///
241    /// If the @self is active, this function returns [`true`] and
242    /// fills in @x and @y with the coordinates of the current point,
243    /// as an offset to the starting drag point.
244    ///
245    /// # Returns
246    ///
247    /// [`true`] if the gesture is active
248    ///
249    /// ## `x`
250    /// X offset for the current point
251    ///
252    /// ## `y`
253    /// Y offset for the current point
254    #[doc(alias = "gtk_gesture_drag_get_offset")]
255    #[doc(alias = "get_offset")]
256    fn offset(&self) -> Option<(f64, f64)> {
257        unsafe {
258            let mut x = std::mem::MaybeUninit::uninit();
259            let mut y = std::mem::MaybeUninit::uninit();
260            let ret = from_glib(ffi::gtk_gesture_drag_get_offset(
261                self.as_ref().to_glib_none().0,
262                x.as_mut_ptr(),
263                y.as_mut_ptr(),
264            ));
265            if ret {
266                Some((x.assume_init(), y.assume_init()))
267            } else {
268                None
269            }
270        }
271    }
272
273    /// Gets the point where the drag started.
274    ///
275    /// If the @self is active, this function returns [`true`]
276    /// and fills in @x and @y with the drag start coordinates,
277    /// in widget-relative coordinates.
278    ///
279    /// # Returns
280    ///
281    /// [`true`] if the gesture is active
282    ///
283    /// ## `x`
284    /// X coordinate for the drag start point
285    ///
286    /// ## `y`
287    /// Y coordinate for the drag start point
288    #[doc(alias = "gtk_gesture_drag_get_start_point")]
289    #[doc(alias = "get_start_point")]
290    fn start_point(&self) -> Option<(f64, f64)> {
291        unsafe {
292            let mut x = std::mem::MaybeUninit::uninit();
293            let mut y = std::mem::MaybeUninit::uninit();
294            let ret = from_glib(ffi::gtk_gesture_drag_get_start_point(
295                self.as_ref().to_glib_none().0,
296                x.as_mut_ptr(),
297                y.as_mut_ptr(),
298            ));
299            if ret {
300                Some((x.assume_init(), y.assume_init()))
301            } else {
302                None
303            }
304        }
305    }
306
307    /// Emitted whenever dragging starts.
308    /// ## `start_x`
309    /// X coordinate, relative to the widget allocation
310    /// ## `start_y`
311    /// Y coordinate, relative to the widget allocation
312    #[doc(alias = "drag-begin")]
313    fn connect_drag_begin<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
314        unsafe extern "C" fn drag_begin_trampoline<
315            P: IsA<GestureDrag>,
316            F: Fn(&P, f64, f64) + 'static,
317        >(
318            this: *mut ffi::GtkGestureDrag,
319            start_x: std::ffi::c_double,
320            start_y: std::ffi::c_double,
321            f: glib::ffi::gpointer,
322        ) {
323            let f: &F = &*(f as *const F);
324            f(
325                GestureDrag::from_glib_borrow(this).unsafe_cast_ref(),
326                start_x,
327                start_y,
328            )
329        }
330        unsafe {
331            let f: Box_<F> = Box_::new(f);
332            connect_raw(
333                self.as_ptr() as *mut _,
334                b"drag-begin\0".as_ptr() as *const _,
335                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
336                    drag_begin_trampoline::<Self, F> as *const (),
337                )),
338                Box_::into_raw(f),
339            )
340        }
341    }
342
343    /// Emitted whenever the dragging is finished.
344    /// ## `offset_x`
345    /// X offset, relative to the start point
346    /// ## `offset_y`
347    /// Y offset, relative to the start point
348    #[doc(alias = "drag-end")]
349    fn connect_drag_end<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
350        unsafe extern "C" fn drag_end_trampoline<
351            P: IsA<GestureDrag>,
352            F: Fn(&P, f64, f64) + 'static,
353        >(
354            this: *mut ffi::GtkGestureDrag,
355            offset_x: std::ffi::c_double,
356            offset_y: std::ffi::c_double,
357            f: glib::ffi::gpointer,
358        ) {
359            let f: &F = &*(f as *const F);
360            f(
361                GestureDrag::from_glib_borrow(this).unsafe_cast_ref(),
362                offset_x,
363                offset_y,
364            )
365        }
366        unsafe {
367            let f: Box_<F> = Box_::new(f);
368            connect_raw(
369                self.as_ptr() as *mut _,
370                b"drag-end\0".as_ptr() as *const _,
371                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
372                    drag_end_trampoline::<Self, F> as *const (),
373                )),
374                Box_::into_raw(f),
375            )
376        }
377    }
378
379    /// Emitted whenever the dragging point moves.
380    /// ## `offset_x`
381    /// X offset, relative to the start point
382    /// ## `offset_y`
383    /// Y offset, relative to the start point
384    #[doc(alias = "drag-update")]
385    fn connect_drag_update<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
386        unsafe extern "C" fn drag_update_trampoline<
387            P: IsA<GestureDrag>,
388            F: Fn(&P, f64, f64) + 'static,
389        >(
390            this: *mut ffi::GtkGestureDrag,
391            offset_x: std::ffi::c_double,
392            offset_y: std::ffi::c_double,
393            f: glib::ffi::gpointer,
394        ) {
395            let f: &F = &*(f as *const F);
396            f(
397                GestureDrag::from_glib_borrow(this).unsafe_cast_ref(),
398                offset_x,
399                offset_y,
400            )
401        }
402        unsafe {
403            let f: Box_<F> = Box_::new(f);
404            connect_raw(
405                self.as_ptr() as *mut _,
406                b"drag-update\0".as_ptr() as *const _,
407                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
408                    drag_update_trampoline::<Self, F> as *const (),
409                )),
410                Box_::into_raw(f),
411            )
412        }
413    }
414}
415
416impl<O: IsA<GestureDrag>> GestureDragExt for O {}