GestureProtocol
public protocol GestureProtocol : EventControllerProtocol
GtkGesture 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 nil GdkEventSequence value for these).
The number of touches that a GtkGesture need to be recognized is controlled
by the GtkGesture:n-points property, if a gesture is keeping track of less
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
run the GtkGesture::check signal regularly on input events until the gesture
is recognized, the criteria to consider a gesture as “recognized” is left to
GtkGesture subclasses.
A recognized gesture will then emit the following signals:
GtkGesture::beginwhen the gesture is recognized.- A number of
GtkGesture::update, whenever an input event is processed. GtkGesture::endwhen the gesture is no longer recognized.
Event propagation
In order to receive events, a gesture needs to either set a propagation phase
through gtk_event_controller_set_propagation_phase(), or feed those manually
through gtk_event_controller_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 GtkWidget::button-press-event,
GtkWidget::button-release-event, GtkWidget::touch-event, etc signals. Gestures
with the GTK_PHASE_TARGET phase are fed events from the default GtkWidget::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
GtkGestures, 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_DENIEDon every other gesture group within the widget, and every gesture on parent widgets in the propagation chain. - calling
GtkGesture::cancelon 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 GTK_EVENT_SEQUENCE_CLAIMED on
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 GdkEventSequence.
Touchpad gestures
On the platforms that support it, GtkGesture will handle transparently
touchpad gesture events. The only precautions users of GtkGesture should do
to enable this support are:
- Enabling
GDK_TOUCHPAD_GESTURE_MASKon theirGdkWindows - If the gesture has
GTK_PHASE_NONE, ensuring events of typeGDK_TOUCHPAD_SWIPEandGDK_TOUCHPAD_PINCHare handled by theGtkGesture
The GestureProtocol protocol exposes the methods and properties of an underlying GtkGesture instance.
The default implementation of these can be found in the protocol extension below.
For a concrete class that implements these methods and properties, see Gesture.
Alternatively, use GestureRef as a lighweight, unowned reference if you already have an instance you just want to use.
-
Untyped pointer to the underlying
GtkGestureinstance.Declaration
Swift
var ptr: UnsafeMutableRawPointer! { get } -
gesture_ptrDefault implementationTyped pointer to the underlying
GtkGestureinstance.Default Implementation
Return the stored, untyped pointer as a typed pointer to the
GtkGestureinstance.Declaration
Swift
var gesture_ptr: UnsafeMutablePointer<GtkGesture>! { get } -
Required Initialiser for types conforming to
GestureProtocolDeclaration
Swift
init(raw: UnsafeMutableRawPointer)
-
bind(property:Extension methodto: _: flags: transformFrom: transformTo: ) Bind a
GesturePropertyNamesource property to a given target object.Declaration
Swift
@discardableResult @inlinable func bind<Q, T>(property source_property: GesturePropertyName, to target: T, _ target_property: Q, flags f: BindingFlags = .default, transformFrom transform_from: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }, transformTo transform_to: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }) -> BindingRef! where Q : PropertyNameProtocol, T : ObjectProtocolParameters
source_propertythe source property to bind
targetthe target object to bind to
target_propertythe target property to bind to
flagsthe flags to pass to the
Bindingtransform_fromValueTransformerto use for forward transformationtransform_toValueTransformerto use for backwards transformationReturn Value
binding reference or
nilin case of an error -
get(property:Extension method) Get the value of a Gesture property
Declaration
Swift
@inlinable func get(property: GesturePropertyName) -> GLibObject.ValueParameters
propertythe property to get the value for
Return Value
the value of the named property
-
set(property:Extension methodvalue: ) Set the value of a Gesture property. Note that this will only have an effect on properties that are writable and not construct-only!
Declaration
Swift
@inlinable func set(property: GesturePropertyName, value v: GLibObject.Value)Parameters
propertythe property to get the value for
Return Value
the value of the named property
-
connect(signal:Extension methodflags: handler: ) Connect a Swift signal handler to the given, typed
GestureSignalNamesignalDeclaration
Swift
@discardableResult @inlinable func connect(signal s: GestureSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> IntParameters
signalThe signal to connect
flagsThe connection flags to use
dataA pointer to user data to provide to the callback
destroyDataA
GClosureNotifyC function to destroy the data pointed to byuserDatahandlerThe Swift signal handler (function or callback) to invoke on the given signal
Return Value
The signal handler ID (always greater than 0 for successful connections)
-
connect(signal:Extension methodflags: data: destroyData: signalHandler: ) Connect a C signal handler to the given, typed
GestureSignalNamesignalDeclaration
Swift
@discardableResult @inlinable func connect(signal s: GestureSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> IntParameters
signalThe signal to connect
flagsThe connection flags to use
dataA pointer to user data to provide to the callback
destroyDataA
GClosureNotifyC function to destroy the data pointed to byuserDatasignalHandlerThe C function to be called on the given signal
Return Value
The signal handler ID (always greater than 0 for successful connections)
-
onBegin(flags:Extension methodhandler: ) This signal is emitted when the gesture is recognized. This means the number of touch sequences matches
GtkGesture:n-points, and theGtkGesture::checkhandler(s)returnedTRUE.Note: These conditions may also happen when an extra touch (eg. a third touch on a 2-touches gesture) is lifted, in that situation
sequencewon’t pertain to the current set of active touches, so don’t rely on this being true.Note
This represents the underlyingbeginsignalDeclaration
Swift
@discardableResult @inlinable func onBegin(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GestureRef, _ sequence: Gdk.EventSequenceRef?) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
sequencethe
GdkEventSequencethat made the gesture to be recognizedhandlerThe signal handler to call Run the given callback whenever the
beginsignal is emitted -
beginSignalExtension methodTyped
beginsignal for using theconnect(signal:)methodsDeclaration
Swift
static var beginSignal: GestureSignalName { get } -
onCancel(flags:Extension methodhandler: ) This signal is emitted whenever a sequence is cancelled. This usually happens on active touches when
gtk_event_controller_reset()is called ongesture(manually, due to grabs…), or the individualsequencewas claimed by parent widgets’ controllers (seegtk_gesture_set_sequence_state()).gesturemust forget everything aboutsequenceas a reaction to this signal.Note
This represents the underlyingcancelsignalDeclaration
Swift
@discardableResult @inlinable func onCancel(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GestureRef, _ sequence: Gdk.EventSequenceRef?) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
sequencethe
GdkEventSequencethat was cancelledhandlerThe signal handler to call Run the given callback whenever the
cancelsignal is emitted -
cancelSignalExtension methodTyped
cancelsignal for using theconnect(signal:)methodsDeclaration
Swift
static var cancelSignal: GestureSignalName { get } -
onEnd(flags:Extension methodhandler: ) This signal is emitted when
gestureeither stopped recognizing the event sequences as something to be handled (theGtkGesture::checkhandler returnedfalse), or the number of touch sequences became higher or lower thanGtkGesture:n-points.Note:
sequencemight not pertain to the group of sequences that were previously triggering recognition ongesture(ie. a just pressed touch sequence that exceedsGtkGesture:n-points). This situation may be detected by checking throughgtk_gesture_handles_sequence().Note
This represents the underlyingendsignalDeclaration
Swift
@discardableResult @inlinable func onEnd(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GestureRef, _ sequence: Gdk.EventSequenceRef?) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
sequencethe
GdkEventSequencethat made gesture recognition to finishhandlerThe signal handler to call Run the given callback whenever the
endsignal is emitted -
endSignalExtension methodTyped
endsignal for using theconnect(signal:)methodsDeclaration
Swift
static var endSignal: GestureSignalName { get } -
onSequenceStateChanged(flags:Extension methodhandler: ) This signal is emitted whenever a sequence state changes. See
gtk_gesture_set_sequence_state()to know more about the expectable sequence lifetimes.Note
This represents the underlyingsequence-state-changedsignalDeclaration
Swift
@discardableResult @inlinable func onSequenceStateChanged(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GestureRef, _ sequence: Gdk.EventSequenceRef?, _ state: EventSequenceState) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
sequencethe
GdkEventSequencethat was cancelledstatethe new sequence state
handlerThe signal handler to call Run the given callback whenever the
sequenceStateChangedsignal is emitted -
sequenceStateChangedSignalExtension methodTyped
sequence-state-changedsignal for using theconnect(signal:)methodsDeclaration
Swift
static var sequenceStateChangedSignal: GestureSignalName { get } -
onUpdate(flags:Extension methodhandler: ) This signal is emitted whenever an event is handled while the gesture is recognized.
sequenceis guaranteed to pertain to the set of active touches.Note
This represents the underlyingupdatesignalDeclaration
Swift
@discardableResult @inlinable func onUpdate(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GestureRef, _ sequence: Gdk.EventSequenceRef?) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
sequencethe
GdkEventSequencethat was updatedhandlerThe signal handler to call Run the given callback whenever the
updatesignal is emitted -
updateSignalExtension methodTyped
updatesignal for using theconnect(signal:)methodsDeclaration
Swift
static var updateSignal: GestureSignalName { get } -
onNotifyNPoints(flags:Extension methodhandler: ) The notify signal is emitted on an object when one of its properties has its value set through
g_object_set_property(),g_object_set(), et al.Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with
G_PARAM_EXPLICIT_NOTIFY, then any call tog_object_set_property()results innotifybeing emitted, even if the new value is the same as the old. If they did passG_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly callg_object_notify()org_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the
g_signal_connect()call, like this:(C Language Example):
g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view)It is important to note that you must use canonical parameter names as detail strings for the notify signal.
Note
This represents the underlyingnotify::n-pointssignalDeclaration
Swift
@discardableResult @inlinable func onNotifyNPoints(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GestureRef, _ pspec: ParamSpecRef) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
pspecthe
GParamSpecof the property which changed.handlerThe signal handler to call Run the given callback whenever the
notifyNPointssignal is emitted -
notifyNPointsSignalExtension methodTyped
notify::n-pointssignal for using theconnect(signal:)methodsDeclaration
Swift
static var notifyNPointsSignal: GestureSignalName { get } -
onNotifyWindow(flags:Extension methodhandler: ) The notify signal is emitted on an object when one of its properties has its value set through
g_object_set_property(),g_object_set(), et al.Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with
G_PARAM_EXPLICIT_NOTIFY, then any call tog_object_set_property()results innotifybeing emitted, even if the new value is the same as the old. If they did passG_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly callg_object_notify()org_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the
g_signal_connect()call, like this:(C Language Example):
g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view)It is important to note that you must use canonical parameter names as detail strings for the notify signal.
Note
This represents the underlyingnotify::windowsignalDeclaration
Swift
@discardableResult @inlinable func onNotifyWindow(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: GestureRef, _ pspec: ParamSpecRef) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
pspecthe
GParamSpecof the property which changed.handlerThe signal handler to call Run the given callback whenever the
notifyWindowsignal is emitted -
notifyWindowSignalExtension methodTyped
notify::windowsignal for using theconnect(signal:)methodsDeclaration
Swift
static var notifyWindowSignal: GestureSignalName { get }
-
getBoundingBox(rect:Extension method) If there are touch sequences being currently handled by
gesture, this function returnstrueand fills inrectwith the bounding box containing all active touches. Otherwise,falsewill 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,
rectwidth and height will thus be 0 regardless of the number of touchpoints.Declaration
Swift
@inlinable func getBoundingBox<RectangleT>(rect: RectangleT) -> Bool where RectangleT : RectangleProtocol -
getBoundingBoxCenter(x:Extension methody: ) If there are touch sequences being currently handled by
gesture, this function returnstrueand fills inxandywith the center of the bounding box containing all active touches. Otherwise,falsewill be returned.Declaration
Swift
@inlinable func getBoundingBoxCenter(x: UnsafeMutablePointer<gdouble>!, y: UnsafeMutablePointer<gdouble>!) -> Bool -
getDevice()Extension methodReturns the master
GdkDevicethat is currently operating ongesture, ornilif the gesture is not being interacted.Declaration
Swift
@inlinable func getDevice() -> Gdk.DeviceRef! -
getGroup()Extension methodReturns all gestures in the group of
gestureDeclaration
Swift
@inlinable func getGroup() -> GLib.ListRef! -
getLastEvent(sequence:Extension method) Returns the last event that was processed for
sequence.Note that the returned pointer is only valid as long as the
sequenceis still interpreted by thegesture. If in doubt, you should make a copy of the event.Declaration
Swift
@inlinable func getLastEvent(sequence: Gdk.EventSequenceRef? = nil) -> Gdk.EventRef! -
getLastEvent(sequence:Extension method) Returns the last event that was processed for
sequence.Note that the returned pointer is only valid as long as the
sequenceis still interpreted by thegesture. If in doubt, you should make a copy of the event.Declaration
Swift
@inlinable func getLastEvent<EventSequenceT>(sequence: EventSequenceT?) -> Gdk.EventRef! where EventSequenceT : EventSequenceProtocol -
getLastUpdatedSequence()Extension methodReturns the
GdkEventSequencethat was last updated ongesture.Declaration
Swift
@inlinable func getLastUpdatedSequence() -> Gdk.EventSequenceRef! -
getPoint(sequence:Extension methodx: y: ) If
sequenceis currently being interpreted bygesture, this function returnstrueand fills inxandywith the last coordinates stored for that event sequence. The coordinates are always relative to the widget allocation.Declaration
Swift
@inlinable func getPoint(sequence: Gdk.EventSequenceRef? = nil, x: UnsafeMutablePointer<gdouble>! = nil, y: UnsafeMutablePointer<gdouble>! = nil) -> Bool -
getPoint(sequence:Extension methodx: y: ) If
sequenceis currently being interpreted bygesture, this function returnstrueand fills inxandywith the last coordinates stored for that event sequence. The coordinates are always relative to the widget allocation.Declaration
Swift
@inlinable func getPoint<EventSequenceT>(sequence: EventSequenceT?, x: UnsafeMutablePointer<gdouble>! = nil, y: UnsafeMutablePointer<gdouble>! = nil) -> Bool where EventSequenceT : EventSequenceProtocol -
getSequenceState(sequence:Extension method) Returns the
sequencestate, as seen bygesture.Declaration
Swift
@inlinable func getSequenceState<EventSequenceT>(sequence: EventSequenceT) -> GtkEventSequenceState where EventSequenceT : EventSequenceProtocol -
getSequences()Extension methodReturns the list of
GdkEventSequencescurrently being interpreted bygesture.Declaration
Swift
@inlinable func getSequences() -> GLib.ListRef! -
getWindow()Extension methodReturns the user-defined window that receives the events handled by
gesture. Seegtk_gesture_set_window()for more information.Declaration
Swift
@inlinable func getWindow() -> Gdk.WindowRef! -
getGroup(gesture:Extension method) Adds
gestureto the same group thangroup_gesture. Gestures are by default isolated in their own groups.When gestures are grouped, the state of
GdkEventSequencesis kept in sync for all of those, so callinggtk_gesture_set_sequence_state(), on one will transfer the same value to the others.Groups also perform an “implicit grabbing” of sequences, if a
GdkEventSequencestate is set toGTK_EVENT_SEQUENCE_CLAIMEDon one group, every other gesture group attached to the sameGtkWidgetwill switch the state for that sequence toGTK_EVENT_SEQUENCE_DENIED.Declaration
Swift
@inlinable func getGroup<GestureT>(gesture: GestureT) where GestureT : GestureProtocol -
handles(sequence:Extension method) Returns
trueifgestureis currently handling events corresponding tosequence.Declaration
Swift
@inlinable func handles(sequence: Gdk.EventSequenceRef? = nil) -> Bool -
handles(sequence:Extension method) Returns
trueifgestureis currently handling events corresponding tosequence.Declaration
Swift
@inlinable func handles<EventSequenceT>(sequence: EventSequenceT?) -> Bool where EventSequenceT : EventSequenceProtocol -
isGroupedWith(other:Extension method) Returns
trueif both gestures pertain to the same group.Declaration
Swift
@inlinable func isGroupedWith<GestureT>(other: GestureT) -> Bool where GestureT : GestureProtocol -
setSequenceState(sequence:Extension methodstate: ) Sets the state of
sequenceingesture. Sequences start in stateGTK_EVENT_SEQUENCE_NONE, and whenever they change state, they can never go back to that state. Likewise, sequences in stateGTK_EVENT_SEQUENCE_DENIEDcannot turn back to a not denied state. With these rules, the lifetime of 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 to set the state on another gesture within a
GtkGesture::beginsignal handler, as the callback might be executed before the other gesture knows about the sequence. A safe way to perform this could be: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.
Declaration
Swift
@inlinable func setSequenceState<EventSequenceT>(sequence: EventSequenceT, state: GtkEventSequenceState) -> Bool where EventSequenceT : EventSequenceProtocol -
set(state:Extension method) Sets the state of all sequences that
gestureis currently interacting with. Seegtk_gesture_set_sequence_state()for more details on sequence states.Declaration
Swift
@inlinable func set(state: GtkEventSequenceState) -> Bool -
set(window:Extension method) -
set(window:Extension method) Sets a specific window to receive events about, so
gesturewill effectively handle only events targetingwindow, or a child of it.windowmust pertain togtk_event_controller_get_widget().Declaration
Swift
@inlinable func set<WindowT>(window: WindowT?) where WindowT : WindowProtocol -
ungroup()Extension methodSeparates
gestureinto an isolated group.Declaration
Swift
@inlinable func ungroup() -
deviceExtension methodReturns the master
GdkDevicethat is currently operating ongesture, ornilif the gesture is not being interacted.Declaration
Swift
@inlinable var device: Gdk.DeviceRef! { get } -
groupExtension methodReturns all gestures in the group of
gestureDeclaration
Swift
@inlinable var group: GLib.ListRef! { get } -
isActiveExtension methodReturns
trueif the gesture is currently active. A gesture is active meanwhile there are touch sequences interacting with it.Declaration
Swift
@inlinable var isActive: Bool { get } -
isRecognizedExtension methodReturns
trueif the gesture is currently recognized. A gesture is recognized if there are as many interacting touch sequences as required bygesture, andGtkGesture::checkreturnedtruefor the sequences being currently interpreted.Declaration
Swift
@inlinable var isRecognized: Bool { get } -
lastUpdatedSequenceExtension methodReturns the
GdkEventSequencethat was last updated ongesture.Declaration
Swift
@inlinable var lastUpdatedSequence: Gdk.EventSequenceRef! { get } -
sequencesExtension methodReturns the list of
GdkEventSequencescurrently being interpreted bygesture.Declaration
Swift
@inlinable var sequences: GLib.ListRef! { get } -
windowExtension methodIf non-
nil, the gesture will only listen for events that happen on thisGdkWindow, or a child of it.Declaration
Swift
@inlinable var window: Gdk.WindowRef! { get nonmutating set }
View on GitHub
Install in Dash
GestureProtocol Protocol Reference