X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=atk%2Fatkstateset.c;h=d240ee6e10fc8ce7699f8ab965adde15ae40a86a;hb=refs%2Fheads%2Ftizen_3.0_tv;hp=7ff9348eb9ab8fff0913c11a2606f7807167fb26;hpb=e5d4548d3f59062dd2b9923826ef86ac3b626524;p=platform%2Fupstream%2Fatk.git diff --git a/atk/atkstateset.c b/atk/atkstateset.c index 7ff9348..d240ee6 100755 --- a/atk/atkstateset.c +++ b/atk/atkstateset.c @@ -17,12 +17,24 @@ * Boston, MA 02111-1307, USA. */ +#include "config.h" + #include #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 { @@ -79,34 +91,38 @@ atk_state_set_new (void) /** * atk_state_set_is_empty: - * @set: a #AtkStateType + * @set: an #AtkStateType * * Checks whether the state set is empty, i.e. has no states set. * - * Returns: %TRUE if @set 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 + * @set: an #AtkStateSet + * @type: an #AtkStateType + * + * Adds the state of the specified type to the state set if it is not already + * present. * - * Add a new state for the specified type to the current 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. **/ @@ -115,7 +131,6 @@ 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; @@ -130,11 +145,16 @@ atk_state_set_add_state (AtkStateSet *set, } /** * atk_state_set_add_states: - * @set: a #AtkStateSet - * @types: a array of #AtkStateType + * @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 + * 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, @@ -143,7 +163,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; @@ -156,7 +175,7 @@ atk_state_set_add_states (AtkStateSet *set, /** * atk_state_set_clear_states: - * @set: a #AtkStateSet + * @set: an #AtkStateSet * * Removes all states from the state set. **/ @@ -164,7 +183,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; @@ -174,8 +192,8 @@ atk_state_set_clear_states (AtkStateSet *set) /** * atk_state_set_contains_state: - * @set: a #AtkStateSet - * @type: a #AtkStateType + * @set: an #AtkStateSet + * @type: an #AtkStateType * * Checks whether the state for the specified type is in the specified set. * @@ -186,7 +204,6 @@ 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; @@ -199,8 +216,8 @@ atk_state_set_contains_state (AtkStateSet *set, /** * atk_state_set_contains_states: - * @set: a #AtkStateSet - * @types: a array of #AtkStateType + * @set: an #AtkStateSet + * @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 @@ -215,7 +232,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; @@ -230,11 +246,16 @@ atk_state_set_contains_states (AtkStateSet *set, /** * atk_state_set_remove_state: - * @set: a #AtkStateSet - * @type: a #AtkType + * @set: an #AtkStateSet + * @type: an #AtkType * * 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 @@ -242,7 +263,6 @@ 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; @@ -258,13 +278,14 @@ atk_state_set_remove_state (AtkStateSet *set, /** * atk_state_set_and_sets: - * @set: a #AtkStateSet + * @set: an #AtkStateSet * @compare_set: another #AtkStateSet * - * 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: 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, @@ -274,10 +295,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; @@ -293,12 +312,13 @@ atk_state_set_and_sets (AtkStateSet *set, /** * atk_state_set_or_sets: - * @set: a #AtkStateSet + * @set: an #AtkStateSet * @compare_set: another #AtkStateSet * * Constructs the union of the two sets. * - * Returns: a new #AtkStateSet which is the union of the two sets. + * 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,30 +328,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 + * @set: an #AtkStateSet * @compare_set: another #AtkStateSet * - * 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: a new #AtkStateSet which contains the states which are in exactly one of ht 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, @@ -341,10 +365,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;