[clutter] docs: Document ClutterDropAction

[Emmanuele Bassi <ebassi src gnome org>]

commit e5641dabf86f765ff5b4e67aa761db52f2a45f16
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Fri Jun 17 17:22:01 2011 +0100

    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 1052dc7..b52dc0d 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 <http://www.gnu.org/licenses/>.
+ *
+ * Author:
+ *   Emmanuele Bassi <ebassi linux intel com>
+ */
+
+/**
+ * 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 290c90e..732baad 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 <http://www.gnu.org/licenses/>.
+ *
+ * Author:
+ *   Emmanuele Bassi <ebassi linux intel com>
+ */
+
 #if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
 #error "Only <clutter/clutter.h> 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 <structname>ClutterDropActionClass</structname> structure contains
  * only private data.
diff --git a/doc/reference/clutter/clutter-docs.xml.in b/doc/reference/clutter/clutter-docs.xml.in
index 789d71f..81686b2 100644
--- a/doc/reference/clutter/clutter-docs.xml.in
+++ b/doc/reference/clutter/clutter-docs.xml.in
@@ -98,6 +98,7 @@
 
       <xi:include href="xml/clutter-click-action.xml"/>
       <xi:include href="xml/clutter-drag-action.xml"/>
+      <xi:include href="xml/clutter-drop-action.xml"/>
       <xi:include href="xml/clutter-gesture-action.xml"/>
       <xi:include href="xml/clutter-swipe-action.xml"/>
     </chapter>
diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt
index 13c7ea7..34c7115 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
 </SECTION>
+
+<SECTION>
+<FILE>clutter-drop-action</FILE>
+ClutterDropAction
+ClutterDropActionClass
+clutter_drop_action_new
+<SUBSECTION Standard>
+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
+<SUBSECTION Private>
+ClutterDropActionClass
+clutter_drop_action_get_type
+</SECTION>
diff --git a/doc/reference/clutter/clutter.types b/doc/reference/clutter/clutter.types
index c4eefe8..8fc224c 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