offapi/com/sun/star/accessibility/XAccessibleComponent.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
  24 /** The XAccessibleComponent interface should be supported by
  25     any class that can be rendered on the screen.
  26
  27     <p>This interface provides the standard mechanism for an assistive
  28     technology to retrieve information concerning the graphical
  29     representation of an object.  This interface combines methods from
  30     the Java interfaces <code>javax.accessibility.AccessibleComponent</code>
  31     and <code>javax.accessibility.AccessibleExtendedComponent</code>.</p>
  32
  33     <p>Further information about the graphical appearance of an object can
  34     be expressed with the XAccessibleExtendedComponent
  35     interface.</p>
  36
  37     <p>Coordinates used by the functions of this interface are specified in
  38     different coordinate systems.  Their scale is the same and is equal to
  39     that of the screen coordinate system.  In other words all coordinates
  40     are measured in pixel.  They differ in their respective origin:
  41     <ul><li>The screen coordinate system has its origin in the upper left
  42     corner of the current screen.  Used by the
  43     getLocationOnScreen() function.</li>
  44     <li>The origin of the parent coordinate system is the upper left corner
  45     of the parent's bounding box.  With no parent the screen coordinate
  46     system is used instead.  Used by the getLocation()
  47     function.</li>
  48     <li>The object coordinate system is relative to the upper left corner of
  49     an object's bounding box.  It is relative to itself so to speak.  Used
  50     by the containsPoint() and
  51     getAccessibleAtPoint() functions.</li>
  52     </ul></p>
  53
  54     <p>Key bindings which are associated with an accessible component can be
  55     retrieved at the component's action.  The reason for this is that key
  56     bindings are associated with actions and directly with a component.
  57     This distinction becomes important when there are more than one action.
  58     To get access to the key bindings you have to get the
  59     XAccessibleAction interface of a component, provided that
  60     it is supported, and use the XAccessibleAction::getAccessibleKeyBinding().
  61     </p>
  62
  63     @see XAccessibleExtendedComponent
  64
  65     @since OOo 1.1.2
  66 */
  67 interface XAccessibleComponent : ::com::sun::star::uno::XInterface
  68 {
  69     /** Tests whether the specified point lies within this object's bounds.
  70
  71         <p>The test point's coordinates are defined relative to the
  72         coordinate system of the object.  That means that when the object is
  73         an opaque rectangle then both the points (0,0) and (width-1,height-1)
  74         would yield a `TRUE` value.</p>
  75
  76         @param Point
  77             Coordinates of the point to test.  The origin of the coordinate
  78             system is the upper left corner of the object's bounding box as
  79             returned by the getBounds().  The scale of the
  80             coordinate system is identical to that of the screen coordinate
  81             system.
  82
  83         @return
  84             Returns `TRUE` if the point lies within or on the object's bounding
  85             box and `FALSE` otherwise.
  86     */
  87     boolean containsPoint ([in] ::com::sun::star::awt::Point Point);
  88
  89     /** Returns the Accessible child that is rendered under the given point.
  90
  91         <p>The test point's coordinates are defined relative to the
  92         coordinate system of the object.  That means that when the object is
  93         an opaque rectangle then both the points (0,0) and (width-1,height-1)
  94         are points inside of the object.
  95
  96         @param Point
  97             Coordinates of the test point for which to find the Accessible
  98             child.  The origin of the coordinate system is the upper left
  99             corner of the object's bounding box as returned by the
 100             getBounds().  The scale of the coordinate
 101             system is identical to that of the screen coordinate system.
 102
 103         @return
 104             If there is one child which is rendered so that its bounding box
 105             contains the test point then a reference to that object is
 106             returned.  If there is more than one child which satisfies that
 107             condition then a reference to that one is returned that is
 108             painted on top of the others.  If there is no child which is
 109             rendered at the test point an empty reference is returned.
 110     */
 111     XAccessible  getAccessibleAtPoint ([in] ::com::sun::star::awt::Point Point);
 112
 113     /** Returns the bounding box of this object.
 114
 115         <p>The returned bounding box has the form of a rectangle.  Its
 116         coordinates are relative to the object's parent coordinate system.
 117         Note that the two methods getLocation() and
 118         getSize() return the same information.  With method
 119         getLocationOnScreen() you can get the bound box
 120         position in screen coordinates.</p>
 121
 122         @return
 123             The coordinates of the returned rectangle are relative to this
 124             object's parent or relative to the screen on which this object
 125             is rendered if it has no parent.  If the object is not on any
 126             screen the returned rectangle is empty and located at position
 127             (0,0).
 128     */
 129     ::com::sun::star::awt::Rectangle getBounds ();
 130
 131     /** Returns the location of the upper left corner of the object's
 132         bounding box relative to the parent.</p>
 133
 134         <p>The coordinates of the bounding box are given relative to the
 135         parent's coordinate system.</p>
 136
 137         @return
 138             The coordinates of the returned position are relative to this
 139             object's parent or relative to the screen on which this object
 140             is rendered if it has no parent.  If the object is not on any
 141             screen the returned position is (0,0).
 142     */
 143     ::com::sun::star::awt::Point getLocation ();
 144
 145     /** Returns the location of the upper left corner of the object's
 146         bounding box in screen coordinates.
 147
 148         <p>This method returns the same point as does the method
 149         getLocation().  The difference is that the
 150         coordinates are absolute screen coordinates of the screen to which
 151         the object is rendered instead of being relative to the object's
 152         parent.</p>
 153
 154         @return
 155             The coordinates of the returned position are relative to the
 156             screen on which this object is rendered.  If the object is not
 157             on any screen the returned position is (0,0).
 158     */
 159     ::com::sun::star::awt::Point getLocationOnScreen ();
 160
 161     /** Returns the size of this object's bounding box.
 162
 163         @return
 164             The returned size is the size of this object or empty if it is
 165             not rendered on any screen.
 166     */
 167     ::com::sun::star::awt::Size getSize();
 168
 169     /** Grabs the focus to this object.
 170
 171         <p>If this object can not accept the focus,
 172         i.e. isFocusTraversable() returns `FALSE` for this
 173         object then nothing happens.  Otherwise the object will attempt to
 174         take the focus.  Nothing happens if that fails, otherwise the object
 175         has the focus.  This method is called <code>requestFocus</code> in
 176         the Java Accessibility API 1.4.</p>
 177     */
 178     void grabFocus ();
 179
 180     /** Returns the foreground color of this object.
 181
 182         @return
 183             The returned color is the foreground color of this object or, if
 184             that is not supported, the default foreground color.
 185     */
 186     ::com::sun::star::util::Color getForeground ();
 187
 188     /** Returns the background color of this object.
 189
 190         @return
 191             The returned color is the background color of this object or, if
 192             that is not supported, the default background color.
 193     */
 194     ::com::sun::star::util::Color getBackground ();
 195
 196 };
 197
 198 }; }; }; };
 199
 200 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */