1 /*
2 * Copyright (c) 1997, 2013, 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.Transient;
31 import java.net.URL;
32
33 import java.io.Serializable;
34 import java.io.ObjectOutputStream;
35 import java.io.ObjectInputStream;
36 import java.io.IOException;
37
38 import java.util.Locale;
39 import javax.accessibility.*;
40
41 import sun.awt.AppContext;
42 import java.lang.reflect.Field;
43 import java.security.*;
44
45 /**
46 * An implementation of the Icon interface that paints Icons
47 * from Images. Images that are created from a URL, filename or byte array
48 * are preloaded using MediaTracker to monitor the loaded state
49 * of the image.
50 *
51 * <p>
52 * For further information and examples of using image icons, see
53 * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/icon.html">How to Use Icons</a>
54 * in <em>The Java Tutorial.</em>
55 *
56 * <p>
57 * <strong>Warning:</strong>
58 * Serialized objects of this class will not be compatible with
59 * future Swing releases. The current serialization support is
60 * appropriate for short term storage or RMI between applications running
61 * the same version of Swing. As of 1.4, support for long term storage
62 * of all JavaBeans™
63 * has been added to the <code>java.beans</code> package.
64 * Please see {@link java.beans.XMLEncoder}.
65 *
66 * @author Jeff Dinkins
67 * @author Lynn Monsanto
68 */
69 public class ImageIcon implements Icon, Serializable, Accessible {
70 /* Keep references to the filename and location so that
71 * alternate persistence schemes have the option to archive
72 * images symbolically rather than including the image data
73 * in the archive.
74 */
75 transient private String filename;
76 transient private URL location;
77
78 transient Image image;
79 transient int loadStatus = 0;
80 ImageObserver imageObserver;
81 String description = null;
82
83 /**
84 * Do not use this shared component, which is used to track image loading.
85 * It is left for backward compatibility only.
86 * @deprecated since 1.8
87 */
88 @Deprecated
89 protected final static Component component;
90
91 /**
92 * Do not use this shared media tracker, which is used to load images.
93 * It is left for backward compatibility only.
94 * @deprecated since 1.8
95 */
96 @Deprecated
97 protected final static MediaTracker tracker;
98
99 static {
100 component = AccessController.doPrivileged(new PrivilegedAction<Component>() {
101 public Component run() {
102 try {
103 final Component component = createNoPermsComponent();
104
105 // 6482575 - clear the appContext field so as not to leak it
106 Field appContextField =
107
108 Component.class.getDeclaredField("appContext");
109 appContextField.setAccessible(true);
110 appContextField.set(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 final static 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 s.defaultReadObject();
492
493 int w = s.readInt();
494 int h = s.readInt();
495 int[] pixels = (int[])(s.readObject());
496
497 if (pixels != null) {
498 Toolkit tk = Toolkit.getDefaultToolkit();
499 ColorModel cm = ColorModel.getRGBdefault();
500 image = tk.createImage(new MemoryImageSource(w, h, cm, pixels, 0, w));
501 loadImage(image);
502 }
503 }
504
505
506 private void writeObject(ObjectOutputStream s)
507 throws IOException
508 {
509 s.defaultWriteObject();
510
511 int w = getIconWidth();
512 int h = getIconHeight();
513 int[] pixels = image != null? new int[w * h] : null;
514
515 if (image != null) {
516 try {
517 PixelGrabber pg = new PixelGrabber(image, 0, 0, w, h, pixels, 0, w);
518 pg.grabPixels();
519 if ((pg.getStatus() & ImageObserver.ABORT) != 0) {
520 throw new IOException("failed to load image contents");
521 }
522 }
523 catch (InterruptedException e) {
524 throw new IOException("image load interrupted");
525 }
526 }
527
528 s.writeInt(w);
529 s.writeInt(h);
530 s.writeObject(pixels);
531 }
532
533 /**
534 * --- Accessibility Support ---
535 */
536
537 private AccessibleImageIcon accessibleContext = null;
538
539 /**
540 * Gets the AccessibleContext associated with this ImageIcon.
541 * For image icons, the AccessibleContext takes the form of an
542 * AccessibleImageIcon.
543 * A new AccessibleImageIcon instance is created if necessary.
544 *
545 * @return an AccessibleImageIcon that serves as the
546 * AccessibleContext of this ImageIcon
547 * @beaninfo
548 * expert: true
549 * description: The AccessibleContext associated with this ImageIcon.
550 * @since 1.3
551 */
552 public AccessibleContext getAccessibleContext() {
553 if (accessibleContext == null) {
554 accessibleContext = new AccessibleImageIcon();
555 }
556 return accessibleContext;
557 }
558
559 /**
560 * This class implements accessibility support for the
561 * <code>ImageIcon</code> class. It provides an implementation of the
562 * Java Accessibility API appropriate to image icon user-interface
563 * elements.
564 * <p>
565 * <strong>Warning:</strong>
566 * Serialized objects of this class will not be compatible with
567 * future Swing releases. The current serialization support is
568 * appropriate for short term storage or RMI between applications running
569 * the same version of Swing. As of 1.4, support for long term storage
570 * of all JavaBeans™
571 * has been added to the <code>java.beans</code> package.
572 * Please see {@link java.beans.XMLEncoder}.
573 * @since 1.3
574 */
575 protected class AccessibleImageIcon extends AccessibleContext
576 implements AccessibleIcon, Serializable {
577
578 /*
579 * AccessibleContest implementation -----------------
580 */
581
582 /**
583 * Gets the role of this object.
584 *
585 * @return an instance of AccessibleRole describing the role of the
586 * object
587 * @see AccessibleRole
588 */
589 public AccessibleRole getAccessibleRole() {
590 return AccessibleRole.ICON;
591 }
592
593 /**
594 * Gets the state of this object.
595 *
596 * @return an instance of AccessibleStateSet containing the current
597 * state set of the object
598 * @see AccessibleState
599 */
600 public AccessibleStateSet getAccessibleStateSet() {
601 return null;
602 }
603
604 /**
605 * Gets the Accessible parent of this object. If the parent of this
606 * object implements Accessible, this method should simply return
607 * getParent().
608 *
609 * @return the Accessible parent of this object -- can be null if this
610 * object does not have an Accessible parent
611 */
612 public Accessible getAccessibleParent() {
613 return null;
614 }
615
616 /**
617 * Gets the index of this object in its accessible parent.
618 *
619 * @return the index of this object in its parent; -1 if this
620 * object does not have an accessible parent.
621 * @see #getAccessibleParent
622 */
623 public int getAccessibleIndexInParent() {
624 return -1;
625 }
626
627 /**
628 * Returns the number of accessible children in the object. If all
629 * of the children of this object implement Accessible, than this
630 * method should return the number of children of this object.
631 *
632 * @return the number of accessible children in the object.
633 */
634 public int getAccessibleChildrenCount() {
635 return 0;
636 }
637
638 /**
639 * Returns the nth Accessible child of the object.
640 *
641 * @param i zero-based index of child
642 * @return the nth Accessible child of the object
643 */
644 public Accessible getAccessibleChild(int i) {
645 return null;
646 }
647
648 /**
649 * Returns the locale of this object.
650 *
651 * @return the locale of this object
652 */
653 public Locale getLocale() throws IllegalComponentStateException {
654 return null;
655 }
656
657 /*
658 * AccessibleIcon implementation -----------------
659 */
660
661 /**
662 * Gets the description of the icon. This is meant to be a brief
663 * textual description of the object. For example, it might be
664 * presented to a blind user to give an indication of the purpose
665 * of the icon.
666 *
667 * @return the description of the icon
668 */
669 public String getAccessibleIconDescription() {
670 return ImageIcon.this.getDescription();
671 }
672
673 /**
674 * Sets the description of the icon. This is meant to be a brief
675 * textual description of the object. For example, it might be
676 * presented to a blind user to give an indication of the purpose
677 * of the icon.
678 *
679 * @param description the description of the icon
680 */
681 public void setAccessibleIconDescription(String description) {
682 ImageIcon.this.setDescription(description);
683 }
684
685 /**
686 * Gets the height of the icon.
687 *
688 * @return the height of the icon
689 */
690 public int getAccessibleIconHeight() {
691 return ImageIcon.this.height;
692 }
693
694 /**
695 * Gets the width of the icon.
696 *
697 * @return the width of the icon
698 */
699 public int getAccessibleIconWidth() {
700 return ImageIcon.this.width;
701 }
702
703 private void readObject(ObjectInputStream s)
704 throws ClassNotFoundException, IOException
705 {
706 s.defaultReadObject();
707 }
708
709 private void writeObject(ObjectOutputStream s)
710 throws IOException
711 {
712 s.defaultWriteObject();
713 }
714 } // AccessibleImageIcon
715 }