1 /* 2 * Copyright (c) 2000, 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 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} 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} and 38 * {@code thumbnailProgress} methods), and events indicating when 39 * an entire image has been updated (via the 40 * {@code imageStarted}, {@code imageComplete}, 41 * {@code thumbnailStarted} and {@code thumbnailComplete} 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}. 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} implementations are required to call 56 * this method exactly once from their 57 * {@code readAll(Iterator)} method. 58 * 59 * @param source the {@code ImageReader} object calling this method. 60 * @param minIndex the index of the first image to be read. 61 */ sequenceStarted(ImageReader source, int minIndex)62 void sequenceStarted(ImageReader source, int minIndex); 63 64 /** 65 * Reports that a sequence of read operations has completed. 66 * {@code ImageReader} implementations are required to call 67 * this method exactly once from their 68 * {@code readAll(Iterator)} method. 69 * 70 * @param source the {@code ImageReader} object calling this method. 71 */ sequenceComplete(ImageReader source)72 void sequenceComplete(ImageReader source); 73 74 /** 75 * Reports that an image read operation is beginning. All 76 * {@code ImageReader} implementations are required to call 77 * this method exactly once when beginning an image read 78 * operation. 79 * 80 * @param source the {@code ImageReader} object calling this method. 81 * @param imageIndex the index of the image being read within its 82 * containing input file or stream. 83 */ imageStarted(ImageReader source, int imageIndex)84 void imageStarted(ImageReader source, int imageIndex); 85 86 /** 87 * Reports the approximate degree of completion of the current 88 * {@code read} call of the associated 89 * {@code ImageReader}. 90 * 91 * <p> The degree of completion is expressed as a percentage 92 * varying from {@code 0.0F} to {@code 100.0F}. 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} and {@code 100}, as these may be inferred 101 * by the callee from other methods. 102 * 103 * <p> Each particular {@code ImageReader} 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} object calling this method. 108 * @param percentageDone the approximate percentage of decoding that 109 * has been completed. 110 */ imageProgress(ImageReader source, float percentageDone)111 void imageProgress(ImageReader source, float percentageDone); 112 113 /** 114 * Reports that the current image read operation has completed. 115 * All {@code ImageReader} 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} object calling this 120 * method. 121 */ imageComplete(ImageReader source)122 void imageComplete(ImageReader source); 123 124 /** 125 * Reports that a thumbnail read operation is beginning. All 126 * {@code ImageReader} implementations are required to call 127 * this method exactly once when beginning a thumbnail read 128 * operation. 129 * 130 * @param source the {@code ImageReader} 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 */ thumbnailStarted(ImageReader source, int imageIndex, int thumbnailIndex)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} call within the associated 141 * {@code ImageReader}. The semantics are identical to those 142 * of {@code imageProgress}. 143 * 144 * @param source the {@code ImageReader} object calling this method. 145 * @param percentageDone the approximate percentage of decoding that 146 * has been completed. 147 */ thumbnailProgress(ImageReader source, float percentageDone)148 void thumbnailProgress(ImageReader source, float percentageDone); 149 150 /** 151 * Reports that a thumbnail read operation has completed. All 152 * {@code ImageReader} 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} object calling this 157 * method. 158 */ thumbnailComplete(ImageReader source)159 void thumbnailComplete(ImageReader source); 160 161 /** 162 * Reports that a read has been aborted via the reader's 163 * {@code abort} method. No further notifications will be 164 * given. 165 * 166 * @param source the {@code ImageReader} object calling this 167 * method. 168 */ readAborted(ImageReader source)169 void readAborted(ImageReader source); 170 } 171