Lists and Forms - Beginning J2ME: From Novice to Professional - page 67

The example at the end of this section, in Listing 6-1, demonstrates an IMPLICIT list .
You can also use the setSelectCommand() method to specify your own Command to be used
for selections instead of having to use the SELECT_COMMAND .

Creating Lists
To create a List , specify a title and a list type. If you have the element names and images available
ahead of time, you can pass them in the constructor:

public List(String title, int type)
public List(String title, int type,
String[] stringElements, Image[] imageElements)

The stringElements parameter cannot be null but can be empty; however, imageElements
may contain null array elements. If the image associated with a list element is null, the element
is displayed using just the string. If both the string and the image are defined, the element will
display using the image and the string.
Some List s will have more elements than can be displayed on the screen. Indeed, the actual
number of elements that will fit varies from device to device. But don't worry: List implemen-
tations automatically handle scrolling up and down to show the full contents of the List. MIDlet
developers have no control over how the implementation handles this scrolling.

About Images
Our romp through the List class yields a first look at images. Instances of the
javax.microedition.lcdui.Image class represent images in MIDP. The specification dictates
implementations be able to load images files in PNG format. 1 This format supports both a
transparent color and lossless compression.
Image has no constructors, but the Image class offers a handful of createImage() factory
methods for obtaining Image instances. The first are for loading images from PNG data.

public static Image createImage(String name)
public static Image createImage(byte[] imagedata, int imageoffset,
int imagelength)
public static Image createImage(InputStream stream)

The first method attempts to create an Image from the named file, which should be pack-
aged inside the JAR that contains your MIDlet. You must use an absolute pathname or the
image file will not be found. The second method creates an Image using data in the supplied
array. The data starts at the given array offset, imageoffset , and is imagelength bytes long. The
third method creates an Image from an InputStream .
Images may be mutable or immutable . Mutable Images can be modified by calling
getGraphics() and using the returned Graphics object to draw on the image. (For full details
on Graphics , see Chapter 13.) If you try to call getGraphics() on an immutable Image , an
IllegalStateException will be thrown.

1. MIDP implementations are not required to recognize all varieties of PNG files. The documentation for

the Image class has the specifics.