libjava/javax/accessibility/AccessibleComponent.java

   1 /* AccessibleComponent.java -- aids in accessibly rendering Java components
   2    Copyright (C) 2000, 2001, 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 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)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package javax.accessibility;
  39
  40 import java.awt.Color;
  41 import java.awt.Cursor;
  42 import java.awt.Dimension;
  43 import java.awt.Font;
  44 import java.awt.FontMetrics;
  45 import java.awt.Point;
  46 import java.awt.Rectangle;
  47 import java.awt.event.FocusListener;
  48
  49 /**
  50  * Objects which are to be rendered to a screen as part of a graphical
  51  * user interface should implement this interface.  Accessibility
  52  * software can use the implementations of this interface to determine
  53  * and set the screen representation for an object.
  54  *
  55  * <p>The <code>AccessibleContext.getAccessibleComponent()</code> method
  56  * should return <code>null</code> if an object does not implement this
  57  * interface.
  58  *
  59  * @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
  67 {
  68   /**
  69    * Get the background color of this component.
  70    *
  71    * @return the background color of this component, or null if not supported
  72    * @see #setBackground(Color)
  73    */
  74   Color getBackground();
  75
  76   /**
  77    * Set the background color of this component to the specified color.
  78    *
  79    * @param color the color to set the background to
  80    * @see #getBackground()
  81    */
  82   void setBackground(Color color);
  83
  84   /**
  85    * Get the foreground color of this component.
  86    *
  87    * @return the foreground color of this component, or null if not supported
  88    * @see #setForeground(Color)
  89    */
  90   Color getForeground();
  91
  92   /**
  93    * Set the foreground color of this component.
  94    *
  95    * @param color the color to set the foreground to
  96    * @see #getForeground()
  97    */
  98   void setForeground(Color color);
  99
 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