libjava/classpath/javax/swing/ImageIcon.java

   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 final 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 final 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 }