get_highlight_index callback added to the AtkComponentInterface

[platform/upstream/atk.git] / atk / atkstateset.c

diff --git a/atk/atkstateset.c b/atk/atkstateset.c
index 5f5e683..1497bed 100755 (executable)
--- a/atk/atkstateset.c
+++ b/atk/atkstateset.c
@@ -22,7 +22,16 @@
 #include "atkobject.h"
 #include "atkstateset.h"
 
-#define ATK_STATE(state_enum)             ((AtkStateMask)(1 << ((guint64)(state_enum)%64)))
+/**
+ * SECTION:atkstateset
+ * @Short_description: An AtkStateSet determines a component's state set.
+ * @Title:AtkStateSet
+ *
+ * An AtkStateSet determines a component's state set. It is composed
+ * of a set of AtkStates.
+ */
+
+#define ATK_STATE(state_enum)             ((AtkState)((guint64)1 << ((state_enum)%64)))
 
 struct _AtkRealStateSet
 {
@@ -65,10 +74,11 @@ atk_state_set_class_init (AtkStateSetClass *klass)
 }
 
 /**
- * atk_state_set_new
- * return values: a new #AtkStateSet 
+ * atk_state_set_new:
  * 
  * Creates a new empty state set.
+ * 
+ * Returns: a new #AtkStateSet 
  **/
 AtkStateSet*
 atk_state_set_new (void)
@@ -77,42 +87,42 @@ atk_state_set_new (void)
 }
 
 /**
- * atk_state_set_is_empty
- * @type: a #AtkStateType
- * return values: %TRUE if @set has no states set
+ * atk_state_set_is_empty:
+ * @set: an #AtkStateType
  *
  * Checks whether the state set is empty, i.e. has no states set.
+ *
+ * Returns: %TRUE if @set has no states set, otherwise %FALSE
  **/
 gboolean
 atk_state_set_is_empty (AtkStateSet   *set)
 {
   AtkRealStateSet *real_set;
-  g_return_val_if_fail (set != NULL, FALSE);
   g_return_val_if_fail (ATK_IS_STATE_SET (set), FALSE);
 
   real_set = (AtkRealStateSet *)set;
 
   if (real_set->state)
-    return TRUE;
-  else
     return FALSE;
+  else
+    return TRUE;
 }
 
 /**
- * atk_state_set_add_state
- * @set: a #AtkStateSet
- * @type: a #AtkStateType
- * return values: %TRUE if  the state for @type is not already in @set.
+ * atk_state_set_add_state:
+ * @set: an #AtkStateSet
+ * @type: an #AtkStateType
  *
  * Add a new state for the specified type to the current state set if
- * it is not already present
+ * it is not already present.
+ *
+ * Returns: %TRUE if  the state for @type is not already in @set.
  **/
 gboolean
 atk_state_set_add_state (AtkStateSet   *set,
                          AtkStateType  type)
 {
   AtkRealStateSet *real_set;
-  g_return_val_if_fail (set != NULL, FALSE);
   g_return_val_if_fail (ATK_IS_STATE_SET (set), FALSE);
 
   real_set = (AtkRealStateSet *)set;
@@ -126,12 +136,12 @@ atk_state_set_add_state (AtkStateSet   *set,
   }
 }
 /**
- * atk_state_set_add_states
- * @set: a #AtkStateSet
- * @types: a array of #AtkStateType
+ * atk_state_set_add_states:
+ * @set: an #AtkStateSet
+ * @types: (array length=n_types): an array of #AtkStateType
  * @n_types: The number of elements in the array
  *
- * Add the states for the specified types to the current state set
+ * Add the states for the specified types to the current state set.
  **/
 void
 atk_state_set_add_states (AtkStateSet   *set,
@@ -140,7 +150,6 @@ atk_state_set_add_states (AtkStateSet   *set,
 {
   AtkRealStateSet *real_set;
   gint     i;
-  g_return_if_fail (set != NULL);
   g_return_if_fail (ATK_IS_STATE_SET (set));
 
   real_set = (AtkRealStateSet *)set;
@@ -152,8 +161,8 @@ atk_state_set_add_states (AtkStateSet   *set,
 }
 
 /**
- * atk_state_set_clear_states
- * @set: a #AtkStateSet
+ * atk_state_set_clear_states:
+ * @set: an #AtkStateSet
  *
  * Removes all states from the state set.
  **/
@@ -161,7 +170,6 @@ void
 atk_state_set_clear_states (AtkStateSet   *set)
 {
   AtkRealStateSet *real_set;
-  g_return_if_fail (set != NULL);
   g_return_if_fail (ATK_IS_STATE_SET (set));
 
   real_set = (AtkRealStateSet *)set;
@@ -170,19 +178,19 @@ atk_state_set_clear_states (AtkStateSet   *set)
 }
 
 /**
- * atk_state_set_contains_state
- * @set: a #AtkStateSet
- * @type: a #AtkStateType
- * return values: %TRUE if @type is the state type is in @set.
+ * atk_state_set_contains_state:
+ * @set: an #AtkStateSet
+ * @type: an #AtkStateType
  *
  * Checks whether the state for the specified type is in the specified set.
+ *
+ * Returns: %TRUE if @type is the state type is in @set.
  **/
 gboolean
 atk_state_set_contains_state (AtkStateSet   *set,
                               AtkStateType  type)
 {
   AtkRealStateSet *real_set;
-  g_return_val_if_fail (set != NULL, FALSE);
   g_return_val_if_fail (ATK_IS_STATE_SET (set), FALSE);
 
   real_set = (AtkRealStateSet *)set;
@@ -194,14 +202,15 @@ atk_state_set_contains_state (AtkStateSet   *set,
 }
 
 /**
- * atk_state_set_contains_states
- * @set: a #AtkStateSet
- * @types: a array of #AtkStateType
+ * atk_state_set_contains_states:
+ * @set: an #AtkStateSet
+ * @types: (array length=n_types): an array of #AtkStateType
  * @n_types: The number of elements in the array
- * return values: %TRUE if all the states for @type are in @set.
  *
  * Checks whether the states for all the specified types are in the 
  * specified set.
+ *
+ * Returns: %TRUE if all the states for @type are in @set.
  **/
 gboolean
 atk_state_set_contains_states (AtkStateSet   *set,
@@ -210,7 +219,6 @@ atk_state_set_contains_states (AtkStateSet   *set,
 {
   AtkRealStateSet *real_set;
   gint i;
-  g_return_val_if_fail (set != NULL, FALSE);
   g_return_val_if_fail (ATK_IS_STATE_SET (set), FALSE);
 
   real_set = (AtkRealStateSet *)set;
@@ -224,19 +232,19 @@ atk_state_set_contains_states (AtkStateSet   *set,
 }
 
 /**
- * atk_state_set_remove_state
- * @set: a #AtkStateSet
- * @type: a #AtkType
- * return values: %TRUE if @type was the state type is in @set.
+ * atk_state_set_remove_state:
+ * @set: an #AtkStateSet
+ * @type: an #AtkType
  *
  * Removes the state for the specified type from the state set.
+ *
+ * Returns: %TRUE if @type was the state type is in @set.
  **/
 gboolean
 atk_state_set_remove_state (AtkStateSet  *set,
                             AtkStateType type)
 {
   AtkRealStateSet *real_set;
-  g_return_val_if_fail (set != NULL, FALSE);
   g_return_val_if_fail (ATK_IS_STATE_SET (set), FALSE);
 
   real_set = (AtkRealStateSet *)set;
@@ -251,13 +259,15 @@ atk_state_set_remove_state (AtkStateSet  *set,
 }
 
 /**
- * atk_state_set_and_sets
- * @set: a #AtkStateSet
+ * atk_state_set_and_sets:
+ * @set: an #AtkStateSet
  * @compare_set: another #AtkStateSet
- * return values: a new #AtkStateSet which is the intersection of the two sets.
  *
- * Constructs the intersection of the two sets, returning NULL if the
+ * Constructs the intersection of the two sets, returning %NULL if the
  * intersection is empty.
+ *
+ * Returns: (transfer full): a new #AtkStateSet which is the intersection of
+ * the two sets.
  **/
 AtkStateSet*
 atk_state_set_and_sets (AtkStateSet  *set,
@@ -267,10 +277,8 @@ atk_state_set_and_sets (AtkStateSet  *set,
   AtkStateSet *return_set = NULL;
   AtkState state;
 
-  g_return_val_if_fail (set != NULL, FALSE);
-  g_return_val_if_fail (ATK_IS_STATE_SET (set), FALSE);
-  g_return_val_if_fail (compare_set != NULL, FALSE);
-  g_return_val_if_fail (ATK_IS_STATE_SET (compare_set), FALSE);
+  g_return_val_if_fail (ATK_IS_STATE_SET (set), NULL);
+  g_return_val_if_fail (ATK_IS_STATE_SET (compare_set), NULL);
 
   real_set = (AtkRealStateSet *)set;
   real_compare_set = (AtkRealStateSet *)compare_set;
@@ -285,12 +293,14 @@ atk_state_set_and_sets (AtkStateSet  *set,
 }
 
 /**
- * atk_state_set_or_sets
- * @set: a #AtkStateSet
+ * atk_state_set_or_sets:
+ * @set: an #AtkStateSet
  * @compare_set: another #AtkStateSet
- * return values: a new #AtkStateSet which is the union of the two sets.
  *
  * Constructs the union of the two sets.
+ *
+ * Returns: (transfer full): a new #AtkStateSet which is the union of the two
+ * sets, returning %NULL is empty.
  **/
 AtkStateSet*
 atk_state_set_or_sets (AtkStateSet  *set,
@@ -300,29 +310,34 @@ atk_state_set_or_sets (AtkStateSet  *set,
   AtkStateSet *return_set = NULL;
   AtkState state;
 
-  g_return_val_if_fail (set != NULL, FALSE);
-  g_return_val_if_fail (ATK_IS_STATE_SET (set), FALSE);
-  g_return_val_if_fail (compare_set != NULL, FALSE);
-  g_return_val_if_fail (ATK_IS_STATE_SET (compare_set), FALSE);
+  g_return_val_if_fail (ATK_IS_STATE_SET (set), NULL);
+  g_return_val_if_fail (ATK_IS_STATE_SET (compare_set), NULL);
 
   real_set = (AtkRealStateSet *)set;
   real_compare_set = (AtkRealStateSet *)compare_set;
 
   state = real_set->state | real_compare_set->state;
 
-  return_set = atk_state_set_new();
-  ((AtkRealStateSet *) return_set)->state = state;
+  if (state)
+  {
+    return_set = atk_state_set_new();
+    ((AtkRealStateSet *) return_set)->state = state;
+  }
 
   return return_set;
 }
 
 /**
- * atk_state_set_xor_sets
- * @set: a #AtkStateSet
+ * atk_state_set_xor_sets:
+ * @set: an #AtkStateSet
  * @compare_set: another #AtkStateSet
- * return values: a new #AtkStateSet which contains the states which are in exactly one of ht two sets.
  *
- * Constructs the xor of the two sets, returing NULL is empty. The set returned by this operation contains the4 sattes in exactly one of the two sets.
+ * Constructs the exclusive-or of the two sets, returning %NULL is empty.
+ * The set returned by this operation contains the states in exactly
+ * one of the two sets.
+ *
+ * Returns: (transfer full): a new #AtkStateSet which contains the states
+ * which are in exactly one of the two sets.
  **/
 AtkStateSet*
 atk_state_set_xor_sets (AtkStateSet  *set,
@@ -332,10 +347,8 @@ atk_state_set_xor_sets (AtkStateSet  *set,
   AtkStateSet *return_set = NULL;
   AtkState state, state1, state2;
 
-  g_return_val_if_fail (set != NULL, FALSE);
-  g_return_val_if_fail (ATK_IS_STATE_SET (set), FALSE);
-  g_return_val_if_fail (compare_set != NULL, FALSE);
-  g_return_val_if_fail (ATK_IS_STATE_SET (compare_set), FALSE);
+  g_return_val_if_fail (ATK_IS_STATE_SET (set), NULL);
+  g_return_val_if_fail (ATK_IS_STATE_SET (compare_set), NULL);
 
   real_set = (AtkRealStateSet *)set;
   real_compare_set = (AtkRealStateSet *)compare_set;