callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

gesture: doc fixes

Browse Source
This commit is contained in:
Carlos Garnacho 2014-04-10 13:43:15 +02:00
parent dbc7f011b3
commit ec50d776ce
1 changed files with 39 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
gtk/gtkgesture.c
View File

@ -35,19 +35,20 @@
* is recognized. * is recognized.
* *
* As soon as the gesture has the expected number of touches, the gesture will * As soon as the gesture has the expected number of touches, the gesture will
* run the #GtkGesture:check signal regularly on input events, #GtkGesture * run the #GtkGesture::check signal regularly on input events until the gesture
* subclasses define there the criteria to consider a gesture as "recognized". * is recognized, the criteria to consider a gesture as "recognized" is left to
* #GtkGesture subclasses.
* *
* A recognized gesture will then emit the following signals: * A recognized gesture will then emit the following signals:
* - #GtkGesture:begin when the gesture is recognized. * - #GtkGesture::begin when the gesture is recognized.
* - A number of #GtkGesture:update, whenever an input event is processed. * - A number of #GtkGesture::update, whenever an input event is processed.
* - #GtkGesture:end when the gesture is no longer recognized. * - #GtkGesture::end when the gesture is no longer recognized.
* *
* ## States of a sequence # {#touch-sequence-states} * ## States of a sequence # {#touch-sequence-states}
* *
* Whenever input interaction happens, a single event may trigger a cascade of * Whenever input interaction happens, a single event may trigger a cascade of
* #GtkGestures, both across the parents of the widget receiving the * #GtkGestures, both across the parents of the widget receiving the
* event and parallelly within the same widget. It is a responsibility of the * event and parallelly within an individual widget. It is a responsibility of the
* widgets using those gestures to set the state of touch sequences accordingly * widgets using those gestures to set the state of touch sequences accordingly
* in order to enable cooperation of gestures around the #GdkEventSequences * in order to enable cooperation of gestures around the #GdkEventSequences
* triggering those. * triggering those.
@ -61,16 +62,25 @@
* propagation will continue unstopped by gestures. * propagation will continue unstopped by gestures.
* *
* If a sequence enters into the #GTK_EVENT_SEQUENCE_DENIED state, the gesture * If a sequence enters into the #GTK_EVENT_SEQUENCE_DENIED state, the gesture
* group will effectively ignore the sequence, but the "slot" will still remain * group will effectively ignore the sequence, letting events go unstopped
* occupied while the touch is active. * 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 * If a sequence enters in the #GTK_EVENT_SEQUENCE_CLAIMED state, the gesture
* group will grab all interaction on the sequence, by: * group will grab all interaction on the sequence, by:
* - Setting the sequence to #GTK_EVENT_SEQUENCE_DENIED on every other gesture * - 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 * group within the widget, and every gesture on parent widgets in the propagation
* chain. * chain.
* - calling #GtkGesture:cancel on every gesture in widgets underneath in the * - calling #GtkGesture::cancel on every gesture in widgets underneath in the
* propagation chain. * 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() * Sequence states can't be changed freely, see gtk_gesture_set_sequence_state()
* to know about the possible lifetimes of a #GdkEventSequence. * to know about the possible lifetimes of a #GdkEventSequence.
@ -574,7 +584,7 @@ gtk_gesture_class_init (GtkGestureClass *klass)
TRUE, TRUE,
GTK_PARAM_READWRITE)); GTK_PARAM_READWRITE));
/** /**
* GtkGesture:check: * GtkGesture::check:
* @gesture: the object which received the signal * @gesture: the object which received the signal
* *
* This signal is triggered when the number of interacting touch * This signal is triggered when the number of interacting touch
@ -594,12 +604,12 @@ gtk_gesture_class_init (GtkGestureClass *klass)
NULL, NULL, NULL, NULL,
G_TYPE_BOOLEAN, 0); G_TYPE_BOOLEAN, 0);
/** /**
* GtkGesture:begin: * GtkGesture::begin:
* @gesture: the object which received the signal * @gesture: the object which received the signal
* @sequence: the #GdkEventSequence that made the gesture to be recognized * @sequence: the #GdkEventSequence that made the gesture to be recognized
* *
* This signal is emitted when the gesture is recognized. This means the * This signal is emitted when the gesture is recognized. This means the
* number of touch sequences matches #GtkGesture:n-points, and the #GtkGesture:check * number of touch sequences matches #GtkGesture:n-points, and the #GtkGesture::check
* handler(s) returned #TRUE. * handler(s) returned #TRUE.
* *
* Note: These conditions may also happen when an extra touch (eg. a third touch * Note: These conditions may also happen when an extra touch (eg. a third touch
@ -616,12 +626,12 @@ gtk_gesture_class_init (GtkGestureClass *klass)
NULL, NULL, NULL, NULL, NULL, NULL,
G_TYPE_NONE, 1, G_TYPE_POINTER); G_TYPE_NONE, 1, G_TYPE_POINTER);
/** /**
* GtkGesture:end: * GtkGesture::end:
* @gesture: the object which received the signal * @gesture: the object which received the signal
* @sequence: the #GdkEventSequence that made gesture recognition to finish. * @sequence: the #GdkEventSequence that made gesture recognition to finish.
* *
* This signal is emitted when @gesture either stopped recognizing the event * This signal is emitted when @gesture either stopped recognizing the event
* sequences as something to be handled (the #GtkGesture:check handler returned * sequences as something to be handled (the #GtkGesture::check handler returned
* #FALSE), or the number of touch sequences became higher or lower than * #FALSE), or the number of touch sequences became higher or lower than
* #GtkGesture:n-points. * #GtkGesture:n-points.
* *
@ -635,7 +645,7 @@ gtk_gesture_class_init (GtkGestureClass *klass)
NULL, NULL, NULL, NULL, NULL, NULL,
G_TYPE_NONE, 1, G_TYPE_POINTER); G_TYPE_NONE, 1, G_TYPE_POINTER);
/** /**
* GtkGesture:update: * GtkGesture::update:
* @gesture: the object which received the signal * @gesture: the object which received the signal
* @sequence: the #GdkEventSequence that was updated. * @sequence: the #GdkEventSequence that was updated.
* *
@ -652,7 +662,7 @@ gtk_gesture_class_init (GtkGestureClass *klass)
NULL, NULL, NULL, NULL, NULL, NULL,
G_TYPE_NONE, 1, G_TYPE_POINTER); G_TYPE_NONE, 1, G_TYPE_POINTER);
/** /**
* GtkGesture:cancel: * GtkGesture::cancel:
* @gesture: the object which received the signal * @gesture: the object which received the signal
* @sequence: the #GdkEventSequence that was cancelled. * @sequence: the #GdkEventSequence that was cancelled.
* *
@ -673,7 +683,7 @@ gtk_gesture_class_init (GtkGestureClass *klass)
NULL, NULL, NULL, NULL, NULL, NULL,
G_TYPE_NONE, 1, G_TYPE_POINTER); G_TYPE_NONE, 1, G_TYPE_POINTER);
/** /**
* GtkGesture:sequence-state-changed: * GtkGesture::sequence-state-changed:
* @gesture: the object which received the signal * @gesture: the object which received the signal
* @sequence: the #GdkEventSequence that was cancelled. * @sequence: the #GdkEventSequence that was cancelled.
* @state: the new sequence state * @state: the new sequence state
@ -853,7 +863,7 @@ gtk_gesture_set_state (GtkGesture *gesture,
* Returns the list of #GdkEventSequences currently being interpreted * Returns the list of #GdkEventSequences currently being interpreted
* by @gesture * by @gesture
* *
* Returns: (transfer container) (element-type:Gdk.EventSequence): A list * Returns: (transfer container) (element-type GdkEventSequence): A list
* of #GdkEventSequences, the list elements are owned by GTK+ * of #GdkEventSequences, the list elements are owned by GTK+
* and must not be freed or modified, the list itself must be deleted * and must not be freed or modified, the list itself must be deleted
* through g_list_free() * through g_list_free()
@ -908,6 +918,15 @@ gtk_gesture_get_last_updated_sequence (GtkGesture *gesture)
return priv->last_sequence; return priv->last_sequence;
} }
/**
* gtk_gesture_get_last_event:
* @gesture: a #GtkGesture
* @sequence: a #GdkEventSequence
*
* Returns the last event that was processed for @sequence.
*
* Returns: (transfer none): The last event from @sequence
**/
const GdkEvent * const GdkEvent *
gtk_gesture_get_last_event (GtkGesture *gesture, gtk_gesture_get_last_event (GtkGesture *gesture,
GdkEventSequence *sequence) GdkEventSequence *sequence)
@ -1388,7 +1407,7 @@ gtk_gesture_group (GtkGesture *gesture,
* gtk_gesture_ungroup: * gtk_gesture_ungroup:
* @gesture: a #GtkGesture * @gesture: a #GtkGesture
* *
* Ungroups @gesture from its current group. * Separates @gesture into an isolated group.
* *
* Since: 3.14 * Since: 3.14
**/ **/