001 /* AccessibleComponent.java -- aids in accessibly rendering Java components
002 Copyright (C) 2000, 2001, 2002, 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package javax.accessibility;
039
040 import java.awt.Color;
041 import java.awt.Cursor;
042 import java.awt.Dimension;
043 import java.awt.Font;
044 import java.awt.FontMetrics;
045 import java.awt.Point;
046 import java.awt.Rectangle;
047 import java.awt.event.FocusListener;
048
049 /**
050 * Objects which are to be rendered to a screen as part of a graphical
051 * user interface should implement this interface. Accessibility
052 * software can use the implementations of this interface to determine
053 * and set the screen representation for an object.
054 *
055 * <p>The <code>AccessibleContext.getAccessibleComponent()</code> method
056 * should return <code>null</code> if an object does not implement this
057 * interface.
058 *
059 * @author Eric Blake (ebb9@email.byu.edu)
060 * @see Accessible
061 * @see AccessibleContext
062 * @see AccessibleContext#getAccessibleComponent()
063 * @since 1.2
064 * @status updated to 1.4
065 */
066 public interface AccessibleComponent
067 {
068 /**
069 * Get the background color of this component.
070 *
071 * @return the background color of this component, or null if not supported
072 * @see #setBackground(Color)
073 */
074 Color getBackground();
075
076 /**
077 * Set the background color of this component to the specified color.
078 *
079 * @param color the color to set the background to
080 * @see #getBackground()
081 */
082 void setBackground(Color color);
083
084 /**
085 * Get the foreground color of this component.
086 *
087 * @return the foreground color of this component, or null if not supported
088 * @see #setForeground(Color)
089 */
090 Color getForeground();
091
092 /**
093 * Set the foreground color of this component.
094 *
095 * @param color the color to set the foreground to
096 * @see #getForeground()
097 */
098 void setForeground(Color color);
099
100 /**
101 * Get the cursor of this component.
102 *
103 * @return the Cursor of this component, or null if not supported
104 * @see #setCursor(Cursor)
105 */
106 Cursor getCursor();
107
108 /**
109 * Set the cursor of the component.
110 *
111 * @param cursor the graphical representation of the cursor to use
112 * @see #getCursor()
113 */
114 void setCursor(Cursor cursor);
115
116 /**
117 * Get the font of this component
118 *
119 * @return the font of the component, or null if not supported
120 * @see #setFont(Font)
121 */
122 Font getFont();
123
124 /**
125 * Set the font of this component.
126 *
127 * @param font the font to use
128 * @see #getFont()
129 */
130 void setFont(Font font);
131
132 /**
133 * Get the <code>FontMetrics</code> of the specified font in this component.
134 *
135 * @param font the specified font
136 * @return the metrics for the specified font, or null if not supported
137 * @throws NullPointerException if font is null
138 * @see #getFont()
139 */
140 FontMetrics getFontMetrics(Font font);
141
142 /**
143 * Indicates whether or not this component is enabled. An object which is
144 * enabled also has AccessibleState.ENABLED in its StateSet.
145 *
146 * @return true if the component is enabled
147 * @see #setEnabled(boolean)
148 * @see AccessibleContext#getAccessibleStateSet()
149 * @see AccessibleState#ENABLED
150 */
151 boolean isEnabled();
152
153 /**
154 * Set this component to an enabled or disabled state.
155 *
156 * @param b true to enable the component, else disable it
157 * @see #isEnabled()
158 */
159 void setEnabled(boolean b);
160
161 /**
162 * Indicates whether or not this component is visible or intends to be
163 * visible although one of its ancestors may not be. An object which is
164 * visible also has AccessibleState.VISIBLE in its StateSet. Check
165 * <code>isShowing()</code> to see if the object is on screen.
166 *
167 * @return true if the component is visible
168 * @see #setVisible(boolean)
169 * @see AccessibleContext#getAccessibleStateSet()
170 * @see AccessibleState#VISIBLE
171 */
172 boolean isVisible();
173
174 /**
175 * Set the visible state of this component.
176 *
177 * @param b true to make the component visible, else hide it
178 * @see #isVisible()
179 */
180 void setVisible(boolean b);
181
182 /**
183 * Indicates whether or not this component is visible by checking
184 * 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 * StateSet.
188 *
189 * @return true if component and ancestors are visible
190 * @see #isVisible()
191 * @see #setVisible(boolean)
192 * @see AccessibleContext#getAccessibleStateSet()
193 * @see AccessibleState#SHOWING
194 */
195 boolean isShowing();
196
197 /**
198 * Tests whether or not the specified point is contained within
199 * this component. The coordinates are specified relative to this
200 * component's coordinate system.
201 *
202 * @param point the Point to locate
203 * @return true if the point is within this component
204 * @throws NullPointerException if point is null
205 * @see #getBounds()
206 */
207 boolean contains(Point point);
208
209 /**
210 * Get the location of this component in the screen's coordinate space.
211 * The point specified is the top-left corner of this component.
212 *
213 * @return the location on screen, or null if off-screen
214 * @see #getBounds()
215 * @see #getLocation()
216 */
217 Point getLocationOnScreen();
218
219 /**
220 * Get the location of this component in the parent's coordinate system.
221 * The point specified is the top-left corner of this component.
222 *
223 * @return the location in the parent on screen, or null if off-screen
224 * @see #getBounds()
225 * @see #getLocationOnScreen()
226 * @see #setLocation(Point)
227 */
228 Point getLocation();
229
230 /**
231 * Set the location of this component relative to its parent. The point
232 * specified represents the top-left corner of this component.
233 *
234 * @param point the top-left corner of this component relative to the parent
235 * @throws NullPointerException if point is null
236 * @see #getLocation()
237 */
238 void setLocation(Point point);
239
240 /**
241 * Get the bounds of this component relative to its parent - it's width,
242 * height, and relative location to its parent.
243 *
244 * @return the bounds of this component, or null if not on screen
245 * @see #contains(Point)
246 */
247 Rectangle getBounds();
248
249 /**
250 * Set the bounds of this component to the specified height and width, and
251 * relative location to its parent.
252 *
253 * @param rectangle the new height, width, and relative location
254 * @throws NullPointerException if rectangle is null
255 */
256 void setBounds(Rectangle rectangle);
257
258 /**
259 * Get the size of this component - it's width and height.
260 *
261 * @return the dimensions of this component, or null if not on screen
262 * @see #setSize(Dimension)
263 */
264 Dimension getSize();
265
266 /**
267 * Set the size of this component to the given dimensions.
268 *
269 * @param dimension the new size of the component
270 * @throws NullPointerException if dimension is null
271 * @see #getSize()
272 */
273 void setSize(Dimension dimension);
274
275 /**
276 * If an object exists at the specified point which is a child of this
277 * parent component, and it is accessible, then it is returned.
278 *
279 * @param point the location within this component's coordinate system
280 * @return the accessible child object at that point, or null
281 */
282 Accessible getAccessibleAt(Point point);
283
284 /**
285 * Indicates whether or not this component can accept focus. An object
286 * which can accept focus also has AccessibleState.FOCUSABLE in its
287 * StateSet.
288 *
289 * @return true if the component can accept focus
290 * @see AccessibleContext#getAccessibleStateSet()
291 * @see AccessibleState#FOCUSABLE
292 * @see AccessibleState#FOCUSED
293 */
294 boolean isFocusTraversable();
295
296 /**
297 * If this method is called this component will attempt to gain focus,
298 * but if it cannot accept focus nothing happens. On success, the StateSet
299 * will contain AccessibleState.FOCUSED
300 *
301 * @see #isFocusTraversable()
302 * @see AccessibleState#FOCUSED
303 */
304 void requestFocus();
305
306 /**
307 * Adds the specified listener to this component.
308 *
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