libjava/classpath/javax/swing/ImageIcon.java

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