1 /* 2 * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package javax.swing; 26 27 import java.awt.*; 28 import java.awt.image.*; 29 import java.beans.ConstructorProperties; 30 import java.beans.BeanProperty; 31 import java.beans.Transient; 32 import java.net.URL; 33 34 import java.io.Serializable; 35 import java.io.ObjectOutputStream; 36 import java.io.ObjectInputStream; 37 import java.io.IOException; 38 39 import java.util.Locale; 40 import javax.accessibility.*; 41 42 import sun.awt.AppContext; 43 import java.security.*; 44 import sun.awt.AWTAccessor; 45 46 /** 47 * An implementation of the Icon interface that paints Icons 48 * from Images. Images that are created from a URL, filename or byte array 49 * are preloaded using MediaTracker to monitor the loaded state 50 * of the image. 51 * 52 * <p> 53 * For further information and examples of using image icons, see 54 * <a href="https://docs.oracle.com/javase/tutorial/uiswing/components/icon.html">How to Use Icons</a> 55 * in <em>The Java Tutorial.</em> 56 * 57 * <p> 58 * <strong>Warning:</strong> 59 * Serialized objects of this class will not be compatible with 60 * future Swing releases. The current serialization support is 61 * appropriate for short term storage or RMI between applications running 62 * the same version of Swing. As of 1.4, support for long term storage 63 * of all JavaBeans 64 * has been added to the <code>java.beans</code> package. 65 * Please see {@link java.beans.XMLEncoder}. 66 * 67 * @author Jeff Dinkins 68 * @author Lynn Monsanto 69 * @since 1.2 70 */ 71 @SuppressWarnings("serial") // Same-version serialization only 72 public class ImageIcon implements Icon, Serializable, Accessible { 73 /* Keep references to the filename and location so that 74 * alternate persistence schemes have the option to archive 75 * images symbolically rather than including the image data 76 * in the archive. 77 */ 78 private transient String filename; 79 private transient URL location; 80 81 transient Image image; 82 transient int loadStatus = 0; 83 ImageObserver imageObserver; 84 String description = null; 85 86 /** 87 * Do not use this shared component, which is used to track image loading. 88 * It is left for backward compatibility only. 89 * @deprecated since 1.8 90 */ 91 @Deprecated 92 protected static final Component component; 93 94 /** 95 * Do not use this shared media tracker, which is used to load images. 96 * It is left for backward compatibility only. 97 * @deprecated since 1.8 98 */ 99 @Deprecated 100 protected static final MediaTracker tracker; 101 102 static { 103 component = AccessController.doPrivileged(new PrivilegedAction<Component>() { 104 public Component run() { 105 try { 106 final Component component = createNoPermsComponent(); 107 108 // 6482575 - clear the appContext field so as not to leak it 109 AWTAccessor.getComponentAccessor(). 110 setAppContext(component, null); 111 112 return component; 113 } catch (Throwable e) { 114 // We don't care about component. 115 // So don't prevent class initialisation. 116 e.printStackTrace(); 117 return null; 118 } 119 } 120 }); 121 tracker = new MediaTracker(component); 122 } 123 124 private static Component createNoPermsComponent() { 125 // 7020198 - set acc field to no permissions and no subject 126 // Note, will have appContext set. 127 return AccessController.doPrivileged( 128 new PrivilegedAction<Component>() { 129 public Component run() { 130 return new Component() { 131 }; 132 } 133 }, 134 new AccessControlContext(new ProtectionDomain[]{ 135 new ProtectionDomain(null, null) 136 }) 137 ); 138 } 139 140 /** 141 * Id used in loading images from MediaTracker. 142 */ 143 private static int mediaTrackerID; 144 145 private static final Object TRACKER_KEY = new StringBuilder("TRACKER_KEY"); 146 147 int width = -1; 148 int height = -1; 149 150 /** 151 * Creates an ImageIcon from the specified file. The image will 152 * be preloaded by using MediaTracker to monitor the loading state 153 * of the image. 154 * @param filename the name of the file containing the image 155 * @param description a brief textual description of the image 156 * @see #ImageIcon(String) 157 */ 158 public ImageIcon(String filename, String description) { 159 image = Toolkit.getDefaultToolkit().getImage(filename); 160 if (image == null) { 161 return; 162 } 163 this.filename = filename; 164 this.description = description; 165 loadImage(image); 166 } 167 168 /** 169 * Creates an ImageIcon from the specified file. The image will 170 * be preloaded by using MediaTracker to monitor the loading state 171 * of the image. The specified String can be a file name or a 172 * file path. When specifying a path, use the Internet-standard 173 * forward-slash ("/") as a separator. 174 * (The string is converted to an URL, so the forward-slash works 175 * on all systems.) 176 * For example, specify: 177 * <pre> 178 * new ImageIcon("images/myImage.gif") </pre> 179 * The description is initialized to the <code>filename</code> string. 180 * 181 * @param filename a String specifying a filename or path 182 * @see #getDescription 183 */ 184 @ConstructorProperties({"description"}) 185 public ImageIcon (String filename) { 186 this(filename, filename); 187 } 188 189 /** 190 * Creates an ImageIcon from the specified URL. The image will 191 * be preloaded by using MediaTracker to monitor the loaded state 192 * of the image. 193 * @param location the URL for the image 194 * @param description a brief textual description of the image 195 * @see #ImageIcon(String) 196 */ 197 public ImageIcon(URL location, String description) { 198 image = Toolkit.getDefaultToolkit().getImage(location); 199 if (image == null) { 200 return; 201 } 202 this.location = location; 203 this.description = description; 204 loadImage(image); 205 } 206 207 /** 208 * Creates an ImageIcon from the specified URL. The image will 209 * be preloaded by using MediaTracker to monitor the loaded state 210 * of the image. 211 * The icon's description is initialized to be 212 * a string representation of the URL. 213 * @param location the URL for the image 214 * @see #getDescription 215 */ 216 public ImageIcon (URL location) { 217 this(location, location.toExternalForm()); 218 } 219 220 /** 221 * Creates an ImageIcon from the image. 222 * @param image the image 223 * @param description a brief textual description of the image 224 */ 225 public ImageIcon(Image image, String description) { 226 this(image); 227 this.description = description; 228 } 229 230 /** 231 * Creates an ImageIcon from an image object. 232 * If the image has a "comment" property that is a string, 233 * then the string is used as the description of this icon. 234 * @param image the image 235 * @see #getDescription 236 * @see java.awt.Image#getProperty 237 */ 238 public ImageIcon (Image image) { 239 this.image = image; 240 Object o = image.getProperty("comment", imageObserver); 241 if (o instanceof String) { 242 description = (String) o; 243 } 244 loadImage(image); 245 } 246 247 /** 248 * Creates an ImageIcon from an array of bytes which were 249 * read from an image file containing a supported image format, 250 * such as GIF, JPEG, or (as of 1.3) PNG. 251 * Normally this array is created 252 * by reading an image using Class.getResourceAsStream(), but 253 * the byte array may also be statically stored in a class. 254 * 255 * @param imageData an array of pixels in an image format supported 256 * by the AWT Toolkit, such as GIF, JPEG, or (as of 1.3) PNG 257 * @param description a brief textual description of the image 258 * @see java.awt.Toolkit#createImage 259 */ 260 public ImageIcon (byte[] imageData, String description) { 261 this.image = Toolkit.getDefaultToolkit().createImage(imageData); 262 if (image == null) { 263 return; 264 } 265 this.description = description; 266 loadImage(image); 267 } 268 269 /** 270 * Creates an ImageIcon from an array of bytes which were 271 * read from an image file containing a supported image format, 272 * such as GIF, JPEG, or (as of 1.3) PNG. 273 * Normally this array is created 274 * by reading an image using Class.getResourceAsStream(), but 275 * the byte array may also be statically stored in a class. 276 * If the resulting image has a "comment" property that is a string, 277 * then the string is used as the description of this icon. 278 * 279 * @param imageData an array of pixels in an image format supported by 280 * the AWT Toolkit, such as GIF, JPEG, or (as of 1.3) PNG 281 * @see java.awt.Toolkit#createImage 282 * @see #getDescription 283 * @see java.awt.Image#getProperty 284 */ 285 public ImageIcon (byte[] imageData) { 286 this.image = Toolkit.getDefaultToolkit().createImage(imageData); 287 if (image == null) { 288 return; 289 } 290 Object o = image.getProperty("comment", imageObserver); 291 if (o instanceof String) { 292 description = (String) o; 293 } 294 loadImage(image); 295 } 296 297 /** 298 * Creates an uninitialized image icon. 299 */ 300 public ImageIcon() { 301 } 302 303 /** 304 * Loads the image, returning only when the image is loaded. 305 * @param image the image 306 */ 307 protected void loadImage(Image image) { 308 MediaTracker mTracker = getTracker(); 309 synchronized(mTracker) { 310 int id = getNextID(); 311 312 mTracker.addImage(image, id); 313 try { 314 mTracker.waitForID(id, 0); 315 } catch (InterruptedException e) { 316 System.out.println("INTERRUPTED while loading Image"); 317 } 318 loadStatus = mTracker.statusID(id, false); 319 mTracker.removeImage(image, id); 320 321 width = image.getWidth(imageObserver); 322 height = image.getHeight(imageObserver); 323 } 324 } 325 326 /** 327 * Returns an ID to use with the MediaTracker in loading an image. 328 */ 329 private int getNextID() { 330 synchronized(getTracker()) { 331 return ++mediaTrackerID; 332 } 333 } 334 335 /** 336 * Returns the MediaTracker for the current AppContext, creating a new 337 * MediaTracker if necessary. 338 */ 339 private MediaTracker getTracker() { 340 Object trackerObj; 341 AppContext ac = AppContext.getAppContext(); 342 // Opt: Only synchronize if trackerObj comes back null? 343 // If null, synchronize, re-check for null, and put new tracker 344 synchronized(ac) { 345 trackerObj = ac.get(TRACKER_KEY); 346 if (trackerObj == null) { 347 Component comp = new Component() {}; 348 trackerObj = new MediaTracker(comp); 349 ac.put(TRACKER_KEY, trackerObj); 350 } 351 } 352 return (MediaTracker) trackerObj; 353 } 354 355 /** 356 * Returns the status of the image loading operation. 357 * @return the loading status as defined by java.awt.MediaTracker 358 * @see java.awt.MediaTracker#ABORTED 359 * @see java.awt.MediaTracker#ERRORED 360 * @see java.awt.MediaTracker#COMPLETE 361 */ 362 public int getImageLoadStatus() { 363 return loadStatus; 364 } 365 366 /** 367 * Returns this icon's <code>Image</code>. 368 * @return the <code>Image</code> object for this <code>ImageIcon</code> 369 */ 370 @Transient 371 public Image getImage() { 372 return image; 373 } 374 375 /** 376 * Sets the image displayed by this icon. 377 * @param image the image 378 */ 379 public void setImage(Image image) { 380 this.image = image; 381 loadImage(image); 382 } 383 384 /** 385 * Gets the description of the image. This is meant to be a brief 386 * textual description of the object. For example, it might be 387 * presented to a blind user to give an indication of the purpose 388 * of the image. 389 * The description may be null. 390 * 391 * @return a brief textual description of the image 392 */ 393 public String getDescription() { 394 return description; 395 } 396 397 /** 398 * Sets the description of the image. This is meant to be a brief 399 * textual description of the object. For example, it might be 400 * presented to a blind user to give an indication of the purpose 401 * of the image. 402 * @param description a brief textual description of the image 403 */ 404 public void setDescription(String description) { 405 this.description = description; 406 } 407 408 /** 409 * Paints the icon. 410 * The top-left corner of the icon is drawn at 411 * the point (<code>x</code>, <code>y</code>) 412 * in the coordinate space of the graphics context <code>g</code>. 413 * If this icon has no image observer, 414 * this method uses the <code>c</code> component 415 * as the observer. 416 * 417 * @param c the component to be used as the observer 418 * if this icon has no image observer 419 * @param g the graphics context 420 * @param x the X coordinate of the icon's top-left corner 421 * @param y the Y coordinate of the icon's top-left corner 422 */ 423 public synchronized void paintIcon(Component c, Graphics g, int x, int y) { 424 if(imageObserver == null) { 425 g.drawImage(image, x, y, c); 426 } else { 427 g.drawImage(image, x, y, imageObserver); 428 } 429 } 430 431 /** 432 * Gets the width of the icon. 433 * 434 * @return the width in pixels of this icon 435 */ 436 public int getIconWidth() { 437 return width; 438 } 439 440 /** 441 * Gets the height of the icon. 442 * 443 * @return the height in pixels of this icon 444 */ 445 public int getIconHeight() { 446 return height; 447 } 448 449 /** 450 * Sets the image observer for the image. Set this 451 * property if the ImageIcon contains an animated GIF, so 452 * the observer is notified to update its display. 453 * For example: 454 * <pre> 455 * icon = new ImageIcon(...) 456 * button.setIcon(icon); 457 * icon.setImageObserver(button); 458 * </pre> 459 * 460 * @param observer the image observer 461 */ 462 public void setImageObserver(ImageObserver observer) { 463 imageObserver = observer; 464 } 465 466 /** 467 * Returns the image observer for the image. 468 * 469 * @return the image observer, which may be null 470 */ 471 @Transient 472 public ImageObserver getImageObserver() { 473 return imageObserver; 474 } 475 476 /** 477 * Returns a string representation of this image. 478 * 479 * @return a string representing this image 480 */ 481 public String toString() { 482 if (description != null) { 483 return description; 484 } 485 return super.toString(); 486 } 487 488 private void readObject(ObjectInputStream s) 489 throws ClassNotFoundException, IOException 490 { 491 ObjectInputStream.GetField f = s.readFields(); 492 493 imageObserver = (ImageObserver) f.get("imageObserver", null); 494 description = (String) f.get("description", null); 495 width = f.get("width", -1); 496 height = f.get("height", -1); 497 accessibleContext = (AccessibleImageIcon) f.get("accessibleContext", null); 498 499 int w = s.readInt(); 500 int h = s.readInt(); 501 int[] pixels = (int[])(s.readObject()); 502 503 if (pixels == null && (w != -1 || h != -1)) { 504 throw new IllegalStateException("Inconsistent width and height" 505 + " for null image [" + w + ", " + h + "]"); 506 } 507 508 if (pixels != null && (w < 0 || h < 0)) { 509 throw new IllegalStateException("Inconsistent width and height" 510 + " for image [" + w + ", " + h + "]"); 511 } 512 513 if (w != getIconWidth() || h != getIconHeight()) { 514 throw new IllegalStateException("Inconsistent width and height" 515 + " for image [" + w + ", " + h + "]"); 516 } 517 518 if (pixels != null) { 519 Toolkit tk = Toolkit.getDefaultToolkit(); 520 ColorModel cm = ColorModel.getRGBdefault(); 521 image = tk.createImage(new MemoryImageSource(w, h, cm, pixels, 0, w)); 522 loadImage(image); 523 } 524 } 525 526 527 private void writeObject(ObjectOutputStream s) 528 throws IOException 529 { 530 s.defaultWriteObject(); 531 532 int w = getIconWidth(); 533 int h = getIconHeight(); 534 int[] pixels = image != null? new int[w * h] : null; 535 536 if (image != null) { 537 try { 538 PixelGrabber pg = new PixelGrabber(image, 0, 0, w, h, pixels, 0, w); 539 pg.grabPixels(); 540 if ((pg.getStatus() & ImageObserver.ABORT) != 0) { 541 throw new IOException("failed to load image contents"); 542 } 543 } 544 catch (InterruptedException e) { 545 throw new IOException("image load interrupted"); 546 } 547 } 548 549 s.writeInt(w); 550 s.writeInt(h); 551 s.writeObject(pixels); 552 } 553 554 /** 555 * --- Accessibility Support --- 556 */ 557 558 private AccessibleImageIcon accessibleContext = null; 559 560 /** 561 * Gets the AccessibleContext associated with this ImageIcon. 562 * For image icons, the AccessibleContext takes the form of an 563 * AccessibleImageIcon. 564 * A new AccessibleImageIcon instance is created if necessary. 565 * 566 * @return an AccessibleImageIcon that serves as the 567 * AccessibleContext of this ImageIcon 568 * @since 1.3 569 */ 570 @BeanProperty(expert = true, description 571 = "The AccessibleContext associated with this ImageIcon.") 572 public AccessibleContext getAccessibleContext() { 573 if (accessibleContext == null) { 574 accessibleContext = new AccessibleImageIcon(); 575 } 576 return accessibleContext; 577 } 578 579 /** 580 * This class implements accessibility support for the 581 * <code>ImageIcon</code> class. It provides an implementation of the 582 * Java Accessibility API appropriate to image icon user-interface 583 * elements. 584 * <p> 585 * <strong>Warning:</strong> 586 * Serialized objects of this class will not be compatible with 587 * future Swing releases. The current serialization support is 588 * appropriate for short term storage or RMI between applications running 589 * the same version of Swing. As of 1.4, support for long term storage 590 * of all JavaBeans 591 * has been added to the <code>java.beans</code> package. 592 * Please see {@link java.beans.XMLEncoder}. 593 * @since 1.3 594 */ 595 @SuppressWarnings("serial") // Same-version serialization only 596 protected class AccessibleImageIcon extends AccessibleContext 597 implements AccessibleIcon, Serializable { 598 599 /* 600 * AccessibleContest implementation ----------------- 601 */ 602 603 /** 604 * Gets the role of this object. 605 * 606 * @return an instance of AccessibleRole describing the role of the 607 * object 608 * @see AccessibleRole 609 */ 610 public AccessibleRole getAccessibleRole() { 611 return AccessibleRole.ICON; 612 } 613 614 /** 615 * Gets the state of this object. 616 * 617 * @return an instance of AccessibleStateSet containing the current 618 * state set of the object 619 * @see AccessibleState 620 */ 621 public AccessibleStateSet getAccessibleStateSet() { 622 return null; 623 } 624 625 /** 626 * Gets the Accessible parent of this object. If the parent of this 627 * object implements Accessible, this method should simply return 628 * getParent(). 629 * 630 * @return the Accessible parent of this object -- can be null if this 631 * object does not have an Accessible parent 632 */ 633 public Accessible getAccessibleParent() { 634 return null; 635 } 636 637 /** 638 * Gets the index of this object in its accessible parent. 639 * 640 * @return the index of this object in its parent; -1 if this 641 * object does not have an accessible parent. 642 * @see #getAccessibleParent 643 */ 644 public int getAccessibleIndexInParent() { 645 return -1; 646 } 647 648 /** 649 * Returns the number of accessible children in the object. If all 650 * of the children of this object implement Accessible, than this 651 * method should return the number of children of this object. 652 * 653 * @return the number of accessible children in the object. 654 */ 655 public int getAccessibleChildrenCount() { 656 return 0; 657 } 658 659 /** 660 * Returns the nth Accessible child of the object. 661 * 662 * @param i zero-based index of child 663 * @return the nth Accessible child of the object 664 */ 665 public Accessible getAccessibleChild(int i) { 666 return null; 667 } 668 669 /** 670 * Returns the locale of this object. 671 * 672 * @return the locale of this object 673 */ 674 public Locale getLocale() throws IllegalComponentStateException { 675 return null; 676 } 677 678 /* 679 * AccessibleIcon implementation ----------------- 680 */ 681 682 /** 683 * Gets the description of the icon. This is meant to be a brief 684 * textual description of the object. For example, it might be 685 * presented to a blind user to give an indication of the purpose 686 * of the icon. 687 * 688 * @return the description of the icon 689 */ 690 public String getAccessibleIconDescription() { 691 return ImageIcon.this.getDescription(); 692 } 693 694 /** 695 * Sets the description of the icon. This is meant to be a brief 696 * textual description of the object. For example, it might be 697 * presented to a blind user to give an indication of the purpose 698 * of the icon. 699 * 700 * @param description the description of the icon 701 */ 702 public void setAccessibleIconDescription(String description) { 703 ImageIcon.this.setDescription(description); 704 } 705 706 /** 707 * Gets the height of the icon. 708 * 709 * @return the height of the icon 710 */ 711 public int getAccessibleIconHeight() { 712 return ImageIcon.this.height; 713 } 714 715 /** 716 * Gets the width of the icon. 717 * 718 * @return the width of the icon 719 */ 720 public int getAccessibleIconWidth() { 721 return ImageIcon.this.width; 722 } 723 724 private void readObject(ObjectInputStream s) 725 throws ClassNotFoundException, IOException 726 { 727 s.defaultReadObject(); 728 } 729 730 private void writeObject(ObjectOutputStream s) 731 throws IOException 732 { 733 s.defaultWriteObject(); 734 } 735 } // AccessibleImageIcon 736 }