X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=idl%2FAccessibility_State.idl;h=189fa7cd46b6c53c3b67a3e60ac58d7574f70528;hb=54e12e5a757d6eace45f45f08edaa778af6e0960;hp=566c70d43439cef76d4b75bf9fa30753b20a3673;hpb=be2f9288bfa43de706c8abc2197c3660069ad0ae;p=platform%2Fcore%2Fuifw%2Fat-spi2-atk.git diff --git a/idl/Accessibility_State.idl b/idl/Accessibility_State.idl index 566c70d..189fa7c 100644 --- a/idl/Accessibility_State.idl +++ b/idl/Accessibility_State.idl @@ -27,101 +27,252 @@ module Accessibility { 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 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 (); @@ -132,6 +283,9 @@ module Accessibility { */ void unImplemented (); void unImplemented2 (); + void unImplemented3 (); + void unImplemented4 (); + /** \endcond */ }; };