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

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