Struct gtk4::Gesture[][src]

pub struct Gesture(_);
Expand description

Gesture is the base class for gesture recognition.

Although 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 value for these).

The number of touches that a Gesture need to be recognized is controlled by the property::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 subclasses.

A recognized gesture will then emit the following signals:

  • signal::Gesture::begin when the gesture is recognized.
  • signal::Gesture::update, whenever an input event is processed.
  • signal::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().

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 Gestures, 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::EventSequences triggering those.

Within a widget, gestures can be grouped through GestureExt::group_with(). Grouped gestures synchronize the state of sequences, so calling GestureExt::set_sequence_state() on one will effectively propagate the state throughout the group.

By default, all sequences start out in the 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 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 state, the gesture group will grab all interaction on the sequence, by:

  • Setting the same sequence to EventSequenceState::Denied on every other gesture group within the widget, and every gesture on parent widgets in the propagation chain.
  • Emitting signal::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 on GDK_TOUCH_BEGIN/GDK_BUTTON_PRESS (so those events are captured before reaching the event widget, this implies PropagationPhase::Capture), one similar event will emulated if the sequence changes to EventSequenceState::Denied. This way event coherence is preserved before event propagation is unstopped again.

Sequence states can’t be changed freely. See GestureExt::set_sequence_state() to know about the possible lifetimes of a gdk::EventSequence.

Touchpad gestures

On the platforms that support it, Gesture will handle transparently touchpad gesture events. The only precautions users of Gesture should do to enable this support are:

This is an Abstract Base Class, you cannot instantiate it.

Implements

GestureExt, EventControllerExt, glib::ObjectExt

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Formats the value using the given formatter. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Returns the type identifier of Self.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Upcasts an object to a superclass or interface T. Read more

Upcasts an object to a reference of its superclass or interface T. Read more

Tries to downcast to a subclass or interface implementor T. Read more

Tries to downcast to a reference of its subclass or interface implementor T. Read more

Tries to cast to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more

Tries to cast to reference to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more

Casts to T unconditionally. Read more

Casts to &T unconditionally. Read more

Performs the conversion.

Performs the conversion.

Returns true if the object is an instance of (can be cast to) T.

Safety Read more

Safety Read more

Safety Read more

Safety Read more

Safety Read more

Safety Read more

Same as connect but takes a SignalId instead of a signal name.

Same as connect_local but takes a SignalId instead of a signal name.

Same as connect_unsafe but takes a SignalId instead of a signal name.

Emit signal by signal id.

Same as emit but takes Value for the arguments.

Emit signal by its name.

Same as emit_by_name but takes Value for the arguments.

Emit signal with details by signal id.

Same as emit_with_details but takes Value for the arguments.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

Returns a SendValue clone of self.

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.