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