From e5641dabf86f765ff5b4e67aa761db52f2a45f16 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Fri, 17 Jun 2011 17:22:01 +0100 Subject: [PATCH] docs: Document ClutterDropAction And add it to the API reference. https://bugzilla.gnome.org/show_bug.cgi?id=652842 --- clutter/clutter-drop-action.c | 115 ++++++++++++++++++++- clutter/clutter-drop-action.h | 28 +++++ doc/reference/clutter/clutter-docs.xml.in | 1 + doc/reference/clutter/clutter-sections.txt | 17 +++ doc/reference/clutter/clutter.types | 1 + 5 files changed, 160 insertions(+), 2 deletions(-) diff --git a/clutter/clutter-drop-action.c b/clutter/clutter-drop-action.c index 1052dc792..b52dc0d91 100644 --- a/clutter/clutter-drop-action.c +++ b/clutter/clutter-drop-action.c @@ -1,3 +1,57 @@ +/* + * Clutter. + * + * An OpenGL based 'interactive canvas' library. + * + * Copyright © 2011 Intel Corporation. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library. If not, see . + * + * Author: + * Emmanuele Bassi + */ + +/** + * SECTION:clutter-drop-action + * @Title: ClutterDropAction + * @short_description: An action for drop targets + * + * #ClutterDropAction is a #ClutterAction that allows a #ClutterActor + * implementation to control what happens when a dragged actor crosses + * the target area or when a dragged actor is released (or "dropped") + * on the target area. + * + * A trivial use of #ClutterDropAction consists in connecting to the + * #ClutterDropAction::drop signal and handling the drop from there, + * for instance: + * + * |[ + * ClutterAction *action = clutter_drop_action (); + * + * g_signal_connect (action, "drop", G_CALLBACK (on_drop), NULL); + * clutter_actor_add_action (an_actor, action); + * ]| + * + * The #ClutterDropAction::can-drop can be used to control whether the + * #ClutterDropAction::drop signal is going to be emitted; returning %FALSE + * from a handler connected to the #ClutterDropAction::can-drop signal will + * cause the #ClutterDropAction::drop signal to be skipped when the input + * device button is released. + * + * #ClutterDropAction is available since Clutter 1.8 + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -17,8 +71,6 @@ struct _ClutterDropActionPrivate ClutterActor *stage; gulong mapped_id; - - guint is_inside : 1; }; typedef struct _DropTarget { @@ -299,6 +351,23 @@ clutter_drop_action_class_init (ClutterDropActionClass *klass) klass->can_drop = clutter_drop_action_real_can_drop; + /** + * ClutterDropAction::can-drop: + * @action: the #ClutterDropAction that emitted the signal + * @actor: the #ClutterActor attached to the @action + * + * The ::can-drop signal is emitted when the dragged actor is dropped + * on @actor. The return value of the ::can-drop signal will determine + * whether or not the #ClutterDropAction::drop signal is going to be + * emitted on @action. + * + * The default implementation of #ClutterDropAction returns %TRUE for + * this signal. + * + * Return value: %TRUE if the drop is accepted, and %FALSE otherwise + * + * Since: 1.8 + */ drop_signals[CAN_DROP] = g_signal_new (I_("can-drop"), G_TYPE_FROM_CLASS (klass), @@ -311,6 +380,16 @@ clutter_drop_action_class_init (ClutterDropActionClass *klass) G_TYPE_FLOAT, G_TYPE_FLOAT); + /** + * ClutterDropAction::over-in: + * @action: the #ClutterDropAction that emitted the signal + * @actor: the #ClutterActor attached to the @action + * + * The ::over-in signal is emitted when the dragged actor crosses + * into @actor. + * + * Since: 1.8 + */ drop_signals[OVER_IN] = g_signal_new (I_("over-in"), G_TYPE_FROM_CLASS (klass), @@ -321,6 +400,16 @@ clutter_drop_action_class_init (ClutterDropActionClass *klass) G_TYPE_NONE, 1, CLUTTER_TYPE_ACTOR); + /** + * ClutterDropAction::over-out: + * @action: the #ClutterDropAction that emitted the signal + * @actor: the #ClutterActor attached to the @action + * + * The ::over-out signal is emitted when the dragged actor crosses + * outside @actor. + * + * Since: 1.8 + */ drop_signals[OVER_OUT] = g_signal_new (I_("over-out"), G_TYPE_FROM_CLASS (klass), @@ -331,6 +420,17 @@ clutter_drop_action_class_init (ClutterDropActionClass *klass) G_TYPE_NONE, 1, CLUTTER_TYPE_ACTOR); + /** + * ClutterDropAction::drop: + * @action: the #ClutterDropAction that emitted the signal + * @actor: the #ClutterActor attached to the @action + * + * The ::drop signal is emitted when the dragged actor is dropped + * on @actor. This signal is only emitted if at least an handler of + * #ClutterDropAction::can-drop returns %TRUE. + * + * Since: 1.8 + */ drop_signals[DROP] = g_signal_new (I_("drop"), G_TYPE_FROM_CLASS (klass), @@ -351,6 +451,17 @@ clutter_drop_action_init (ClutterDropAction *self) ClutterDropActionPrivate); } +/** + * clutter_drop_action_new: + * + * Creates a new #ClutterDropAction. + * + * Use clutter_actor_add_action() to add the action to a #ClutterActor. + * + * Return value: the newly created #ClutterDropAction + * + * Since: 1.8 + */ ClutterAction * clutter_drop_action_new (void) { diff --git a/clutter/clutter-drop-action.h b/clutter/clutter-drop-action.h index 290c90eb6..732baad57 100644 --- a/clutter/clutter-drop-action.h +++ b/clutter/clutter-drop-action.h @@ -1,3 +1,27 @@ +/* + * Clutter. + * + * An OpenGL based 'interactive canvas' library. + * + * Copyright © 2011 Intel Corporation. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library. If not, see . + * + * Author: + * Emmanuele Bassi + */ + #if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION) #error "Only can be directly included." #endif @@ -38,6 +62,10 @@ struct _ClutterDropAction /** * ClutterDropActionClass: + * @can_drop: class handler for the #ClutterDropAction::can-drop signal + * @over_in: class handler for the #ClutterDropAction::over-in signal + * @over_out: class handler for the #ClutterDropAction::over-out signal + * @drop: class handler for the #ClutterDropAction::drop signal * * The ClutterDropActionClass structure contains * only private data. diff --git a/doc/reference/clutter/clutter-docs.xml.in b/doc/reference/clutter/clutter-docs.xml.in index 789d71f86..81686b22d 100644 --- a/doc/reference/clutter/clutter-docs.xml.in +++ b/doc/reference/clutter/clutter-docs.xml.in @@ -98,6 +98,7 @@ + diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt index 13c7ea7cb..34c71155d 100644 --- a/doc/reference/clutter/clutter-sections.txt +++ b/doc/reference/clutter/clutter-sections.txt @@ -2717,3 +2717,20 @@ CLUTTER_TYPE_SWIPE_ACTION ClutterSwipeActionPrivate clutter_swipe_action_get_type + +
+clutter-drop-action +ClutterDropAction +ClutterDropActionClass +clutter_drop_action_new + +CLUTTER_TYPE_DROP_ACTION +CLUTTER_DROP_ACTION +CLUTTER_DROP_ACTION_CLASS +CLUTTER_IS_DROP_ACTION +CLUTTER_IS_DROP_ACTION_CLASS +CLUTTER_DROP_ACTION_GET_CLASS + +ClutterDropActionClass +clutter_drop_action_get_type +
diff --git a/doc/reference/clutter/clutter.types b/doc/reference/clutter/clutter.types index c4eefe8af..8fc224c75 100644 --- a/doc/reference/clutter/clutter.types +++ b/doc/reference/clutter/clutter.types @@ -31,6 +31,7 @@ clutter_deform_effect_get_type clutter_desaturate_effect_get_type clutter_device_manager_get_type clutter_drag_action_get_type +clutter_drop_action_get_type clutter_effect_get_type clutter_fixed_layout_get_type clutter_flow_layout_get_type