ImageDescriptor


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jface.resource;
12  
13  import java.net.URL  ;
14  
15  import org.eclipse.swt.SWTException;
16  import org.eclipse.swt.graphics.Device;
17  import org.eclipse.swt.graphics.Image;
18  import org.eclipse.swt.graphics.ImageData;
19  import org.eclipse.swt.graphics.PaletteData;
20  import org.eclipse.swt.graphics.RGB;
21  import org.eclipse.swt.widgets.Display;
22  
23  /**
24   * An image descriptor is an object that knows how to create
25   * an SWT image.  It does not hold onto images or cache them,
26   * but rather just creates them on demand.  An image descriptor
27   * is intended to be a lightweight representation of an image
28   * that can be manipulated even when no SWT display exists.
29   * <p>
30   * This package defines a concrete image descriptor implementation
31   * which reads an image from a file (<code>FileImageDescriptor</code>).
32   * It also provides abstract framework classes (this one and
33   * <code>CompositeImageDescriptor</code>) which may be subclassed to define
34   * news kinds of image descriptors.
35   * </p>
36   * <p>
37   * Using this abstract class involves defining a concrete subclass
38   * and providing an implementation for the <code>getImageData</code>
39   * method.
40   * </p>
41   * <p>
42   * There are two ways to get an Image from an ImageDescriptor. The method
43   * createImage will always return a new Image which must be disposed by
44   * the caller. Alternatively, createResource() returns a shared
45   * Image. When the caller is done with an image obtained from createResource,
46   * they must call destroyResource() rather than disposing the Image directly.
47   * The result of createResource() can be safely cast to an Image. 
48   * </p>
49   *
50   * @see org.eclipse.swt.graphics.Image
51   */
52  public abstract class ImageDescriptor extends DeviceResourceDescriptor {
53  
54      /** 
55       * A small red square used to warn that an image cannot be created.
56       * <p>
57       */
58      protected static final ImageData DEFAULT_IMAGE_DATA = new ImageData(6, 6,
59              1, new PaletteData(new RGB[] { new RGB(255, 0, 0) }));
60  
61      /**
62       * Constructs an image descriptor.
63       */
64      protected ImageDescriptor() {
65          // do nothing
66      }
67  
68      /**
69       * Creates and returns a new image descriptor from a file.
70       * Convenience method for
71       * <code>new FileImageDescriptor(location,filename)</code>.
72       *
73       * @param location the class whose resource directory contain the file
74       * @param filename the file name
75       * @return a new image descriptor
76       */
77      public static ImageDescriptor createFromFile(Class   location, String   filename) {
78          return new FileImageDescriptor(location, filename);
79      }
80      
81      /**
82       * Creates and returns a new image descriptor given ImageData
83       * describing the image.
84       * 
85       * @since 3.1 
86       *
87       * @param data contents of the image
88       * @return newly created image descriptor
89       */
90      public static ImageDescriptor createFromImageData(ImageData data) {
91          return new ImageDataImageDescriptor(data);
92      }
93      
94      /**
95       * Creates and returns a new image descriptor for the given image. Note 
96       * that disposing the original Image will cause the descriptor to become invalid.
97       * 
98       * @since 3.1 
99       *
100      * @param img image to create
101      * @return a newly created image descriptor
102      */
103     public static ImageDescriptor createFromImage(Image img) {
104         return new ImageDataImageDescriptor(img);
105     }
106     
107     /**
108      * Creates an ImageDescriptor based on the given original descriptor, but with additional
109      * SWT flags.
110      *  
111      * <p>
112      * Note that this sort of ImageDescriptor is slower and consumes more resources than
113      * a regular image descriptor. It will also never generate results that look as nice as
114      * a hand-drawn image. Clients are encouraged to supply their own disabled/grayed/etc. images
115      * rather than using a default image and transforming it.
116      * </p>
117      * 
118      * @param originalImage image to transform
119      * @param swtFlags any flag that can be passed to the flags argument of Image#Image(Device, Image, int)
120      * @return an ImageDescriptor that creates new images by transforming the given image descriptor
121      * 
122      * @see Image#Image(Device, Image, int) 
123      * @since 3.1 
124      *
125      */
126     public static ImageDescriptor createWithFlags(ImageDescriptor originalImage, int swtFlags) {
127         return new DerivedImageDescriptor(originalImage, swtFlags);
128     }
129 
130     /**
131      * Creates and returns a new image descriptor for the given image. This
132      * method takes the Device that created the Image as an argument, allowing
133      * the original Image to be reused if the descriptor is asked for another
134      * Image on the same device. Note that disposing the original Image will 
135      * cause the descriptor to become invalid.
136      * 
137      * @deprecated use {@link ImageDescriptor#createFromImage(Image)}
138      * @since 3.1 
139      *
140      * @param img image to create
141      * @param theDevice the device that was used to create the Image
142      * @return a newly created image descriptor
143      */
144     public static ImageDescriptor createFromImage(Image img, Device theDevice) {
145         return new ImageDataImageDescriptor(img);
146     }
147     
148     /**
149      * Creates and returns a new image descriptor from a URL.
150      *
151      * @param url The URL of the image file.
152      * @return a new image descriptor
153      */
154     public static ImageDescriptor createFromURL(URL   url) {
155         if (url == null) {
156             return getMissingImageDescriptor();
157         }
158         return new URLImageDescriptor(url);
159     }
160 
161     /* (non-Javadoc)
162      * @see org.eclipse.jface.resource.DeviceResourceDescriptor#createResource(org.eclipse.swt.graphics.Device)
163      */
164     public Object   createResource(Device device) throws DeviceResourceException {
165         Image result = createImage(false, device);
166         if (result == null) {
167             throw new DeviceResourceException(this);
168         }
169         return result;
170     }
171     
172     /* (non-Javadoc)
173      * @see org.eclipse.jface.resource.DeviceResourceDescriptor#destroyResource(Object)
174      */
175     public void destroyResource(Object   previouslyCreatedObject) {
176         ((Image)previouslyCreatedObject).dispose();
177     }
178     
179     /**
180      * Creates and returns a new SWT image for this image descriptor. Note that
181      * each call returns a new SWT image object. The returned image must be
182      * explicitly disposed using the image's dispose call. The image will not be
183      * automatically garbage collected. A default image is returned in the event
184      * of an error.
185      * 
186      * <p>
187      * Note: this method differs from createResource(Device) in that the returned image
188      * must be disposed directly, whereas an image obtained from createResource(...)
189      * must be disposed by calling destroyResource(...). It is not possible to 
190      * mix-and-match. If you obtained the Image from this method, you must not dispose
191      * it by calling destroyResource. Clients are encouraged to use 
192      * create/destroyResource and downcast the result to Image rather than using 
193      * createImage.
194      * </p>
195      * 
196      * <p>
197      * Note: it is still possible for this method to return <code>null</code>
198      * in extreme cases, for example if SWT runs out of image handles.
199      * </p>
200      * 
201      * @return a new image or <code>null</code> if the image could not be
202      *         created
203      */
204     public Image createImage() {
205         return createImage(true);
206     }
207 
208     /**
209      * Creates and returns a new SWT image for this image descriptor. The
210      * returned image must be explicitly disposed using the image's dispose
211      * call. The image will not be automatically garbage collected. In the event
212      * of an error, a default image is returned if
213      * <code>returnMissingImageOnError</code> is true, otherwise
214      * <code>null</code> is returned.
215      * <p>
216      * Note: Even if <code>returnMissingImageOnError</code> is true, it is
217      * still possible for this method to return <code>null</code> in extreme
218      * cases, for example if SWT runs out of image handles.
219      * </p>
220      * 
221      * @param returnMissingImageOnError
222      *            flag that determines if a default image is returned on error
223      * @return a new image or <code>null</code> if the image could not be
224      *         created
225      */
226     public Image createImage(boolean returnMissingImageOnError) {
227         return createImage(returnMissingImageOnError, Display.getCurrent());
228     }
229 
230     /**
231      * Creates and returns a new SWT image for this image descriptor. The
232      * returned image must be explicitly disposed using the image's dispose
233      * call. The image will not be automatically garbage collected. A default
234      * image is returned in the event of an error.
235      * <p>
236      * Note: it is still possible for this method to return <code>null</code>
237      * in extreme cases, for example if SWT runs out of image handles.
238      * </p>
239      * 
240      * @param device
241      *            the device on which to create the image
242      * @return a new image or <code>null</code> if the image could not be
243      *         created
244      * @since 2.0
245      */
246     public Image createImage(Device device) {
247         return createImage(true, device);
248     }
249 
250     /**
251      * Creates and returns a new SWT image for this image descriptor. The
252      * returned image must be explicitly disposed using the image's dispose
253      * call. The image will not be automatically garbage collected. In the even
254      * of an error, a default image is returned if
255      * <code>returnMissingImageOnError</code> is true, otherwise
256      * <code>null</code> is returned.
257      * <p>
258      * Note: Even if <code>returnMissingImageOnError</code> is true, it is
259      * still possible for this method to return <code>null</code> in extreme
260      * cases, for example if SWT runs out of image handles.
261      * </p>
262      * 
263      * @param returnMissingImageOnError
264      *            flag that determines if a default image is returned on error
265      * @param device
266      *            the device on which to create the image
267      * @return a new image or <code>null</code> if the image could not be
268      *         created
269      * @since 2.0
270      */
271     public Image createImage(boolean returnMissingImageOnError, Device device) {
272 
273         ImageData data = getImageData();
274         if (data == null) {
275             if (!returnMissingImageOnError) {
276                 return null;
277             }
278             data = DEFAULT_IMAGE_DATA;
279         }
280 
281         /*
282          * Try to create the supplied image. If there is an SWT Exception try and create
283          * the default image if that was requested. Return null if this fails.
284          */
285 
286         try {
287             if (data.transparentPixel >= 0) {
288                 ImageData maskData = data.getTransparencyMask();
289                 return new Image(device, data, maskData);
290             }
291             return new Image(device, data);
292         } catch (SWTException exception) {
293             if (returnMissingImageOnError) {
294                 try {
295                     return new Image(device, DEFAULT_IMAGE_DATA);
296                 } catch (SWTException nextException) {
297                     return null;
298                 }
299             }
300             return null;
301         }
302     }
303 
304     /**
305      * Creates and returns a new SWT <code>ImageData</code> object
306      * for this image descriptor.
307      * Note that each call returns a new SWT image data object.
308      * <p>
309      * This framework method is declared public so that it is
310      * possible to request an image descriptor's image data without
311      * creating an SWT image object.
312      * </p>
313      * <p>
314      * Returns <code>null</code> if the image data could not be created.
315      * </p>
316      *
317      * @return a new image data or <code>null</code>
318      */
319     public abstract ImageData getImageData();
320 
321     /**
322      * Returns the shared image descriptor for a missing image.
323      *
324      * @return the missing image descriptor
325      */
326     public static ImageDescriptor getMissingImageDescriptor() {
327         return MissingImageDescriptor.getInstance();
328     }
329 }
330
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags