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_Accessible.idl next >
Encoding:
Text File  |  2006-08-22  |  11.0 KB  |  276 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_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.    *         and accessible-parent. 
  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.  
  276.