javax.microedition.lcdui
Class Image

java.lang.Object
  |
  +--javax.microedition.lcdui.Image

public class Image
extends Object

The Image class is used to used to hold graphical image data. Image objects exist independently of the display device. They exist only in off-screen memory and will not be painted on the display unless an explicit command is issued by the application (such as within the paint() method of a Canvas) or when an Image object is placed within a Form screen or an Alert screen and that screen is made current.

Images are either mutable or immutable depending upon how they are created. Immutable images are generally created by loading image data from resource bundles, from files, or from the network. They may not be modified once created. Mutable images are created in off-screen memory. The application may paint into them after having created a Graphics object expressly for this purpose. Images to be placed within an ImageItem or onto Form or Alert screens must be immutable. An immutable image may be created from a mutable image through the use of the createImage method. It is possible to create a mutable copy of an immutable image using a technique similar to the following:

     Image source; // the image to be copied
     Image copy = Image.createImage(source.getWidth(),
         source.getHeight());
     Graphics g = copy.getGraphics();
     g.drawImage(source, 0, 0, TOP|LEFT);
 
It is also possible to use this technique to create a subrectangle of an image, by altering the width and height parameters of the createImage(width, height) call that creates the destination image and by altering the x and y parameters of the drawImage() call.

PNG Image Format

Implementations are required to suport images stored in the Portable Network Graphics (PNG format). All of the 'critical' chunks specified by PNG must be supported, with the following considerations:

The IHDR chunk. MIDP devices must handle the following values in the IHDR chunk:

The PLTE chunk. Palette-based images must be supported.

The IDAT chunk. Image data may be encoded using any of the 5 filter types defined by filter method 0 (None, Sub, Up, Average, Paeth).

The IEND chunk. This chunk must be found in order for the image to be considered valid.

The Ancillary chunk support. PNG defines several 'ancillary' chunks that may be present in a PNG image but are not critical for image decoding. A MIDP implementation may (but is not required to) support any of these chunks. The implementation should silently ignore any unsupported ancillary chunks that it encounters. The defined ancillary chunks are:

 bKGD cHRM gAMA hIST iCCP iTXt pHYs
 sBIT sPLT sRGB tEXT tIME tRNS zTXt
 

Reference: Portable Network Graphics Specification. Version 1.0 W3c Recommendation, October 1, 1996. http://www.w3.org/TR/REC-png.html. Also available as RFC 2083, http://www.ietf.org/rfc/rfc2083.txt

Version:
MIDP 0.95 Public Draft

Method Summary
static Image createImage(byte[] imagedata, int imageoffset, int imagelength)
          Creates an immutable image which is decoded from the data stored in the specified byte array at the specified offset and length.
static Image createImage(Image image)
          Creates an immutable image from a source image.
static Image createImage(int width, int height)
          Creates a new, mutable image for off-screen drawing.
static Image createImage(String name)
          Creates an immutable image from decoded image data obtained from the named resource.
 Graphics getGraphics()
          Creates a Graphics object that renders to this image.
 int getHeight()
          Gets the height of the image in pixels.
 int getWidth()
          Gets the width of the image in pixels.
 boolean isMutable()
          Check if this image is mutable.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

createImage

public static Image createImage(byte[] imagedata,
                                int imageoffset,
                                int imagelength)
Creates an immutable image which is decoded from the data stored in the specified byte array at the specified offset and length. The data must be in some image format supported by the implementation, such as PNG.

The imageoffset and imagelength parameters specify a range of data in the imagedata byte array. The imageoffset parameter specifies the offset within the array of the first data byte to be used. It must therefore lie within the range [0..(imagedata.length-1)]. The imagelength parameter specifies the number of data bytes to be used. It must be a positive integer and it must not cause the range to extend beyond the end of the array. That is, it must be true that imageoffset + imagelength <= imagedata.length.

This method is intended for use when loading an image from a variety of sources, such as from persistent storage or from the network.

Parameters:
imagedata - the array of image data in a supported image format
imageoffset - the offset of the start of the data in the array
imagelength - the length of the data in the array

Returns:
the created image

Throws:
ArrayIndexOutOfBoundsException - if imageoffset and imagelength specify an invalid range
IllegalArgumentException - if imagedata is malformatted or otherwise cannot be decoded

createImage

public static Image createImage(Image image)
Creates an immutable image from a source image. If the source image is mutable, an immutable copy is created and returned. If the source image is immutable, the implemenation may simply return it without creating a new image.

This method is useful for placing images draw off-screen into Alert, Choice, Form, and ImageItem objects. The application can create an off-screen image using the createImage(width, height) method, draw into it using a Graphics object obtained with the getGraphics() method, and then create an immutable copy of it with this method. The immutable copy may then be placed into the Alert, Choice, Form, or ImageItem object.

Parameters:
image - the image to be copied

Returns:
the new, immutable image

createImage

public static Image createImage(int width,
                                int height)
Creates a new, mutable image for off-screen drawing. Every pixel within the newly created image is white. The width and height of the image must both be greater than zero.
Parameters:
width - the width, in pixels, of the new image
height - the height, in pixels, of the new image

Returns:
the created image

Throws:
IllegalArgumentException - if width or height is less than zero.

createImage

public static Image createImage(String name)
                         throws IOException
Creates an immutable image from decoded image data obtained from the named resource.
Parameters:
name - the name of the resource containing the pixel data in one of the supported image formats.

Returns:
the created image

Throws:
IOException - if the resource does not exist, the data cannot be loaded, or the image data cannot be decoded

getGraphics

public Graphics getGraphics()
Creates a Graphics object that renders to this image. This image must be mutable; it is illegal to call this method on an immutable image. The mutability of an image may be tested with the isMutable() method.

The newly created Graphics object has the following properties:

The lifetime of Graphics objects created using this method is indefinite. They may be used at any time, by any thread.

Returns:
a Graphics object with this image as its destination

Throws:
IllegalStateException - if the image is immutable

getHeight

public int getHeight()
Gets the height of the image in pixels.
Returns:
height of the image

getWidth

public int getWidth()
Gets the width of the image in pixels.
Returns:
width of the image

isMutable

public boolean isMutable()
Check if this image is mutable. Mutable images can be modified by rendering to them through a Graphics object obtained from the getGraphics() method of this object.
Returns:
true if the image is mutable, false otherwise