enum StateType {
STATE_INVALID,
- /* Indicates a window is currently the active window */
+ /** Indicates a window is currently the active window, or is an active subelement within a container or table **/
STATE_ACTIVE,
- /* Indicates that the object is armed */
+ /** Indicates that the object is armed */
STATE_ARMED,
- /* Indicates the current object is busy */
+ /**
+ * Indicates the current object is busy, i.e. onscreen representation is in the process of changing, or
+ * the object is temporarily unavailable for interaction due to activity already in progress.
+ */
STATE_BUSY,
- /* Indicates this object is currently checked */
+ /** Indicates this object is currently checked */
STATE_CHECKED,
- /* Indicates this object is collapsed */
+ /** Indicates this object is collapsed */
STATE_COLLAPSED,
- /* Indicates that this object no longer contains a backing widget */
+ /** Indicates that this object no longer has a valid backing widget
+ * (for instance, if its peer object has been destroyed) */
STATE_DEFUNCT,
- /* Indicates the user can change the contents of this object */
+ /** Indicates the user can change the contents of this object */
STATE_EDITABLE,
- /* Indicates that this object is enabled */
+ /** Indicates that this object is enabled, i.e. that it currently reflects some application state.
+ * Objects that are "greyed out" may lack this state, and may lack the STATE_SENSITIVE if direct user
+ * interaction cannot cause them to acquire STATE_ENABLED. @see STATE_SENSITIVE.
+ */
STATE_ENABLED,
- /* Indicates this object allows progressive disclosure of its children */
+ /** Indicates this object allows progressive disclosure of its children */
STATE_EXPANDABLE,
- /* Indicates this object its expanded */
+ /** Indicates this object its expanded */
STATE_EXPANDED,
- /*
+ /**
* Indicates this object can accept keyboard focus, which means all
* events resulting from typing on the keyboard will normally be passed
* to it when it has focus
*/
STATE_FOCUSABLE,
- /* Indicates this object currently has the keyboard focus */
+ /** Indicates this object currently has the keyboard focus */
STATE_FOCUSED,
- /* Indicates that the object has an associated tooltip */
+ /** Indicates that the object has an associated tooltip */
STATE_HAS_TOOLTIP,
- /* Indicates the orientation of thsi object is horizontal */
+ /** Indicates the orientation of thsi object is horizontal */
STATE_HORIZONTAL,
- /* Indicates this object is minimized and is represented only by an icon */
+ /** Indicates this object is minimized and is represented only by an icon */
STATE_ICONIFIED,
- /*
+ /**
* Indicates something must be done with this object before the user can
* interact with an object in a different window.
*/
STATE_MODAL,
- /* Indicates this (text) object can contain multiple lines of text */
+ /** Indicates this (text) object can contain multiple lines of text */
STATE_MULTI_LINE,
- /*
+ /**
* Indicates this object allows more than one of its children to be
- * selected at the same time
+ * selected at the same time, or in the case of text objects,
+ * that the object supports non-contiguous text selections.
*/
STATE_MULTISELECTABLE,
- /* Indicates this object paints every pixel within its rectangular region. */
+ /** Indicates this object paints every pixel within its rectangular region.
+ * It also indicates an alpha value of unity, if it supports alpha blending.
+ */
STATE_OPAQUE,
- /* Indicates this object is currently pressed */
+ /** Indicates this object is currently pressed */
STATE_PRESSED,
- /* Indicates the size of this object is not fixed */
+ /** Indicates the size of this object's size is not fixed */
STATE_RESIZABLE,
- /*
+ /**
* Indicates this object is the child of an object that allows its
* children to be selected and that this child is one of those children
* that can be selected.
*/
STATE_SELECTABLE,
- /*
+ /**
* Indicates this object is the child of an object that allows its
* children to be selected and that this child is one of those children
* that has been selected.
*/
STATE_SELECTED,
- /* Indicates this object is sensitive */
+ /** Indicates this object is sensitive, e.g. to user interaction.
+ * STATE_SENSITIVE usually accompanies STATE_ENABLED for user-actionable controls,
+ * but may be found in the absence of STATE_ENABLED if the current visible state of the
+ * control is "disconnected" from the application state. In such cases, direct user interaction
+ * can often result in the object gaining STATE_SENSITIVE, for instance if a user makes
+ * an explicit selection using an object whose current state is ambiguous or undefined.
+ * @see STATE_ENABLED, STATE_INDETERMINATE. */
STATE_SENSITIVE,
- /*
+ /**
* Indicates this object, the object's parent, the object's parent's
- * parent, and so on, are all visible
+ * parent, and so on, are all 'shown' to the end-user, i.e.
+ * subject to "exposure" if blocking or obscuring objects do not interpose
+ * between this object and the top of the window stack.
*/
STATE_SHOWING,
- /* Indicates this (text) object can contain only a single line of text */
+ /** Indicates this (text) object can contain only a single line of text */
STATE_SINGLE_LINE,
- /* Indicates that this object's index within parent information may be invalid */
+ /** Indicates that the information returned for this object may no longer be
+ * synchronized with the application state. This can occur if the object has STATE_TRANSIENT,
+ * and can also occur towards the end of the object peer's lifecycle. */
STATE_STALE,
- /* Indicates this object is transient */
+ /** Indicates this object is transient */
STATE_TRANSIENT,
- /* Indicates the orientation of this object is vertical */
+ /** Indicates the orientation of this object is vertical; for example this state may appear on
+ * such objects as scrollbars, text objects (with vertical text flow), separators, etc.
+ */
STATE_VERTICAL,
- /* Indicates this object is visible */
+ /** Indicates this object is visible, e.g. has been explicitly marked for exposure to the user.
+ * @note: STATE_VISIBLE is no guarantee that the object is actually unobscured on the screen, only
+ * that it is 'potentially' visible, barring obstruction, being scrolled or clipped out of the
+ * field of view, or having an ancestor container that has not yet made visible.
+ * A widget is potentially onscreen if it has both STATE_VISIBLE and STATE_SHOWING.
+ * The absence of STATE_VISIBLE and STATE_SHOWING is semantically equivalent to saying
+ * that an object is 'hidden'.
+ */
STATE_VISIBLE,
+ /**
+ * Indicates that "active-descendant-changed" event is sent when children
+ * become 'active' (i.e. are selected or navigated to onscreen). Used to
+ * prevent need to enumerate all children in very large containers, like
+ * tables. The presence of STATE_MANAGES_DESCENDANTS is an indication to the client.
+ * that the children should not, and need not, be enumerated by the client.
+ * Objects implementing this state are expected to provide relevant state
+ * notifications to listening clients, for instance notifications of visibility
+ * changes and activation of their contained child objects, without the client
+ * having previously requested references to those children.
+ */
+ STATE_MANAGES_DESCENDANTS,
+ /**
+ * Indicates that a check box or other boolean indicator is in a state other than
+ * checked or not checked. This usually means that the boolean value reflected or
+ * controlled by the object does not apply consistently to the entire current context.
+ * For example, a checkbox for the "Bold" attribute of text may have STATE_INDETERMINATE
+ * if the currently selected text contains a mixture of weight attributes.
+ * In many cases interacting with a STATE_INDETERMINATE object will cause
+ * the context's corresponding boolean attribute to be homogenized, whereupon the object
+ * will lose STATE_INDETERMINATE and a corresponding state-changed event will be fired.
+ */
+ STATE_INDETERMINATE,
+ /**
+ * Indicates that user interaction with this object is 'required' from the user,
+ * for instance before completing the processing of a form.
+ */
+ STATE_REQUIRED,
+ /**
+ * Indicates that an object's onscreen content is truncated, e.g. a text value in a spreadsheet cell.
+ * @since AT-SPI 1.7.0.
+ */
+ STATE_TRUNCATED,
+ /**
+ * Indicates this object's visual representation is dynamic, not static.
+ * This state may be applied to an object during an animated 'effect' and
+ * be removed from the object once its visual representation becomes static.
+ * @note some applications, notably content viewers, may not be able to detect
+ * all kinds of animated content. Therefore the absence of this state should not
+ * be taken as definitive evidence that the object's visual representation is
+ * static; this state is advisory.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_ANIMATED,
+ /**
+ * This object has indicated an error condition due to failure of input
+ * validation. For instance, a form control may acquire this state in response
+ * to invalid or malformed user input.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_INVALID_ENTRY,
+ /**
+ * This state indicates that the object in question implements some form of ¨typeahead¨ or
+ * pre-selection behavior whereby entering the first character of one or more sub-elements
+ * causes those elements to scroll into view or become selected. Subsequent character input
+ * may narrow the selection further as long as one or more sub-elements match the string.
+ * This state is normally only useful and encountered on objects that implement Selection.
+ * In some cases the typeahead behavior may result in full or partial ¨completion¨ of
+ * the data in the input field, in which case these input events may trigger text-changed
+ * events from the source.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_SUPPORTS_AUTOCOMPLETION,
+ /**
+ * This state indicates that the object in question supports text selection.
+ * It should only be exposed on objects which implement the Text interface,
+ * in order to distinguish this state from STATE_SELECTABLE, which infers that
+ * the object in question is a selectable child of an object which implements
+ * Selection. While similar, text selection and subelement selection are
+ * distinct operations.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_SELECTABLE_TEXT,
+ /**
+ * This state indicates that the object in question is the 'default' interaction object
+ * in a dialog, i.e. the one that gets activated if the user presses "Enter" when the
+ * dialog is initially posted.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_IS_DEFAULT,
+ /**
+ * This state indicates that the object (typically a hyperlink)
+ * has already been activated or invoked, with the result that some backing data
+ * has been downloaded or rendered.
+ *
+ * @since AT-SPI 1.7.1
+ */
+ STATE_VISITED,
+
+ /** This value of the enumeration should not be used as a parameter, it indicates the number of
+ * items in the StateType enumeration.
+ */
STATE_LAST_DEFINED
};
typedef sequence <StateType> StateSeq;
+ /**
+ * The StateSet interface encapsulates a collection of state information.
+ * It allows comparison of state information between object instances, and comparisons
+ * of an object's state with some hypothetical collection of states.
+ */
interface StateSet : Bonobo::Unknown {
+
+ /** Query a StateSet for a specific StateType.
+ * @param state the StateType being queried for.
+ * @returns \c TRUE if the StateSet contains StateType \a state.
+ */
boolean contains (in StateType state);
+
+ /** Add a StateType to an existing StateSet, if not already present. */
void add (in StateType state);
+
+ /** Remove a StateType to an existing StateSet, if it is present. */
void remove (in StateType state);
- boolean equals (in StateSet stateSet);
- /* returns a 'difference set' */
+
+ /** Compare two statesets for equivalence.
+ * @param tarStateSet the StateSet to be compared with this one.
+ * @returns \c TRUE if the two StateSet objects are composed of the same StateTypes.
+ */
+ boolean equals (in StateSet tarStateSet);
+
+ /** Compare two StateSet instances and obtain their differences.
+ * @returns a 'difference set', i.e. a StateSet consisting of those states
+ * not shared by the two sets being compared. */
StateSet compare (in StateSet compareState);
+
+ /** @returns \c TRUE if the StateSet contains no states. */
boolean isEmpty ();
+ /** \cond */
/* Private */
StateSeq getStates ();
*/
void unImplemented ();
void unImplemented2 ();
+ void unImplemented3 ();
+ void unImplemented4 ();
+ /** \endcond */
};
};
projects / platform / core / uifw / at-spi2-atk.git / blobdiff