offapi/com/sun/star/accessibility/XAccessibleContext.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XAccessibleContext.idl,v $
  10  * $Revision: 1.8 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_accessibility_XAccessibleContext_idl__
  32 #define __com_sun_star_accessibility_XAccessibleContext_idl__
  33
  34 #ifndef __com_sun_star_accessibility_IllegalAccessibleComponentStateException_idl__
  35 #include <com/sun/star/accessibility/IllegalAccessibleComponentStateException.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
  39 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_beans_XPropertyChangeListener_idl__
  43 #include <com/sun/star/beans/XPropertyChangeListener.idl>
  44 #endif
  45
  46 #ifndef __com_sun_star_lang_Locale_idl__
  47 #include <com/sun/star/lang/Locale.idl>
  48 #endif
  49
  50 module com { module sun { module star { module accessibility {
  51
  52  published interface XAccessible;
  53  published interface XAccessibleRelationSet;
  54  published interface XAccessibleSelection;
  55  published interface XAccessibleStateSet;
  56
  57 /** Implement this interface for exposing various aspects of a class'
  58     content.
  59
  60     <p>This interface serves two purposes: On the one hand it gives access
  61     to the tree structure in which all accessible objects are
  62     organized. Each node in this tree supports this interface.  On the other
  63     hand it gives access to objects that expose the represented content.
  64     That are role, state, name, description, and relations to other objects.
  65     Take an OK button of a dialog as an example.  Its role is
  66     <const>AccessibleRole::BUTTON</const>, its name is 'OK', and its description
  67     is something like 'Accepts all changes made in the dialog'.</p>
  68
  69     @since OOo 1.1.2
  70 */
  71 published interface XAccessibleContext : ::com::sun::star::uno::XInterface
  72 {
  73     /** Return the number of children.
  74
  75         <p>Returns the number of accessible children of the object.</p>
  76
  77         @return
  78             The returned value is non-negative.
  79     */
  80     long getAccessibleChildCount();
  81
  82     /** Returns the i-th child of this object.
  83
  84         <p>The order in which the children are enumerated is implementation
  85         dependend.</p>
  86
  87         @param i
  88             The index may have any value.  If it is outside the range from 0
  89             to n-1, with n being the number of children as returned by
  90             <member>XAccessibleContext::getAccessibleChild</member> an empty
  91             reference is returned.
  92         @return
  93             If the object has an i-th child the returned value is a
  94             reference to that child.  Otherwise an empty reference is
  95             returned.
  96         @throws ::com::sun::star::lang::IndexOutOfBoundsException
  97             If no child with the given index exists then an
  98             <type scope="::com::sun::star::lang">IndexOutOfBoundsException</type>
  99             exception is thrown.
 100     */
 101     XAccessible getAccessibleChild ([in] long i)
 102         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 103
 104     /** Returns the parent of this object.
 105
 106         <p>This function may be called for every node, including the root
 107         node, of the accessible tree.</p>
 108
 109         @return
 110             The returned reference points to a valid object for all but the
 111             root node.  If called for the root node an empty reference is
 112             returned.
 113     */
 114     XAccessible getAccessibleParent ();
 115
 116     /** Returns the index of this object in its accessible parent.
 117
 118         <p>If you call getAccessibeChild on the object's parent with the
 119         index returned by this function you get a reference to this
 120         object.</p>
 121
 122         @return
 123            The returned index is zero based.
 124     */
 125     long getAccessibleIndexInParent ();
 126
 127     /** Returns the role of this object.
 128
 129         <p>The role is a generic description of an objects function.  The
 130         relation between role and name is similar to the relation between
 131         class and object.</p>
 132
 133         @return
 134             The returned value is a role defined in the enumeration
 135             AccessibleRole.
 136
 137         @see AccessibleRole
 138             for a list of the available roles.
 139     */
 140     short getAccessibleRole ();
 141
 142     /** Returns the object's description.
 143
 144         <p>Returns the object's localized description.  The description should
 145         complement the more generic descriptions given by an object's role
 146         and name.</p>
 147
 148         @return
 149             The returned string is the object's localized description.
 150     */
 151     string getAccessibleDescription ();
 152
 153     /** Return the object's localized name.
 154
 155         <p>See <member>XAccessibleContext::getAccessibleRole</member>'s
 156         documentation for the relation between an object's name and role.
 157         Names should be unique, at least between children of the same
 158         parent, although the uniqueness is neither enforced nor used inside
 159         the API.</p>
 160
 161         @return
 162             The returned string is the object's localized name.
 163     */
 164     string  getAccessibleName ();
 165
 166     /** Returns the set of relations defined for this object.
 167
 168         <p>The returned set of relations is a copy of this objects relation
 169         set: changing the returned object does not change this objects
 170         relations.</p>
 171
 172         <p>aThere are two ways to represent an empty list of relations:
 173         Return an empty reference or return a valid object that contains an
 174         empty list.
 175
 176         @return
 177            The returned value is either an empty referece or a reference to
 178            a valid object that represents a copy of the objects list of
 179            relations.
 180     */
 181     XAccessibleRelationSet getAccessibleRelationSet ();
 182
 183     /** Returns the set of states that are currently active for this
 184         object.
 185
 186         <p>The returned state set is a copy: Changing the returned state set
 187         will not be refelected by changing the object's set of states.  See
 188         the documentation of <type>XAccessibleStateSet</type> for a
 189         description of the individual states.</p>
 190
 191         @return
 192             A reference to this object's state set or an empty reference if
 193             states are not supported.
 194
 195         @see XAccessibleStateSet
 196     */
 197     XAccessibleStateSet getAccessibleStateSet ();
 198
 199     /** Returns the locale of the component.
 200
 201         <p>This locale is used for example to determine the language to use
 202         for the name and description texts.</p>
 203
 204         @return
 205             If this object does not have a locale, the locale of its parent
 206             is returned.  If it does not have (yet) a parent it throws the
 207             exception <type>IllegalAccessibleComponentStateException</type>.
 208
 209         @throws IllegalAccessibleComponentStateException
 210             when this object does not (yet) have a parent.
 211     */
 212     ::com::sun::star::lang::Locale getLocale ()
 213         raises (IllegalAccessibleComponentStateException);
 214 };
 215
 216 }; }; }; };
 217
 218 #endif