X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=atk%2Fatkstateset.c;h=d240ee6e10fc8ce7699f8ab965adde15ae40a86a;hb=e91d02fcd860bd758e8ec9b85b19a16cdffba2bc;hp=6c800217f53be345cdbb68e381c77cdf066f0618;hpb=3c9d927bbeacec90436f53d5eecca478706ce24d;p=platform%2Fupstream%2Fatk.git diff --git a/atk/atkstateset.c b/atk/atkstateset.c index 6c80021..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 { @@ -65,10 +77,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 +90,47 @@ 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 + * + * 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. **/ 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 +144,17 @@ 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 + * 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, @@ -140,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; @@ -152,8 +174,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 +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; @@ -170,19 +191,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 +215,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 +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; @@ -224,19 +245,24 @@ 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. + * + * 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 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 +277,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 +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; @@ -285,12 +311,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: (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, @@ -300,29 +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 + * 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 +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;