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