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    /// Recognizes drag gestures.
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
228/// Trait containing all [`struct@GestureDrag`] methods.
229///
230/// # Implementors
231///
232/// [`GestureDrag`][struct@crate::GestureDrag], [`GesturePan`][struct@crate::GesturePan]
233pub trait GestureDragExt: IsA<GestureDrag> + 'static {
234    /// Gets the offset from the start point.
235    ///
236    /// If the @self is active, this function returns [`true`] and
237    /// fills in @x and @y with the coordinates of the current point,
238    /// as an offset to the starting drag point.
239    ///
240    /// # Returns
241    ///
242    /// [`true`] if the gesture is active
243    ///
244    /// ## `x`
245    /// X offset for the current point
246    ///
247    /// ## `y`
248    /// Y offset for the current point
249    #[doc(alias = "gtk_gesture_drag_get_offset")]
250    #[doc(alias = "get_offset")]
251    fn offset(&self) -> Option<(f64, f64)> {
252        unsafe {
253            let mut x = std::mem::MaybeUninit::uninit();
254            let mut y = std::mem::MaybeUninit::uninit();
255            let ret = from_glib(ffi::gtk_gesture_drag_get_offset(
256                self.as_ref().to_glib_none().0,
257                x.as_mut_ptr(),
258                y.as_mut_ptr(),
259            ));
260            if ret {
261                Some((x.assume_init(), y.assume_init()))
262            } else {
263                None
264            }
265        }
266    }
267
268    /// Gets the point where the drag started.
269    ///
270    /// If the @self is active, this function returns [`true`]
271    /// and fills in @x and @y with the drag start coordinates,
272    /// in widget-relative coordinates.
273    ///
274    /// # Returns
275    ///
276    /// [`true`] if the gesture is active
277    ///
278    /// ## `x`
279    /// X coordinate for the drag start point
280    ///
281    /// ## `y`
282    /// Y coordinate for the drag start point
283    #[doc(alias = "gtk_gesture_drag_get_start_point")]
284    #[doc(alias = "get_start_point")]
285    fn start_point(&self) -> Option<(f64, f64)> {
286        unsafe {
287            let mut x = std::mem::MaybeUninit::uninit();
288            let mut y = std::mem::MaybeUninit::uninit();
289            let ret = from_glib(ffi::gtk_gesture_drag_get_start_point(
290                self.as_ref().to_glib_none().0,
291                x.as_mut_ptr(),
292                y.as_mut_ptr(),
293            ));
294            if ret {
295                Some((x.assume_init(), y.assume_init()))
296            } else {
297                None
298            }
299        }
300    }
301
302    /// Emitted whenever dragging starts.
303    /// ## `start_x`
304    /// X coordinate, relative to the widget allocation
305    /// ## `start_y`
306    /// Y coordinate, relative to the widget allocation
307    #[doc(alias = "drag-begin")]
308    fn connect_drag_begin<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
309        unsafe extern "C" fn drag_begin_trampoline<
310            P: IsA<GestureDrag>,
311            F: Fn(&P, f64, f64) + 'static,
312        >(
313            this: *mut ffi::GtkGestureDrag,
314            start_x: std::ffi::c_double,
315            start_y: std::ffi::c_double,
316            f: glib::ffi::gpointer,
317        ) {
318            let f: &F = &*(f as *const F);
319            f(
320                GestureDrag::from_glib_borrow(this).unsafe_cast_ref(),
321                start_x,
322                start_y,
323            )
324        }
325        unsafe {
326            let f: Box_<F> = Box_::new(f);
327            connect_raw(
328                self.as_ptr() as *mut _,
329                c"drag-begin".as_ptr() as *const _,
330                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
331                    drag_begin_trampoline::<Self, F> as *const (),
332                )),
333                Box_::into_raw(f),
334            )
335        }
336    }
337
338    /// Emitted whenever the dragging is finished.
339    /// ## `offset_x`
340    /// X offset, relative to the start point
341    /// ## `offset_y`
342    /// Y offset, relative to the start point
343    #[doc(alias = "drag-end")]
344    fn connect_drag_end<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
345        unsafe extern "C" fn drag_end_trampoline<
346            P: IsA<GestureDrag>,
347            F: Fn(&P, f64, f64) + 'static,
348        >(
349            this: *mut ffi::GtkGestureDrag,
350            offset_x: std::ffi::c_double,
351            offset_y: std::ffi::c_double,
352            f: glib::ffi::gpointer,
353        ) {
354            let f: &F = &*(f as *const F);
355            f(
356                GestureDrag::from_glib_borrow(this).unsafe_cast_ref(),
357                offset_x,
358                offset_y,
359            )
360        }
361        unsafe {
362            let f: Box_<F> = Box_::new(f);
363            connect_raw(
364                self.as_ptr() as *mut _,
365                c"drag-end".as_ptr() as *const _,
366                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
367                    drag_end_trampoline::<Self, F> as *const (),
368                )),
369                Box_::into_raw(f),
370            )
371        }
372    }
373
374    /// Emitted whenever the dragging point moves.
375    /// ## `offset_x`
376    /// X offset, relative to the start point
377    /// ## `offset_y`
378    /// Y offset, relative to the start point
379    #[doc(alias = "drag-update")]
380    fn connect_drag_update<F: Fn(&Self, f64, f64) + 'static>(&self, f: F) -> SignalHandlerId {
381        unsafe extern "C" fn drag_update_trampoline<
382            P: IsA<GestureDrag>,
383            F: Fn(&P, f64, f64) + 'static,
384        >(
385            this: *mut ffi::GtkGestureDrag,
386            offset_x: std::ffi::c_double,
387            offset_y: std::ffi::c_double,
388            f: glib::ffi::gpointer,
389        ) {
390            let f: &F = &*(f as *const F);
391            f(
392                GestureDrag::from_glib_borrow(this).unsafe_cast_ref(),
393                offset_x,
394                offset_y,
395            )
396        }
397        unsafe {
398            let f: Box_<F> = Box_::new(f);
399            connect_raw(
400                self.as_ptr() as *mut _,
401                c"drag-update".as_ptr() as *const _,
402                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
403                    drag_update_trampoline::<Self, F> as *const (),
404                )),
405                Box_::into_raw(f),
406            )
407        }
408    }
409}
410
411impl<O: IsA<GestureDrag>> GestureDragExt for O {}