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