gtk4/auto/

gesture.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT
#![allow(deprecated)]

use crate::{EventController, EventSequenceState, ffi};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// The base class for gesture recognition.
    ///
    /// Although [`Gesture`][crate::Gesture] is quite generalized to serve as a base for
    /// multi-touch gestures, it is suitable to implement single-touch and
    /// pointer-based gestures (using the special [`None`] [`gdk::EventSequence`][crate::gdk::EventSequence]
    /// value for these).
    ///
    /// The number of touches that a [`Gesture`][crate::Gesture] need to be recognized is
    /// controlled by the [`n-points`][struct@crate::Gesture#n-points] property, if a
    /// gesture is keeping track of less or more than that number of sequences,
    /// it won't check whether the gesture is recognized.
    ///
    /// As soon as the gesture has the expected number of touches, it will check
    /// regularly if it is recognized, the criteria to consider a gesture as
    /// "recognized" is left to [`Gesture`][crate::Gesture] subclasses.
    ///
    /// A recognized gesture will then emit the following signals:
    ///
    /// - [`begin`][struct@crate::Gesture#begin] when the gesture is recognized.
    /// - [`update`][struct@crate::Gesture#update], whenever an input event is processed.
    /// - [`end`][struct@crate::Gesture#end] when the gesture is no longer recognized.
    ///
    /// ## Event propagation
    ///
    /// In order to receive events, a gesture needs to set a propagation phase
    /// through [`EventControllerExt::set_propagation_phase()`][crate::prelude::EventControllerExt::set_propagation_phase()].
    ///
    /// In the capture phase, events are propagated from the toplevel down
    /// to the target widget, and gestures that are attached to containers
    /// above the widget get a chance to interact with the event before it
    /// reaches the target.
    ///
    /// In the bubble phase, events are propagated up from the target widget
    /// to the toplevel, and gestures that are attached to containers above
    /// the widget get a chance to interact with events that have not been
    /// handled yet.
    ///
    /// ## States of a sequence
    ///
    /// Whenever input interaction happens, a single event may trigger a cascade
    /// of [`Gesture`][crate::Gesture]s, both across the parents of the widget receiving the
    /// event and in parallel within an individual widget. It is a responsibility
    /// of the widgets using those gestures to set the state of touch sequences
    /// accordingly in order to enable cooperation of gestures around the
    /// [`gdk::EventSequence`][crate::gdk::EventSequence]s triggering those.
    ///
    /// Within a widget, gestures can be grouped through [`GestureExt::group_with()`][crate::prelude::GestureExt::group_with()].
    /// Grouped gestures synchronize the state of sequences, so calling
    /// [`GestureExt::set_state()`][crate::prelude::GestureExt::set_state()] on one will effectively propagate
    /// the state throughout the group.
    ///
    /// By default, all sequences start out in the [`EventSequenceState::None`][crate::EventSequenceState::None] state,
    /// sequences in this state trigger the gesture event handler, but event
    /// propagation will continue unstopped by gestures.
    ///
    /// If a sequence enters into the [`EventSequenceState::Denied`][crate::EventSequenceState::Denied] state, the gesture
    /// group will effectively ignore the sequence, letting events go unstopped
    /// through the gesture, but the "slot" will still remain occupied while
    /// the touch is active.
    ///
    /// If a sequence enters in the [`EventSequenceState::Claimed`][crate::EventSequenceState::Claimed] state, the gesture
    /// group will grab all interaction on the sequence, by:
    ///
    /// - Setting the same sequence to [`EventSequenceState::Denied`][crate::EventSequenceState::Denied] on every other
    ///   gesture group within the widget, and every gesture on parent widgets
    ///   in the propagation chain.
    /// - Emitting [`cancel`][struct@crate::Gesture#cancel] on every gesture in widgets
    ///   underneath in the propagation chain.
    /// - Stopping event propagation after the gesture group handles the event.
    ///
    /// Note: if a sequence is set early to [`EventSequenceState::Claimed`][crate::EventSequenceState::Claimed] on
    /// `GDK_TOUCH_BEGIN`/`GDK_BUTTON_PRESS` (so those events are captured before
    /// reaching the event widget, this implies [`PropagationPhase::Capture`][crate::PropagationPhase::Capture]), one similar
    /// event will be emulated if the sequence changes to [`EventSequenceState::Denied`][crate::EventSequenceState::Denied].
    /// This way event coherence is preserved before event propagation is unstopped
    /// again.
    ///
    /// Sequence states can't be changed freely.
    /// See [`GestureExt::set_state()`][crate::prelude::GestureExt::set_state()] to know about the possible
    /// lifetimes of a [`gdk::EventSequence`][crate::gdk::EventSequence].
    ///
    /// ## Touchpad gestures
    ///
    /// On the platforms that support it, [`Gesture`][crate::Gesture] will handle transparently
    /// touchpad gesture events. The only precautions users of [`Gesture`][crate::Gesture] should
    /// do to enable this support are:
    ///
    /// - If the gesture has [`PropagationPhase::None`][crate::PropagationPhase::None], ensuring events of type
    ///   `GDK_TOUCHPAD_SWIPE` and `GDK_TOUCHPAD_PINCH` are handled by the [`Gesture`][crate::Gesture]
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `n-points`
    ///  The number of touch points that trigger
    /// recognition on this gesture.
    ///
    /// Readable | Writable | Construct Only
    /// <details><summary><h4>EventController</h4></summary>
    ///
    ///
    /// #### `name`
    ///  The name for this controller, typically used for debugging purposes.
    ///
    /// Readable | Writable
    ///
    ///
    /// #### `propagation-limit`
    ///  The limit for which events this controller will handle.
    ///
    /// Readable | Writable
    ///
    ///
    /// #### `propagation-phase`
    ///  The propagation phase at which this controller will handle events.
    ///
    /// Readable | Writable
    ///
    ///
    /// #### `widget`
    ///  The widget receiving the `GdkEvents` that the controller will handle.
    ///
    /// Readable
    /// </details>
    ///
    /// ## Signals
    ///
    ///
    /// #### `begin`
    ///  Emitted when the gesture is recognized.
    ///
    /// This means the number of touch sequences matches
    /// [`n-points`][struct@crate::Gesture#n-points].
    ///
    /// Note: These conditions may also happen when an extra touch
    /// (eg. a third touch on a 2-touches gesture) is lifted, in that
    /// situation @sequence won't pertain to the current set of active
    /// touches, so don't rely on this being true.
    ///
    ///
    ///
    ///
    /// #### `cancel`
    ///  Emitted whenever a sequence is cancelled.
    ///
    /// This usually happens on active touches when
    /// [`EventControllerExt::reset()`][crate::prelude::EventControllerExt::reset()] is called on @gesture
    /// (manually, due to grabs...), or the individual @sequence
    /// was claimed by parent widgets' controllers (see
    /// [`GestureExt::set_sequence_state()`][crate::prelude::GestureExt::set_sequence_state()]).
    ///
    /// @gesture must forget everything about @sequence as in
    /// response to this signal.
    ///
    ///
    ///
    ///
    /// #### `end`
    ///  Emitted when @gesture either stopped recognizing the event
    /// sequences as something to be handled, or the number of touch
    /// sequences became higher or lower than [`n-points`][struct@crate::Gesture#n-points].
    ///
    /// Note: @sequence might not pertain to the group of sequences that
    /// were previously triggering recognition on @gesture (ie. a just
    /// pressed touch sequence that exceeds [`n-points`][struct@crate::Gesture#n-points]).
    /// This situation may be detected by checking through
    /// [`GestureExt::handles_sequence()`][crate::prelude::GestureExt::handles_sequence()].
    ///
    ///
    ///
    ///
    /// #### `sequence-state-changed`
    ///  Emitted whenever a sequence state changes.
    ///
    /// See [`GestureExt::set_sequence_state()`][crate::prelude::GestureExt::set_sequence_state()] to know
    /// more about the expectable sequence lifetimes.
    ///
    ///
    ///
    ///
    /// #### `update`
    ///  Emitted whenever an event is handled while the gesture is recognized.
    ///
    /// @sequence is guaranteed to pertain to the set of active touches.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`GestureExt`][trait@crate::prelude::GestureExt], [`EventControllerExt`][trait@crate::prelude::EventControllerExt], [`trait@glib::ObjectExt`], [`EventControllerExtManual`][trait@crate::prelude::EventControllerExtManual]
    #[doc(alias = "GtkGesture")]
    pub struct Gesture(Object<ffi::GtkGesture, ffi::GtkGestureClass>) @extends EventController;

    match fn {
        type_ => || ffi::gtk_gesture_get_type(),
    }
}

impl Gesture {
    pub const NONE: Option<&'static Gesture> = None;
}

/// Trait containing all [`struct@Gesture`] methods.
///
/// # Implementors
///
/// [`GestureRotate`][struct@crate::GestureRotate], [`GestureSingle`][struct@crate::GestureSingle], [`GestureZoom`][struct@crate::GestureZoom], [`Gesture`][struct@crate::Gesture]
pub trait GestureExt: IsA<Gesture> + 'static {
    /// If there are touch sequences being currently handled by @self,
    /// returns [`true`] and fills in @rect with the bounding box containing
    /// all active touches.
    ///
    /// Otherwise, [`false`] will be returned.
    ///
    /// Note: This function will yield unexpected results on touchpad
    /// gestures. Since there is no correlation between physical and
    /// pixel distances, these will look as if constrained in an
    /// infinitely small area, @rect width and height will thus be 0
    /// regardless of the number of touchpoints.
    ///
    /// # Returns
    ///
    /// [`true`] if there are active touches, [`false`] otherwise
    ///
    /// ## `rect`
    /// bounding box containing all active touches.
    #[doc(alias = "gtk_gesture_get_bounding_box")]
    #[doc(alias = "get_bounding_box")]
    fn bounding_box(&self) -> Option<gdk::Rectangle> {
        unsafe {
            let mut rect = gdk::Rectangle::uninitialized();
            let ret = from_glib(ffi::gtk_gesture_get_bounding_box(
                self.as_ref().to_glib_none().0,
                rect.to_glib_none_mut().0,
            ));
            if ret { Some(rect) } else { None }
        }
    }

    /// If there are touch sequences being currently handled by @self,
    /// returns [`true`] and fills in @x and @y with the center of the bounding
    /// box containing all active touches.
    ///
    /// Otherwise, [`false`] will be returned.
    ///
    /// # Returns
    ///
    /// [`false`] if no active touches are present, [`true`] otherwise
    ///
    /// ## `x`
    /// X coordinate for the bounding box center
    ///
    /// ## `y`
    /// Y coordinate for the bounding box center
    #[doc(alias = "gtk_gesture_get_bounding_box_center")]
    #[doc(alias = "get_bounding_box_center")]
    fn bounding_box_center(&self) -> Option<(f64, f64)> {
        unsafe {
            let mut x = std::mem::MaybeUninit::uninit();
            let mut y = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gtk_gesture_get_bounding_box_center(
                self.as_ref().to_glib_none().0,
                x.as_mut_ptr(),
                y.as_mut_ptr(),
            ));
            if ret {
                Some((x.assume_init(), y.assume_init()))
            } else {
                None
            }
        }
    }

    /// Returns the logical [`gdk::Device`][crate::gdk::Device] that is currently operating
    /// on @self.
    ///
    /// This returns [`None`] if the gesture is not being interacted.
    ///
    /// # Returns
    ///
    /// a [`gdk::Device`][crate::gdk::Device]
    #[doc(alias = "gtk_gesture_get_device")]
    #[doc(alias = "get_device")]
    fn device(&self) -> Option<gdk::Device> {
        unsafe { from_glib_none(ffi::gtk_gesture_get_device(self.as_ref().to_glib_none().0)) }
    }

    /// Returns all gestures in the group of @self
    ///
    /// # Returns
    ///
    /// The list
    ///   of [`Gesture`][crate::Gesture]s, free with g_list_free()
    #[doc(alias = "gtk_gesture_get_group")]
    #[doc(alias = "get_group")]
    fn group(&self) -> Vec<Gesture> {
        unsafe {
            FromGlibPtrContainer::from_glib_container(ffi::gtk_gesture_get_group(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Returns the last event that was processed for @sequence.
    ///
    /// Note that the returned pointer is only valid as long as the
    /// @sequence is still interpreted by the @self. If in doubt,
    /// you should make a copy of the event.
    /// ## `sequence`
    /// a [`gdk::EventSequence`][crate::gdk::EventSequence]
    ///
    /// # Returns
    ///
    /// The last event from @sequence
    #[doc(alias = "gtk_gesture_get_last_event")]
    #[doc(alias = "get_last_event")]
    fn last_event(&self, sequence: Option<&gdk::EventSequence>) -> Option<gdk::Event> {
        unsafe {
            from_glib_none(ffi::gtk_gesture_get_last_event(
                self.as_ref().to_glib_none().0,
                mut_override(sequence.to_glib_none().0),
            ))
        }
    }

    /// Returns the [`gdk::EventSequence`][crate::gdk::EventSequence] that was last updated on @self.
    ///
    /// # Returns
    ///
    /// The last updated sequence
    #[doc(alias = "gtk_gesture_get_last_updated_sequence")]
    #[doc(alias = "get_last_updated_sequence")]
    fn last_updated_sequence(&self) -> Option<gdk::EventSequence> {
        unsafe {
            from_glib_none(ffi::gtk_gesture_get_last_updated_sequence(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// If @sequence is currently being interpreted by @self,
    /// returns [`true`] and fills in @x and @y with the last coordinates
    /// stored for that event sequence.
    ///
    /// The coordinates are always relative to the widget allocation.
    /// ## `sequence`
    /// a [`gdk::EventSequence`][crate::gdk::EventSequence], or [`None`] for pointer events
    ///
    /// # Returns
    ///
    /// [`true`] if @sequence is currently interpreted
    ///
    /// ## `x`
    /// return location for X axis of the sequence coordinates
    ///
    /// ## `y`
    /// return location for Y axis of the sequence coordinates
    #[doc(alias = "gtk_gesture_get_point")]
    #[doc(alias = "get_point")]
    fn point(&self, sequence: Option<&gdk::EventSequence>) -> Option<(f64, f64)> {
        unsafe {
            let mut x = std::mem::MaybeUninit::uninit();
            let mut y = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gtk_gesture_get_point(
                self.as_ref().to_glib_none().0,
                mut_override(sequence.to_glib_none().0),
                x.as_mut_ptr(),
                y.as_mut_ptr(),
            ));
            if ret {
                Some((x.assume_init(), y.assume_init()))
            } else {
                None
            }
        }
    }

    /// Returns the @sequence state, as seen by @self.
    /// ## `sequence`
    /// a [`gdk::EventSequence`][crate::gdk::EventSequence]
    ///
    /// # Returns
    ///
    /// The sequence state in @self
    #[doc(alias = "gtk_gesture_get_sequence_state")]
    #[doc(alias = "get_sequence_state")]
    fn sequence_state(&self, sequence: &gdk::EventSequence) -> EventSequenceState {
        unsafe {
            from_glib(ffi::gtk_gesture_get_sequence_state(
                self.as_ref().to_glib_none().0,
                mut_override(sequence.to_glib_none().0),
            ))
        }
    }

    /// Returns the list of `GdkEventSequences` currently being interpreted
    /// by @self.
    ///
    /// # Returns
    ///
    /// A list
    ///   of [`gdk::EventSequence`][crate::gdk::EventSequence], the list elements are owned by GTK and must
    ///   not be freed or modified, the list itself must be deleted
    ///   through g_list_free()
    #[doc(alias = "gtk_gesture_get_sequences")]
    #[doc(alias = "get_sequences")]
    fn sequences(&self) -> Vec<gdk::EventSequence> {
        unsafe {
            FromGlibPtrContainer::from_glib_container(ffi::gtk_gesture_get_sequences(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Adds @gesture to the same group than @self.
    ///
    /// Gestures are by default isolated in their own groups.
    ///
    /// Both gestures must have been added to the same widget before
    /// they can be grouped.
    ///
    /// When gestures are grouped, the state of `GdkEventSequences`
    /// is kept in sync for all of those, so calling
    /// [`set_sequence_state()`][Self::set_sequence_state()], on one will transfer
    /// the same value to the others.
    ///
    /// Groups also perform an "implicit grabbing" of sequences, if a
    /// [`gdk::EventSequence`][crate::gdk::EventSequence] state is set to [`EventSequenceState::Claimed`][crate::EventSequenceState::Claimed]
    /// on one group, every other gesture group attached to the same
    /// [`Widget`][crate::Widget] will switch the state for that sequence to
    /// [`EventSequenceState::Denied`][crate::EventSequenceState::Denied].
    /// ## `gesture`
    /// a [`Gesture`][crate::Gesture]
    #[doc(alias = "gtk_gesture_group")]
    #[doc(alias = "group")]
    fn group_with(&self, gesture: &impl IsA<Gesture>) {
        unsafe {
            ffi::gtk_gesture_group(
                self.as_ref().to_glib_none().0,
                gesture.as_ref().to_glib_none().0,
            );
        }
    }

    /// Returns [`true`] if @self is currently handling events
    /// corresponding to @sequence.
    /// ## `sequence`
    /// a [`gdk::EventSequence`][crate::gdk::EventSequence]
    ///
    /// # Returns
    ///
    /// [`true`] if @self is handling @sequence, [`false`] otherwise
    #[doc(alias = "gtk_gesture_handles_sequence")]
    fn handles_sequence(&self, sequence: Option<&gdk::EventSequence>) -> bool {
        unsafe {
            from_glib(ffi::gtk_gesture_handles_sequence(
                self.as_ref().to_glib_none().0,
                mut_override(sequence.to_glib_none().0),
            ))
        }
    }

    /// Returns [`true`] if the gesture is currently active.
    ///
    /// A gesture is active while there are touch sequences
    /// interacting with it.
    ///
    /// # Returns
    ///
    /// [`true`] if gesture is active
    #[doc(alias = "gtk_gesture_is_active")]
    fn is_active(&self) -> bool {
        unsafe { from_glib(ffi::gtk_gesture_is_active(self.as_ref().to_glib_none().0)) }
    }

    /// Returns [`true`] if both gestures pertain to the same group.
    /// ## `other`
    /// another [`Gesture`][crate::Gesture]
    ///
    /// # Returns
    ///
    /// whether the gestures are grouped
    #[doc(alias = "gtk_gesture_is_grouped_with")]
    fn is_grouped_with(&self, other: &impl IsA<Gesture>) -> bool {
        unsafe {
            from_glib(ffi::gtk_gesture_is_grouped_with(
                self.as_ref().to_glib_none().0,
                other.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Returns [`true`] if the gesture is currently recognized.
    ///
    /// A gesture is recognized if there are as many interacting
    /// touch sequences as required by @self.
    ///
    /// # Returns
    ///
    /// [`true`] if gesture is recognized
    #[doc(alias = "gtk_gesture_is_recognized")]
    fn is_recognized(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_gesture_is_recognized(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    ///  Denied
    ///
    /// Note: Due to event handling ordering, it may be unsafe to set the
    /// state on another gesture within a [`begin`][struct@crate::Gesture#begin] signal
    /// handler, as the callback might be executed before the other gesture
    /// knows about the sequence. A safe way to perform this could be:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// static void
    /// first_gesture_begin_cb (GtkGesture       *first_gesture,
    ///                         GdkEventSequence *sequence,
    ///                         gpointer          user_data)
    /// {
    ///   gtk_gesture_set_sequence_state (first_gesture, sequence, GTK_EVENT_SEQUENCE_CLAIMED);
    ///   gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
    /// }
    ///
    /// static void
    /// second_gesture_begin_cb (GtkGesture       *second_gesture,
    ///                          GdkEventSequence *sequence,
    ///                          gpointer          user_data)
    /// {
    ///   if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED)
    ///     gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
    /// }
    /// ```
    ///
    /// If both gestures are in the same group, just set the state on
    /// the gesture emitting the event, the sequence will be already
    /// be initialized to the group's global state when the second
    /// gesture processes the event.
    ///
    /// # Deprecated since 4.10
    ///
    /// Use [`set_state()`][Self::set_state()]
    /// ## `sequence`
    /// a [`gdk::EventSequence`][crate::gdk::EventSequence]
    /// ## `state`
    /// the sequence state
    ///
    /// # Returns
    ///
    /// [`true`] if @sequence is handled by @self,
    ///   and the state is changed successfully
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_gesture_set_sequence_state")]
    fn set_sequence_state(&self, sequence: &gdk::EventSequence, state: EventSequenceState) -> bool {
        unsafe {
            from_glib(ffi::gtk_gesture_set_sequence_state(
                self.as_ref().to_glib_none().0,
                mut_override(sequence.to_glib_none().0),
                state.into_glib(),
            ))
        }
    }

    ///  Denied
    ///
    /// Note: Due to event handling ordering, it may be unsafe to set the
    /// state on another gesture within a [`begin`][struct@crate::Gesture#begin] signal
    /// handler, as the callback might be executed before the other gesture
    /// knows about the sequence. A safe way to perform this could be:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// static void
    /// first_gesture_begin_cb (GtkGesture       *first_gesture,
    ///                         GdkEventSequence *sequence,
    ///                         gpointer          user_data)
    /// {
    ///   gtk_gesture_set_state (first_gesture, GTK_EVENT_SEQUENCE_CLAIMED);
    ///   gtk_gesture_set_state (second_gesture, GTK_EVENT_SEQUENCE_DENIED);
    /// }
    ///
    /// static void
    /// second_gesture_begin_cb (GtkGesture       *second_gesture,
    ///                          GdkEventSequence *sequence,
    ///                          gpointer          user_data)
    /// {
    ///   if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED)
    ///     gtk_gesture_set_state (second_gesture, GTK_EVENT_SEQUENCE_DENIED);
    /// }
    /// ```
    ///
    /// If both gestures are in the same group, just set the state on
    /// the gesture emitting the event, the sequence will be already
    /// be initialized to the group's global state when the second
    /// gesture processes the event.
    /// ## `state`
    /// the sequence state
    ///
    /// # Returns
    ///
    /// [`true`] if the state of at least one sequence
    ///   was changed successfully
    #[doc(alias = "gtk_gesture_set_state")]
    fn set_state(&self, state: EventSequenceState) -> bool {
        unsafe {
            from_glib(ffi::gtk_gesture_set_state(
                self.as_ref().to_glib_none().0,
                state.into_glib(),
            ))
        }
    }

    /// Separates @self into an isolated group.
    #[doc(alias = "gtk_gesture_ungroup")]
    fn ungroup(&self) {
        unsafe {
            ffi::gtk_gesture_ungroup(self.as_ref().to_glib_none().0);
        }
    }

    /// The number of touch points that trigger
    /// recognition on this gesture.
    #[doc(alias = "n-points")]
    fn n_points(&self) -> u32 {
        ObjectExt::property(self.as_ref(), "n-points")
    }

    /// Emitted when the gesture is recognized.
    ///
    /// This means the number of touch sequences matches
    /// [`n-points`][struct@crate::Gesture#n-points].
    ///
    /// Note: These conditions may also happen when an extra touch
    /// (eg. a third touch on a 2-touches gesture) is lifted, in that
    /// situation @sequence won't pertain to the current set of active
    /// touches, so don't rely on this being true.
    /// ## `sequence`
    /// the [`gdk::EventSequence`][crate::gdk::EventSequence] that made the gesture
    ///   to be recognized
    #[doc(alias = "begin")]
    fn connect_begin<F: Fn(&Self, Option<&gdk::EventSequence>) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn begin_trampoline<
            P: IsA<Gesture>,
            F: Fn(&P, Option<&gdk::EventSequence>) + 'static,
        >(
            this: *mut ffi::GtkGesture,
            sequence: *mut gdk::ffi::GdkEventSequence,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    Gesture::from_glib_borrow(this).unsafe_cast_ref(),
                    Option::<gdk::EventSequence>::from_glib_borrow(sequence)
                        .as_ref()
                        .as_ref(),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"begin".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    begin_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted whenever a sequence is cancelled.
    ///
    /// This usually happens on active touches when
    /// [`EventControllerExt::reset()`][crate::prelude::EventControllerExt::reset()] is called on @gesture
    /// (manually, due to grabs...), or the individual @sequence
    /// was claimed by parent widgets' controllers (see
    /// [`set_sequence_state()`][Self::set_sequence_state()]).
    ///
    /// @gesture must forget everything about @sequence as in
    /// response to this signal.
    /// ## `sequence`
    /// the [`gdk::EventSequence`][crate::gdk::EventSequence] that was cancelled
    #[doc(alias = "cancel")]
    fn connect_cancel<F: Fn(&Self, Option<&gdk::EventSequence>) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn cancel_trampoline<
            P: IsA<Gesture>,
            F: Fn(&P, Option<&gdk::EventSequence>) + 'static,
        >(
            this: *mut ffi::GtkGesture,
            sequence: *mut gdk::ffi::GdkEventSequence,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    Gesture::from_glib_borrow(this).unsafe_cast_ref(),
                    Option::<gdk::EventSequence>::from_glib_borrow(sequence)
                        .as_ref()
                        .as_ref(),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"cancel".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    cancel_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted when @gesture either stopped recognizing the event
    /// sequences as something to be handled, or the number of touch
    /// sequences became higher or lower than [`n-points`][struct@crate::Gesture#n-points].
    ///
    /// Note: @sequence might not pertain to the group of sequences that
    /// were previously triggering recognition on @gesture (ie. a just
    /// pressed touch sequence that exceeds [`n-points`][struct@crate::Gesture#n-points]).
    /// This situation may be detected by checking through
    /// [`handles_sequence()`][Self::handles_sequence()].
    /// ## `sequence`
    /// the [`gdk::EventSequence`][crate::gdk::EventSequence] that made gesture
    ///   recognition to finish
    #[doc(alias = "end")]
    fn connect_end<F: Fn(&Self, Option<&gdk::EventSequence>) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn end_trampoline<
            P: IsA<Gesture>,
            F: Fn(&P, Option<&gdk::EventSequence>) + 'static,
        >(
            this: *mut ffi::GtkGesture,
            sequence: *mut gdk::ffi::GdkEventSequence,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    Gesture::from_glib_borrow(this).unsafe_cast_ref(),
                    Option::<gdk::EventSequence>::from_glib_borrow(sequence)
                        .as_ref()
                        .as_ref(),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"end".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    end_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted whenever a sequence state changes.
    ///
    /// See [`set_sequence_state()`][Self::set_sequence_state()] to know
    /// more about the expectable sequence lifetimes.
    /// ## `sequence`
    /// the [`gdk::EventSequence`][crate::gdk::EventSequence] that was cancelled
    /// ## `state`
    /// the new sequence state
    #[doc(alias = "sequence-state-changed")]
    fn connect_sequence_state_changed<
        F: Fn(&Self, Option<&gdk::EventSequence>, EventSequenceState) + 'static,
    >(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn sequence_state_changed_trampoline<
            P: IsA<Gesture>,
            F: Fn(&P, Option<&gdk::EventSequence>, EventSequenceState) + 'static,
        >(
            this: *mut ffi::GtkGesture,
            sequence: *mut gdk::ffi::GdkEventSequence,
            state: ffi::GtkEventSequenceState,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    Gesture::from_glib_borrow(this).unsafe_cast_ref(),
                    Option::<gdk::EventSequence>::from_glib_borrow(sequence)
                        .as_ref()
                        .as_ref(),
                    from_glib(state),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"sequence-state-changed".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    sequence_state_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted whenever an event is handled while the gesture is recognized.
    ///
    /// @sequence is guaranteed to pertain to the set of active touches.
    /// ## `sequence`
    /// the [`gdk::EventSequence`][crate::gdk::EventSequence] that was updated
    #[doc(alias = "update")]
    fn connect_update<F: Fn(&Self, Option<&gdk::EventSequence>) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn update_trampoline<
            P: IsA<Gesture>,
            F: Fn(&P, Option<&gdk::EventSequence>) + 'static,
        >(
            this: *mut ffi::GtkGesture,
            sequence: *mut gdk::ffi::GdkEventSequence,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    Gesture::from_glib_borrow(this).unsafe_cast_ref(),
                    Option::<gdk::EventSequence>::from_glib_borrow(sequence)
                        .as_ref()
                        .as_ref(),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"update".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    update_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Gesture>> GestureExt for O {}