X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=atk%2Fatkstateset.c;h=d240ee6e10fc8ce7699f8ab965adde15ae40a86a;hb=9466ce9bee6c89abed3014f399c34c0ea3563d31;hp=bb71a3a705a5ab3cff31fe9300e1df866010be76;hpb=6c403fd5b8ab042c3bf8671d3c832cf85570008a;p=platform%2Fupstream%2Fatk.git

diff --git a/atk/atkstateset.c b/atk/atkstateset.c
old mode 100755
new mode 100644
index bb71a3a..d240ee6
--- a/atk/atkstateset.c
+++ b/atk/atkstateset.c
@@ -17,12 +17,24 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "config.h"
+
 #include <glib-object.h>
 
 #include "atkobject.h"
 #include "atkstateset.h"
 
-#define ATK_STATE(state_enum)             ((AtkState)(1 << ((guint64)(state_enum)%64)))
+/**
+ * SECTION:atkstateset
+ * @Short_description: An AtkStateSet contains the states of an object.
+ * @Title:AtkStateSet
+ *
+ * An AtkStateSet is a read-only representation of the full set of #AtkStates
+ * that apply to an object at a given time. This set is not meant to be
+ * modified, but rather created when #atk_object_ref_state_set() is called.
+ */
+
+#define ATK_STATE(state_enum)             ((AtkState)((guint64)1 << ((state_enum)%64)))
 
 struct _AtkRealStateSet
 {
@@ -104,8 +116,13 @@ atk_state_set_is_empty (AtkStateSet   *set)
  * @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.
+ * Adds the state of the specified type to the state set if it is not already
+ * present.
+ *
+ * Note that because an #AtkStateSet is a read-only object, this method should
+ * be used to add a state to a newly-created set which will then be returned by
+ * #atk_object_ref_state_set. It should not be used to modify the existing state
+ * of an object. See also #atk_object_notify_state_change.
  *
  * Returns: %TRUE if  the state for @type is not already in @set.
  **/
@@ -129,10 +146,15 @@ atk_state_set_add_state (AtkStateSet   *set,
 /**
  * atk_state_set_add_states:
  * @set: an #AtkStateSet
- * @types: an array of #AtkStateType
+ * @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.
+ * Adds the states of the specified types to the state set.
+ *
+ * Note that because an #AtkStateSet is a read-only object, this method should
+ * be used to add states to a newly-created set which will then be returned by
+ * #atk_object_ref_state_set. It should not be used to modify the existing state
+ * of an object. See also #atk_object_notify_state_change.
  **/
 void
 atk_state_set_add_states (AtkStateSet   *set,
@@ -195,7 +217,7 @@ atk_state_set_contains_state (AtkStateSet   *set,
 /**
  * atk_state_set_contains_states:
  * @set: an #AtkStateSet
- * @types: an array of #AtkStateType
+ * @types: (array length=n_types): an array of #AtkStateType
  * @n_types: The number of elements in the array
  *
  * Checks whether the states for all the specified types are in the 
@@ -229,6 +251,11 @@ atk_state_set_contains_states (AtkStateSet   *set,
  *
  * Removes the state for the specified type from the state set.
  *
+ * Note that because an #AtkStateSet is a read-only object, this method should
+ * be used to remove a state to a newly-created set which will then be returned
+ * by #atk_object_ref_state_set. It should not be used to modify the existing
+ * state of an object. See also #atk_object_notify_state_change.
+ *
  * Returns: %TRUE if @type was the state type is in @set.
  **/
 gboolean
@@ -257,7 +284,8 @@ atk_state_set_remove_state (AtkStateSet  *set,
  * Constructs the intersection of the two sets, returning %NULL if the
  * intersection is empty.
  *
- * Returns: a new #AtkStateSet which is the intersection of the two sets.
+ * Returns: (transfer full): a new #AtkStateSet which is the intersection of
+ * the two sets.
  **/
 AtkStateSet*
 atk_state_set_and_sets (AtkStateSet  *set,
@@ -289,8 +317,8 @@ atk_state_set_and_sets (AtkStateSet  *set,
  *
  * Constructs the union of the two sets.
  *
- * Returns: a new #AtkStateSet which is the union of the two sets,
- * returning %NULL is empty.
+ * Returns: (nullable) (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,
@@ -308,8 +336,11 @@ atk_state_set_or_sets (AtkStateSet  *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;
 }
@@ -323,8 +354,8 @@ atk_state_set_or_sets (AtkStateSet  *set,
  * The set returned by this operation contains the states in exactly
  * one of the two sets.
  *
- * Returns: a new #AtkStateSet which contains the states which are 
- * 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,