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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XAccessibleComponent.idl,v $
  10  * $Revision: 1.9 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_accessibility_XAccessibleComponent_idl__
  32 #define __com_sun_star_accessibility_XAccessibleComponent_idl__
  33
  34 #ifndef __com_sun_star_uno_XInterface_idl__
  35 #include <com/sun/star/uno/XInterface.idl>
  36 #endif
  37 #ifndef __com_sun_star_awt_XFocusListener_idl__
  38 #include <com/sun/star/awt/XFocusListener.idl>
  39 #endif
  40 #ifndef __com_sun_star_awt_XFont_idl__
  41 #include <com/sun/star/awt/XFont.idl>
  42 #endif
  43 #ifndef __com_sun_star_awt_FontDescriptor_idl__
  44 #include <com/sun/star/awt/FontDescriptor.idl>
  45 #endif
  46 #ifndef __com_sun_star_awt_Point_idl__
  47 #include <com/sun/star/awt/Point.idl>
  48 #endif
  49 #ifndef __com_sun_star_awt_Rectangle_idl__
  50 #include <com/sun/star/awt/Rectangle.idl>
  51 #endif
  52 #ifndef __com_sun_star_awt_Size_idl__
  53 #include <com/sun/star/awt/Size.idl>
  54 #endif
  55 #ifndef __com_sun_star_util_Color_idl__
  56 #include <com/sun/star/util/Color.idl>
  57 #endif
  58
  59 module com { module sun { module star { module accessibility {
  60
  61  published interface XAccessible;
  62
  63 /** The <type>XAccessibleComponent</type> interface should be supported by
  64     any class that can be rendered on the screen.
  65
  66     <p>This interface provides the standard mechanism for an assistive
  67     technology to retrieve information concerning the graphical
  68     representation of an object.  This interface combines methods from
  69     the Java interfaces <code>javax.accessibility.AccessibleComponent</code>
  70     and <code>javax.accessibility.AccessibleExtendedComponent</code>.</p>
  71
  72     <p>Further information about the graphical appearance of an object can
  73     be expressed with the <type>XAccessibleExtendedComponent</type>
  74     interface.</p>
  75
  76     <p>Coordinates used by the functions of this interface are specified in
  77     different coordinate systems.  Their scale is the same and is equal to
  78     that of the screen coordiante system.  In other words all coordinates
  79     are measured in pixel.  They differ in their respective origin:
  80     <ul><li>The screen coordinate system has its origin in the upper left
  81     corner of the current screen.  Used by the
  82     <method>getLocationOnScreen</method> function.</li>
  83     <li>The origin of the parent coordinate system is the upper left corner
  84     of the parent's bounding box.  With no parent the screen coordinate
  85     system is used instead.  Used by the <method>getLocation</method>
  86     function.</li>
  87     <li>The object coordinate system is relative to the upper left corner of
  88     an object's bounding box.  It is relative to itself so to speak.  Used
  89     by the <method>containsPoint</method> and
  90     <method>getAccessibleAtPoint</method> functions.</li>
  91     </ul></p>
  92
  93     <p>Key bindings which are associated with an accessible component can be
  94     retrieved at the component's action.  The reason for this is that key
  95     bindings are associated with actions and directly with a component.
  96     This distinction becomes important when there are more than one action.
  97     To get access to the key bindings you have to get the
  98     <type>XAccessibleAction</type> interface of a component, provided that
  99     it is supported, and use the <method
 100     scope="XAccessibleAction">getAccessibleKeyBinding()</method>.</p>
 101
 102     @see XAccessibleExtendedComponent
 103
 104     @since OOo 1.1.2
 105 */
 106 published interface XAccessibleComponent : ::com::sun::star::uno::XInterface
 107 {
 108     /** Tests whether the specified point lies within this object's bounds.
 109
 110         <p>The test point's coordinates are defined relative to the
 111         coordinate system of the object.  That means that when the object is
 112         an opaque rectangle then both the points (0,0) and (with-1,height-1)
 113         would yield a <TRUE/> value.</p>
 114
 115         @param point
 116             Coordinates of the point to test.  The origin of the coordinate
 117             system is the upper left corner of the object's bounding box as
 118             returned by the <method>getBounds</method>.  The scale of the
 119             coordinate system is identical to that of the screen coordiante
 120             system.
 121
 122         @return
 123             Returns <TRUE/> if the point lies within or on the object's bounding
 124             box and <FALSE/> otherwise.
 125     */
 126     boolean containsPoint ([in] ::com::sun::star::awt::Point aPoint);
 127
 128     /** Returns the Accessible child that is rendered under the given point.
 129
 130         <p>The test point's coordinates are defined relative to the
 131         coordinate system of the object.  That means that when the object is
 132         an opaque rectangle then both the points (0,0) and (with-1,height-1)
 133         would yield a <TRUE/> value.</p>
 134
 135         @param aPoint
 136             Coordinates of the test point for which to find the Accessible
 137             child.  The origin of the coordinate system is the upper left
 138             corner of the object's bounding box as returned by the
 139             <method>getBounds</method>.  The scale of the coordinate
 140             system is identical to that of the screen coordiante system.
 141
 142         @return
 143             If there is one child which is rendered so that its bounding box
 144             contains the test point then a reference to that object is
 145             returned.  If there is more than one child which satisfies that
 146             condition then a reference to that one is returned that is
 147             painted on top of the others.  If no there is no child which is
 148             rendered at the test point an empty reference is returned.
 149     */
 150     XAccessible  getAccessibleAtPoint ([in] ::com::sun::star::awt::Point aPoint);
 151
 152     /** Returns the bounding box of this object.
 153
 154         <p>The returned bounding box has the form of a rectangle.  Its
 155         coordinates are relative to the object's parent coordinate system.
 156         Note that the two methods <method>getLocation</methodmber> and
 157         <method>getSize</method> return the same information.  With method
 158         <method>getLocationOnScreen</method> you can get the bound box
 159         position in screen coordinates.</p>
 160
 161         @return
 162             The coordinates of the returned rectangle are relative to this
 163             object's parent or relative to the screen on which this object
 164             is rendered if it has no parent.  If the object is not on any
 165             screen the returnred rectangle is empty and located at position
 166             (0,0).
 167     */
 168     ::com::sun::star::awt::Rectangle getBounds ();
 169
 170     /** Returns the location of the upper left corner of the object's
 171         bounding box relative to the parent.</p>
 172
 173         <p>The coordinates of the bounding box are given relative to the
 174         parent's coordinate system.</p>
 175
 176         @return
 177             The coordinates of the returned position are relative to this
 178             object's parent or relative to the screen on which this object
 179             is rendered if it has no parent.  If the object is not on any
 180             screen the returnred position is (0,0).
 181     */
 182     ::com::sun::star::awt::Point getLocation ();
 183
 184     /** Returns the location of the upper left corner of the object's
 185         bounding box in screen coordinates.
 186
 187         <p>This method returns the same point as does the method
 188         <method>getLocation</method>.  The difference is that the
 189         coordinates are absolute screen coordinates of the screen to which
 190         the object is rendered instead of being relative to the object's
 191         parent.</p>
 192
 193         @return
 194             The coordinates of the returned position are relative to the
 195             screen on which this object is rendered.  If the object is not
 196             on any screen the returnred position is (0,0).
 197     */
 198     ::com::sun::star::awt::Point getLocationOnScreen ();
 199
 200     /** Returns the size of this object's bounding box.
 201
 202         @return
 203             The returned size is the size of this object or empty if it is
 204             not rendered on any screen.
 205     */
 206     ::com::sun::star::awt::Size getSize();
 207
 208     /** Grabs the focus to this object.
 209
 210         <p>If this object can not accept the focus,
 211         i.e. <method>isFocusTraversable</method> returns <FALSE/> for this
 212         object then nothing happens.  Otherwise the object will attempt to
 213         take the focus.  Nothing happens if that fails, otherwise the object
 214         has the focus.  This method is called <code>requestFocus</code> in
 215         the Java Accessibility API 1.4.</p>
 216     */
 217     [oneway] void grabFocus ();
 218
 219     /** Returns the foreground color of this object.
 220
 221         @return
 222             The returned color is the foreground color of this object or, if
 223             that is not supported, the default foreground color.
 224     */
 225     ::com::sun::star::util::Color getForeground ();
 226
 227     /** Returns the background color of this object.
 228
 229         @return
 230             The returned color is the background color of this object or, if
 231             that is not supported, the default background color.
 232     */
 233     ::com::sun::star::util::Color getBackground ();
 234
 235 };
 236
 237 }; }; }; };
 238
 239 #endif