idl/Accessibility_Accessible.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_ACCESSIBLE_IDL
  24 #define _ACCESSIBILITY_ACCESSIBLE_IDL
  25
  26 #include "Accessibility_Relation.idl"
  27 #include "Accessibility_State.idl"
  28 #include "Accessibility_Role.idl"
  29
  30 module Accessibility {
  31
  32   /** used by Text and Document: these correspond to the POSIX setlocale() enum values. **/
  33   enum LOCALE_TYPE {
  34       LOCALE_TYPE_MESSAGES,
  35       LOCALE_TYPE_COLLATE,
  36       LOCALE_TYPE_CTYPE,
  37       LOCALE_TYPE_MONETARY,
  38       LOCALE_TYPE_NUMERIC,
  39       LOCALE_TYPE_TIME
  40   };
  41
  42     /** A list of Relations, which may be many-to-many. */
  43   typedef sequence<Relation> RelationSet;
  44
  45     /**
  46      * A list of name-value pairs, returned as a sequence of strings;
  47      * the name and value are separated by a colon.
  48      * @note "Attributes" returned in AttributeSet lists are distinct from,
  49      * and should not be confused with, "attribute" members of interfaces
  50      * as defined by the IDL "attribute" keyword.  IDL attributes are
  51      * strongly-typed values which are individually obtained via
  52      * language-specific bindings whose syntax is dictated by the OMG's
  53      * IDL language bindings.  For instance using the C language,
  54      * the "Accessible::name" attribute is queried using
  55      * \c Accessibility_Accessible__get_name (obj, &ev);
  56      * Name-value pairs associated with Accessible instances are not
  57      * normally redundant with these IDL attributes, i.e. there is no
  58      * "accessible-name" attribute in the AttributeSet returned from
  59      * Accessible::getAttributes().
  60      *
  61      * Where possible, the names and values in the name-value pairs
  62      * should be chosen from well-established attribute namespaces
  63      * using standard semantics.  For example, metadata namespace and
  64      * values should be chosen from the 'Dublin Core' Metadata
  65      * namespace using Dublin Core semantics:
  66      * http://dublincore.org/dcregistry/
  67      * Similarly, relevant structural metadata should be exposed
  68      * using attribute names and values chosen from the CSS2 and WICD specification:
  69      * http://www.w3.org/TR/1998/REC-CSS2-19980512
  70      * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
  71      *
  72      * Finally, note that typographic, semantic, and presentational annotations which
  73      * are associated with text content, in particular which are associated with particular
  74      * text ranges, should be exposed via Accessibility::Text::getAttributeRun instead of
  75      * via these more general 'Object attributes'.
  76      *
  77      * @since AT-SPI 1.7.0
  78      */
  79   typedef sequence<string> AttributeSet;
  80
  81     /**
  82      * A list of accessible roles
  83      * @since AT-SPI 1.7.0
  84      **/
  85   typedef sequence<Role> RoleSet;
  86
  87     /** Used by Component and Text, a struct defining a bounding rectangle.
  88      * The relevant coordinate system is determined by the context of the
  89      * API call which returned or receives the value.
  90      */
  91   struct BoundingBox {
  92           long x; /**< the value corresponding to the minimum or leftmost x position. */
  93           long y; /**< the value corresponding to the minimum y value.  */
  94           long width; /**< the horizontal extent of the bounding box,
  95                        * that is, the difference between the maximum and minimum
  96                        * x coordinate bounds.
  97                        */
  98           long height; /**< the vertical extent of the bounding box,
  99                         * that is, the difference between the maximum and minimum
 100                         * y coordinate bounds.
 101                         */
 102   };
 103
 104
 105   interface Application; /**< defined in Accessibility_Application.idl **/
 106
 107   /**
 108    * The base interface which is implemented by all accessible objects.
 109    * All objects support interfaces for querying their contained 'children'
 110    * and position in the accessible-object hierarchy, whether or not they
 111    * actually have children.
 112    *
 113    * @note Events that may be emitted by instances of Accessible include:
 114    * \li \c "object:property-change" A base (strongly-typed) object attribute has changed,
 115    *         for instance "object:property-change:accessible-name".
 116    *         Notifed property subtypes include accessible-name, accessible-description,
 117    *         accessible-parent and accessible-role.
 118    *
 119    * \li \c "object:children-changed" The number or identity of an object's children
 120    *         has changed.
 121    * \li \c "object:state-changed" The object's StateSet has had a state added
 122    *         or removed.
 123    * \li \c "object:active-descendant-changed" If the object includes
 124    *         STATE_MANAGES_DESCENDANTS, this event is fired to indicate that the
 125    *         descendant having STATE_ACTIVE has changed; this corresponds to
 126    *         "micro" keyboard focus when the containing/emitting object has
 127    *         "macro" or technical keyboard focus.  For instance, this event is
 128    *         usually emitted while traversing tables and/or spreadsheet cells.
 129    * \li \c "object:attribute-change" A weakly-typed property, as contained in the
 130    *         AttributeSet returned by Accessible::getAttributes, has changed in value,
 131    *         been added, or been removed from the object.
 132    *         ("object:attribute-change" notifications were added in AT-SPI 1.7.0)
 133    */
 134   interface Accessible : Bonobo::Unknown {
 135
 136     /**
 137      * a (short) \c string representing the object's name.
 138      **/
 139     attribute string name;
 140
 141     /**
 142      * a \c string describing the object in more detail than \a name.
 143      **/
 144     attribute string description;
 145
 146     /**
 147      * an ::Accessible object which is this object's containing object.
 148      **/
 149     readonly attribute Accessibility::Accessible parent;
 150
 151     /**
 152      * childCount: the number of children contained by this object.
 153      **/
 154     readonly attribute long     childCount;
 155
 156     /**
 157      * Determine whether an ::Accessible refers to the same object as another.
 158      * This method should be used rather than brute-force comparison of
 159      * object references (i.e. "by-value" comparison), as two object references
 160      * may have different apparent values yet refer to the same object.
 161      *
 162      * @param obj: an ::Accessible object reference to compare to
 163      * @returns: a \c boolean indicating whether the two object references
 164      *         point to the same object.
 165      **/
 166     boolean isEqual (in Accessible obj);
 167
 168     /**
 169      * Get the accessible child of this object at \c index.
 170      * @param index: an in parameter indicating which child is requested (zero-indexed).
 171      * @returns: the 'nth' ::Accessible child of this object.
 172      **/
 173     Accessible  getChildAtIndex (in long index);
 174
 175     /**
 176      * Get the index of this object in its parent's child list.
 177      * @returns: a long integer indicating this object's index in the parent's list.
 178      **/
 179     long                getIndexInParent ();
 180
 181     /**
 182      * Get a set defining this object's relationship to other accessible objects.
 183      * @returns: a ::RelationSet defining this object's relationships.
 184      **/
 185     RelationSet getRelationSet ();
 186
 187     /**
 188      * Get the ::Role indicating the type of UI role played by this object.
 189      *
 190      * @returns: a ::Role indicating the type of UI role played by this object.
 191      **/
 192     Role                getRole ();
 193
 194     /**
 195      * Get a string indicating the type of UI role played by this object.
 196      *
 197      * @returns: a UTF-8 string indicating the type of UI role played by this object.
 198      **/
 199     string              getRoleName ();
 200
 201     /**
 202      * Get a string indicating the type of UI role played by this object,
 203      * translated to the current locale.
 204      *
 205      * @returns: a UTF-8 string indicating the type of UI role played by this object.
 206      **/
 207     string              getLocalizedRoleName ();
 208
 209     /**
 210      * Get the current state of the object as a ::StateSet.
 211      * @returns: a ::StateSet encapsulating the currently true states of the object.
 212      **/
 213     StateSet    getState ();
 214
 215     /**
 216      * Get a list of properties applied to this object as a whole, as an
 217      * ::AttributeSet consisting of name-value pairs.  As such these attributes
 218      * may be considered weakly-typed properties or annotations, as distinct
 219      * from the strongly-typed interface instance data declared using the IDL
 220      * "attribute" keyword.
 221      *
 222      * Not all objects have explicit "name-value pair" AttributeSet properties.
 223      *
 224      * Attribute names and values may have any UTF-8 string value, however where possible,
 225      * in order to facilitate consistent use and exposure of "attribute" properties by
 226      * applications and AT clients, attribute names and values should chosen from
 227      * a publicly-specified namespace where appropriate.
 228      *
 229      * Where possible, the names and values in the name-value pairs
 230      * should be chosen from well-established attribute namespaces
 231      * using standard semantics.
 232      * For example, attributes of ::Accessible objects corresponding to XHTML content
 233      * elements should correspond to attribute names and values specified in the w3c
 234      * XHTML specification, at http://www.w3.org/TR/xhtml2, where such values are not
 235      * already exposed via a more strongly-typed aspect of the AT-SPI API.
 236      * Metadata names and
 237      * values should be chosen from the 'Dublin Core' Metadata
 238      * namespace using Dublin Core semantics:
 239      * http://dublincore.org/dcregistry/
 240      * Similarly, relevant structural metadata should be exposed
 241      * using attribute names and values chosen from the CSS2 and WICD specification:
 242      * http://www.w3.org/TR/1998/REC-CSS2-19980512
 243      * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
 244      *
 245      * @note Clients seeking semantic or typographical attributes associated with
 246      * specific character spans of text content should use ::Text::getAttributeRun instead.
 247      * The attributes returned by Accessible::getAttributes do not include
 248      * "text attributes".
 249      *
 250      * @see ::Accessibility::Text::getAttributeRun
 251      *
 252      * @returns: an ::AttributeSet encapsulating any "attribute values" currently
 253      * defined for the object.
 254      *
 255      * @since AT-SPI 1.7.0
 256      **/
 257     AttributeSet        getAttributes ();
 258
 259     /**
 260      * Get the containing Application for this object.
 261      *
 262      * @returns the Application instance to which this object belongs.
 263      * @since AT-SPI 1.7.0
 264      **/
 265     Application getApplication ();
 266
 267      /** /cond future expansion */
 268      void unimplemented ();
 269      /** /endcond */
 270
 271   };
 272 };
 273
 274 #endif
 275