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
26package javax.imageio.event;
27
28import java.util.EventListener;
29import 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 */
38public 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     */
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     */
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     */
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     */
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     */
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     */
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     */
139    void writeAborted(ImageWriter source);
140}
141