IIOReadProgressListener


1   /*
2    * @(#)IIOReadProgressListener.java 1.16 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.imageio.event;
9   
10  import java.util.EventListener  ;
11  import java.util.Locale  ;
12  import javax.imageio.ImageReader  ;
13  
14  /**
15   * An interface used by <code>ImageReader</code> implementations to
16   * notify callers of their image and thumbnail reading methods of
17   * progress.
18   *
19   * <p> This interface receives general indications of decoding
20   * progress (via the <code>imageProgress</code> and
21   * <code>thumbnailProgress</code> methods), and events indicating when
22   * an entire image has been updated (via the
23   * <code>imageStarted</code>, <code>imageComplete</code>,
24   * <code>thumbnailStarted</code> and <code>thumbnailComplete</code>
25   * methods).  Applications that wish to be informed of pixel updates
26   * as they happen (for example, during progressive decoding), should
27   * provide an <code>IIOReadUpdateListener</code>.
28   *
29   * @see IIOReadUpdateListener
30   * @see javax.imageio.ImageReader#addIIOReadProgressListener
31   * @see javax.imageio.ImageReader#removeIIOReadProgressListener
32   *
33   * @version 0.5
34   */
35  public interface IIOReadProgressListener extends EventListener   {
36  
37      /**
38       * Reports that a sequence of read operations is beginning.
39       * <code>ImageReader</code> implementations are required to call
40       * this method exactly once from their
41       * <code>readAll(Iterator)</code> method.
42       *
43       * @param source the <code>ImageReader</code> object calling this method.
44       * @param minIndex the index of the first image to be read.
45       */
46      void sequenceStarted(ImageReader   source, int minIndex);
47  
48      /**
49       * Reports that a sequence of read operationshas completed.
50       * <code>ImageReader</code> implementations are required to call
51       * this method exactly once from their
52       * <code>readAll(Iterator)</code> method.
53       *
54       * @param source the <code>ImageReader</code> object calling this method.
55       */
56      void sequenceComplete(ImageReader   source);
57  
58      /**
59       * Reports that an image read operation is beginning.  All
60       * <code>ImageReader</code> implementations are required to call
61       * this method exactly once when beginning an image read
62       * operation.
63       *
64       * @param source the <code>ImageReader</code> object calling this method.
65       * @param imageIndex the index of the image being read within its
66       * containing input file or stream.
67       */
68      void imageStarted(ImageReader   source, int imageIndex);
69  
70      /**
71       * Reports the approximate degree of completion of the current
72       * <code>read</code> call of the associated
73       * <code>ImageReader</code>.
74       *
75       * <p> The degree of completion is expressed as a percentage
76       * varying from <code>0.0F</code> to <code>100.0F</code>.  The
77       * percentage should ideally be calculated in terms of the
78       * remaining time to completion, but it is usually more practical
79       * to use a more well-defined metric such as pixels decoded or
80       * portion of input stream consumed.  In any case, a sequence of
81       * calls to this method during a given read operation should
82       * supply a monotonically increasing sequence of percentage
83       * values.  It is not necessary to supply the exact values
84       * <code>0</code> and <code>100</code>, as these may be inferred
85       * by the callee from other methods.
86       *
87       * <p> Each particular <code>ImageReader</code> implementation may
88       * call this method at whatever frequency it desires.  A rule of
89       * thumb is to call it around each 5 percent mark.
90       *
91       * @param source the <code>ImageReader</code> object calling this method.
92       * @param percentageDone the approximate percentage of decoding that
93       * has been completed.
94       */
95      void imageProgress(ImageReader   source, float percentageDone);
96  
97      /**
98       * Reports that the current image read operation has completed.
99       * All <code>ImageReader</code> implementations are required to
100      * call this method exactly once upon completion of each image
101      * read operation.
102      *
103      * @param source the <code>ImageReader</code> object calling this
104      * method.
105      */
106     void imageComplete(ImageReader   source);
107 
108     /**
109      * Reports that a thumbnail read operation is beginning.  All
110      * <code>ImageReader</code> implementations are required to call
111      * this method exactly once when beginning a thumbnail read
112      * operation.
113      *
114      * @param source the <code>ImageReader</code> object calling this method.
115      * @param imageIndex the index of the image being read within its
116      * containing input file or stream.
117      * @param thumbnailIndex the index of the thumbnail being read.
118      */
119     void thumbnailStarted(ImageReader   source,
120                           int imageIndex, int thumbnailIndex);
121 
122     /**
123      * Reports the approximate degree of completion of the current
124      * <code>getThumbnail</code> call within the associated
125      * <code>ImageReader</code>.  The semantics are identical to those
126      * of <code>imageProgress</code>.
127      *
128      * @param source the <code>ImageReader</code> object calling this method.
129      * @param percentageDone the approximate percentage of decoding that
130      * has been completed.
131      */
132     void thumbnailProgress(ImageReader   source, float percentageDone);
133 
134     /**
135      * Reports that a thumbnail read operation has completed.  All
136      * <code>ImageReader</code> implementations are required to call
137      * this method exactly once upon completion of each thumbnail read
138      * operation.
139      *
140      * @param source the <code>ImageReader</code> object calling this
141      * method.
142      */
143     void thumbnailComplete(ImageReader   source);
144 
145     /**
146      * Reports that a read has been aborted via the reader's
147      * <code>abort</code> method.  No further notifications will be
148      * given.
149      *
150      * @param source the <code>ImageReader</code> object calling this
151      * method.
152      */
153     void readAborted(ImageReader   source);
154 }
155
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags