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