1 /*
2 * Copyright 2000-2007 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.imageio.event;
27
28 import java.util.EventListener;
29 import javax.imageio.ImageReader;
30
31 /**
32 * An interface used by <code>ImageReader</code> implementations to
33 * notify callers of their image and thumbnail reading methods of
34 * progress.
35 *
36 * <p> This interface receives general indications of decoding
37 * progress (via the <code>imageProgress</code> and
38 * <code>thumbnailProgress</code> methods), and events indicating when
39 * an entire image has been updated (via the
40 * <code>imageStarted</code>, <code>imageComplete</code>,
41 * <code>thumbnailStarted</code> and <code>thumbnailComplete</code>
42 * methods). Applications that wish to be informed of pixel updates
43 * as they happen (for example, during progressive decoding), should
44 * provide an <code>IIOReadUpdateListener</code>.
45 *
46 * @see IIOReadUpdateListener
47 * @see javax.imageio.ImageReader#addIIOReadProgressListener
48 * @see javax.imageio.ImageReader#removeIIOReadProgressListener
49 *
50 */
51 public interface IIOReadProgressListener extends EventListener {
52
53 /**
54 * Reports that a sequence of read operations is beginning.
55 * <code>ImageReader</code> implementations are required to call
56 * this method exactly once from their
57 * <code>readAll(Iterator)</code> method.
58 *
59 * @param source the <code>ImageReader</code> object calling this method.
60 * @param minIndex the index of the first image to be read.
61 */
62 void sequenceStarted(ImageReader source, int minIndex);
63
64 /**
65 * Reports that a sequence of read operationshas completed.
66 * <code>ImageReader</code> implementations are required to call
67 * this method exactly once from their
68 * <code>readAll(Iterator)</code> method.
69 *
70 * @param source the <code>ImageReader</code> object calling this method.
71 */
72 void sequenceComplete(ImageReader source);
73
74 /**
75 * Reports that an image read operation is beginning. All
76 * <code>ImageReader</code> implementations are required to call
77 * this method exactly once when beginning an image read
78 * operation.
79 *
80 * @param source the <code>ImageReader</code> object calling this method.
81 * @param imageIndex the index of the image being read within its
82 * containing input file or stream.
83 */
84 void imageStarted(ImageReader source, int imageIndex);
85
86 /**
87 * Reports the approximate degree of completion of the current
88 * <code>read</code> call of the associated
89 * <code>ImageReader</code>.
90 *
91 * <p> The degree of completion is expressed as a percentage
92 * varying from <code>0.0F</code> to <code>100.0F</code>. The
93 * percentage should ideally be calculated in terms of the
94 * remaining time to completion, but it is usually more practical
95 * to use a more well-defined metric such as pixels decoded or
96 * portion of input stream consumed. In any case, a sequence of
97 * calls to this method during a given read operation should
98 * supply a monotonically increasing sequence of percentage
99 * values. It is not necessary to supply the exact values
100 * <code>0</code> and <code>100</code>, as these may be inferred
101 * by the callee from other methods.
102 *
103 * <p> Each particular <code>ImageReader</code> implementation may
104 * call this method at whatever frequency it desires. A rule of
105 * thumb is to call it around each 5 percent mark.
106 *
107 * @param source the <code>ImageReader</code> object calling this method.
108 * @param percentageDone the approximate percentage of decoding that
109 * has been completed.
110 */
111 void imageProgress(ImageReader source, float percentageDone);
112
113 /**
114 * Reports that the current image read operation has completed.
115 * All <code>ImageReader</code> implementations are required to
116 * call this method exactly once upon completion of each image
117 * read operation.
118 *
119 * @param source the <code>ImageReader</code> object calling this
120 * method.
121 */
122 void imageComplete(ImageReader source);
123
124 /**
125 * Reports that a thumbnail read operation is beginning. All
126 * <code>ImageReader</code> implementations are required to call
127 * this method exactly once when beginning a thumbnail read
128 * operation.
129 *
130 * @param source the <code>ImageReader</code> object calling this method.
131 * @param imageIndex the index of the image being read within its
132 * containing input file or stream.
133 * @param thumbnailIndex the index of the thumbnail being read.
134 */
135 void thumbnailStarted(ImageReader source,
136 int imageIndex, int thumbnailIndex);
137
138 /**
139 * Reports the approximate degree of completion of the current
140 * <code>getThumbnail</code> call within the associated
141 * <code>ImageReader</code>. The semantics are identical to those
142 * of <code>imageProgress</code>.
143 *
144 * @param source the <code>ImageReader</code> object calling this method.
145 * @param percentageDone the approximate percentage of decoding that
146 * has been completed.
147 */
148 void thumbnailProgress(ImageReader source, float percentageDone);
149
150 /**
151 * Reports that a thumbnail read operation has completed. All
152 * <code>ImageReader</code> implementations are required to call
153 * this method exactly once upon completion of each thumbnail read
154 * operation.
155 *
156 * @param source the <code>ImageReader</code> object calling this
157 * method.
158 */
159 void thumbnailComplete(ImageReader source);
160
161 /**
162 * Reports that a read has been aborted via the reader's
163 * <code>abort</code> method. No further notifications will be
164 * given.
165 *
166 * @param source the <code>ImageReader</code> object calling this
167 * method.
168 */
169 void readAborted(ImageReader source);
170 }
Save This Page