1 /* 2 * Copyright (c) 2000, 2001, 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.ImageWriter; 30 31 /** 32 * An interface used by {@code ImageWriter} implementations to notify 33 * callers of their image writing methods of progress. 34 * 35 * @see javax.imageio.ImageWriter#write 36 * 37 */ 38 public interface IIOWriteProgressListener extends EventListener { 39 40 /** 41 * Reports that an image write operation is beginning. All 42 * {@code ImageWriter} implementations are required to call 43 * this method exactly once when beginning an image write 44 * operation. 45 * 46 * @param source the {@code ImageWriter} object calling this 47 * method. 48 * @param imageIndex the index of the image being written within 49 * its containing input file or stream. 50 */ imageStarted(ImageWriter source, int imageIndex)51 void imageStarted(ImageWriter source, int imageIndex); 52 53 /** 54 * Reports the approximate degree of completion of the current 55 * {@code write} call within the associated 56 * {@code ImageWriter}. 57 * 58 * <p> The degree of completion is expressed as an index 59 * indicating which image is being written, and a percentage 60 * varying from {@code 0.0F} to {@code 100.0F} 61 * indicating how much of the current image has been output. The 62 * percentage should ideally be calculated in terms of the 63 * remaining time to completion, but it is usually more practical 64 * to use a more well-defined metric such as pixels decoded or 65 * portion of input stream consumed. In any case, a sequence of 66 * calls to this method during a given read operation should 67 * supply a monotonically increasing sequence of percentage 68 * values. It is not necessary to supply the exact values 69 * {@code 0} and {@code 100}, as these may be inferred 70 * by the callee from other methods. 71 * 72 * <p> Each particular {@code ImageWriter} implementation may 73 * call this method at whatever frequency it desires. A rule of 74 * thumb is to call it around each 5 percent mark. 75 * 76 * @param source the {@code ImageWriter} object calling this method. 77 * @param percentageDone the approximate percentage of decoding that 78 * has been completed. 79 */ imageProgress(ImageWriter source, float percentageDone)80 void imageProgress(ImageWriter source, 81 float percentageDone); 82 83 /** 84 * Reports that the image write operation has completed. All 85 * {@code ImageWriter} implementations are required to call 86 * this method exactly once upon completion of each image write 87 * operation. 88 * 89 * @param source the {@code ImageWriter} object calling this method. 90 */ imageComplete(ImageWriter source)91 void imageComplete(ImageWriter source); 92 93 /** 94 * Reports that a thumbnail write operation is beginning. All 95 * {@code ImageWriter} implementations are required to call 96 * this method exactly once when beginning a thumbnail write 97 * operation. 98 * 99 * @param source the {@code ImageWrite} object calling this method. 100 * @param imageIndex the index of the image being written within its 101 * containing input file or stream. 102 * @param thumbnailIndex the index of the thumbnail being written. 103 */ thumbnailStarted(ImageWriter source, int imageIndex, int thumbnailIndex)104 void thumbnailStarted(ImageWriter source, 105 int imageIndex, int thumbnailIndex); 106 107 /** 108 * Reports the approximate degree of completion of the current 109 * thumbnail write within the associated {@code ImageWriter}. 110 * The semantics are identical to those of 111 * {@code imageProgress}. 112 * 113 * @param source the {@code ImageWriter} object calling this 114 * method. 115 * @param percentageDone the approximate percentage of decoding that 116 * has been completed. 117 */ thumbnailProgress(ImageWriter source, float percentageDone)118 void thumbnailProgress(ImageWriter source, float percentageDone); 119 120 /** 121 * Reports that a thumbnail write operation has completed. All 122 * {@code ImageWriter} implementations are required to call 123 * this method exactly once upon completion of each thumbnail 124 * write operation. 125 * 126 * @param source the {@code ImageWriter} object calling this 127 * method. 128 */ thumbnailComplete(ImageWriter source)129 void thumbnailComplete(ImageWriter source); 130 131 /** 132 * Reports that a write has been aborted via the writer's 133 * {@code abort} method. No further notifications will be 134 * given. 135 * 136 * @param source the {@code ImageWriter} object calling this 137 * method. 138 */ writeAborted(ImageWriter source)139 void writeAborted(ImageWriter source); 140 } 141