1 |
/* AccessibleComponent.java -- Java interface for aiding in accessibly rendering |
/* AccessibleComponent.java -- aids in accessibly rendering Java components |
2 |
other Java components |
Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. |
|
Copyright (C) 2000, 2001 Free Software Foundation, Inc. |
|
3 |
|
|
4 |
This file is part of GNU Classpath. |
This file is part of GNU Classpath. |
5 |
|
|
7 |
it under the terms of the GNU General Public License as published by |
it under the terms of the GNU General Public License as published by |
8 |
the Free Software Foundation; either version 2, or (at your option) |
the Free Software Foundation; either version 2, or (at your option) |
9 |
any later version. |
any later version. |
10 |
|
|
11 |
GNU Classpath is distributed in the hope that it will be useful, but |
GNU Classpath is distributed in the hope that it will be useful, but |
12 |
WITHOUT ANY WARRANTY; without even the implied warranty of |
WITHOUT ANY WARRANTY; without even the implied warranty of |
13 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
37 |
|
|
38 |
package javax.accessibility; |
package javax.accessibility; |
39 |
|
|
40 |
import java.awt.event.FocusListener; |
import java.awt.Color; |
41 |
import java.awt.Point; |
import java.awt.Cursor; |
42 |
|
import java.awt.Dimension; |
43 |
import java.awt.Font; |
import java.awt.Font; |
44 |
import java.awt.FontMetrics; |
import java.awt.FontMetrics; |
45 |
import java.awt.Color; |
import java.awt.Point; |
46 |
import java.awt.Rectangle; |
import java.awt.Rectangle; |
47 |
import java.awt.Dimension; |
import java.awt.event.FocusListener; |
|
import java.awt.Cursor; |
|
48 |
|
|
49 |
/** |
/** |
50 |
* Objects which are to be rendered to a screen as part of a graphical |
* Objects which are to be rendered to a screen as part of a graphical |
51 |
* user interface should implement this interface. Accessibility |
* user interface should implement this interface. Accessibility |
52 |
* software can use the implementations of this interface to determine |
* software can use the implementations of this interface to determine |
53 |
* and set the screen representation for an object. |
* and set the screen representation for an object. |
54 |
* <p> |
* |
55 |
* The <code>AccessibleContext.getAccessibleComponent()</code> method |
* <p>The <code>AccessibleContext.getAccessibleComponent()</code> method |
56 |
* should return <code>null</code> if an object does not implement this |
* should return <code>null</code> if an object does not implement this |
57 |
* interface. |
* interface. |
58 |
* |
* |
59 |
* @see AccessibleContext#getAccessibleComponent() |
* @author Eric Blake <ebb9@email.byu.edu> |
60 |
|
* @see Accessible |
61 |
|
* @see AccessibleContext |
62 |
|
* @see AccessibleContext#getAccessibleComponent() |
63 |
|
* @since 1.2 |
64 |
|
* @status updated to 1.4 |
65 |
*/ |
*/ |
66 |
public interface AccessibleComponent { |
public interface AccessibleComponent |
67 |
|
{ |
68 |
/** |
/** |
69 |
* Adds the specified listener to this component. |
* Get the background color of this component. |
70 |
* |
* |
71 |
* @param listener the listener to add to this component |
* @return the background color of this component, or null if not supported |
72 |
*/ |
* @see #setBackground(Color) |
73 |
public abstract void addFocusListener(FocusListener listener); |
*/ |
74 |
|
Color getBackground(); |
75 |
/** |
|
76 |
* Tests whether or not the specified point is contained within |
/** |
77 |
* this component. The coordinates are specified relative to this |
* Set the background color of this component to the specified color. |
78 |
* component's coordinate system. |
* |
79 |
* |
* @param color the color to set the background to |
80 |
* @param point the <code>Point</code> specifying the location within |
* @see #getBackground() |
81 |
* this component |
*/ |
82 |
* |
void setBackground(Color color); |
83 |
* @return <code>true</code> if the point is within this component, |
|
84 |
* <code>false</code> otherwise |
/** |
85 |
*/ |
* Get the foreground color of this component. |
86 |
public abstract boolean contains(Point point); |
* |
87 |
|
* @return the foreground color of this component, or null if not supported |
88 |
/** |
* @see #setForeground(Color) |
89 |
* If a object exists which is a child of this parent component at |
*/ |
90 |
* the specified point which implements the Accessible interface then |
Color getForeground(); |
91 |
* that object is returned. |
|
92 |
* |
/** |
93 |
* @param point the <code>Point</code> specifying the location within |
* Set the foreground color of this component. |
94 |
* this component |
* |
95 |
* |
* @param color the color to set the foreground to |
96 |
* @return <code>null</code> if no <code>Accessible</code> child exists |
* @see #getForeground() |
97 |
* at the given point |
*/ |
98 |
*/ |
void setForeground(Color color); |
99 |
public abstract Accessible getAccessibleAt(Point point); |
|
100 |
|
/** |
101 |
/** |
* Get the cursor of this component. |
102 |
* Get the background color of this component. |
* |
103 |
* |
* @return the Cursor of this component, or null if not supported |
104 |
* @return the background color of this component if supported, |
* @see #setCursor(Cursor) |
105 |
* else <code>null</code> |
*/ |
106 |
*/ |
Cursor getCursor(); |
107 |
public abstract Color getBackground(); |
|
108 |
|
/** |
109 |
/** |
* Set the cursor of the component. |
110 |
* Get the bounds of this component relative to its parent. |
* |
111 |
* |
* @param cursor the graphical representation of the cursor to use |
112 |
* @return the <code>Rectangle</code> representing the bounds of this component |
* @see #getCursor() |
113 |
* if it is visible on the screen, else <code>null</code> |
*/ |
114 |
*/ |
void setCursor(Cursor cursor); |
115 |
public abstract Rectangle getBounds(); |
|
116 |
|
/** |
117 |
/** |
* Get the font of this component |
118 |
* Get the cursor of this component. |
* |
119 |
* |
* @return the font of the component, or null if not supported |
120 |
* @return the <code>Cursor</code> representing the mouse cursor if supported, |
* @see setFont(Font) |
121 |
* else <code>null</code> |
*/ |
122 |
*/ |
Font getFont(); |
123 |
public abstract Cursor getCursor(); |
|
124 |
|
/** |
125 |
/** |
* Set the font of this component. |
126 |
* Get the font of this component |
* |
127 |
* |
* @param font the font to use |
128 |
* @return the <code>Font</code> of the component if supported, |
* @see #getFont() |
129 |
* else <code>null</code> |
*/ |
130 |
*/ |
void setFont(Font font); |
131 |
public abstract Font getFont(); |
|
132 |
|
/** |
133 |
/** |
* Get the <code>FontMetrics</code> of the specified font in this component. |
134 |
* Get the <code>FontMetrics</code> of the specified font in this component. |
* |
135 |
* |
* @param font the specified font |
136 |
* @param font the specified font |
* @return the metrics for the specified font, or null if not supported |
137 |
* @return the <code>FontMetrics</code> for the specified font if supported, |
* @see #getFont() |
138 |
* else <code>null</code> |
*/ |
139 |
*/ |
// XXX What happens if font is null? |
140 |
public abstract FontMetrics getFontMetrics(Font font); |
FontMetrics getFontMetrics(Font font); |
141 |
|
|
142 |
/** |
/** |
143 |
* Get the foreground color of this component |
* Indicates whether or not this component is enabled. An object which is |
144 |
* |
* enabled also has AccessibleState.ENABLED in its StateSet. |
145 |
* @return the foreground color of this component if supported, |
* |
146 |
* else <code>null</code> |
* @return true if the component is enabled |
147 |
*/ |
* @see #setEnabled(boolean) |
148 |
public abstract Color getForeground(); |
* @see AccessibleContext#getAccessibleStateSet() |
149 |
|
* @see AccessibleState#ENABLED |
150 |
/** |
*/ |
151 |
* Get the location of this component in the screen's coordinate system. |
boolean isEnabled(); |
152 |
* The point specified is the top-left corner of this component. |
|
153 |
* <p> |
/** |
154 |
* <i>FIXME - Sun indicates this location is relative to the parent, but in the |
* Set this component to an enabled or disabled state. |
155 |
* screen's coordinate space I am not sure how this is possible yet. What |
* |
156 |
* makes the most sense is that this location is truly relative to the |
* @param b true to enable the component, else disable it |
157 |
* parent and the coordinates are in the parent's coordinate system.</i> |
* @see #isEnabled() |
158 |
*/ |
*/ |
159 |
public abstract Point getLocation(); |
void setEnabled(boolean b); |
160 |
|
|
161 |
/** |
/** |
162 |
* Get the location of this component in the screen's coordinate space. |
* Indicates whether or not this component is visible or intends to be |
163 |
* The point specified is the top-left corner of this component. |
* visible although one of its ancestors may not be. An object which is |
164 |
*/ |
* visible also has AccessibleState.VISIBLE in its StateSet. Check |
165 |
public abstract Point getLocationOnScreen(); |
* <code>isShowing()</code> to see if the object is on screen. |
166 |
|
* |
167 |
/** |
* @return true if the component is visible |
168 |
* Get the size of this component. |
* @see #setVisible(boolean) |
169 |
* |
* @see AccessibleContext#getAccessibleStateSet() |
170 |
* @return the <code>Dimension</code> giving the height and width of this |
* @see AccessibleState#VISIBLE |
171 |
* component, <code>null</code> if the component is not on the screen |
*/ |
172 |
*/ |
boolean isVisible(); |
173 |
public abstract Dimension getSize(); |
|
174 |
|
/** |
175 |
/** |
* Set the visible state of this component. |
176 |
* Indicates whether or not this component is enabled. |
* |
177 |
* |
* @param b true to make the component visible, else hide it |
178 |
* @return <code>true</code> if the component is enabled, |
* @see #isVisible() |
179 |
* else <code>false</code> |
*/ |
180 |
* |
void setVisible(boolean b); |
181 |
* @see AccessibleContext#getAccessibleStateSet() |
|
182 |
* @see AccessibleState#ENABLED |
/** |
183 |
*/ |
* Indicates whether or not this component is visible by checking |
184 |
public abstract boolean isEnabled(); |
* the visibility of this component and its ancestors. The component may |
185 |
|
* be hidden on screen by another component like pop-up help. An object |
186 |
/** |
* which is showing on screen also has AccessibleState.SHOWING in its |
187 |
* Indicates whether or not this component can accept focus. |
* StateSet. |
188 |
* |
* |
189 |
* @return <code>true</code> if the component accepts focus, |
* @return true if component and ancestors are visible |
190 |
* else <code>false</code> |
* @see #isVisible() |
191 |
* |
* @see #setVisible(boolean) |
192 |
* @see AccessibleContext#getAccessibleStateSet() |
* @see AccessibleContext#getAccessibleStateSet() |
193 |
* @see AccessibleState#FOCUSABLE |
* @see AccessibleState#SHOWING |
194 |
* @see AccessibleState#FOCUSED |
*/ |
195 |
*/ |
boolean isShowing(); |
196 |
public abstract boolean isFocusTraversable(); |
|
197 |
|
/** |
198 |
/** |
* Tests whether or not the specified point is contained within |
199 |
* Indicates whether or not this component is visible by checking |
* this component. The coordinates are specified relative to this |
200 |
* the visibility of this component and its ancestors. |
* component's coordinate system. |
201 |
* <p> |
* |
202 |
* The component may be hidden on screen by another component like |
* @param point the Point to locate |
203 |
* pop-up help. |
* @return true if the point is within this component |
204 |
* |
* @see #getBounds() |
205 |
* @return <code>true</code> if component and ancestors are visible, |
*/ |
206 |
* else <code>false</code> |
// XXX What happens if point is null? |
207 |
* |
boolean contains(Point point); |
208 |
* @see AccessibleContext#getAccessibleStateSet() |
|
209 |
* @see AccessibleState#SHOWING |
/** |
210 |
*/ |
* Get the location of this component in the screen's coordinate space. |
211 |
public abstract boolean isShowing(); |
* The point specified is the top-left corner of this component. |
212 |
|
* |
213 |
/** |
* @return the location on screen, or null if off-screen |
214 |
* Indicates whether or not this component is visible or intends to be |
* @see #getBounds() |
215 |
* visible although one of its ancestors may not be. |
* @see #getLocation() |
216 |
* |
*/ |
217 |
* @return <code>true</code> if the component is visible, |
Point getLocationOnScreen(); |
218 |
* else <code>false</code> |
|
219 |
* |
/** |
220 |
* @see AccessibleContext#getAccessibleStateSet() |
* Get the location of this component in the parent's coordinate system. |
221 |
* @see AccessibleState#VISIBLE |
* The point specified is the top-left corner of this component. |
222 |
*/ |
* |
223 |
public abstract boolean isVisible(); |
* @return the location in the parent on screen, or null if off-screen |
224 |
|
* @see #getBounds() |
225 |
/** |
* @see #getLocationOnScreen() |
226 |
* Removes the specified listener from this component. |
* @see #setLocation(Point) |
227 |
* |
*/ |
228 |
* @param listener the listener to remove |
Point getLocation(); |
229 |
*/ |
|
230 |
public abstract void removeFocusListener(FocusListener listener); |
/** |
231 |
|
* Set the location of this component relative to its parent. The point |
232 |
/** |
* specified represents the top-left corner of this component. |
233 |
* If this method is called this component will attempt to gain focus, |
* |
234 |
* but if it cannot accept focus nothing happens. |
* @param point the top-left corner of this component relative to the parent |
235 |
*/ |
* @see #getLocation() |
236 |
public abstract void requestFocus(); |
*/ |
237 |
|
// XXX What happens if point is null? |
238 |
/** |
void setLocation(Point point); |
239 |
* Set the background color of this component to the specified color. |
|
240 |
* |
/** |
241 |
* @param color the color to set the background to |
* Get the bounds of this component relative to its parent - it's width, |
242 |
*/ |
* height, and relative location to its parent. |
243 |
public abstract void setBackground(Color color); |
* |
244 |
|
* @return the bounds of this component, or null if not on screen |
245 |
/** |
* @see #contains(Point) |
246 |
* Set the bounds of this component to the specified height and width. |
*/ |
247 |
* |
Rectangle getBounds(); |
248 |
* @param rectangle the object representing the height, width, and location |
|
249 |
* of this component relative to its parent. |
/** |
250 |
*/ |
* Set the bounds of this component to the specified height and width, and |
251 |
public abstract void setBounds(Rectangle rectangle); |
* relative location to its parent. |
252 |
|
* |
253 |
/** |
* @param rectangle the new height, width, and relative location |
254 |
* Set the cursor of the component. |
*/ |
255 |
* |
// XXX What happens if rectangle is null? |
256 |
* @param cursor the graphical representation of the cursor to use |
void setBounds(Rectangle rectangle); |
257 |
*/ |
|
258 |
public abstract void setCursor(Cursor cursor); |
/** |
259 |
|
* Get the size of this component - it's width and height. |
260 |
/** |
* |
261 |
* Set this component to an enabled or disabled state. |
* @return the dimensions of this component, or null if not on screen |
262 |
* |
* @see #setSize(Dimension) |
263 |
* @param b if <code>true</code> enable the component, else disable it |
*/ |
264 |
* |
Dimension getSize(); |
265 |
* @see #isEnabled() |
|
266 |
*/ |
/** |
267 |
public abstract void setEnabled(boolean b); |
* Set the size of this component to the given dimensions. |
268 |
|
* |
269 |
/** |
* @param dimension the new size of the component |
270 |
* Set the font of this component. |
* @see #getSize() |
271 |
* |
*/ |
272 |
* @param font the font to use |
// XXX What happens if dimension is null? |
273 |
*/ |
void setSize(Dimension dimension); |
274 |
public abstract void setFont(Font font); |
|
275 |
|
/** |
276 |
/** |
* If a object exists at the specified point which is a child of this |
277 |
* Set the foreground color of this component. |
* parent component, and it is accessible, then it is returned. |
278 |
* |
* |
279 |
* @param color the color to set the foreground to |
* @param point the location within this component's coordinate system |
280 |
*/ |
* @return the accessible child object at that point, or null |
281 |
public abstract void setForeground(Color color); |
*/ |
282 |
|
Accessible getAccessibleAt(Point point); |
283 |
/** |
|
284 |
* Set the location of this component relative to its parent. The point |
/** |
285 |
* specified represents the top-left corner of this component. |
* Indicates whether or not this component can accept focus. An object |
286 |
* |
* which can accept focus also has AccessibleState.FOCUSABLE in its |
287 |
* @param point the top-left corner of this component relative to the parent |
* StateSet. |
288 |
*/ |
* |
289 |
public abstract void setLocation(Point point); |
* @return true if the component can accept focus |
290 |
|
* @see AccessibleContext#getAccessibleStateSet() |
291 |
/** |
* @see AccessibleState#FOCUSABLE |
292 |
* Set the size of this component to the given dimensions. |
* @see AccessibleState#FOCUSED |
293 |
* |
*/ |
294 |
* @param dimension the new size of the component |
boolean isFocusTraversable(); |
295 |
* |
|
296 |
* @see #getSize() |
/** |
297 |
*/ |
* If this method is called this component will attempt to gain focus, |
298 |
public abstract void setSize(Dimension dimension); |
* but if it cannot accept focus nothing happens. On success, the StateSet |
299 |
|
* will contain AccessibleState.FOCUSED |
300 |
/** |
* |
301 |
* Set the visible state of this component. |
* @see #isFocusTraversable() |
302 |
* |
* @see AccessibleState#FOCUSED |
303 |
* @param b if <code>true</code> make the component visible, else make |
*/ |
304 |
* it invisible |
void requestFocus(); |
305 |
* |
|
306 |
* @see #isVisible() |
/** |
307 |
*/ |
* Adds the specified listener to this component. |
308 |
public abstract void setVisible(boolean b); |
* |
309 |
} |
* @param listener the listener to add to this component |
310 |
|
* @see #removeFocusListener(FocusListener) |
311 |
|
*/ |
312 |
|
void addFocusListener(FocusListener listener); |
313 |
|
|
314 |
|
/** |
315 |
|
* Removes the specified listener from this component. |
316 |
|
* |
317 |
|
* @param listener the listener to remove |
318 |
|
* @see #addFocusListener(FocusListener) |
319 |
|
*/ |
320 |
|
void removeFocusListener(FocusListener listener); |
321 |
|
} // interface AccessibleComponent |