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

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