Source for javax.swing.ImageIcon

   1: /* ImageIcon.java --
   2:    Copyright (C) 2002, 2004, 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.swing;
  39: 
  40: import java.awt.Component;
  41: import java.awt.Graphics;
  42: import java.awt.Image;
  43: import java.awt.MediaTracker;
  44: import java.awt.Toolkit;
  45: import java.awt.image.ImageObserver;
  46: import java.io.Serializable;
  47: import java.net.URL;
  48: import java.util.Locale;
  49: 
  50: import javax.accessibility.Accessible;
  51: import javax.accessibility.AccessibleContext;
  52: import javax.accessibility.AccessibleIcon;
  53: import javax.accessibility.AccessibleRole;
  54: import javax.accessibility.AccessibleStateSet;
  55: 
  56: /**
  57:  * An {@link Icon} implementation that is backed by an {@link Image}.
  58:  */
  59: public class ImageIcon
  60:   implements Icon, Serializable, Accessible
  61: {
  62:   /**
  63:    * Accessibility support for ImageIcon.
  64:    */
  65:   protected class AccessibleImageIcon
  66:     extends AccessibleContext
  67:     implements AccessibleIcon, Serializable
  68:   {
  69:     private static final long serialVersionUID = 2113430526551336564L;
  70: 
  71:     /**
  72:      * Creates a new instance of AccessibleImageIcon.
  73:      */
  74:     protected AccessibleImageIcon()
  75:     {
  76:       // Nothing to do here.
  77:     }
  78: 
  79:     /**
  80:      * Returns the AccessibleRole of ImageIcon, which is
  81:      * {@link AccessibleRole#ICON}.
  82:      *
  83:      * @return {@link AccessibleRole#ICON}
  84:      */
  85:     public AccessibleRole getAccessibleRole()
  86:     {
  87:       return AccessibleRole.ICON;
  88:     }
  89: 
  90:     /**
  91:      * Returns the accessible state of this ImageIcon.
  92:      *
  93:      * @return the accessible state of this ImageIcon
  94:      */
  95:     public AccessibleStateSet getAccessibleStateSet()
  96:     {
  97:       // TODO: which state information from ImageIcon is returned here??
  98:       return new AccessibleStateSet();
  99:     }
 100: 
 101:     /**
 102:      * Returns the accessible parent of this object, which is <code>null</code>
 103:      * in this case, because ImageIcons have no parent.
 104:      *
 105:      * @return <code>null</code>, because ImageIcons have no parent
 106:      */
 107:     public Accessible getAccessibleParent()
 108:     {
 109:       // TODO: ImageIcons have no parent, have they ??
 110:       return null;
 111:     }
 112: 
 113:     /**
 114:      * Returns the index of this object in its accessible parent, which is
 115:      * -1 here, because ImageIcons have no accessible parent.
 116:      *
 117:      * @return -1 because ImageIcons have no parent
 118:      */
 119:     public int getAccessibleIndexInParent()
 120:     {
 121:       // TODO: do ImageIcons have parents??
 122:       return -1;
 123:     }
 124: 
 125:     /**
 126:      * Returns the number of accessible children of this component,
 127:      * which is 0, because ImageIcons have no children.
 128:      *
 129:      * @return 0 because ImageIcons have no children
 130:      */
 131:     public int getAccessibleChildrenCount()
 132:     {
 133:       return 0;
 134:     }
 135: 
 136:     /**
 137:      * Returns the accessible child at index <code>i</code>, which is
 138:      * <code>null</code> in this case because ImageIcons have no children.
 139:      *
 140:      * @param i the index of the child to be fetched
 141:      *
 142:      * @return <code>null</code> because ImageIcons have no children
 143:      */
 144:     public Accessible getAccessibleChild(int i)
 145:     {
 146:       return null;
 147:     }
 148: 
 149:     /**
 150:      * Returns the locale of this object. This returns the default locale
 151:      * that is set for the current VM.
 152:      *
 153:      * @return the locale of this object
 154:      */
 155:     public Locale getLocale()
 156:     {
 157:       return Locale.getDefault();
 158:     }
 159: 
 160:     /**
 161:      * Returns the accessible Icon description. This returns the
 162:      * actual 'description' property of the ImageIcon.
 163:      *
 164:      * @return the accessible Icon description
 165:      */
 166:     public String getAccessibleIconDescription()
 167:     {
 168:       return getDescription();
 169:     }
 170: 
 171:     /**
 172:      * Sets the accessible Icon description. This sets the
 173:      * actual 'description' property of the ImageIcon.
 174:      *
 175:      * @param newDescr the description to be set
 176:      */
 177:     public void setAccessibleIconDescription(String newDescr)
 178:     {
 179:       setDescription(newDescr);
 180:     }
 181: 
 182:     /**
 183:      * Returns the icon height. This returns the iconHeight property of
 184:      * the underlying Icon.
 185:      *
 186:      * @return the icon height
 187:      */
 188:     public int getAccessibleIconHeight()
 189:     {
 190:       return getIconHeight();
 191:     }
 192:     
 193:     /**
 194:      * Returns the icon width. This returns the iconWidth property of
 195:      * the underlying Icon.
 196:      *
 197:      * @return the icon width
 198:      */
 199:     public int getAccessibleIconWidth()
 200:     {
 201:       return getIconWidth();
 202:     }
 203:   } // AccessibleIcon
 204: 
 205:   private static final long serialVersionUID = 532615968316031794L;
 206: 
 207:   /** A dummy Component that is used in the MediaTracker. */
 208:   protected static Component component = new Component()
 209:   {
 210:     // No need to implement this. 
 211:   };
 212: 
 213:   /** The MediaTracker used to monitor the loading of images. */
 214:   protected static MediaTracker tracker = new MediaTracker(component);
 215: 
 216:   /** The ID that is used in the tracker. */
 217:   private static int id;
 218: 
 219:   Image image;
 220:   String description;
 221:   ImageObserver observer;
 222: 
 223:   /** The image loading status. */
 224:   private int loadStatus;
 225: 
 226:   /** The AccessibleContext of this ImageIcon. */
 227:   private AccessibleContext accessibleContext;
 228: 
 229:   /**
 230:    * Creates an ImageIcon without any properties set.
 231:    */
 232:   public ImageIcon()
 233:   {
 234:     // Nothing to do here.
 235:   }
 236:  
 237:   /**
 238:    * Constructs an ImageIcon given a filename.  The icon's description
 239:    * is initially set to the filename itself.  A filename of "" means
 240:    * create a blank icon.
 241:    *
 242:    * @param filename name of file to load or "" for a blank icon
 243:    */
 244:   public ImageIcon(String filename)
 245:   {
 246:     this(filename, filename);
 247:   }
 248: 
 249:   /**
 250:    * Constructs an ImageIcon from the given filename, setting its
 251:    * description to the given description.  A filename of "" means
 252:    * create a blank icon.
 253:    *
 254:    * @param filename name of file to load or "" for a blank icon
 255:    * @param description human-readable description of this icon
 256:    */
 257:   public ImageIcon(String filename, String description)
 258:   {
 259:     this(Toolkit.getDefaultToolkit().getImage(filename), description);
 260:   }
 261: 
 262:   /**
 263:    * Creates an ImageIcon from the given byte array without any
 264:    * description set.
 265:    */
 266:   public ImageIcon(byte[] imageData)
 267:   {
 268:     this(imageData, null);
 269:   }
 270:   
 271:   /**
 272:    * Creates an ImageIcon from the given byte array and sets the given
 273:    * description.
 274:    */
 275:   public ImageIcon(byte[] imageData, String description)
 276:   {
 277:     this(Toolkit.getDefaultToolkit().createImage(imageData), description);
 278:   }
 279: 
 280:   /**
 281:    * Creates an ImageIcon from the given URL without any description
 282:    * set.
 283:    */
 284:   public ImageIcon(URL url)
 285:   {
 286:     this(url, null);
 287:   }
 288: 
 289:   /**
 290:    * Creates an ImageIcon from the given URL and sets the given
 291:    * description.
 292:    */
 293:   public ImageIcon(URL url, String description)
 294:   {
 295:     this(Toolkit.getDefaultToolkit().getImage(url), description);
 296:   }
 297: 
 298:   /**
 299:    * Creates an ImageIcon from the given Image without any description
 300:    * set.
 301:    */
 302:   public ImageIcon(Image image)
 303:   {
 304:     this(image, null);
 305:   }
 306: 
 307:   /**
 308:    * Creates an ImageIcon from the given Image and sets the given
 309:    * description.
 310:    */
 311:   public ImageIcon(Image image, String description)
 312:   {
 313:     setImage(image);
 314:     setDescription(description);
 315:   }
 316: 
 317:   /**
 318:    * Returns the ImageObserver that is used for all Image
 319:    * operations. Defaults to null when not explicitly set.
 320:    */
 321:   public ImageObserver getImageObserver()
 322:   {
 323:     return observer;
 324:   }
 325:   
 326:   /**
 327:    * Sets the ImageObserver that will be used for all Image
 328:    * operations. Can be set to null (the default) when no observer is
 329:    * needed.
 330:    */
 331:   public void setImageObserver(ImageObserver newObserver)
 332:   {
 333:     observer = newObserver;
 334:   }
 335: 
 336:   /**
 337:    * Returns the backing Image for this ImageIcon. Might be set to
 338:    * null in which case no image is shown.
 339:    */
 340:   public Image getImage()
 341:   {
 342:     return image;
 343:   }
 344: 
 345:   /**
 346:    * Explicitly sets the backing Image for this ImageIcon. Will call
 347:    * loadImage() to make sure that the Image is completely loaded
 348:    * before returning.
 349:    */
 350:   public void setImage(Image image)
 351:   {
 352:     loadImage(image);
 353:     this.image = image;
 354:   }
 355: 
 356:   /**
 357:    * Returns a human readable description for this ImageIcon or null
 358:    * when no description is set or available.
 359:    */
 360:   public String getDescription()
 361:   {
 362:     return description;
 363:   }
 364: 
 365:   /**
 366:    * Sets a human readable description for this ImageIcon. Can be set
 367:    * to null when no description is available.
 368:    */
 369:   public void setDescription(String description)
 370:   {
 371:     this.description = description;
 372:   }
 373: 
 374:   /**
 375:    * Returns the the height of the backing Image, or -1 if the backing
 376:    * Image is null. The getHeight() method of the Image will be called
 377:    * with the set observer of this ImageIcon.
 378:    */
 379:   public int getIconHeight()
 380:   {
 381:     if (image == null)
 382:       return -1;
 383: 
 384:     return image.getHeight(observer);
 385:   }
 386: 
 387:   /**
 388:    * Returns the the width of the backing Image, or -1 if the backing
 389:    * Image is null. The getWidth() method of the Image will be called
 390:    * with the set observer of this ImageIcon.
 391:    */
 392:   public int getIconWidth()
 393:   {
 394:     if (image == null)
 395:       return -1;
 396: 
 397:     return image.getWidth(observer);
 398:   }
 399: 
 400:   /**
 401:    * Calls <code>g.drawImage()</code> on the backing Image using the
 402:    * set observer of this ImageIcon. If the set observer is null, the
 403:    * given Component is used as observer.
 404:    */
 405:   public void paintIcon(Component c, Graphics g, int x, int y)
 406:   {
 407:     g.drawImage(image, x, y, observer != null ? observer : c);
 408:   }
 409: 
 410:   /**
 411:    * Loads the image and blocks until the loading operation is finished.
 412:    *
 413:    * @param image the image to be loaded
 414:    */
 415:   protected void loadImage(Image image)
 416:   {
 417:     try
 418:       {
 419:         tracker.addImage(image, id);
 420:         id++;
 421:         tracker.waitForID(id - 1);
 422:       }
 423:     catch (InterruptedException ex)
 424:       {
 425:         // Ignore this for now.
 426:       }
 427:     finally
 428:       {
 429:         loadStatus = tracker.statusID(id - 1, false);
 430:       }
 431:   }
 432: 
 433:   /**
 434:    * Returns the load status of the icon image.
 435:    *
 436:    * @return the load status of the icon image
 437:    *
 438:    * @see MediaTracker#COMPLETE
 439:    * @see MediaTracker#ABORTED
 440:    * @see MediaTracker#ERRORED
 441:    */
 442:   public int getImageLoadStatus()
 443:   {
 444:     return loadStatus;
 445:   }
 446: 
 447:   /**
 448:    * Returns the AccessibleContext for this ImageIcon.
 449:    *
 450:    * @return the AccessibleContext for this ImageIcon
 451:    */
 452:   public AccessibleContext getAccessibleContext()
 453:   {
 454:     if (accessibleContext == null)
 455:       accessibleContext = new AccessibleImageIcon();
 456:     return accessibleContext;
 457:   }
 458: }