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
56module 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*/
103published 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
237