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