diff options
author | Joanmarie Diggs <jdiggs@igalia.com> | 2014-11-13 09:11:04 -0500 |
---|---|---|
committer | Joanmarie Diggs <jdiggs@igalia.com> | 2014-11-14 07:06:03 -0500 |
commit | be5805852c8888585575da00c98807196b396610 (patch) | |
tree | d9dfb42dd3a5582cad878deb21604eaca4de29ac | |
parent | f460594f554f798214c94e5df6e8735bb16bb2ce (diff) | |
download | atk-be5805852c8888585575da00c98807196b396610.tar.gz |
Improve documentation related to AtkState and AtkStateSet
https://bugzilla.gnome.org/show_bug.cgi?id=740066
-rwxr-xr-x | atk/atkobject.c | 5 | ||||
-rwxr-xr-x | atk/atkstate.c | 8 | ||||
-rwxr-xr-x | atk/atkstateset.c | 28 | ||||
-rw-r--r-- | docs/atk-sections.txt | 1 |
4 files changed, 30 insertions, 12 deletions
diff --git a/atk/atkobject.c b/atk/atkobject.c index f381df1..3358ea5 100755 --- a/atk/atkobject.c +++ b/atk/atkobject.c @@ -1200,7 +1200,10 @@ atk_object_remove_property_change_handler (AtkObject *accessible, * @state: an #AtkState whose state is changed * @value: a gboolean which indicates whether the state is being set on or off * - * Emits a state-change signal for the specified state. + * Emits a state-change signal for the specified state. + * + * Note that as a general rule when the state of an existing object changes, + * emitting a notification is expected. **/ void atk_object_notify_state_change (AtkObject *accessible, diff --git a/atk/atkstate.c b/atk/atkstate.c index 2334fe8..b715c96 100755 --- a/atk/atkstate.c +++ b/atk/atkstate.c @@ -25,12 +25,12 @@ /** * SECTION:atkstate - * @Short_description: An AtkState describes a component's particular state. + * @Short_description: An AtkState describes a single state of an object. * @Title:AtkState * - * An AtkState describes a component's particular state. The actual - * state of an component is described by its AtkStateSet, which is a - * set of AtkStates. + * An AtkState describes a single state of an object. The full set of states + * that apply to an object at a given time are contained in its #AtkStateSet. + * See also #atk_object_ref_state_set and #atk_object_notify_state_change. */ static guint last_type = ATK_STATE_LAST_DEFINED; diff --git a/atk/atkstateset.c b/atk/atkstateset.c index 1740d05..d240ee6 100755 --- a/atk/atkstateset.c +++ b/atk/atkstateset.c @@ -26,11 +26,12 @@ /** * SECTION:atkstateset - * @Short_description: An AtkStateSet determines a component's state set. + * @Short_description: An AtkStateSet contains the states of an object. * @Title:AtkStateSet * - * An AtkStateSet determines a component's state set. It is composed - * of a set of AtkStates. + * 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))) @@ -115,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. **/ @@ -143,7 +149,12 @@ atk_state_set_add_state (AtkStateSet *set, * @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, @@ -240,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 diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt index f83bd50..1224f31 100644 --- a/docs/atk-sections.txt +++ b/docs/atk-sections.txt @@ -211,7 +211,6 @@ ATK_IS_IMPLEMENTOR ATK_IMPLEMENTOR ATK_TYPE_ROLE ATK_TYPE_LAYER -AtkStateSet atk_implementor_get_type atk_object_get_type atk_role_get_type |