CONTENTS | PREV | NEXT | JavaTM Image I/O API Guide |
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 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);
As theImageReader.read
method progresses, methods onlistener
will be called at various times to indicate how much of the image has been read. Because these methods are being called whileImageReader.read
is active, they must not call most methods from the sameImageReader
object. They may callImageReader.abort()
, which will causeImageReader.read
to return even if it is only partially complete.
IIOReadProgressListener
Interface
AnIIOReadProgressListener
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 SwingJProgressBar
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, theimageProgress
method will be called multiple times, each time with a different, increasing value for itspercentageDone
parameter. When the read is about to complete, theimageComplete
method will be called.Similarly, the
thumbnailStarted
,thumbnailProgress
, andthumbnailComplete
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 theImageReader.abort
method; in this case, the listener'sreadAborted
method will be called.
IIOReadUpdateListener
Interface
AnIIOReadUpdateListener
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 theBufferedImage
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, theimageUpdate
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, thepassComplete
method is called. Similar methods allow the progress of thumbnail image reads to be tracked.
IIOReadWarningListener
Interface
By attaching anIIOReadWarningListener
to anImageReader
, 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 ofLocale
s for which they can provide localized warning messages. The set of available locales can be obtained from the reader'sgetAvailableLocales
method. The desired locale should then be set by calling the reader'ssetLocale
method prior to attaching theIIOReadWarningListener
. Each listener will receive messages in theLocale
that was in effect at the time it was attached to the reader.
IIOWriteProgressListener
and IIOWriteWarningListener
Interfaces
TheIIOWriteProgressListener
andIIOWriteWarningListener
interfaces function similarly to their reader counterparts.