#ifndef _ACCESSIBILITY_ACCESSIBLE_IDL
#define _ACCESSIBILITY_ACCESSIBLE_IDL
-#include <Bonobo_Unknown.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;
- long y;
- long width;
- long height;
+ 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 {
/**
- * @name: a (short) #string representing the object's name.
+ * a (short) \c string representing the object's name.
**/
attribute string name;
/**
- * @description: a #string describing the object in more detail than @name.
+ * a \c string describing the object in more detail than \a name.
**/
attribute string description;
/**
- * @parent: an #Accessible object which is this object's containing object.
+ * an ::Accessible object which is this object's containing object.
**/
- readonly attribute Accessible parent;
+ readonly attribute Accessibility::Accessible parent;
/**
- * @childCount: the number of children contained by this object.
+ * childCount: the number of children contained by this object.
**/
readonly attribute long childCount;
/**
- * isEqual:
- * @obj: an #Accessible object reference to compare to
+ * 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.
*
- * Determine whether an #Accessible refers to the same object as another
- *
- * Returns: a #boolean indicating whether the two object references
+ * @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);
/**
- * getChildAtIndex:
- * @index: an in parameter indicating which child is requested (zero-indexed).
- *
- * Get the accessible child of this object at index @index.
- *
- * Returns: the 'nth' @Accessible child of this object.
+ * 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);
/**
- * getIndexInParent:
- *
* 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.
+ * @returns: a long integer indicating this object's index in the parent's list.
**/
long getIndexInParent ();
/**
- * getRelationSet:
- *
* Get a set defining this object's relationship to other accessible objects.
- *
- * Returns: a @RelationSet defining this object's relationships.
+ * @returns: a ::RelationSet defining this object's relationships.
**/
RelationSet getRelationSet ();
/**
- * getRole:
- * Get the @Role indicating the type of UI role played by this object.
+ * 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.
+ * @returns: a ::Role indicating the type of UI role played by this object.
**/
Role getRole ();
/**
- * getRoleName:
* 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.
+ * @returns: a UTF-8 string indicating the type of UI role played by this object.
**/
string getRoleName ();
/**
- * getState:
+ * Get a string indicating the type of UI role played by this object,
+ * translated to the current locale.
*
- * Get the current state of the object as a @StateSet.
- * Returns: a @StateSet encapsulating the currently true states of the object.
+ * @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 */
+
};
};
projects / platform / core / uifw / at-spi2-atk.git / blobdiff