idl/Accessibility_State.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems Inc.
   6  *
   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.
  11  *
  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.
  16  *
  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.
  21  */
  22
  23 #ifndef _ACCESSIBILITY_STATE_IDL
  24 #define _ACCESSIBILITY_STATE_IDL
  25
  26 module Accessibility {
  27
  28   enum StateType {
  29   STATE_INVALID,
  30   /** Indicates a window is currently the active window, or is an active subelement within a container or table **/
  31   STATE_ACTIVE,
  32   /** Indicates that the object is armed */
  33   STATE_ARMED,
  34   /**
  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.
  37    */
  38   STATE_BUSY,
  39   /** Indicates this object is currently checked */
  40   STATE_CHECKED,
  41   /** Indicates this object is collapsed */
  42   STATE_COLLAPSED,
  43   /** Indicates that this object no longer has a valid backing widget
  44    * (for instance, if its peer object has been destroyed) */
  45   STATE_DEFUNCT,
  46   /** Indicates the user can change the contents of this object */
  47   STATE_EDITABLE,
  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.
  51    */
  52   STATE_ENABLED,
  53   /** Indicates this object allows progressive disclosure of its children */
  54   STATE_EXPANDABLE,
  55   /** Indicates this object its expanded */
  56   STATE_EXPANDED,
  57   /**
  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
  61    */
  62   STATE_FOCUSABLE,
  63   /** Indicates this object currently has the keyboard focus */
  64   STATE_FOCUSED,
  65   /** Indicates that the object has an associated tooltip */
  66   STATE_HAS_TOOLTIP,
  67   /** Indicates the orientation of thsi object is horizontal */
  68   STATE_HORIZONTAL,
  69   /** Indicates this object is minimized and is represented only by an icon */
  70   STATE_ICONIFIED,
  71   /**
  72    * Indicates something must be done with this object before the user can
  73    * interact with an object in a different window.
  74    */
  75   STATE_MODAL,
  76   /** Indicates this (text) object can contain multiple lines of text */
  77   STATE_MULTI_LINE,
  78   /**
  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.
  82    */
  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.
  86    */
  87   STATE_OPAQUE,
  88   /** Indicates this object is currently pressed */
  89   STATE_PRESSED,
  90   /** Indicates the size of this object's size is not fixed */
  91   STATE_RESIZABLE,
  92   /**
  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.
  96    */
  97   STATE_SELECTABLE,
  98   /**
  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.
 102    */
 103   STATE_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. */
 111   STATE_SENSITIVE,
 112   /**
 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.
 117    */
 118   STATE_SHOWING,
 119   /** Indicates this (text) object can contain only a single line of text */
 120   STATE_SINGLE_LINE,
 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. */
 124   STATE_STALE,
 125   /** Indicates this object is transient */
 126   STATE_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.
 129    */
 130   STATE_VERTICAL,
 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'.
 138    */
 139   STATE_VISIBLE,
 140   /**
 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.
 150    */
 151   STATE_MANAGES_DESCENDANTS,
 152   /**
 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.
 161    */
 162   STATE_INDETERMINATE,
 163   /**
 164    * Indicates that user interaction with this object is 'required' from the user,
 165    * for instance before completing the processing of a form.
 166    */
 167   STATE_REQUIRED,
 168   /**
 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.
 171    */
 172   STATE_TRUNCATED,
 173   /**
 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.
 181    *
 182    * @since AT-SPI 1.7.0
 183    */
 184   STATE_ANIMATED,
 185   /**
 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.
 189    *
 190    * @since AT-SPI 1.7.0
 191    */
 192   STATE_INVALID_ENTRY,
 193   /**
 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.
 202    *
 203    * @since AT-SPI 1.7.0
 204    */
 205   STATE_SUPPORTS_AUTOCOMPLETION,
 206   /**
 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.
 213    *
 214    * @since AT-SPI 1.7.0
 215    */
 216   STATE_SELECTABLE_TEXT,
 217   /**
 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.
 221    *
 222    * @since AT-SPI 1.7.0
 223    */
 224   STATE_IS_DEFAULT,
 225   /**
 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.
 229    *
 230    * @since AT-SPI 1.7.1
 231    */
 232   STATE_VISITED,
 233
 234   /** This value of the enumeration should not be used as a parameter, it indicates the number of
 235    * items in the StateType enumeration.
 236    */
 237   STATE_LAST_DEFINED
 238   };
 239
 240   typedef sequence <StateType> StateSeq;
 241
 242     /**
 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.
 246      */
 247   interface StateSet : Bonobo::Unknown {
 248
 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.
 252      */
 253     boolean             contains (in StateType state);
 254
 255     /** Add a StateType to an existing StateSet, if not already present. */
 256     void                add (in StateType state);
 257
 258     /** Remove a StateType to an existing StateSet, if it is present. */
 259     void                remove (in StateType state);
 260
 261     /** Compare two statesets for equivalence.
 262      * @param tarStateSet the StateSet to be compared with this one.
 263      * @returns \c TRUE if the two StateSet objects are composed of the same StateTypes.
 264      */
 265     boolean             equals (in StateSet tarStateSet);
 266
 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);
 271
 272     /** @returns \c TRUE if the StateSet contains no states. */
 273     boolean             isEmpty ();
 274
 275     /** \cond */
 276     /* Private */
 277     StateSeq getStates ();
 278
 279     /**
 280      * unImplemented:
 281      *
 282      * placeholders for future expansion.
 283      */
 284     void unImplemented ();
 285     void unImplemented2 ();
 286     void unImplemented3 ();
 287     void unImplemented4 ();
 288     /** \endcond */
 289   };
 290 };
 291
 292 #endif