/* 
 * AT-SPI - Assistive Technology Service Provider Interface 
 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
 *
 * Copyright 2001 Sun Microsystems Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#ifndef _ACCESSIBILITY_STATE_IDL
#define _ACCESSIBILITY_STATE_IDL

module Accessibility {

  enum StateType {
  STATE_INVALID,
  /** 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 */
  STATE_ARMED,
  /** 
   * 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 */
  STATE_CHECKED,
  /** Indicates this object is collapsed */
  STATE_COLLAPSED,
  /** 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 */
  STATE_EDITABLE,
  /** 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 */
  STATE_EXPANDABLE,
  /** 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 */
  STATE_FOCUSED,
  /** Indicates that the object has an associated tooltip */
  STATE_HAS_TOOLTIP,
  /** Indicates the orientation of thsi object is horizontal */
  STATE_HORIZONTAL,
  /** 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 */
  STATE_MULTI_LINE,
  /**
   * Indicates this object allows more than one of its children to be
   * 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.
   * It also indicates an alpha value of unity, if it supports alpha blending. 
   */
  STATE_OPAQUE,
  /** Indicates this object is currently pressed */
  STATE_PRESSED,
  /** 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, 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 '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 */
  STATE_SINGLE_LINE,
  /** 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 */
  STATE_TRANSIENT,
  /** 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, 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);

    /** 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 ();

    /**
     * unImplemented:
     *
     * placeholders for future expansion.
     */
    void unImplemented ();
    void unImplemented2 ();
    void unImplemented3 ();
    void unImplemented4 ();
    /** \endcond */
  };
};

#endif