Gtk.Gesture

Gtk.Gesture — Base class for gestures

Object Hierarchy:

    GObject
    ╰── Gtk.EventController
        ╰── Gtk.Gesture
            ├── Gtk.GestureSingle
            ├── Gtk.GestureRotate
            ╰── Gtk.GestureZoom

See also:

Gtk.EventController, Gtk.GestureSingle

Functions:

Signals:

  • “begin” (gesture, sequence, user_data)
  • “cancel” (gesture, sequence, user_data)
  • “end” (gesture, sequence, user_data)
  • “sequence-state-changed” (gesture, sequence, state, user_data)

Description:

Gtk.Gesture is the base object for gesture recognition, although this object 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 #GdkEventSequence value for these).

The number of touches that a Gtk.Gesture need to be recognized is controlled or more than that number of sequences, it won't check wether the gesture is recognized.

As soon as the gesture has the expected number of touches, the gesture will is recognized, the criteria to consider a gesture as "recognized" is left to Gtk.Gesture subclasses.

A recognized gesture will then emit the following signals:

  • A number of Gtk.Gesture::update, whenever an input event is processed.
Event propagation

In order to receive events, a gesture needs to either set a propagation phase through Gtk.EventController::set_propagation_phase(), or feed those manually through Gtk.EventController::handle_event().

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.

After the capture phase, GTK+ emits the traditional Gtk.Widget::button-press, with the %GTK_PHASE_TARGET phase are fed events from the default Gtk.Widget::event handlers.

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 Gtk.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 #GdkEventSequences triggering those.

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

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

  • Setting the same sequence to #GTK_EVENT_SEQUENCE_DENIED on every other gesture group within the widget, and every gesture on parent widgets in the propagation chain.

  • calling Gtk.Gesture::cancel on every gesture in widgets underneath in the propagation chain.

  • Stopping event propagation after the gesture group handles the event.

GDK_TOUCH_BEGIN/#GDK_BUTTON_PRESS (so those events are captured before reaching the event widget, this implies #GTK_PHASE_CAPTURE), one similar event will emulated if the sequence changes to #GTK_EVENT_SEQUENCE_DENIED.

This way event coherence is preserved before event propagation is unstopped again.

Sequence states can't be changed freely, see Gtk.Gesture::set_sequence_state() to know about the possible lifetimes of a Gdk.EventSequence.

Touchpad gestures

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

  • Enabling %GDK_TOUCHPAD_GESTURE_MASK on their Gdk.Windows
  • If the gesture has %GTK_PHASE_NONE, ensuring events of type %GDK_TOUCHPAD_SWIPE and %GDK_TOUCHPAD_PINCH are handled by the Gtk.Gesture

Function Details:

get_device()

get_device (self) -> Gdk.Device

Returns the master GdkDevice that is currently operatingon gesture, or None if the gesture is not being interacted.

  • Returns: a GdkDevice, or None.

  • Since: 3.14

get_window()

get_window (self) -> Gdk.Window

Returns the user-defined window that receives the eventshandled by gesture. See Gtk.Gesture:set_window() for moreinformation.

  • Returns: the user defined window, or None if none.

  • Since: 3.14

set_window()

set_window (self, window:Gdk.Window=None)

Sets a specific window to receive events about, so gesturewill effectively handle only events targeting window, ora child of it. window must pertain to `Gtk.EventController:get_widget()`.

  • Since: 3.14

is_active()

is_active (self) -> bool

Returns True if the gesture is currently active.A gesture is active meanwhile there are touch sequencesinteracting with it.

  • Returns: True if gesture is active

  • Since: 3.14

is_recognized()

is_recognized (self) -> bool

Returns True if the gesture is currently recognized.A gesture is recognized if there are as many interactingtouch sequences as required by gesture, and “check”returned True for the sequences being currently interpreted.

  • Returns: True if gesture is recognized

  • Since: 3.14

get_sequence_state()

get_sequence_state (self, sequence:Gdk.EventSequence) -> Gtk.EventSequenceState

Returns the sequence state, as seen by gesture.

  • Returns: The sequence state in gesture

  • Since: 3.14

set_sequence_state()

set_sequence_state (self, sequence:Gdk.EventSequence, state:Gtk.EventSequenceState) -> bool

Sets the state of sequence in gesture. Sequences startin state GTK_EVENT_SEQUENCE_NONE, and whenever they changestate, they can never go back to that state. Likewise,sequences in state GTK_EVENT_SEQUENCE_DENIED cannot turnback to a not denied state. With these rules, the lifetimeof an event sequence is constrained to the next four: None None → Denied None → Claimed None → Claimed → Denied Note: Due to event handling ordering, it may be unsafe toset the state on another gesture within a “begin”signal handler, as the callback might be executed beforethe other gesture knows about the sequence. A safe way toperform this could be: static voidfirst_gesture_begin_cb (Gtk.Gesture first_gesture, GdkEventSequence sequence, gpointer user_data){ Gtk.Gesture:set_sequence_state (first_gesture, sequence, GTK_EVENT_SEQUENCE_ACCEPTED); Gtk.Gesture:set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);}static voidsecond_gesture_begin_cb (Gtk.Gesture second_gesture, GdkEventSequence sequence, gpointer user_data){ if (Gtk.Gesture:get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_ACCEPTED) Gtk.Gesture:set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);} If both gestures are in the same group, just set the state onthe gesture emitting the event, the sequence will be alreadybe initialized to the group's global state when the secondgesture processes the event.

  • Returns: True if sequenceis handled by gesture,and the state is changed successfully

  • Since: 3.14

set_state()

set_state (self, state:Gtk.EventSequenceState) -> bool

Sets the state of all sequences that gesture is currentlyinteracting with. See Gtk.Gesture:set_sequence_state()for more details on sequence states.

  • Returns: True if the state of at least one sequencewas changed successfully

  • Since: 3.14

get_sequences()

get_sequences (self) -> list

Returns the list of GdkEventSequences currently being interpretedby gesture.

  • Returns: A listof GdkEventSequences, the list elements are owned by GTK+and must not be freed or modified, the list itself must be deletedthrough g_list_free().

  • Since: 3.14

handles_sequence()

handles_sequence (self, sequence:Gdk.EventSequence) -> bool

Returns True if gesture is currently handling events corresponding tosequence.

  • Returns: True if gestureis handling sequence

  • Since: 3.14

get_last_updated_sequence()

get_last_updated_sequence (self) -> Gdk.EventSequence or None

Returns the GdkEventSequence that was last updated on gesture.

  • Returns: The last updated sequence.

  • Since: 3.14

get_last_event()

get_last_event (self, sequence:Gdk.EventSequence) -> Gdk.Event or None

Returns the last event that was processed for sequence.

  • Returns: The last event from sequence.

get_point()

get_point (self, sequence:Gdk.EventSequence=None) -> bool, x:float, y:float

If sequence is currently being interpreted by gesture, thisfunction returns True and fills in x and y with the last coordinatesstored for that event sequence. The coordinates are always relative to thewidget allocation.

  • Returns: True if sequenceis currently interpreted

  • Since: 3.14

get_bounding_box()

get_bounding_box (self) -> bool, rect:Gdk.Rectangle

If there are touch sequences being currently handled by gesture,this function returns True and fills in rect with the boundingbox containing all active touches. Otherwise, FALSE will bereturned. Note: This function will yield unexpected results on touchpadgestures. Since there is no correlation between physical andpixel distances, these will look as if constrained in aninfinitely small area, rect width and height will thus be 0regardless of the number of touchpoints.

  • Returns: True if there are active touches, FALSE otherwise

  • Since: 3.14

get_bounding_box_center()

get_bounding_box_center (self) -> bool, x:float, y:float

If there are touch sequences being currently handled by gesture,this function returns True and fills in x and y with the centerof the bounding box containing all active touches. Otherwise, FALSEwill be returned.

  • Returns: FALSE if no active touches are present, True otherwise

  • Since: 3.14

group()

group (self, gesture:Gtk.Gesture)

Adds gesture to the same group than group_gesture. Gesturesare by default isolated in their own groups. When gestures are grouped, the state of GdkEventSequencesis kept in sync for all of those, so calling Gtk.Gesture:set_sequence_state(),on one will transfer the same value to the others. Groups also perform an "implicit grabbing" of sequences, if aGdkEventSequence state is set to GTK_EVENT_SEQUENCE_CLAIMED on one group,every other gesture group attached to the same Gtk.Widget will switch thestate for that sequence to GTK_EVENT_SEQUENCE_DENIED.

  • Since: 3.14

ungroup()

ungroup (self)

Separates gesture into an isolated group.

  • Since: 3.14

get_group()

get_group (self) -> list

Returns all gestures in the group of gesture

  • Returns: The listof Gtk.Gestures, free with g_list_free().

  • Since: 3.14

is_grouped_with()

is_grouped_with (self, other:Gtk.Gesture) -> bool

Returns True if both gestures pertain to the same group.

  • Returns: whether the gestures are grouped

  • Since: 3.14

results matching ""

    No results matching ""