ImageLoader


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.swt.graphics;
12  
13  
14  import java.io.*;
15  import java.util.Vector  ;
16  import org.eclipse.swt.*;
17  import org.eclipse.swt.internal.Compatibility;
18  import org.eclipse.swt.internal.image.*;
19  
20  /**
21   * Instances of this class are used to load images from,
22   * and save images to, a file or stream.
23   * <p>
24   * Currently supported image formats are:
25   * </p><ul>
26   * <li>BMP (Windows or OS/2 Bitmap)</li>
27   * <li>ICO (Windows Icon)</li>
28   * <li>JPEG</li>
29   * <li>GIF</li>
30   * <li>PNG</li>
31   * <li>TIFF</li>
32   * </ul>
33   * <code>ImageLoaders</code> can be used to:
34   * <ul>
35   * <li>load/save single images in all formats</li>
36   * <li>load/save multiple images (GIF/ICO/TIFF)</li>
37   * <li>load/save animated GIF images</li>
38   * <li>load interlaced GIF/PNG images</li>
39   * <li>load progressive JPEG images</li>
40   * </ul>
41   */
42   
43  public class ImageLoader {
44      
45      /**
46       * the array of ImageData objects in this ImageLoader.
47       * This array is read in when the load method is called,
48       * and it is written out when the save method is called
49       */
50      public ImageData[] data;
51      
52      /**
53       * the width of the logical screen on which the images
54       * reside, in pixels (this corresponds to the GIF89a
55       * Logical Screen Width value)
56       */
57      public int logicalScreenWidth;
58  
59      /**
60       * the height of the logical screen on which the images
61       * reside, in pixels (this corresponds to the GIF89a
62       * Logical Screen Height value)
63       */
64      public int logicalScreenHeight;
65  
66      /**
67       * the background pixel for the logical screen (this 
68       * corresponds to the GIF89a Background Color Index value).
69       * The default is -1 which means 'unspecified background'
70       * 
71       */
72      public int backgroundPixel;
73  
74      /**
75       * the number of times to repeat the display of a sequence
76       * of animated images (this corresponds to the commonly-used
77       * GIF application extension for "NETSCAPE 2.0 01").
78       * The default is 1. A value of 0 means 'display repeatedly'
79       */
80      public int repeatCount;
81          
82      /*
83       * the set of ImageLoader event listeners, created on demand
84       */
85      Vector   imageLoaderListeners;
86  
87  /**
88   * Construct a new empty ImageLoader.
89   */
90  public ImageLoader() {
91      reset();
92  }
93  
94  /**
95   * Resets the fields of the ImageLoader, except for the
96   * <code>imageLoaderListeners</code> field.
97   */
98  void reset() {
99      data = null;
100     logicalScreenWidth = 0;
101     logicalScreenHeight = 0;
102     backgroundPixel = -1;
103     repeatCount = 1;
104 }
105 
106 /**
107  * Loads an array of <code>ImageData</code> objects from the
108  * specified input stream. Throws an error if either an error
109  * occurs while loading the images, or if the images are not
110  * of a supported type. Returns the loaded image data array.
111  *
112  * @param stream the input stream to load the images from
113  * @return an array of <code>ImageData</code> objects loaded from the specified input stream
114  *
115  * @exception IllegalArgumentException <ul>
116  *    <li>ERROR_NULL_ARGUMENT - if the stream is null</li>
117  * </ul>
118  * @exception SWTException <ul>
119  *    <li>ERROR_IO - if an IO error occurs while reading from the stream</li>
120  *    <li>ERROR_INVALID_IMAGE - if the image stream contains invalid data</li>
121  *    <li>ERROR_UNSUPPORTED_FORMAT - if the image stream contains an unrecognized format</li>
122  * </ul>
123  */
124 public ImageData[] load(InputStream stream) {
125     if (stream == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
126     reset();
127     data = FileFormat.load(stream, this);
128     return data;
129 }
130 
131 /**
132  * Loads an array of <code>ImageData</code> objects from the
133  * file with the specified name. Throws an error if either
134  * an error occurs while loading the images, or if the images are
135  * not of a supported type. Returns the loaded image data array.
136  *
137  * @param filename the name of the file to load the images from
138  * @return an array of <code>ImageData</code> objects loaded from the specified file
139  *
140  * @exception IllegalArgumentException <ul>
141  *    <li>ERROR_NULL_ARGUMENT - if the file name is null</li>
142  * </ul>
143  * @exception SWTException <ul>
144  *    <li>ERROR_IO - if an IO error occurs while reading from the file</li>
145  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data</li>
146  *    <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li>
147  * </ul>
148  */
149 public ImageData[] load(String   filename) {
150     if (filename == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
151     InputStream stream = null;
152     try {
153         stream = Compatibility.newFileInputStream(filename);
154         return load(stream);
155     } catch (IOException e) {
156         SWT.error(SWT.ERROR_IO, e);
157     } finally {
158         try {
159             if (stream != null) stream.close();
160         } catch (IOException e) {
161             // Ignore error
162         }
163     }
164     return null;
165 }
166 
167 /**
168  * Saves the image data in this ImageLoader to the specified stream.
169  * The format parameter can have one of the following values:
170  * <dl>
171  * <dt><code>IMAGE_BMP</code></dt>
172  * <dd>Windows BMP file format, no compression</dd>
173  * <dt><code>IMAGE_BMP_RLE</code></dt>
174  * <dd>Windows BMP file format, RLE compression if appropriate</dd>
175  * <dt><code>IMAGE_GIF</code></dt>
176  * <dd>GIF file format</dd>
177  * <dt><code>IMAGE_ICO</code></dt>
178  * <dd>Windows ICO file format</dd>
179  * <dt><code>IMAGE_JPEG</code></dt>
180  * <dd>JPEG file format</dd>
181  * <dt><code>IMAGE_PNG</code></dt>
182  * <dd>PNG file format</dd>
183  * </dl>
184  *
185  * @param stream the output stream to write the images to
186  * @param format the format to write the images in
187  *
188  * @exception IllegalArgumentException <ul>
189  *    <li>ERROR_NULL_ARGUMENT - if the stream is null</li>
190  * </ul>
191  * @exception SWTException <ul>
192  *    <li>ERROR_IO - if an IO error occurs while writing to the stream</li>
193  *    <li>ERROR_INVALID_IMAGE - if the image data contains invalid data</li>
194  *    <li>ERROR_UNSUPPORTED_FORMAT - if the image data cannot be saved to the requested format</li>
195  * </ul>
196  */
197 public void save(OutputStream stream, int format) {
198     if (stream == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
199     FileFormat.save(stream, format, this);
200 }
201 
202 /**
203  * Saves the image data in this ImageLoader to a file with the specified name.
204  * The format parameter can have one of the following values:
205  * <dl>
206  * <dt><code>IMAGE_BMP</code></dt>
207  * <dd>Windows BMP file format, no compression</dd>
208  * <dt><code>IMAGE_BMP_RLE</code></dt>
209  * <dd>Windows BMP file format, RLE compression if appropriate</dd>
210  * <dt><code>IMAGE_GIF</code></dt>
211  * <dd>GIF file format</dd>
212  * <dt><code>IMAGE_ICO</code></dt>
213  * <dd>Windows ICO file format</dd>
214  * <dt><code>IMAGE_JPEG</code></dt>
215  * <dd>JPEG file format</dd>
216  * <dt><code>IMAGE_PNG</code></dt>
217  * <dd>PNG file format</dd>
218  * </dl>
219  *
220  * @param filename the name of the file to write the images to
221  * @param format the format to write the images in
222  *
223  * @exception IllegalArgumentException <ul>
224  *    <li>ERROR_NULL_ARGUMENT - if the file name is null</li>
225  * </ul>
226  * @exception SWTException <ul>
227  *    <li>ERROR_IO - if an IO error occurs while writing to the file</li>
228  *    <li>ERROR_INVALID_IMAGE - if the image data contains invalid data</li>
229  *    <li>ERROR_UNSUPPORTED_FORMAT - if the image data cannot be saved to the requested format</li>
230  * </ul>
231  */
232 public void save(String   filename, int format) {
233     if (filename == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
234     OutputStream stream = null;
235     try {
236         stream = Compatibility.newFileOutputStream(filename);
237     } catch (IOException e) {
238         SWT.error(SWT.ERROR_IO, e);
239     }
240     save(stream, format);
241     try {
242         stream.close();
243     } catch (IOException e) {
244     }
245 }
246 
247 /**  
248  * Adds the listener to the collection of listeners who will be
249  * notified when image data is either partially or completely loaded.
250  * <p>
251  * An ImageLoaderListener should be added before invoking
252  * one of the receiver's load methods. The listener's 
253  * <code>imageDataLoaded</code> method is called when image
254  * data has been partially loaded, as is supported by interlaced
255  * GIF/PNG or progressive JPEG images.
256  *
257  * @param listener the listener which should be notified
258  * 
259  * @exception IllegalArgumentException <ul>
260  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
261  * </ul>
262  * 
263  * @see ImageLoaderListener
264  * @see ImageLoaderEvent
265  */
266 public void addImageLoaderListener(ImageLoaderListener listener) {
267     if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
268     if (imageLoaderListeners == null) {
269         imageLoaderListeners = new Vector  ();
270     }
271     imageLoaderListeners.addElement(listener);
272 }
273 
274 /**  
275  * Removes the listener from the collection of listeners who will be
276  * notified when image data is either partially or completely loaded.
277  *
278  * @param listener the listener which should no longer be notified
279  * 
280  * @exception IllegalArgumentException <ul>
281  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
282  * </ul>
283  * 
284  * @see #addImageLoaderListener(ImageLoaderListener)
285  */
286 public void removeImageLoaderListener(ImageLoaderListener listener) {
287     if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
288     if (imageLoaderListeners == null) return;
289     imageLoaderListeners.removeElement(listener);
290 }
291 
292 /**  
293  * Returns <code>true</code> if the receiver has image loader
294  * listeners, and <code>false</code> otherwise.
295  *
296  * @return <code>true</code> if there are <code>ImageLoaderListener</code>s, and <code>false</code> otherwise
297  *
298  * @see #addImageLoaderListener(ImageLoaderListener)
299  * @see #removeImageLoaderListener(ImageLoaderListener)
300  */
301 public boolean hasListeners() {
302     return imageLoaderListeners != null && imageLoaderListeners.size() > 0;
303 }
304 
305 /**  
306  * Notifies all image loader listeners that an image loader event
307  * has occurred. Pass the specified event object to each listener.
308  *
309  * @param event the <code>ImageLoaderEvent</code> to send to each <code>ImageLoaderListener</code>
310  */
311 public void notifyListeners(ImageLoaderEvent event) {
312     if (!hasListeners()) return;
313     int size = imageLoaderListeners.size();
314     for (int i = 0; i < size; i++) {
315         ImageLoaderListener listener = (ImageLoaderListener) imageLoaderListeners.elementAt(i);
316         listener.imageDataLoaded(event);
317     }
318 }
319 
320 }
321
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags