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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 module com { module sun { module star { module accessibility {
  21
  22  interface XAccessible;
  23  interface XAccessibleRelationSet;
  24  interface XAccessibleSelection;
  25
  26 /** Implement this interface for exposing various aspects of a class's
  27     content.
  28
  29     <p>This interface serves two purposes: On the one hand it gives access
  30     to the tree structure in which all accessible objects are
  31     organized. Each node in this tree supports this interface.  On the other
  32     hand it gives access to objects that expose the represented content.
  33     That are role, state, name, description, and relations to other objects.
  34     Take an OK button of a dialog as an example.  Its role is
  35     AccessibleRole::BUTTON, its name is "OK", and its description
  36     is something like "Accepts all changes made in the dialog".</p>
  37
  38     @since OOo 1.1.2
  39 */
  40 interface XAccessibleContext : ::com::sun::star::uno::XInterface
  41 {
  42     /** Return the number of children.
  43
  44         <p>Returns the number of accessible children of the object.</p>
  45
  46         @return
  47             The returned value is non-negative.
  48     */
  49     hyper getAccessibleChildCount();
  50
  51     /** Returns the i-th child of this object.
  52
  53         <p>The order in which the children are enumerated is implementation
  54         dependent.</p>
  55
  56         @param i
  57             The index may have any value.  If it is outside the range from 0
  58             to n-1, with n being the number of children as returned by
  59             XAccessibleContext::getAccessibleChild() an empty
  60             reference is returned.
  61         @return
  62             If the object has an i-th child the returned value is a
  63             reference to that child.  Otherwise an empty reference is
  64             returned.
  65         @throws ::com::sun::star::lang::IndexOutOfBoundsException
  66             If no child with the given index exists then an
  67             ::com::sun::star::lang::IndexOutOfBoundsException
  68             exception is thrown.
  69     */
  70     XAccessible getAccessibleChild ([in] hyper i)
  71         raises (::com::sun::star::lang::IndexOutOfBoundsException);
  72
  73     /** Returns the parent of this object.
  74
  75         <p>This function may be called for every node, including the root
  76         node, of the accessible tree.</p>
  77
  78         @return
  79             The returned reference points to a valid object for all but the
  80             root node.  If called for the root node an empty reference is
  81             returned.
  82     */
  83     XAccessible getAccessibleParent ();
  84
  85     /** Returns the index of this object in its accessible parent.
  86
  87         <p>If you call getAccessibleChild on the object's parent with the
  88         index returned by this function you get a reference to this
  89         object.</p>
  90
  91         @return
  92            The returned index is zero based.
  93     */
  94     hyper getAccessibleIndexInParent ();
  95
  96     /** Returns the role of this object.
  97
  98         <p>The role is a generic description of an objects function.  The
  99         relation between role and name is similar to the relation between
 100         class and object.</p>
 101
 102         @return
 103             The returned value is a role defined in the enumeration
 104             AccessibleRole.
 105
 106         @see AccessibleRole
 107             for a list of the available roles.
 108     */
 109     short getAccessibleRole ();
 110
 111     /** Returns the object's description.
 112
 113         <p>Returns the object's localized description.  The description should
 114         complement the more generic descriptions given by an object's role
 115         and name.</p>
 116
 117         @return
 118             The returned string is the object's localized description.
 119     */
 120     string getAccessibleDescription ();
 121
 122     /** Return the object's localized name.
 123
 124         <p>See XAccessibleContext::getAccessibleRole()'s
 125         documentation for the relation between an object's name and role.
 126         Names should be unique, at least between children of the same
 127         parent, although the uniqueness is neither enforced nor used inside
 128         the API.</p>
 129
 130         @return
 131             The returned string is the object's localized name.
 132     */
 133     string  getAccessibleName ();
 134
 135     /** Returns the set of relations defined for this object.
 136
 137         <p>The returned set of relations is a copy of this object's relation
 138         set: changing the returned object does not change this object's
 139         relations.</p>
 140
 141         <p>There are two ways to represent an empty list of relations:
 142         Return an empty reference or return a valid object that contains an
 143         empty list.
 144
 145         @return
 146            The returned value is either an empty reference or a reference to
 147            a valid object that represents a copy of the objects list of
 148            relations.
 149     */
 150     XAccessibleRelationSet getAccessibleRelationSet ();
 151
 152     /** Returns the set of states that are currently active for this
 153         object.
 154
 155         <p>See the documentation of AccessibleStateType for a
 156         description of the individual states.</p>
 157
 158         @see AccessibleStateType
 159     */
 160     hyper getAccessibleStateSet ();
 161
 162     /** Returns the locale of the component.
 163
 164         <p>This locale is used for example to determine the language to use
 165         for the name and description texts.</p>
 166
 167         @return
 168             If this object does not have a locale, the locale of its parent
 169             is returned.  If it does not have (yet) a parent it throws the
 170             exception IllegalAccessibleComponentStateException.
 171
 172         @throws IllegalAccessibleComponentStateException
 173             when this object does not (yet) have a parent.
 174     */
 175     ::com::sun::star::lang::Locale getLocale ()
 176         raises (IllegalAccessibleComponentStateException);
 177 };
 178
 179 }; }; }; };
 180
 181 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */