X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=atk%2Fatkselection.c;h=d4bd8363ec27dabf3d8bdfb8e828417acbc0f99c;hb=c2e2f1b65b4e7a1a921434a4f34f63cce09684ff;hp=3c620426d8f3a800ce7a9189b3642211947539d9;hpb=dba66b4bec94a908cd35a5537209db255fa5fa33;p=platform%2Fupstream%2Fatk.git

diff --git a/atk/atkselection.c b/atk/atkselection.c
old mode 100755
new mode 100644
index 3c62042..d4bd836
--- a/atk/atkselection.c
+++ b/atk/atkselection.c
@@ -17,10 +17,40 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "config.h"
+
 #include "atkselection.h"
 
+/**
+ * SECTION:atkselection
+ * @Short_description: The ATK interface implemented by container
+ *  objects whose #AtkObject children can be selected.
+ * @Title:AtkSelection
+ *
+ * #AtkSelection should be implemented by UI components with children
+ * which are exposed by #atk_object_ref_child and
+ * #atk_object_get_n_children, if the use of the parent UI component
+ * ordinarily involves selection of one or more of the objects
+ * corresponding to those #AtkObject children - for example,
+ * selectable lists.
+ *
+ * Note that other types of "selection" (for instance text selection)
+ * are accomplished a other ATK interfaces - #AtkSelection is limited
+ * to the selection/deselection of children.
+ */
+
+
+enum {
+  SELECTION_CHANGED,
+  LAST_SIGNAL
+};
+
+static void atk_selection_base_init (gpointer *g_class);
+
+static guint atk_selection_signals[LAST_SIGNAL] = { 0 };
+
 GType
-atk_selection_get_type ()
+atk_selection_get_type (void)
 {
   static GType type = 0;
 
@@ -28,8 +58,8 @@ atk_selection_get_type ()
     GTypeInfo tinfo =
     {
       sizeof (AtkSelectionIface),
-      NULL,
-      NULL,
+      (GBaseInitFunc)atk_selection_base_init,
+      (GBaseFinalizeFunc) NULL,
 
     };
 
@@ -39,55 +69,100 @@ atk_selection_get_type ()
   return type;
 }
 
+static void
+atk_selection_base_init (gpointer *g_class)
+{
+  static gboolean initialized = FALSE;
+
+  if (! initialized)
+    {
+      /**
+       * AtkSelection::selection-changed:
+       * @atkselection: the object which received the signal.
+       *
+       * The "selection-changed" signal is emitted by an object which
+       * implements AtkSelection interface when the selection changes.
+       */
+      atk_selection_signals[SELECTION_CHANGED] =
+        g_signal_new ("selection_changed",
+                      ATK_TYPE_SELECTION,
+                      G_SIGNAL_RUN_LAST,
+                      G_STRUCT_OFFSET (AtkSelectionIface, selection_changed),
+                      (GSignalAccumulator) NULL, NULL,
+                      g_cclosure_marshal_VOID__VOID,
+                      G_TYPE_NONE, 0);
+
+
+      initialized = TRUE;
+    }
+}
+
 /**
  * atk_selection_add_selection:
- * @value: a GObject instance that implements AtkSelectionIface
- * @return: void
+ * @selection: a #GObject instance that implements AtkSelectionIface
+ * @i: a #gint specifying the child index.
+ *
+ * Adds the specified accessible child of the object to the
+ * object's selection.
+ *
+ * Returns: TRUE if success, FALSE otherwise.
  **/
-void
+gboolean
 atk_selection_add_selection (AtkSelection *obj,
                              gint         i)
 {
   AtkSelectionIface *iface;
 
-  g_return_if_fail (obj != NULL);
-  g_return_if_fail (ATK_IS_SELECTION (obj));
+  g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 
   iface = ATK_SELECTION_GET_IFACE (obj);
 
   if (iface->add_selection)
-    (iface->add_selection) (obj, i);
+    return (iface->add_selection) (obj, i);
+  else
+    return FALSE;
 }
 
 /**
  * atk_selection_clear_selection:
- * @value: a GObject instance that implements AtkSelectionIface
- * @return: void
+ * @selection: a #GObject instance that implements AtkSelectionIface
+ *
+ * Clears the selection in the object so that no children in the object
+ * are selected.
+ *
+ * Returns: TRUE if success, FALSE otherwise.
  **/
-void
+gboolean
 atk_selection_clear_selection (AtkSelection *obj)
 {
   AtkSelectionIface *iface;
 
-  g_return_if_fail (obj != NULL);
-  g_return_if_fail (ATK_IS_SELECTION (obj));
+  g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 
   iface = ATK_SELECTION_GET_IFACE (obj);
 
   if (iface->clear_selection)
-    (iface->clear_selection) (obj);
+    return (iface->clear_selection) (obj);
+  else
+    return FALSE;
 }
 
 /**
  * atk_selection_ref_selection:
- * @value: a GObject instance that implements AtkSelectionIface
- * @return: a AtkObject* representing the selected accessible , or NULL
- * if value does not implement this interface.
+ * @selection: a #GObject instance that implements AtkSelectionIface
+ * @i: a #gint specifying the index in the selection set.  (e.g. the
+ * ith selection as opposed to the ith child).
  *
- * WARNING: callers should not rely on %NULL or on a zero value for
+ * Gets a reference to the accessible object representing the specified 
+ * selected child of the object.
+ * Note: callers should not rely on %NULL or on a zero value for
  * indication of whether AtkSelectionIface is implemented, they should
  * use type checking/interface checking macros or the
  * atk_get_accessible_value() convenience method.
+ *
+ * Returns: (nullable) (transfer full): an #AtkObject representing the
+ * selected accessible, or %NULL if @selection does not implement this
+ * interface.
  **/
 AtkObject*
 atk_selection_ref_selection (AtkSelection *obj,
@@ -95,7 +170,6 @@ atk_selection_ref_selection (AtkSelection *obj,
 {
   AtkSelectionIface *iface;
 
-  g_return_val_if_fail (obj != NULL, NULL);
   g_return_val_if_fail (ATK_IS_SELECTION (obj), NULL);
 
   iface = ATK_SELECTION_GET_IFACE (obj);
@@ -108,21 +182,22 @@ atk_selection_ref_selection (AtkSelection *obj,
 
 /**
  * atk_selection_get_selection_count:
- * @value: a GObject instance that implements AtkSelectionIface
- * @return: a gint representing the number of items selected, or 0
- * if value does not implement this interface.
+ * @selection: a #GObject instance that implements AtkSelectionIface
  *
- * WARNING: callers should not rely on %NULL or on a zero value for
+ * Gets the number of accessible children currently selected.
+ * Note: callers should not rely on %NULL or on a zero value for
  * indication of whether AtkSelectionIface is implemented, they should
  * use type checking/interface checking macros or the
  * atk_get_accessible_value() convenience method.
+ *
+ * Returns: a gint representing the number of items selected, or 0
+ * if @selection does not implement this interface.
  **/
 gint
 atk_selection_get_selection_count (AtkSelection *obj)
 {
   AtkSelectionIface *iface;
 
-  g_return_val_if_fail (obj != NULL, 0);
   g_return_val_if_fail (ATK_IS_SELECTION (obj), 0);
 
   iface = ATK_SELECTION_GET_IFACE (obj);
@@ -135,14 +210,17 @@ atk_selection_get_selection_count (AtkSelection *obj)
 
 /**
  * atk_selection_is_child_selected:
- * @value: a GObject instance that implements AtkSelectionIface
- * @return: a gboolean representing the specified child is selected, or 0
- * if value does not implement this interface.
+ * @selection: a #GObject instance that implements AtkSelectionIface
+ * @i: a #gint specifying the child index.
  *
- * WARNING: callers should not rely on %NULL or on a zero value for
+ * Determines if the current child of this object is selected
+ * Note: callers should not rely on %NULL or on a zero value for
  * indication of whether AtkSelectionIface is implemented, they should
  * use type checking/interface checking macros or the
  * atk_get_accessible_value() convenience method.
+ *
+ * Returns: a gboolean representing the specified child is selected, or 0
+ * if @selection does not implement this interface.
  **/
 gboolean
 atk_selection_is_child_selected (AtkSelection *obj,
@@ -150,7 +228,6 @@ atk_selection_is_child_selected (AtkSelection *obj,
 {
   AtkSelectionIface *iface;
 
-  g_return_val_if_fail (obj != NULL, FALSE);
   g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 
   iface = ATK_SELECTION_GET_IFACE (obj);
@@ -163,39 +240,50 @@ atk_selection_is_child_selected (AtkSelection *obj,
 
 /**
  * atk_selection_remove_selection:
- * @value: a GObject instance that implements AtkSelectionIface
- * @return: void
+ * @selection: a #GObject instance that implements AtkSelectionIface
+ * @i: a #gint specifying the index in the selection set.  (e.g. the
+ * ith selection as opposed to the ith child).
+ *
+ * Removes the specified child of the object from the object's selection.
+ *
+ * Returns: TRUE if success, FALSE otherwise.
  **/
-void
+gboolean
 atk_selection_remove_selection (AtkSelection *obj,
                                 gint         i)
 {
   AtkSelectionIface *iface;
 
-  g_return_if_fail (obj != NULL);
-  g_return_if_fail (ATK_IS_SELECTION (obj));
+  g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 
   iface = ATK_SELECTION_GET_IFACE (obj);
 
   if (iface->remove_selection)
-    (iface->remove_selection) (obj, i);
+    return (iface->remove_selection) (obj, i);
+  else
+    return FALSE;
 }
 
 /**
  * atk_selection_select_all_selection:
- * @value: a GObject instance that implements AtkSelectionIface
- * @return: void
+ * @selection: a #GObject instance that implements AtkSelectionIface
+ *
+ * Causes every child of the object to be selected if the object
+ * supports multiple selections.
+ *
+ * Returns: TRUE if success, FALSE otherwise.
  **/
-void
+gboolean
 atk_selection_select_all_selection (AtkSelection *obj)
 {
   AtkSelectionIface *iface;
 
-  g_return_if_fail (obj != NULL);
-  g_return_if_fail (ATK_IS_SELECTION (obj));
+  g_return_val_if_fail (ATK_IS_SELECTION (obj), FALSE);
 
   iface = ATK_SELECTION_GET_IFACE (obj);
 
   if (iface->select_all_selection)
-    (iface->select_all_selection) (obj);
+    return (iface->select_all_selection) (obj);
+  else
+    return FALSE;
 }