home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / idl / at-spi-1.0 / Accessibility_State.idl < prev    next >
Encoding:
Text File  |  2006-08-22  |  12.2 KB  |  293 lines
  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 stateSet 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 stateSet);
  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
  293.