[gtk/ebassi/gidocgen: 378/478] gesture: Convert docs
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/ebassi/gidocgen: 378/478] gesture: Convert docs
- Date: Fri, 5 Mar 2021 23:02:41 +0000 (UTC)
commit 22998eb3dfbf29db0bbcbb2ed70ca33f6aa40b22
Author: Matthias Clasen <mclasen redhat com>
Date: Mon Mar 1 01:38:10 2021 -0500
gesture: Convert docs
gtk/gtkgesture.c | 390 ++++++++++++++++++++++++++++++-------------------------
1 file changed, 212 insertions(+), 178 deletions(-)
---
diff --git a/gtk/gtkgesture.c b/gtk/gtkgesture.c
index 130c4265cf..c345eb98e5 100644
--- a/gtk/gtkgesture.c
+++ b/gtk/gtkgesture.c
@@ -19,93 +19,97 @@
*/
/**
- * SECTION:gtkgesture
- * @Short_description: Base class for gestures
- * @Title: GtkGesture
- * @See_also: #GtkEventController, #GtkGestureSingle
+ * GtkGesture:
*
- * #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 %NULL #GdkEventSequence value for these).
+ * `GtkGesture` is the base class for gesture recognition.
*
- * 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 whether the gesture
- * is recognized.
+ * Although `GtkGesture` 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 %NULL `GdkEventSequence`
+ * value for these).
+ *
+ * The number of touches that a `GtkGesture` need to be recognized is
+ * controlled by the [property@Gtk.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 #GtkGesture subclasses.
+ * "recognized" is left to `GtkGesture` subclasses.
*
* A recognized gesture will then emit the following signals:
- * - #GtkGesture::begin when the gesture is recognized.
- * - A number of #GtkGesture::update, whenever an input event is processed.
- * - #GtkGesture::end when the gesture is no longer recognized.
+ *
+ * - [signal@Gtk.Gesture::begin] when the gesture is recognized.
+ * - [signal@Gtk.Gesture::update], whenever an input event is processed.
+ * - [signal@Gtk.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 gtk_event_controller_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 # {#touch-sequence-states}
- *
- * 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
+ * through [method@Gtk.EventController.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 `GtkGesture`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
+ * `GdkEventSequence`s triggering those.
+ *
+ * Within a widget, gestures can be grouped through [method@Gtk.Gesture.group].
+ * Grouped gestures synchronize the state of sequences, so calling
+ * [method@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,
+ * 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
+ * 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
+ * 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 #GtkGesture::cancel on every gesture in widgets underneath in the
- * propagation chain.
+ *
+ * - 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.
+ * - Emitting [signal@Gtk.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 #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.
+ * 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.
+ * Sequence states can't be changed freely.
+ * See [method@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_MASK on their #GdkSurfaces
+ * 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:
+ *
* - If the gesture has %GTK_PHASE_NONE, ensuring events of type
- * %GDK_TOUCHPAD_SWIPE and %GDK_TOUCHPAD_PINCH are handled by the #GtkGesture
+ * %GDK_TOUCHPAD_SWIPE and %GDK_TOUCHPAD_PINCH are handled by the `GtkGesture`
*/
#include "config.h"
@@ -749,7 +753,8 @@ gtk_gesture_class_init (GtkGestureClass *klass)
/**
* GtkGesture:n-points:
*
- * The number of touch points that trigger recognition on this gesture,
+ * The number of touch points that trigger
+ * recognition on this gesture.
*/
g_object_class_install_property (object_class,
PROP_N_POINTS,
@@ -763,14 +768,18 @@ gtk_gesture_class_init (GtkGestureClass *klass)
/**
* GtkGesture::begin:
* @gesture: the object which received the signal
- * @sequence: (nullable): the #GdkEventSequence that made the gesture to be recognized
+ * @sequence: (nullable): the `GdkEventSequence` that made the gesture
+ * to be recognized
*
- * This signal is emitted when the gesture is recognized. This means the
- * number of touch sequences matches #GtkGesture:n-points.
+ * Emitted when the gesture is recognized.
*
- * 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.
+ * This means the number of touch sequences matches
+ * [property@Gtk.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.
*/
signals[BEGIN] =
g_signal_new (I_("begin"),
@@ -779,19 +788,22 @@ gtk_gesture_class_init (GtkGestureClass *klass)
G_STRUCT_OFFSET (GtkGestureClass, begin),
NULL, NULL, NULL,
G_TYPE_NONE, 1, GDK_TYPE_EVENT_SEQUENCE);
+
/**
* GtkGesture::end:
* @gesture: the object which received the signal
- * @sequence: (nullable): the #GdkEventSequence that made gesture recognition to finish
+ * @sequence: (nullable): the `GdkEventSequence` that made gesture
+ * recognition to finish
*
- * This signal is 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 #GtkGesture:n-points.
+ * 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 [property@Gtk.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 #GtkGesture:n-points). This situation may be detected
- * by checking through gtk_gesture_handles_sequence().
+ * 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 [property@Gtk.Gesture:n-points]).
+ * This situation may be detected by checking through
+ * [method@Gtk.Gesture.handles_sequence].
*/
signals[END] =
g_signal_new (I_("end"),
@@ -800,13 +812,15 @@ gtk_gesture_class_init (GtkGestureClass *klass)
G_STRUCT_OFFSET (GtkGestureClass, end),
NULL, NULL, NULL,
G_TYPE_NONE, 1, GDK_TYPE_EVENT_SEQUENCE);
+
/**
* GtkGesture::update:
* @gesture: the object which received the signal
- * @sequence: (nullable): the #GdkEventSequence that was updated
+ * @sequence: (nullable): the `GdkEventSequence` that was updated
+ *
+ * Emitted whenever an event is handled while the gesture is recognized.
*
- * This signal is emitted whenever an event is handled while the gesture is
- * recognized. @sequence is guaranteed to pertain to the set of active touches.
+ * @sequence is guaranteed to pertain to the set of active touches.
*/
signals[UPDATE] =
g_signal_new (I_("update"),
@@ -815,17 +829,22 @@ gtk_gesture_class_init (GtkGestureClass *klass)
G_STRUCT_OFFSET (GtkGestureClass, update),
NULL, NULL, NULL,
G_TYPE_NONE, 1, GDK_TYPE_EVENT_SEQUENCE);
+
/**
* GtkGesture::cancel:
* @gesture: the object which received the signal
- * @sequence: (nullable): the #GdkEventSequence that was cancelled
+ * @sequence: (nullable): the `GdkEventSequence` that was cancelled
*
- * This signal is emitted whenever a sequence is cancelled. This usually
- * happens on active touches when gtk_event_controller_reset() is called
- * on @gesture (manually, due to grabs...), or the individual @sequence
- * was claimed by parent widgets' controllers (see gtk_gesture_set_sequence_state()).
+ * Emitted whenever a sequence is cancelled.
*
- * @gesture must forget everything about @sequence as a reaction to this signal.
+ * This usually happens on active touches when
+ * [method@Gtk.EventController.reset] is called on @gesture
+ * (manually, due to grabs...), or the individual @sequence
+ * was claimed by parent widgets' controllers (see
+ * [method@Gtk.Gesture.set_sequence_state]).
+ *
+ * @gesture must forget everything about @sequence as in
+ * response to this signal.
*/
signals[CANCEL] =
g_signal_new (I_("cancel"),
@@ -834,15 +853,17 @@ gtk_gesture_class_init (GtkGestureClass *klass)
G_STRUCT_OFFSET (GtkGestureClass, cancel),
NULL, NULL, NULL,
G_TYPE_NONE, 1, GDK_TYPE_EVENT_SEQUENCE);
+
/**
* GtkGesture::sequence-state-changed:
* @gesture: the object which received the signal
- * @sequence: (nullable): the #GdkEventSequence that was cancelled
+ * @sequence: (nullable): the `GdkEventSequence` that was cancelled
* @state: the new sequence state
*
- * This signal is emitted whenever a sequence state changes. See
- * gtk_gesture_set_sequence_state() to know more about the expectable
- * sequence lifetimes.
+ * Emitted whenever a sequence state changes.
+ *
+ * See [method@Gtk.Gesture.set_sequence_state] to know
+ * more about the expectable sequence lifetimes.
*/
signals[SEQUENCE_STATE_CHANGED] =
g_signal_new (I_("sequence-state-changed"),
@@ -885,13 +906,15 @@ gtk_gesture_init (GtkGesture *gesture)
/**
* gtk_gesture_get_device:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
*
- * Returns the logical #GdkDevice that is currently operating
- * on @gesture, or %NULL if the gesture is not being interacted.
+ * Returns the logical `GdkDevice` that is currently operating
+ * on @gesture.
*
- * Returns: (nullable) (transfer none): a #GdkDevice, or %NULL
- **/
+ * This returns %NULL if the gesture is not being interacted.
+ *
+ * Returns: (nullable) (transfer none): a `GdkDevice`, or %NULL
+ */
GdkDevice *
gtk_gesture_get_device (GtkGesture *gesture)
{
@@ -906,13 +929,13 @@ gtk_gesture_get_device (GtkGesture *gesture)
/**
* gtk_gesture_get_sequence_state:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
* @sequence: a #GdkEventSequence
*
* Returns the @sequence state, as seen by @gesture.
*
* Returns: The sequence state in @gesture
- **/
+ */
GtkEventSequenceState
gtk_gesture_get_sequence_state (GtkGesture *gesture,
GdkEventSequence *sequence)
@@ -934,29 +957,29 @@ gtk_gesture_get_sequence_state (GtkGesture *gesture,
/**
* gtk_gesture_set_sequence_state:
- * @gesture: a #GtkGesture
- * @sequence: a #GdkEventSequence
+ * @gesture: a `GtkGesture`
+ * @sequence: a `GdkEventSequence`
* @state: the sequence state
*
- * Sets the state of @sequence in @gesture. Sequences start
- * in state #GTK_EVENT_SEQUENCE_NONE, and whenever they change
- * state, they can never go back to that state. Likewise,
- * sequences in state #GTK_EVENT_SEQUENCE_DENIED cannot turn
- * back to a not denied state. With these rules, the lifetime
- * of an event sequence is constrained to the next four:
+ * Sets the state of @sequence in @gesture.
+ *
+ * Sequences start in state %GTK_EVENT_SEQUENCE_NONE, and whenever
+ * they change state, they can never go back to that state. Likewise,
+ * sequences in state %GTK_EVENT_SEQUENCE_DENIED cannot 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::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:
+ * Note: Due to event handling ordering, it may be unsafe to set the
+ * state on another gesture within a [signal@Gtk.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:
*
- * |[
+ * ```c
* static void
* first_gesture_begin_cb (GtkGesture *first_gesture,
* GdkEventSequence *sequence,
@@ -974,7 +997,7 @@ gtk_gesture_get_sequence_state (GtkGesture *gesture,
* 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
@@ -982,8 +1005,8 @@ gtk_gesture_get_sequence_state (GtkGesture *gesture,
* gesture processes the event.
*
* Returns: %TRUE if @sequence is handled by @gesture,
- * and the state is changed successfully
- **/
+ * and the state is changed successfully
+ */
gboolean
gtk_gesture_set_sequence_state (GtkGesture *gesture,
GdkEventSequence *sequence,
@@ -1035,15 +1058,17 @@ gtk_gesture_set_sequence_state (GtkGesture *gesture,
/**
* gtk_gesture_set_state:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
* @state: the sequence state
*
* Sets the state of all sequences that @gesture is currently
- * interacting with. See gtk_gesture_set_sequence_state()
- * for more details on sequence states.
+ * interacting with.
+ *
+ * See [method@Gtk.Gesture.set_sequence_state] for more details
+ * on sequence states.
*
* Returns: %TRUE if the state of at least one sequence
- * was changed successfully
+ * was changed successfully
*/
gboolean
gtk_gesture_set_state (GtkGesture *gesture,
@@ -1070,16 +1095,16 @@ gtk_gesture_set_state (GtkGesture *gesture,
/**
* gtk_gesture_get_sequences:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
*
- * Returns the list of #GdkEventSequences currently being interpreted
+ * Returns the list of `GdkEventSequences` currently being interpreted
* by @gesture.
*
* Returns: (transfer container) (element-type GdkEventSequence): A list
- * of #GdkEventSequences, the list elements are owned by GTK
- * and must not be freed or modified, the list itself must be deleted
- * through g_list_free()
- **/
+ * of `GdkEventSequence`, the list elements are owned by GTK and must
+ * not be freed or modified, the list itself must be deleted
+ * through g_list_free()
+ */
GList *
gtk_gesture_get_sequences (GtkGesture *gesture)
{
@@ -1114,12 +1139,12 @@ gtk_gesture_get_sequences (GtkGesture *gesture)
/**
* gtk_gesture_get_last_updated_sequence:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
*
- * Returns the #GdkEventSequence that was last updated on @gesture.
+ * Returns the `GdkEventSequence` that was last updated on @gesture.
*
* Returns: (transfer none) (nullable): The last updated sequence
- **/
+ */
GdkEventSequence *
gtk_gesture_get_last_updated_sequence (GtkGesture *gesture)
{
@@ -1134,17 +1159,17 @@ gtk_gesture_get_last_updated_sequence (GtkGesture *gesture)
/**
* gtk_gesture_get_last_event:
- * @gesture: a #GtkGesture
- * @sequence: (nullable): a #GdkEventSequence
+ * @gesture: a `GtkGesture`
+ * @sequence: (nullable): a `GdkEventSequence`
*
* 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 @gesture. If in doubt, you should make
- * a copy of the event.
+ * Note that the returned pointer is only valid as long as the
+ * @sequence is still interpreted by the @gesture. If in doubt,
+ * you should make a copy of the event.
*
* Returns: (transfer none) (nullable): The last event from @sequence
- **/
+ */
GdkEvent *
gtk_gesture_get_last_event (GtkGesture *gesture,
GdkEventSequence *sequence)
@@ -1165,11 +1190,12 @@ gtk_gesture_get_last_event (GtkGesture *gesture,
/*
* gtk_gesture_get_last_target:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
* @sequence: event sequence
*
* Returns the widget that the last event was targeted at.
- * See gtk_gesture_get_last_event().
+ *
+ * See [method@Gtk.Gesture.get_last_event].
*
* Returns: (transfer none) (nullable): The target of the last event
*/
@@ -1193,18 +1219,19 @@ gtk_gesture_get_last_target (GtkGesture *gesture,
/**
* gtk_gesture_get_point:
- * @gesture: a #GtkGesture
- * @sequence: (allow-none): a #GdkEventSequence, or %NULL for pointer events
+ * @gesture: a `GtkGesture`
+ * @sequence: (allow-none): a `GdkEventSequence`, or %NULL for pointer events
* @x: (out) (allow-none): return location for X axis of the sequence coordinates
* @y: (out) (allow-none): return location for Y axis of the sequence coordinates
*
- * If @sequence is currently being interpreted by @gesture, this
- * function 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.
+ * If @sequence is currently being interpreted by @gesture,
+ * 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.
*
* Returns: %TRUE if @sequence is currently interpreted
- **/
+ */
gboolean
gtk_gesture_get_point (GtkGesture *gesture,
GdkEventSequence *sequence,
@@ -1254,13 +1281,14 @@ _gtk_gesture_get_last_update_time (GtkGesture *gesture,
/**
* gtk_gesture_get_bounding_box:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
* @rect: (out): bounding box containing all active touches.
*
* If there are touch sequences being currently handled by @gesture,
- * this function returns %TRUE and fills in @rect with the bounding
- * box containing all active touches. Otherwise, %FALSE will be
- * returned.
+ * 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
@@ -1269,7 +1297,7 @@ _gtk_gesture_get_last_update_time (GtkGesture *gesture,
* regardless of the number of touchpoints.
*
* Returns: %TRUE if there are active touches, %FALSE otherwise
- **/
+ */
gboolean
gtk_gesture_get_bounding_box (GtkGesture *gesture,
GdkRectangle *rect)
@@ -1322,17 +1350,18 @@ gtk_gesture_get_bounding_box (GtkGesture *gesture,
/**
* gtk_gesture_get_bounding_box_center:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
* @x: (out): X coordinate for the bounding box center
* @y: (out): Y coordinate for the bounding box center
*
* If there are touch sequences being currently handled by @gesture,
- * this function 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 %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
- **/
+ */
gboolean
gtk_gesture_get_bounding_box_center (GtkGesture *gesture,
double *x,
@@ -1360,14 +1389,15 @@ gtk_gesture_get_bounding_box_center (GtkGesture *gesture,
/**
* gtk_gesture_is_active:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
*
* Returns %TRUE if the gesture is currently active.
- * A gesture is active meanwhile there are touch sequences
+ *
+ * A gesture is active while there are touch sequences
* interacting with it.
*
* Returns: %TRUE if gesture is active
- **/
+ */
gboolean
gtk_gesture_is_active (GtkGesture *gesture)
{
@@ -1378,14 +1408,15 @@ gtk_gesture_is_active (GtkGesture *gesture)
/**
* gtk_gesture_is_recognized:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
*
* Returns %TRUE if the gesture is currently recognized.
+ *
* A gesture is recognized if there are as many interacting
* touch sequences as required by @gesture.
*
* Returns: %TRUE if gesture is recognized
- **/
+ */
gboolean
gtk_gesture_is_recognized (GtkGesture *gesture)
{
@@ -1412,14 +1443,14 @@ _gtk_gesture_check (GtkGesture *gesture)
/**
* gtk_gesture_handles_sequence:
- * @gesture: a #GtkGesture
- * @sequence: (nullable): a #GdkEventSequence or %NULL
+ * @gesture: a `GtkGesture`
+ * @sequence: (nullable): a `GdkEventSequence` or %NULL
*
- * Returns %TRUE if @gesture is currently handling events corresponding to
- * @sequence.
+ * Returns %TRUE if @gesture is currently handling events
+ * corresponding to @sequence.
*
* Returns: %TRUE if @gesture is handling @sequence, %FALSE otherwise
- **/
+ */
gboolean
gtk_gesture_handles_sequence (GtkGesture *gesture,
GdkEventSequence *sequence)
@@ -1475,24 +1506,27 @@ _gtk_gesture_get_group_link (GtkGesture *gesture)
/**
* gtk_gesture_group:
- * @gesture: a #GtkGesture
- * @group_gesture: #GtkGesture to group @gesture with
+ * @gesture: a `GtkGesture`
+ * @group_gesture: `GtkGesture` to group @gesture with
*
- * Adds @gesture to the same group than @group_gesture. Gestures
- * are by default isolated in their own groups.
+ * Adds @gesture to the same group than @group_gesture.
*
- * Both gestures must have been added to the same widget before they
- * can be grouped.
+ * Gestures are by default isolated in their own groups.
*
- * When gestures are grouped, the state of #GdkEventSequences
- * is kept in sync for all of those, so calling gtk_gesture_set_sequence_state(),
- * on one will transfer the same value to the others.
+ * 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
+ * [method@Gtk.Gesture.set_sequence_state], on one will transfer
+ * the same value to the others.
*
* Groups also perform an "implicit grabbing" of sequences, if a
- * #GdkEventSequence state is set to #GTK_EVENT_SEQUENCE_CLAIMED on one group,
- * every other gesture group attached to the same #GtkWidget will switch the
- * state for that sequence to #GTK_EVENT_SEQUENCE_DENIED.
- **/
+ * `GdkEventSequence` state is set to %GTK_EVENT_SEQUENCE_CLAIMED
+ * on one group, every other gesture group attached to the same
+ * `GtkWidget` will switch the state for that sequence to
+ * %GTK_EVENT_SEQUENCE_DENIED.
+ */
void
gtk_gesture_group (GtkGesture *gesture,
GtkGesture *group_gesture)
@@ -1526,10 +1560,10 @@ gtk_gesture_group (GtkGesture *gesture,
/**
* gtk_gesture_ungroup:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
*
* Separates @gesture into an isolated group.
- **/
+ */
void
gtk_gesture_ungroup (GtkGesture *gesture)
{
@@ -1552,13 +1586,13 @@ gtk_gesture_ungroup (GtkGesture *gesture)
/**
* gtk_gesture_get_group:
- * @gesture: a #GtkGesture
+ * @gesture: a `GtkGesture`
*
* Returns all gestures in the group of @gesture
*
* Returns: (element-type GtkGesture) (transfer container): The list
- * of #GtkGestures, free with g_list_free()
- **/
+ * of `GtkGesture`s, free with g_list_free()
+ */
GList *
gtk_gesture_get_group (GtkGesture *gesture)
{
@@ -1573,13 +1607,13 @@ gtk_gesture_get_group (GtkGesture *gesture)
/**
* gtk_gesture_is_grouped_with:
- * @gesture: a #GtkGesture
- * @other: another #GtkGesture
+ * @gesture: a `GtkGesture`
+ * @other: another `GtkGesture`
*
* Returns %TRUE if both gestures pertain to the same group.
*
* Returns: whether the gestures are grouped
- **/
+ */
gboolean
gtk_gesture_is_grouped_with (GtkGesture *gesture,
GtkGesture *other)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
