001/* AccessibleComponent.java -- aids in accessibly rendering Java components
002   Copyright (C) 2000, 2001, 2002, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package javax.accessibility;
039
040import java.awt.Color;
041import java.awt.Cursor;
042import java.awt.Dimension;
043import java.awt.Font;
044import java.awt.FontMetrics;
045import java.awt.Point;
046import java.awt.Rectangle;
047import 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 */
066public 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