/* 
 * 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_ACCESSIBLE_IDL
#define _ACCESSIBILITY_ACCESSIBLE_IDL

#include "Accessibility_Relation.idl"
#include "Accessibility_State.idl"
#include "Accessibility_Role.idl"

module Accessibility {
  
  /** used by Text and Document: these correspond to the POSIX setlocale() enum values. **/
  enum LOCALE_TYPE {
      LOCALE_TYPE_MESSAGES,
      LOCALE_TYPE_COLLATE,
      LOCALE_TYPE_CTYPE,
      LOCALE_TYPE_MONETARY,
      LOCALE_TYPE_NUMERIC,
      LOCALE_TYPE_TIME
  };

    /** A list of Relations, which may be many-to-many. */
  typedef sequence<Relation> RelationSet;

    /** 
     * A list of name-value pairs, returned as a sequence of strings; 
     * the name and value are separated by a colon. 
     * @note "Attributes" returned in AttributeSet lists are distinct from, 
     * and should not be confused with, "attribute" members of interfaces
     * as defined by the IDL "attribute" keyword.  IDL attributes are
     * strongly-typed values which are individually obtained via
     * language-specific bindings whose syntax is dictated by the OMG's
     * IDL language bindings.  For instance using the C language,
     * the "Accessible::name" attribute is queried using
     * \c Accessibility_Accessible__get_name (obj, &ev);
     * Name-value pairs associated with Accessible instances are not
     * normally redundant with these IDL attributes, i.e. there is no
     * "accessible-name" attribute in the AttributeSet returned from
     * Accessible::getAttributes().
     *
     * Where possible, the names and values in the name-value pairs
     * should be chosen from well-established attribute namespaces
     * using standard semantics.  For example, metadata namespace and
     * values should be chosen from the 'Dublin Core' Metadata
     * namespace using Dublin Core semantics:
     * http://dublincore.org/dcregistry/
     * Similarly, relevant structural metadata should be exposed
     * using attribute names and values chosen from the CSS2 and WICD specification:
     * http://www.w3.org/TR/1998/REC-CSS2-19980512
     * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
     * 
     * Finally, note that typographic, semantic, and presentational annotations which
     * are associated with text content, in particular which are associated with particular
     * text ranges, should be exposed via Accessibility::Text::getAttributeRun instead of
     * via these more general 'Object attributes'.
     *
     * @since AT-SPI 1.7.0
     */
  typedef sequence<string> AttributeSet;

    /** 
     * A list of accessible roles 
     * @since AT-SPI 1.7.0
     **/
  typedef sequence<Role> RoleSet;

    /** Used by Component and Text, a struct defining a bounding rectangle. 
     * The relevant coordinate system is determined by the context of the
     * API call which returned or receives the value.
     */
  struct BoundingBox {
          long x; /**< the value corresponding to the minimum or leftmost x position. */
          long y; /**< the value corresponding to the minimum y value.  */
          long width; /**< the horizontal extent of the bounding box,
		       * that is, the difference between the maximum and minimum
		       * x coordinate bounds.
		       */
          long height; /**< the vertical extent of the bounding box, 
			* that is, the difference between the maximum and minimum
			* y coordinate bounds.
			*/
  };

    
  interface Application; /**< defined in Accessibility_Application.idl **/

  /** 
   * The base interface which is implemented by all accessible objects. 
   * All objects support interfaces for querying their contained 'children' 
   * and position in the accessible-object hierarchy, whether or not they
   * actually have children.
   *
   * @note Events that may be emitted by instances of Accessible include:
   * \li \c "object:property-change" A base (strongly-typed) object attribute has changed,
   *         for instance "object:property-change:accessible-name".
   *         Notifed property subtypes include accessible-name, accessible-description,
   *         accessible-parent and accessible-role. 
   *
   * \li \c "object:children-changed" The number or identity of an object's children
   *         has changed.
   * \li \c "object:state-changed" The object's StateSet has had a state added
   *         or removed.
   * \li \c "object:active-descendant-changed" If the object includes 
   *         STATE_MANAGES_DESCENDANTS, this event is fired to indicate that the 
   *         descendant having STATE_ACTIVE has changed; this corresponds to
   *         "micro" keyboard focus when the containing/emitting object has
   *         "macro" or technical keyboard focus.  For instance, this event is
   *         usually emitted while traversing tables and/or spreadsheet cells.
   * \li \c "object:attribute-change" A weakly-typed property, as contained in the
   *         AttributeSet returned by Accessible::getAttributes, has changed in value,
   *         been added, or been removed from the object.
   *         ("object:attribute-change" notifications were added in AT-SPI 1.7.0)
   */
  interface Accessible : Bonobo::Unknown {

    /**
     * a (short) \c string representing the object's name.
     **/
    attribute string name;

    /**
     * a \c string describing the object in more detail than \a name.
     **/
    attribute string description;

    /**
     * an ::Accessible object which is this object's containing object.
     **/
    readonly attribute Accessibility::Accessible parent;

    /**
     * childCount: the number of children contained by this object.
     **/
    readonly attribute long    	childCount;

    /**
     * Determine whether an ::Accessible refers to the same object as another.
     * This method should be used rather than brute-force comparison of
     * object references (i.e. "by-value" comparison), as two object references
     * may have different apparent values yet refer to the same object.
     *
     * @param obj: an ::Accessible object reference to compare to
     * @returns: a \c boolean indicating whether the two object references
     *         point to the same object. 
     **/
    boolean isEqual (in Accessible obj);

    /**
     * Get the accessible child of this object at \c index.
     * @param index: an in parameter indicating which child is requested (zero-indexed).
     * @returns: the 'nth' ::Accessible child of this object.
     **/
    Accessible 	getChildAtIndex (in long index);

    /**
     * Get the index of this object in its parent's child list.
     * @returns: a long integer indicating this object's index in the parent's list.
     **/
    long		getIndexInParent ();

    /**
     * Get a set defining this object's relationship to other accessible objects.
     * @returns: a ::RelationSet defining this object's relationships.
     **/
    RelationSet	getRelationSet ();

    /**
     * Get the ::Role indicating the type of UI role played by this object.
     *
     * @returns: a ::Role indicating the type of UI role played by this object.
     **/
    Role		getRole ();

    /**
     * Get a string indicating the type of UI role played by this object.
     *
     * @returns: a UTF-8 string indicating the type of UI role played by this object.
     **/
    string		getRoleName ();

    /**
     * Get a string indicating the type of UI role played by this object,
     * translated to the current locale.
     *
     * @returns: a UTF-8 string indicating the type of UI role played by this object.
     **/
    string		getLocalizedRoleName ();

    /**
     * Get the current state of the object as a ::StateSet.
     * @returns: a ::StateSet encapsulating the currently true states of the object.
     **/
    StateSet	getState ();

    /**
     * Get a list of properties applied to this object as a whole, as an 
     * ::AttributeSet consisting of name-value pairs.  As such these attributes
     * may be considered weakly-typed properties or annotations, as distinct
     * from the strongly-typed interface instance data declared using the IDL 
     * "attribute" keyword.
     *
     * Not all objects have explicit "name-value pair" AttributeSet properties.  
     *
     * Attribute names and values may have any UTF-8 string value, however where possible,
     * in order to facilitate consistent use and exposure of "attribute" properties by
     * applications and AT clients, attribute names and values should chosen from  
     * a publicly-specified namespace where appropriate.
     *
     * Where possible, the names and values in the name-value pairs
     * should be chosen from well-established attribute namespaces
     * using standard semantics.       
     * For example, attributes of ::Accessible objects corresponding to XHTML content 
     * elements should correspond to attribute names and values specified in the w3c 
     * XHTML specification, at http://www.w3.org/TR/xhtml2, where such values are not 
     * already exposed via a more strongly-typed aspect of the AT-SPI API.
     * Metadata names and
     * values should be chosen from the 'Dublin Core' Metadata
     * namespace using Dublin Core semantics:
     * http://dublincore.org/dcregistry/
     * Similarly, relevant structural metadata should be exposed
     * using attribute names and values chosen from the CSS2 and WICD specification:
     * http://www.w3.org/TR/1998/REC-CSS2-19980512
     * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
     *
     * @note Clients seeking semantic or typographical attributes associated with
     * specific character spans of text content should use ::Text::getAttributeRun instead.
     * The attributes returned by Accessible::getAttributes do not include
     * "text attributes".
     *
     * @see ::Accessibility::Text::getAttributeRun
     *
     * @returns: an ::AttributeSet encapsulating any "attribute values" currently 
     * defined for the object.
     *
     * @since AT-SPI 1.7.0
     **/
    AttributeSet	getAttributes ();

    /**
     * Get the containing Application for this object.
     *
     * @returns the Application instance to which this object belongs.
     * @since AT-SPI 1.7.0
     **/
    Application getApplication ();

     /** /cond future expansion */
     void unimplemented ();
     /** /endcond */

  };
};

#endif