* 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
{
}
/**
- * 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)
}
/**
- * 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;
}
}
/**
- * 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,
{
AtkRealStateSet *real_set;
gint i;
- g_return_if_fail (set != NULL);
g_return_if_fail (ATK_IS_STATE_SET (set));
real_set = (AtkRealStateSet *)set;
}
/**
- * atk_state_set_clear_states
- * @set: a #AtkStateSet
+ * atk_state_set_clear_states:
+ * @set: an #AtkStateSet
*
* Removes all states from the state set.
**/
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;
}
/**
- * 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;
}
/**
- * 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,
{
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;
}
/**
- * 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;
}
/**
- * 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,
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;
}
/**
- * 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,
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,
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;
projects / platform / upstream / atk.git / blobdiff