View Javadoc
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</code> 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</code> implementations are required to call
43       * this method exactly once when beginning an image write
44       * operation.
45       *
46       * @param source the <code>ImageWriter</code> object calling this
47       * method.
48       * @param imageIndex the index of the image being written within
49       * its containing input file or stream.
50       */
51      void imageStarted(ImageWriter source, int imageIndex);
52  
53      /**
54       * Reports the approximate degree of completion of the current
55       * <code>write</code> call within the associated
56       * <code>ImageWriter</code>.
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</code> to <code>100.0F</code>
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</code> and <code>100</code>, as these may be inferred
70       * by the callee from other methods.
71       *
72       * <p> Each particular <code>ImageWriter</code> 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</code> object calling this method.
77       * @param percentageDone the approximate percentage of decoding that
78       * has been completed.
79       */
80      void imageProgress(ImageWriter source,
81                         float percentageDone);
82  
83      /**
84       * Reports that the image write operation has completed.  All
85       * <code>ImageWriter</code> 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</code> object calling this method.
90       */
91      void imageComplete(ImageWriter source);
92  
93      /**
94       * Reports that a thumbnail write operation is beginning.  All
95       * <code>ImageWriter</code> implementations are required to call
96       * this method exactly once when beginning a thumbnail write
97       * operation.
98       *
99       * @param source the <code>ImageWrite</code> 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      */
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</code>.
110      * The semantics are identical to those of
111      * <code>imageProgress</code>.
112      *
113      * @param source the <code>ImageWriter</code> object calling this
114      * method.
115      * @param percentageDone the approximate percentage of decoding that
116      * has been completed.
117      */
118     void thumbnailProgress(ImageWriter source, float percentageDone);
119 
120     /**
121      * Reports that a thumbnail write operation has completed.  All
122      * <code>ImageWriter</code> 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</code> object calling this
127      * method.
128      */
129     void thumbnailComplete(ImageWriter source);
130 
131     /**
132      * Reports that a write has been aborted via the writer's
133      * <code>abort</code> method.  No further notifications will be
134      * given.
135      *
136      * @param source the <code>ImageWriter</code> object calling this
137      * method.
138      */
139     void writeAborted(ImageWriter source);
140 }