diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index c435070341..7db9731c3e 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -68,6 +68,11 @@ + + Multitouch + + + GTK+ Widgets and Objects diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt index 0978b5bc45..276b40809a 100644 --- a/docs/reference/gtk/gtk3-sections.txt +++ b/docs/reference/gtk/gtk3-sections.txt @@ -1579,6 +1579,50 @@ GtkFramePrivate gtk_frame_get_type +
+gtkgesturesinterpreter +GtkGesturesInterpreter +GtkGesturesInterpreter +GtkGestureType +gtk_gestures_interpreter_new +gtk_gestures_interpreter_add_gesture +gtk_gestures_interpreter_remove_gesture +gtk_gestures_interpreter_feed_event +gtk_gestures_interpreter_finish + + +GtkGestureStroke +gtk_gesture_stroke_new +gtk_gesture_stroke_copy +gtk_gesture_stroke_free +gtk_gesture_stroke_append_vector +gtk_gesture_stroke_get_n_vectors +gtk_gesture_stroke_get_vector +GtkGesture +GtkGestureFlags +gtk_gesture_new +gtk_gesture_copy +gtk_gesture_free +gtk_gesture_add_stroke +gtk_gesture_get_n_strokes +gtk_gesture_get_stroke +gtk_gesture_get_flags +gtk_gesture_register +gtk_gesture_register_static +gtk_gesture_lookup + + +GTK_GESTURES_INTERPRETER +GTK_IS_GESTURES_INTERPRETER +GTK_TYPE_GESTURES_INTERPRETER +GTK_IS_GESTURES_INTERPRETER_CLASS +GTK_GESTURES_INTERPRETER_GET_CLASS + +gtk_gestures_interpreter_get_type +gtk_gesture_stroke_get_type +gtk_gesture_get_type +
+
gtkhandlebox GtkHandleBox diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types index c67ac722a0..4828bd06c6 100644 --- a/docs/reference/gtk/gtk3.types +++ b/docs/reference/gtk/gtk3.types @@ -77,6 +77,7 @@ gtk_font_chooser_widget_get_type gtk_font_selection_dialog_get_type gtk_font_selection_get_type gtk_frame_get_type +gtk_gestures_interpreter_get_type gtk_grid_get_type gtk_handle_box_get_type gtk_hbox_get_type diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h index 6273c0f6b3..4a2bb58959 100644 --- a/gtk/gtkenums.h +++ b/gtk/gtkenums.h @@ -932,6 +932,17 @@ typedef enum { GTK_BORDER_STYLE_RIDGE } GtkBorderStyle; +/** + * GtkGestureType: + * @GTK_GESTURE_SWIPE_RIGHT: A swipe from left to right + * @GTK_GESTURE_SWIPE_LEFT: A swipe from right to left + * @GTK_GESTURE_SWIPE_UP: A swipe from bottom to top + * @GTK_GESTURE_SWIPE_DOWN: A swipe from top to bottom + * @GTK_GESTURE_CIRCULAR_CLOCKWISE: A circular clockwise movement + * @GTK_GESTURE_CIRCULAR_COUNTERCLOCKWISE: A circular counterclockwise movement + * + * Describes the stock gestures handled by GTK+. + */ typedef enum { GTK_CAPTURED_EVENT_NONE = 0, GTK_CAPTURED_EVENT_HANDLED = 1 << 0, @@ -968,6 +979,16 @@ typedef enum { GTK_GESTURE_CIRCULAR_COUNTERCLOCKWISE } GtkGestureType; +/** + * GtkGestureFlags: + * @GTK_GESTURE_FLAG_NONE: Gesture is interpreted as-is. + * @GTK_GESTURE_FLAG_IGNORE_INITIAL_ORIENTATION: + * The initial orientation is ignored in comparisons, + * so the gesture doesn't have a sense of direction, + * this is useful for i.e. circular strokes. + * + * Flags accepted by gtk_gesture_new() + */ typedef enum { GTK_GESTURE_FLAG_NONE = 0, GTK_GESTURE_FLAG_IGNORE_INITIAL_ORIENTATION = 1 << 1 diff --git a/gtk/gtkgesturesinterpreter.c b/gtk/gtkgesturesinterpreter.c index 0d6788925c..40c7b0d281 100644 --- a/gtk/gtkgesturesinterpreter.c +++ b/gtk/gtkgesturesinterpreter.c @@ -24,6 +24,32 @@ #include #include +/** + * SECTION:gtkgesturesinterpreter + * @Short_description: Gestures interpreter + * @Title: GtkGesturesInterpreter + * @See_also: #GdkEventMultitouch + * + * #GtkGesturesInterpreter handles interpretation of input events to check + * whether they resemble a handled gesture. If you are using #GtkWidgets + * and want only to enable events for devices with source %GDK_SOURCE_TOUCH, + * you can use gtk_widget_enable_gesture() and the #GtkWidget::gesture signal + * without the need of creating a #GtkGesturesInterpreter. + * + * A #GtkGesturesInterpreter may be told to handle a gesture through + * gtk_gestures_interpreter_add_gesture(), either using a gesture provided + * by the GtkGestureType enum, or creating and registering a gesture through + * gtk_gesture_register() or gtk_gesture_register_static(). + * + * The #GtkGestureInterpreter can be told to interpret user input events + * through gtk_gestures_interpreter_feed_event(), the event is required + * to provide coordinates in order to be handled. + * + * The recognized gesture may be requested through gtk_gestures_interpreter_finish(), + * if the gesture drafted by the input events resembles well enough a handled + * gesture, this function will provide the gesture ID that was recognized. + */ + #define N_CIRCULAR_SIDES 12 #define VECTORIZATION_ANGLE_THRESHOLD (G_PI_2 / 10) #define MINIMUM_CONFIDENCE_ALLOWED 0.78 @@ -180,6 +206,15 @@ gtk_gestures_interpreter_class_init (GtkGesturesInterpreterClass *klass) initialize_gestures_ht (); + /** + * GtkGesturesInterpreter::events-vectorized + * @interpreter: the object which received the signal + * @gesture: the #GtkGesture holding the user gesture + * + * This signal is emitted during gtk_gestures_interpreter_finish() + * after the events introduced through gtk_gestures_interpreter_feed_event() + * are vectorized and transformed into a #GtkGesture. + */ signals[EVENTS_VECTORIZED] = g_signal_new (I_("events-vectorized"), G_TYPE_FROM_CLASS (object_class), @@ -189,6 +224,17 @@ gtk_gestures_interpreter_class_init (GtkGesturesInterpreterClass *klass) NULL, NULL, _gtk_marshal_VOID__BOXED, G_TYPE_NONE, 1, GTK_TYPE_GESTURE); + + /** + * GtkGesturesInterpreter::gesture-detected + * @interpreter: the object which received the signal + * @gesture_id: the gesture ID of the recognized gesture + * @confidence: [0..1] measuring the level of confidence on the recognition. + * + * This signal is emitted when the #GtkGesturesInterpreter + * recognizes a gesture out of the events introduced through + * gtk_gestures_interpreter_feed_event(). + */ signals[GESTURE_DETECTED] = g_signal_new (I_("gesture-detected"), G_TYPE_FROM_CLASS (object_class), @@ -379,6 +425,14 @@ gtk_gestures_interpreter_init (GtkGesturesInterpreter *interpreter) } /* Gesture stroke */ + +/** + * gtk_gesture_stroke_new: + * + * Creates a new, empty stroke to be used in a gesture. + * + * Returns: (transfer full): a newly created #GtkGestureStroke + **/ GtkGestureStroke * gtk_gesture_stroke_new (void) { @@ -390,6 +444,14 @@ gtk_gesture_stroke_new (void) return stroke; } +/** + * gtk_gesture_stroke_copy: + * @stroke: a #GtkGestureStroke + * + * Copies a #GtkGestureStroke + * + * Returns: (transfer full): A copy of @stroke + **/ GtkGestureStroke * gtk_gesture_stroke_copy (const GtkGestureStroke *stroke) { @@ -406,6 +468,12 @@ gtk_gesture_stroke_copy (const GtkGestureStroke *stroke) return copy; } +/** + * gtk_gesture_stroke_free: + * @stroke: a #GtkGestureStroke + * + * Frees a #GtkGestureStroke and all its contained data + **/ void gtk_gesture_stroke_free (GtkGestureStroke *stroke) { @@ -415,6 +483,14 @@ gtk_gesture_stroke_free (GtkGestureStroke *stroke) g_slice_free (GtkGestureStroke, stroke); } +/** + * gtk_gesture_stroke_append_vector: + * @stroke: a #GtkGestureStroke + * @angle: vector angle + * @length: vector length + * + * Appends a vector to stroke. + **/ void gtk_gesture_stroke_append_vector (GtkGestureStroke *stroke, gdouble angle, @@ -431,6 +507,15 @@ gtk_gesture_stroke_append_vector (GtkGestureStroke *stroke, stroke->total_length += length; } +/** + * gtk_gesture_stroke_get_n_vectors: + * @stroke: a #GtkGestureStroke + * + * Returns the number of vectors that @stroke currently + * contains. + * + * Returns: The number of vectors in @stroke + **/ guint gtk_gesture_stroke_get_n_vectors (const GtkGestureStroke *stroke) { @@ -439,6 +524,26 @@ gtk_gesture_stroke_get_n_vectors (const GtkGestureStroke *stroke) return stroke->gesture_data->len; } +/** + * gtk_gesture_stroke_get_vector: + * @stroke: a #GtkGestureStroke + * @n_vector: number of vector to retrieve + * @angle: (out) (allow-none): return location for the vector angle, or %NULL + * @length: (out) (allow-none): return location for the vector distance, or %NULL + * @relative_length: (out) (allow-none): return location for the relative vector + * length within the stroke, or %NULL + * + * If @n_vector falls within the range of vectors contained in @stroke, + * this function will return %TRUE and respectively fill in @angle and + * @length with the vector direction angle and length. Optionally, if + * @relative_length is not %NULL, the relative [0..1] length of the vector + * within the whole stroke will be returned at that location. + * + * If @n_vector doesn't represent a vector of the stroke, %FALSE is + * returned. + * + * Returns: %TRUE if @n_vector is a valid vector + **/ gboolean gtk_gesture_stroke_get_vector (const GtkGestureStroke *stroke, guint n_vector, @@ -466,6 +571,24 @@ gtk_gesture_stroke_get_vector (const GtkGestureStroke *stroke, } /* Gesture */ + +/** + * gtk_gesture_new: + * @stroke: a #GtkGestureStroke + * @flags: #GtkGestureFlags applying to the gesture + * + * Creates a new gesture containing @stroke as its first (or only) + * stroke. Use gtk_gesture_add_stroke() to add create gestures with + * more than one stroke. + * + * If @flags contains %GTK_GESTURE_FLAG_IGNORE_INITIAL_ORIENTATION, + * the gesture will be loosely compared with respect to the initial + * orientation of the gesture, it should be used whenever the + * orientation isn't an important matching factor (for example, + * circular gestures). + * + * Returns: (transfer full): A newly created #GtkGesture + **/ GtkGesture * gtk_gesture_new (const GtkGestureStroke *stroke, GtkGestureFlags flags) @@ -485,6 +608,17 @@ gtk_gesture_new (const GtkGestureStroke *stroke, return gesture; } +/** + * gtk_gesture_add_stroke: + * @gesture: a #GtkGesture + * @stroke: a #GtkGestureStroke + * @dx: X offset with respect to the first stroke + * @dy: Y offset with respect to the first stroke + * + * Adds a further stroke to @gesture, @dx and @dy represent + * the offset with the stroke that was added through + * gtk_gesture_new(). + **/ void gtk_gesture_add_stroke (GtkGesture *gesture, const GtkGestureStroke *stroke, @@ -504,6 +638,15 @@ gtk_gesture_add_stroke (GtkGesture *gesture, g_ptr_array_add (gesture->strokes, copy); } +/** + * gtk_gesture_copy: + * @gesture: a #GtkGesture + * + * Copies a #GtkGesture + * + * Returns: (transfer full): a copy of @gesture. gtk_gesture_free() must be + * called on it when done. + **/ GtkGesture * gtk_gesture_copy (const GtkGesture *gesture) { @@ -529,6 +672,12 @@ gtk_gesture_copy (const GtkGesture *gesture) return copy; } +/** + * gtk_gesture_free: + * @gesture: a #GtkGesture + * + * Frees a #GtkGesture + **/ void gtk_gesture_free (GtkGesture *gesture) { @@ -538,6 +687,14 @@ gtk_gesture_free (GtkGesture *gesture) g_slice_free (GtkGesture, gesture); } +/** + * gtk_gesture_get_flags: + * @gesture: a #GtkGesture + * + * Returns the #GtkGestureFlags applying to @gesture + * + * Returns: the gesture flags + **/ GtkGestureFlags gtk_gesture_get_flags (const GtkGesture *gesture) { @@ -546,6 +703,14 @@ gtk_gesture_get_flags (const GtkGesture *gesture) return gesture->flags; } +/** + * gtk_gesture_get_n_strokes: + * @gesture: a #GtkGesture + * + * Returns the number of strokes that compose @gesture + * + * Returns: the number of strokes + **/ guint gtk_gesture_get_n_strokes (const GtkGesture *gesture) { @@ -554,6 +719,20 @@ gtk_gesture_get_n_strokes (const GtkGesture *gesture) return gesture->strokes->len; } +/** + * gtk_gesture_get_stroke: + * @gesture: a #GtkGesture + * @n_stroke: number of stroke to retrieve + * @dx: (out) (allow-none): return location for the X offset, or %NULL + * @dy: (out) (allow-none): return location for the Y offset, or %NULL + * + * if @n_stroke falls within the number of strokes that + * compose @gesture, this function will return the + * #GtkGestureStroke, and fill in @dx and @dy with the + * offset with respect to the first stroke. + * + * Returns: (transfer none): the @GtkGestureStroke, or %NULL + **/ const GtkGestureStroke * gtk_gesture_get_stroke (const GtkGesture *gesture, guint n_stroke, @@ -579,6 +758,15 @@ gtk_gesture_get_stroke (const GtkGesture *gesture, return stroke; } +/** + * gtk_gesture_register: + * @gesture: a #GtkGesture + * + * Registers a gesture so it can be used in a #GtkGesturesInterpreter. + * This function creates an internal copy of @gesture + * + * Returns: the ID of the just registered gesture + **/ guint gtk_gesture_register (const GtkGesture *gesture) { @@ -587,6 +775,16 @@ gtk_gesture_register (const GtkGesture *gesture) return gtk_gesture_register_static (gtk_gesture_copy (gesture)); } +/** + * gtk_gesture_register_static: + * @gesture: a #GtkGesture + * + * Registers a gesture so it can be used in a #GtkGesturesInterpreter. + * This function assumes @gesture is statically stored, so doesn't + * create a copy of it. + * + * Returns: the ID of the just registered gesture + **/ guint gtk_gesture_register_static (const GtkGesture *gesture) { @@ -603,6 +801,15 @@ gtk_gesture_register_static (const GtkGesture *gesture) return gesture_id; } +/** + * gtk_gesture_lookup: + * @gesture_id: a gesture ID + * + * Returns the #GtkGesture corresponding to @gesture_id, + * or %NULL if there is no gesture registered with such ID. + * + * Returns: (transfer none): the #GtkGesture, or %NULL + **/ const GtkGesture * gtk_gesture_lookup (guint gesture_id) { @@ -614,12 +821,35 @@ gtk_gesture_lookup (guint gesture_id) } /* Gesture interpreter */ + +/** + * gtk_gestures_interpreter_new: + * + * Creates a new #GtkGesturesInterpreter + * + * Returns: (transfer full): the newly created #GtkGesturesInterpreter + **/ GtkGesturesInterpreter * gtk_gestures_interpreter_new (void) { return g_object_new (GTK_TYPE_GESTURES_INTERPRETER, NULL); } +/** + * gtk_gestures_interpreter_add_gesture: + * @interpreter: a #GtkGesturesInterpreter + * @gesture_id: gesture ID to enable in interpreter + * + * Tells @interpreter to handle @gesture_id. @gesture_id may be + * either a custom #GtkGesture registered through gtk_gesture_register() + * or gtk_gesture_register_static(), or a value from the #GtkGestureType + * enum. + * + * If @gesture_id doesn't represent a registered gesture, or is already + * handled by @interpreter, %FALSE will be returned + * + * Returns: %TRUE if the gesture is now handled + **/ gboolean gtk_gestures_interpreter_add_gesture (GtkGesturesInterpreter *interpreter, guint gesture_id) @@ -643,6 +873,13 @@ gtk_gestures_interpreter_add_gesture (GtkGesturesInterpreter *interpreter, return TRUE; } +/** + * gtk_gestures_interpreter_remove_gesture: + * @interpreter: a #GtkGesturesInterpreter + * @gesture_id: gesture ID to stop handling + * + * Removes @gesture_id from being handled by @interpreter. + **/ void gtk_gestures_interpreter_remove_gesture (GtkGesturesInterpreter *interpreter, guint gesture_id) @@ -669,6 +906,20 @@ gtk_gestures_interpreter_remove_gesture (GtkGesturesInterpreter *interpreter, } } +/** + * gtk_gestures_interpreter_feed_event: + * @interpreter: a #GtkGesturesInterpreter + * @event: a #GdkEvent containing coordinates + * + * Feeds an input event into @interpreter, the coordinates of @event will + * be used to build the user gesture that will be later compared to the + * handled gestures. + * + * If @event doesn't contain coordinates information (gdk_event_get_coords() + * returns %FALSE), %FALSE will be returned + * + * Returns: %TRUE if the event was useful to build the user gesture + **/ gboolean gtk_gestures_interpreter_feed_event (GtkGesturesInterpreter *interpreter, GdkEvent *event) @@ -828,6 +1079,20 @@ compare_gestures (const GtkGesture *gesture, return TRUE; } +/** + * gtk_gestures_interpreter_finish: + * @interpreter: a #GtkGesturesInterpreter + * @gesture_id: (out) (allow-none): return location for the resulting + * gesture ID, or %NULL + * + * Finishes the user gesture and compares it to the handled gestures, + * returning %TRUE and filling in @gesture_id with the resulting gesture + * in case of success. + * + * If %FALSE is returned, no gesture was recognized. + * + * Returns: %TRUE if the gesture matched + **/ gboolean gtk_gestures_interpreter_finish (GtkGesturesInterpreter *interpreter, guint *gesture_id)