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

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