Source for javax.accessibility.AccessibleComponent

   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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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