2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001 Sun Microsystems Inc.
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 #ifndef _ACCESSIBILITY_STATE_IDL
24 #define _ACCESSIBILITY_STATE_IDL
26 module Accessibility {
30 /** Indicates a window is currently the active window, or is an active subelement within a container or table **/
32 /** Indicates that the object is armed */
35 * Indicates the current object is busy, i.e. onscreen representation is in the process of changing, or
36 * the object is temporarily unavailable for interaction due to activity already in progress.
39 /** Indicates this object is currently checked */
41 /** Indicates this object is collapsed */
43 /** Indicates that this object no longer has a valid backing widget
44 * (for instance, if its peer object has been destroyed) */
46 /** Indicates the user can change the contents of this object */
48 /** Indicates that this object is enabled, i.e. that it currently reflects some application state.
49 * Objects that are "greyed out" may lack this state, and may lack the STATE_SENSITIVE if direct user
50 * interaction cannot cause them to acquire STATE_ENABLED. @see STATE_SENSITIVE.
53 /** Indicates this object allows progressive disclosure of its children */
55 /** Indicates this object its expanded */
58 * Indicates this object can accept keyboard focus, which means all
59 * events resulting from typing on the keyboard will normally be passed
60 * to it when it has focus
63 /** Indicates this object currently has the keyboard focus */
65 /** Indicates that the object has an associated tooltip */
67 /** Indicates the orientation of thsi object is horizontal */
69 /** Indicates this object is minimized and is represented only by an icon */
72 * Indicates something must be done with this object before the user can
73 * interact with an object in a different window.
76 /** Indicates this (text) object can contain multiple lines of text */
79 * Indicates this object allows more than one of its children to be
80 * selected at the same time, or in the case of text objects,
81 * that the object supports non-contiguous text selections.
83 STATE_MULTISELECTABLE,
84 /** Indicates this object paints every pixel within its rectangular region.
85 * It also indicates an alpha value of unity, if it supports alpha blending.
88 /** Indicates this object is currently pressed */
90 /** Indicates the size of this object's size is not fixed */
93 * Indicates this object is the child of an object that allows its
94 * children to be selected and that this child is one of those children
95 * that can be selected.
99 * Indicates this object is the child of an object that allows its
100 * children to be selected and that this child is one of those children
101 * that has been selected.
104 /** Indicates this object is sensitive, e.g. to user interaction.
105 * STATE_SENSITIVE usually accompanies STATE_ENABLED for user-actionable controls,
106 * but may be found in the absence of STATE_ENABLED if the current visible state of the
107 * control is "disconnected" from the application state. In such cases, direct user interaction
108 * can often result in the object gaining STATE_SENSITIVE, for instance if a user makes
109 * an explicit selection using an object whose current state is ambiguous or undefined.
110 * @see STATE_ENABLED, STATE_INDETERMINATE. */
113 * Indicates this object, the object's parent, the object's parent's
114 * parent, and so on, are all 'shown' to the end-user, i.e.
115 * subject to "exposure" if blocking or obscuring objects do not interpose
116 * between this object and the top of the window stack.
119 /** Indicates this (text) object can contain only a single line of text */
121 /** Indicates that the information returned for this object may no longer be
122 * synchronized with the application state. This can occur if the object has STATE_TRANSIENT,
123 * and can also occur towards the end of the object peer's lifecycle. */
125 /** Indicates this object is transient */
127 /** Indicates the orientation of this object is vertical; for example this state may appear on
128 * such objects as scrollbars, text objects (with vertical text flow), separators, etc.
131 /** Indicates this object is visible, e.g. has been explicitly marked for exposure to the user.
132 * @note: STATE_VISIBLE is no guarantee that the object is actually unobscured on the screen, only
133 * that it is 'potentially' visible, barring obstruction, being scrolled or clipped out of the
134 * field of view, or having an ancestor container that has not yet made visible.
135 * A widget is potentially onscreen if it has both STATE_VISIBLE and STATE_SHOWING.
136 * The absence of STATE_VISIBLE and STATE_SHOWING is semantically equivalent to saying
137 * that an object is 'hidden'.
141 * Indicates that "active-descendant-changed" event is sent when children
142 * become 'active' (i.e. are selected or navigated to onscreen). Used to
143 * prevent need to enumerate all children in very large containers, like
144 * tables. The presence of STATE_MANAGES_DESCENDANTS is an indication to the client.
145 * that the children should not, and need not, be enumerated by the client.
146 * Objects implementing this state are expected to provide relevant state
147 * notifications to listening clients, for instance notifications of visibility
148 * changes and activation of their contained child objects, without the client
149 * having previously requested references to those children.
151 STATE_MANAGES_DESCENDANTS,
153 * Indicates that a check box or other boolean indicator is in a state other than
154 * checked or not checked. This usually means that the boolean value reflected or
155 * controlled by the object does not apply consistently to the entire current context.
156 * For example, a checkbox for the "Bold" attribute of text may have STATE_INDETERMINATE
157 * if the currently selected text contains a mixture of weight attributes.
158 * In many cases interacting with a STATE_INDETERMINATE object will cause
159 * the context's corresponding boolean attribute to be homogenized, whereupon the object
160 * will lose STATE_INDETERMINATE and a corresponding state-changed event will be fired.
164 * Indicates that user interaction with this object is 'required' from the user,
165 * for instance before completing the processing of a form.
169 * Indicates that an object's onscreen content is truncated, e.g. a text value in a spreadsheet cell.
170 * @since AT-SPI 1.7.0.
174 * Indicates this object's visual representation is dynamic, not static.
175 * This state may be applied to an object during an animated 'effect' and
176 * be removed from the object once its visual representation becomes static.
177 * @note some applications, notably content viewers, may not be able to detect
178 * all kinds of animated content. Therefore the absence of this state should not
179 * be taken as definitive evidence that the object's visual representation is
180 * static; this state is advisory.
182 * @since AT-SPI 1.7.0
186 * This object has indicated an error condition due to failure of input
187 * validation. For instance, a form control may acquire this state in response
188 * to invalid or malformed user input.
190 * @since AT-SPI 1.7.0
194 * This state indicates that the object in question implements some form of ¨typeahead¨ or
195 * pre-selection behavior whereby entering the first character of one or more sub-elements
196 * causes those elements to scroll into view or become selected. Subsequent character input
197 * may narrow the selection further as long as one or more sub-elements match the string.
198 * This state is normally only useful and encountered on objects that implement Selection.
199 * In some cases the typeahead behavior may result in full or partial ¨completion¨ of
200 * the data in the input field, in which case these input events may trigger text-changed
201 * events from the source.
203 * @since AT-SPI 1.7.0
205 STATE_SUPPORTS_AUTOCOMPLETION,
207 * This state indicates that the object in question supports text selection.
208 * It should only be exposed on objects which implement the Text interface,
209 * in order to distinguish this state from STATE_SELECTABLE, which infers that
210 * the object in question is a selectable child of an object which implements
211 * Selection. While similar, text selection and subelement selection are
212 * distinct operations.
214 * @since AT-SPI 1.7.0
216 STATE_SELECTABLE_TEXT,
218 * This state indicates that the object in question is the 'default' interaction object
219 * in a dialog, i.e. the one that gets activated if the user presses "Enter" when the
220 * dialog is initially posted.
222 * @since AT-SPI 1.7.0
226 * This state indicates that the object (typically a hyperlink)
227 * has already been activated or invoked, with the result that some backing data
228 * has been downloaded or rendered.
230 * @since AT-SPI 1.7.1
234 /** This value of the enumeration should not be used as a parameter, it indicates the number of
235 * items in the StateType enumeration.
240 typedef sequence <StateType> StateSeq;
243 * The StateSet interface encapsulates a collection of state information.
244 * It allows comparison of state information between object instances, and comparisons
245 * of an object's state with some hypothetical collection of states.
247 interface StateSet : Bonobo::Unknown {
249 /** Query a StateSet for a specific StateType.
250 * @param state the StateType being queried for.
251 * @returns \c TRUE if the StateSet contains StateType \a state.
253 boolean contains (in StateType state);
255 /** Add a StateType to an existing StateSet, if not already present. */
256 void add (in StateType state);
258 /** Remove a StateType to an existing StateSet, if it is present. */
259 void remove (in StateType state);
261 /** Compare two statesets for equivalence.
262 * @param stateSet the StateSet to be compared with this one.
263 * @returns \c TRUE if the two StateSet objects are composed of the same StateTypes.
265 boolean equals (in StateSet stateSet);
267 /** Compare two StateSet instances and obtain their differences.
268 * @returns a 'difference set', i.e. a StateSet consisting of those states
269 * not shared by the two sets being compared. */
270 StateSet compare (in StateSet compareState);
272 /** @returns \c TRUE if the StateSet contains no states. */
277 StateSeq getStates ();
282 * placeholders for future expansion.
284 void unImplemented ();
285 void unImplemented2 ();
286 void unImplemented3 ();
287 void unImplemented4 ();