ch7.htm

JAVA Developing Professional JavaApplets

<BLOCKQUOTE>
<TT>Image newImage = getImage(getCodeBase(),
&quot;image.gif&quot;);</TT>
</BLOCKQUOTE>
<P>
The call you use depends on whether your image is grouped with
the class files or the HTML Web pages on your server.<BR>
<P><CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD><B>Note</B></TD></TR>
<TR VALIGN=TOP><TD>
<BLOCKQUOTE>
You must be aware of the organization of your various data files on the server. If your images reside with your class files (/htdocs/classes/images), then use <TT>getCodeBase()</TT>; however, if your images reside with your html files (/htdocs/images), use <TT>getDocumentBase()</TT>. Many times, class files are grouped together with html files. In this case, both methods will return the same URL.
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
The Toolkit also provides two <TT>getImage()</TT>
methods:
<UL>
<LI><TT>public Image getImage(URL imgLocation);</TT>
<LI><TT>public Image getImage(String filename);</TT>
</UL>
<P>
Although the Toolkit can retrieve a filename, applets can't use
<TT>getImage()</TT> to read local
files because they would cause a security exception. Remember,
applets can read only from the server they originated on. Allowing
applets to read from a local drive is definitely a security no-no.
<H3><A NAME="ImageDisplay">Image Display</A></H3>
<P>
Once an Image object is instantiated, it can be displayed in an
applet's <TT>paint()</TT> method by
using the Graphics object passed to it:
<BLOCKQUOTE>
<TT>g.drawImage(newImage, x, y, this);</TT>
</BLOCKQUOTE>
<P>
Variables <TT>x</TT> and <TT>y</TT>
contain the coordinates of the image's upper-left corner, and
the final parameter is an ImageObserver object. This interface
is implemented in the Component class that the applet is derived
from, which is why you can pass the <TT>this</TT>
pointer. You'll learn more about the ImageObserver interface in
the next section.
<P>
There are four variations of <TT>drawImage()</TT>
in the Graphics class:
<UL>
<LI><TT>public abstract boolean drawImage(Image
img, int x, int y, ImageObserver observer);</TT>
<LI><TT>public abstract boolean drawImage(Image
img, int x, int y, int width, int height, ImageObserver observer);</TT>
<LI><TT>public abstract boolean drawImage(Image
img, int x, int y, Color bgcolor, ImageObserver observer);</TT>
<LI><TT>public abstract boolean drawImage(Image
img, int x, int y, int width, int height, Color bgcolor, ImageObserver
observer);</TT>
</UL>
<P>
The width and height parameters allow you to scale an image, which
can be enlarged or reduced in either the x or y direction. The
<TT>bgcolor</TT> parameter specifies
which color to use for any transparent pixels in the image. Each
<TT>drawImage()</TT> version returns
<TT>true</TT> if the image was painted,
<TT>false</TT> otherwise. The image
will not paint if it hasn't been loaded yet. It will eventually
display because the Component class will be notified of the load
and will call your paint method when the image arrives.
<H3><A NAME="ImageObservers">Image Observers</A></H3>
<P>
The Component class accomplishes this because it implements the
ImageObserver interface. Most of Java's image-manipulation routines
are <I>asynchronous</I>, meaning they return immediately and notify
you when they have completed their assignment. The notification,
which flows through the ImageObserver interface, contains the
following method:
<UL>
<LI><TT>public abstract boolean imageUpdate(Image
img, int infoflags, int x, int y, int width, int height);</TT>
</UL>
<P>
The Component class uses this method, but you can override it
to get information about your image. The <TT>infoflags</TT>
parameter is a bit flag; the settings for the bits are shown in
Table 7.1.<BR>
<P>
<CENTER><B>Table 7.1. <FONT SIZE=1>Infoflags</FONT> bit values
for the ImageObserver interface.</B></CENTER>
<P><CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=124><I>Name</I></TD><TD WIDTH=466><I>Meaning</I>
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=124><TT>WIDTH=1</TT>
</TD><TD WIDTH=466>Width is available and can be read from the width parameter.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=124><TT>HEIGHT=2</TT>
</TD><TD WIDTH=466>Height is available and can be read from the height parameter.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=124><TT>PROPERTIES=4</TT>
</TD><TD WIDTH=466>Image properties are now available. The <TT>getProperty()</TT> method can be used.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=124><TT>SOMEBITS=8</TT>
</TD><TD WIDTH=466>Additional pixels for drawing a scaled image are available. The bounding box of the pixels can be read from the x, y, width, and height parameters.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=124><TT>FRAMEBITS=16</TT>
</TD><TD WIDTH=466>A complete image frame has been built and can now be displayed.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=124><TT>ALLBITS=32</TT>
</TD><TD WIDTH=466>A complete static image has been built and can now be displayed.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=124><TT>ERROR=64</TT>
</TD><TD WIDTH=466>An error occurred. No further information will be available, and drawing will fail.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=124><TT>ABORT=128</TT>
</TD><TD WIDTH=466>Image processing has been aborted. Set at the same time as ERROR. If ERROR is not also set, then you may try to paint the object again.
</TD></TR>
</TABLE></CENTER>
<P>
<P>
The following routine is used to repaint the applet when a complete
image arrives:
<BLOCKQUOTE>
<TT>public boolean imageUpdate(Image whichOne,
int flags, int x, int y, int w, int h)<BR>
{<BR>
&nbsp;&nbsp;&nbsp;&nbsp;if ( (flags &amp; (ERROR | FRAMEBITS |
ALLBITS)) != 0 )<BR>
&nbsp;&nbsp;&nbsp;&nbsp;{<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;repaint();<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return false;
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;}<BR>
&nbsp;&nbsp;&nbsp;&nbsp;return true;<BR>
}</TT>
</BLOCKQUOTE>
<P>
The return value specifies whether you would like to continue
to get information on this image; returning <TT>false</TT>
will stop future notifications.
<H2><A NAME="TrackingImageLoading"><FONT SIZE=5 COLOR=#FF0000>Tracking
Image Loading</FONT></A></H2>
<P>
Image loading can also be tracked by using the MediaTracker class.
Unlike the ImageObserver interface, it will not call back when
something completes. The client of a MediaTracker object must
register images with the tracker, then ask for status. <I>Registration</I>
involves passing an image and assigning a tracking number to it,
which then is used to query for the image's status. The following
methods are available for image registration:
<UL>
<LI><TT>public void addImage(Image image,
int id);</TT>
<LI><TT>public void addImage(Image image,
int id, int w, int h);</TT>
</UL>
<P>
If a width and height are specified, the image will be scaled
to these values. You can assign the same ID to multiple images.
All the status-check routines can work on several images at once.
<BR>
<P><CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD><B>Note</B></TD></TR>
<TR VALIGN=TOP><TD>
<BLOCKQUOTE>
If you assign the same ID to two or more images, then you can't check on the individual status of each image. Only group status as a whole can be checked.</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
You can use the following routines to get status information:
<UL>
<LI><TT>public boolean checkAll();</TT>
<LI><TT>public boolean checkAll(boolean load);</TT>
<LI><TT>public void waitForAll();</TT>
<LI><TT>public boolean waitForAll(long timeout);</TT>
<LI><TT>public int statusAll(boolean load);</TT>
<LI><TT>public boolean checkID(int id);</TT>
<LI><TT>public boolean checkID(int id, boolean
load);</TT>
<LI><TT>public void waitForID(int id);</TT>
<LI><TT>public boolean waitForID(int id,
long timeout);</TT>
<LI><TT>public int statusID(int id, boolean
load);</TT>
</UL>
<P>
The MediaTracker class can be passed a load parameter. If this
parameter is <TT>true</TT>, then the
image (or images) will start to load. Remember, <TT>getImage()</TT>
does not actually load the image. MediaTracker can be used to
preload an image before it is displayed. The methods returning
a Boolean value will indicate <TT>false</TT>
unless all eligible images are complete. Images that encounter
an error are considered to be complete, so you have to check for
errors with these routines:
<UL>
<LI><TT>public boolean isErrorAny();</TT>
<LI><TT>public Object[] getErrorsAny();</TT>
<LI><TT>public boolean isErrorID(int id);</TT>
<LI><TT>public Object[] getErrorsID(int id);</TT>
</UL>
<P>
The integer returned by <TT>statusAll()</TT>
and <TT>statusID()</TT> uses a bit
flag much like <TT>imageUpdate()</TT>
does; the values for the bit flag are listed in Table 7.2. The
wait methods will block until all images are complete. You can
also specify a time-out in milliseconds that determines the maximum
time to wait.<BR>
<P>
<CENTER><B><FONT SIZE=2>Table 7.2. Status bit values for MediaTracker.</FONT></B></CENTER>
<P><CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=112><I>Name</I></TD><TD WIDTH=293><I>Meaning</I>
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=112><TT>LOADING=1</TT>
</TD><TD WIDTH=293>Some (or all) images are still loading.</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=112><TT>ABORTED=2</TT>
</TD><TD WIDTH=293>Some (or all) images have aborted.</TD></TR>
<TR VALIGN=TOP><TD WIDTH=112><TT>ERRORED=4</TT>
</TD><TD WIDTH=293>Some (or all) images have encountered an error.
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=112><TT>COMPLETE=8</TT>
</TD><TD WIDTH=293>Some (or all) images have loaded.</TD></TR>
</TABLE></CENTER>
<H2><A NAME="TheConsumerProducerModel"><FONT SIZE=5 COLOR=#FF0000>The
Consumer/Producer Model</FONT></A></H2>
<P>
In Java, the Image class is just the tip of the iceberg; beneath
it stand the ImageConsumer and ImageProducer interfaces. Image
data is originated in an object that adheres to the ImageProducer
interface, which sends the data to an object using the ImageConsumer
interface. Figure 7.1 illustrates this relationship.
<P>
<A HREF="f7-1.gif" ><B>Figure 7.1 : </B><I>The relationship between ImageProducer and ImageConsumer </I></A>
<P>
This model allows any type of object to both originate and receive
image data. By creating the image subsystems as interfaces, Sun
has freed image production from any specific object type. This
is an important abstraction that you'll exploit in this chapter's
project.
<H2><A NAME="JavaColorModels"><FONT SIZE=5 COLOR=#FF0000>Java
Color Models</FONT></A></H2>
<P>
As stated earlier, an image is a collection of colors and their
layout. Much research has been done on how color is represented.
Humans perceive color when combinations of wavelengths of visible
light stimulate the retina. The number of wavelength combinations
is infinite, but humans can see only a fixed subset as separate
colors. Therefore, <I>color models</I> were invented to group
human-visible colors into a working set. There are two predominant
color models used to represent color information:
<UL>
<LI>The CMY (cyan-magenta-yellow) color model is used in subtractive
color systems, such as printing.
<LI>The RGB (red-green-blue) color model is used in additive color
systems, such as television and computer screens.
</UL>
<P>
Printing is a <I>subtractive system</I> because the perceived
color is contained in wavelengths of light reflected from the
paper. The absorbed colors are said to be &quot;subtracted&quot;
from the perceived color. Conversely, an <I>additive color system</I>
creates the light source containing the color. Therefore, you
can watch television in the dark, but you can't read a magazine.
<BR>
<P><CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD><B>Note</B></TD></TR>
<TR VALIGN=TOP><TD>
<BLOCKQUOTE>
If you're really curious, cyan absorbs red light, magenta absorbs green light, and yellow absorbs blue light. CMY color systems subtract RGB light and thus control the appearance of RGB color on a printed page.</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
Java encapsulates color information for an image in the ColorModel
class. Using the model, pixel data is interpreted into a raw color
component (red, green, blue, and alpha) for display. The ColorModel
class has the following methods:
<UL>
<LI><TT>public static ColorModel getRGBdefault();</TT>
<LI><TT>public int getPixelSize();</TT>
<LI><TT>public int getRed(int pixel);</TT>
<LI><TT>public int getGreen(int pixel);</TT>
<LI><TT>public int getBlue(int pixel);</TT>
<LI><TT>public int getAlpha(int pixel);</TT>
<LI><TT>public int getRGB(int pixel);</TT>
</UL>
<P>
The lone static method returns the system default ColorModel.
<H3><A NAME="DefaultRGB">Default RGB</A></H3>
<P>
Java uses the RGB color model for all its painting; all other
models are eventually translated into this format. It has 8 bits
of red, 8 bits of green, 8 bits of blue, and 8 bits of alpha.
The alpha channel supplies transparency-255 is opaque (visible),
and 0 is transparent. These add up to 32 bits of color information,
which just happens to be the size of a Java integer. The format
of colors within an integer is <TT>0xAARRGGBB</TT>.
<P>
To support images, Java supplies two other ColorModels: DirectColorModel
and IndexColorModel.
<H3><A NAME="DirectColor">Direct Color</A></H3>
<P>
The DirectColorModel is used when the underlying pixels in an