CONTENTS | PREV | NEXT |
As an image is being read or written, the plug-in may provide updates to the application. The application may provide one or more classes that implement interfaces from theAs thejavax.image.event
package. Instances of these classes are then added to theImageReader
orImageWriter
being used. For example, class MyReadProgressListener implements IIOReadProgressListener { public MyReadProgressListener() {} public void imageStarted(ImageReader source) { System.out.println("Started reading!"); } // Other methods from IIOReadProgressListener omitted } IIOReadProgressListener listener = new MyReadProgressListener(); reader.addIIOReadProgressListener(listener);
ImageReader.read
method progresses, methods on listener
will be called
at various times to indicate how much of the image has been read.
Because these methods are being called while
ImageReader.read
is active, they must not call most
methods from the same ImageReader
object. They may
call ImageReader.abort()
, which will cause
ImageReader.read
to return even if it is only
partially complete.IIOReadProgressListener
InterfaceIIOReadProgressListener
may be used to provide simple
status information during reading. An estimate of the percentage of
completion of a read is provided, which may be used to update a
Swing JProgressBar
or other progress indicator, or to
estimate the time remaining to read a large image.
The imageStarted
method will be called at the start of the read. During the read,
the imageProgress
method will be called multiple
times, each time with a different, increasing value for its
percentageDone
parameter. When the read is about to
complete, the imageComplete
method will be called.
Similarly, the
thumbnailStarted
, thumbnailProgress
, and
thumbnailComplete
methods will be called during
thumbnail reads.
Other methods exist to indicate
the start and end of a sequence of image reads performed by the
ImageReader.readAll
method. Additionally, it is
possible for an ongoing read to be aborted using the
ImageReader.abort
method; in this case, the
listener's readAborted
method will be called.
IIOReadUpdateListener
InterfaceIIOReadUpdateListener
provides more detailed information on the progress of an image
read. Some image formats allow interlaced or progressive encoding,
in which a subset of the pixel data is made available quickly, so
that a crude version of the image may be displayed while the
remainder of the pixel data is still being received and decoded. A
typical scheme might begin by sending only every fourth row, and
only every fourth pixel in each of those rows, so that the initial
image requires only one sixteenth of the total amount of data to be
transmitted and decoded. If interlacing were not used, only the top
one-sixteenth of the image would be displayed in the same amount of
time. Thus, a person viewing an interlaced image will be able to
get a sense of its contents much sooner than if a traditional
left-to-right, top-to-bottom order were used.
By implementing the methods of the
IIOReadUpdateListener
interface, an application class
can receive notification when groups of possibly non-contiguous
pixels are ready to be displayed. These methods also receive a
reference to the BufferedImage
that is in the process
of being filled in, which may be used to refresh the display to
include the newly decoded pixels.
When decoding an interlaced or
progressive image, the decoding proceeds in multiple passes. At the
start of each pass, the listener's passStarted
method will be called to indicate the set of pixels that may be
overwritten during the following pass. This estimate is
conservative; not every pixel in the region will necessarily be
updated during the pass. As the pass progresses, the
imageUpdate
method will be called with arguments
describing the region of pixels that have receive new values. This
region is described by the coordinates of its upper-left corner,
its width and height, and the spacing between the pixels that make
up the pass (in the example above, both parameters would be equal
to 4 for the initial pass). When a pass has completed, the
passComplete
method is called. Similar methods allow
the progress of thumbnail image reads to be tracked.
IIOReadWarningListener
InterfaceIIOReadWarningListener
to an ImageReader
,
information on non-fatal errors may be received. For example, a
reader might detect a tag or chunk that should not be present. Even
though the reader may choose to ignore the error and proceed with
decoding, it may wish to inform the application that the input
source was malformed, as this could indicate problems in the
application that generated the images.
ImageReader
s may
specify a set of Locale
s for which they can provide
localized warning messages. The set of available locales can be
obtained from the reader's getAvailableLocales
method. The desired locale should then be set by calling the
reader's setLocale
method prior to attaching the
IIOReadWarningListener
. Each listener will receive
messages in the Locale
that was in effect at the time
it was attached to the reader.
IIOWriteProgressListener
and
IIOWriteWarningListener
InterfacesIIOWriteProgressListener
and
IIOWriteWarningListener
interfaces function similarly
to their reader counterparts.