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