1 /*
2 * Copyright (c) 1997, 2003, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.accessibility;
27
28 import java.awt;
29 import java.awt.event;
30
31 /**
32 * The AccessibleComponent interface should be supported by any object
33 * that is rendered on the screen. This interface provides the standard
34 * mechanism for an assistive technology to determine and set the
35 * graphical representation of an object. Applications can determine
36 * if an object supports the AccessibleComponent interface by first
37 * obtaining its AccessibleContext
38 * and then calling the
39 * {@link AccessibleContext#getAccessibleComponent} method.
40 * If the return value is not null, the object supports this interface.
41 *
42 * @see Accessible
43 * @see Accessible#getAccessibleContext
44 * @see AccessibleContext
45 * @see AccessibleContext#getAccessibleComponent
46 *
47 * @author Peter Korn
48 * @author Hans Muller
49 * @author Willie Walker
50 */
51 public interface AccessibleComponent {
52
53 /**
54 * Gets the background color of this object.
55 *
56 * @return the background color, if supported, of the object;
57 * otherwise, null
58 * @see #setBackground
59 */
60 public Color getBackground();
61
62 /**
63 * Sets the background color of this object.
64 *
65 * @param c the new Color for the background
66 * @see #setBackground
67 */
68 public void setBackground(Color c);
69
70 /**
71 * Gets the foreground color of this object.
72 *
73 * @return the foreground color, if supported, of the object;
74 * otherwise, null
75 * @see #setForeground
76 */
77 public Color getForeground();
78
79 /**
80 * Sets the foreground color of this object.
81 *
82 * @param c the new Color for the foreground
83 * @see #getForeground
84 */
85 public void setForeground(Color c);
86
87 /**
88 * Gets the Cursor of this object.
89 *
90 * @return the Cursor, if supported, of the object; otherwise, null
91 * @see #setCursor
92 */
93 public Cursor getCursor();
94
95 /**
96 * Sets the Cursor of this object.
97 *
98 * @param cursor the new Cursor for the object
99 * @see #getCursor
100 */
101 public void setCursor(Cursor cursor);
102
103 /**
104 * Gets the Font of this object.
105 *
106 * @return the Font,if supported, for the object; otherwise, null
107 * @see #setFont
108 */
109 public Font getFont();
110
111 /**
112 * Sets the Font of this object.
113 *
114 * @param f the new Font for the object
115 * @see #getFont
116 */
117 public void setFont(Font f);
118
119 /**
120 * Gets the FontMetrics of this object.
121 *
122 * @param f the Font
123 * @return the FontMetrics, if supported, the object; otherwise, null
124 * @see #getFont
125 */
126 public FontMetrics getFontMetrics(Font f);
127
128 /**
129 * Determines if the object is enabled. Objects that are enabled
130 * will also have the AccessibleState.ENABLED state set in their
131 * AccessibleStateSets.
132 *
133 * @return true if object is enabled; otherwise, false
134 * @see #setEnabled
135 * @see AccessibleContext#getAccessibleStateSet
136 * @see AccessibleState#ENABLED
137 * @see AccessibleStateSet
138 */
139 public boolean isEnabled();
140
141 /**
142 * Sets the enabled state of the object.
143 *
144 * @param b if true, enables this object; otherwise, disables it
145 * @see #isEnabled
146 */
147 public void setEnabled(boolean b);
148
149 /**
150 * Determines if the object is visible. Note: this means that the
151 * object intends to be visible; however, it may not be
152 * showing on the screen because one of the objects that this object
153 * is contained by is currently not visible. To determine if an object is
154 * showing on the screen, use isShowing().
155 * <p>Objects that are visible will also have the
156 * AccessibleState.VISIBLE state set in their AccessibleStateSets.
157 *
158 * @return true if object is visible; otherwise, false
159 * @see #setVisible
160 * @see AccessibleContext#getAccessibleStateSet
161 * @see AccessibleState#VISIBLE
162 * @see AccessibleStateSet
163 */
164 public boolean isVisible();
165
166 /**
167 * Sets the visible state of the object.
168 *
169 * @param b if true, shows this object; otherwise, hides it
170 * @see #isVisible
171 */
172 public void setVisible(boolean b);
173
174 /**
175 * Determines if the object is showing. This is determined by checking
176 * the visibility of the object and its ancestors.
177 * Note: this
178 * will return true even if the object is obscured by another (for example,
179 * it is underneath a menu that was pulled down).
180 *
181 * @return true if object is showing; otherwise, false
182 */
183 public boolean isShowing();
184
185 /**
186 * Checks whether the specified point is within this object's bounds,
187 * where the point's x and y coordinates are defined to be relative to the
188 * coordinate system of the object.
189 *
190 * @param p the Point relative to the coordinate system of the object
191 * @return true if object contains Point; otherwise false
192 * @see #getBounds
193 */
194 public boolean contains(Point p);
195
196 /**
197 * Returns the location of the object on the screen.
198 *
199 * @return the location of the object on screen; null if this object
200 * is not on the screen
201 * @see #getBounds
202 * @see #getLocation
203 */
204 public Point getLocationOnScreen();
205
206 /**
207 * Gets the location of the object relative to the parent in the form
208 * of a point specifying the object's top-left corner in the screen's
209 * coordinate space.
210 *
211 * @return An instance of Point representing the top-left corner of the
212 * object's bounds in the coordinate space of the screen; null if
213 * this object or its parent are not on the screen
214 * @see #getBounds
215 * @see #getLocationOnScreen
216 */
217 public Point getLocation();
218
219 /**
220 * Sets the location of the object relative to the parent.
221 * @param p the new position for the top-left corner
222 * @see #getLocation
223 */
224 public void setLocation(Point p);
225
226 /**
227 * Gets the bounds of this object in the form of a Rectangle object.
228 * The bounds specify this object's width, height, and location
229 * relative to its parent.
230 *
231 * @return A rectangle indicating this component's bounds; null if
232 * this object is not on the screen.
233 * @see #contains
234 */
235 public Rectangle getBounds();
236
237 /**
238 * Sets the bounds of this object in the form of a Rectangle object.
239 * The bounds specify this object's width, height, and location
240 * relative to its parent.
241 *
242 * @param r rectangle indicating this component's bounds
243 * @see #getBounds
244 */
245 public void setBounds(Rectangle r);
246
247 /**
248 * Returns the size of this object in the form of a Dimension object.
249 * The height field of the Dimension object contains this object's
250 * height, and the width field of the Dimension object contains this
251 * object's width.
252 *
253 * @return A Dimension object that indicates the size of this component;
254 * null if this object is not on the screen
255 * @see #setSize
256 */
257 public Dimension getSize();
258
259 /**
260 * Resizes this object so that it has width and height.
261 *
262 * @param d The dimension specifying the new size of the object.
263 * @see #getSize
264 */
265 public void setSize(Dimension d);
266
267 /**
268 * Returns the Accessible child, if one exists, contained at the local
269 * coordinate Point.
270 *
271 * @param p The point relative to the coordinate system of this object.
272 * @return the Accessible, if it exists, at the specified location;
273 * otherwise null
274 */
275 public Accessible getAccessibleAt(Point p);
276
277 /**
278 * Returns whether this object can accept focus or not. Objects that
279 * can accept focus will also have the AccessibleState.FOCUSABLE state
280 * set in their AccessibleStateSets.
281 *
282 * @return true if object can accept focus; otherwise false
283 * @see AccessibleContext#getAccessibleStateSet
284 * @see AccessibleState#FOCUSABLE
285 * @see AccessibleState#FOCUSED
286 * @see AccessibleStateSet
287 */
288 public boolean isFocusTraversable();
289
290 /**
291 * Requests focus for this object. If this object cannot accept focus,
292 * nothing will happen. Otherwise, the object will attempt to take
293 * focus.
294 * @see #isFocusTraversable
295 */
296 public void requestFocus();
297
298 /**
299 * Adds the specified focus listener to receive focus events from this
300 * component.
301 *
302 * @param l the focus listener
303 * @see #removeFocusListener
304 */
305 public void addFocusListener(FocusListener l);
306
307 /**
308 * Removes the specified focus listener so it no longer receives focus
309 * events from this component.
310 *
311 * @param l the focus listener
312 * @see #addFocusListener
313 */
314 public void removeFocusListener(FocusListener l);
315 }