ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

MIDP GUI Programming, Part 2
Pages: 1, 2, 3, 4

Image and ImageItem

An ImageItem object is an image component that contains a reference to an Image object. First, let's briefly introduce the Image class. We will revisit it again later when we talk about low-level APIs.

The Image class is used as a graphical image data holder. Depending on how they are created, images can either be immutable or mutable. Immutable images are generally created by loading image data from resource bundles, from files, or across a network. Once they are created, they may not be modified. Mutable images, on the other hand, are created in off-screen memory and can be modified.

Images that are to be placed within an Alert, Form, or ImageItem must be immutable, since the implementation will use them to update the display without notifying the application. Otherwise, the containing Alert or Form would have to be updated on every graphics call.

A mutable image can be created using one of the static createImage( ) methods of the Image class.

Related Reading

Learning Wireless JavaLearning Wireless Java
By Qusay H. Mahmoud
Table of Contents
Sample Chapter
Full Description

public static Image createImage(int width, int height);

The other three static createImage( ) methods are used to create immutable images:

public static Image createImage(Image image);
public static Image createImage(String name);
public static Image createImage(byte[] imageData, int imageOffset, 
    int imageLength);

Here is an example of creating an immutable image from a graphics file:

Image image = Image.createImage("/Duke.png");

This image can then be placed on a Form object in the typical fashion:

Form form = new Form("Duke");

Note that the graphics file has the extension png. This acronym stands for Portable Network Graphics. All MIDP implementations are required to support images stored in at least Version 1.0 of PNG. As of this writing, no other graphics formats are accepted. Also, if you're using the emulator within J2ME Wireless Toolkit's KToolbar application, note that the reference to Duke using /duke.png means that the Duke is in the res directory, c:\j2mewtk\apps\Myproject\res. Figure 18 depicts the screen shown with this example.

Screen shot.
Figure 18. Placing an Image object on a form.

The Image class has a few methods that can come in handy to discover the height, width, and mutable status of any image:

public int getHeight(  );
public int getWidth(  );
public boolean isMutable(  );

In addition, if the image is mutable, you can obtain a Graphics object of the image using the following method. (We'll cover this in much more detail when we discuss the low-level graphics API.)

public Graphics getGraphics(  );

Now, let's see how to use the ImageItem class, which provides control and layout when Image objects are added to a form or an alert. To create an ImageItem object, use the ImageItem constructor:

public ImageItem(String label, Image img, int layout,
     String altText);

This constructor is used to create a new immutable ImageItem object with a given label, image, layout directive, and alternative text string. The altText parameter specifies a string to be displayed in place of the image if it exceeds the capacity of the display. The layout parameter is a combination of the following values, which are static field members of the ImageItem class:

The image should be horizontally centered.
You should use the default formatting of the container of the image.
The image should be close to the left edge of the drawing area.
A new line should be started after the image is drawn.
A new line should be started before the image is drawn.
The image should be close to the right edge of the drawing area.

There are some rules on how the above layout values can be combined:

  • ImageItem.LAYOUT_DEFAULT cannot be combined with any other directive.
  • ImageItem.LAYOUT_LEFT, ImageItem.LAYOUT_RIGHT, and ImageItem.LAYOUT_CENTER are mutually exclusive.
  • You can combine ImageItem.LAYOUT_LEFT, ImageItem.LAYOUT_RIGHT, and ImageItem.LAYOUT_CENTER with ImageItem.LAYOUT_NEWLINE_AFTER and ImageItem.LAYOUT_NEWLINE_BEFORE.

TIP:  The layout directives serve merely as a hint, but it may be ignored by the implementation. Such is the case with Sun's MIDP reference implementation.

The ImageItem class also contains the following methods to access the properties that we just saw in the constructor:

public String getAltText(  );
public Image getImage(  );
public int getLayout(  );
public void setAltText(String altText);
public void setImage(Image img);
public void setLayout(int layout);

So, to create an ImageItem object, use the above ImageItem constructor:

Image img = Image.createImage("/Duke.png");
ImageItem imageItem = new ImageItem("Image", img,
    ImageItem.LAYOUT_CENTER, "img");
Form form = new Form("Duke");

This example would produce a screen similar to that in Figure 18, except that this one would have a title for the ImageItem object.


A StringItem object is a text component item that may contain a string that cannot be edited by the user. A StringItem has a label that can be modified by the application. The contents of StringItem can be modified by the application as well. Here is the constructor:

public StringItem(String label, String contents);

Creating a StringItem object is easy:

StringItem si = new StringItem("label", "contents");

The setText() and getText( ) methods are used to set and get the StringItem contents; the setLabel() and getLabel( ) methods, which are defined in the Item abstract class, are used to set and get the label of the StringItem:

public void setText(String s);
public void setLabel(String l);
public String getText(  );
public String getLabel(  );

The following snippet of code creates a StringItem object and places it within a Form object. The form is then set to be the current screen, as shown in Figure 19.

Screen shot.
Figure 19. The user cannot edit the contents of a StringItem object.

Display display = display.getDisplay(this);
StringItem si = new StringItem("String item:\n", "Hello World!");
Form form = new Form("Greetings");


Unlike StringItem, a TextField object is an editable text component that may be placed on a Form. Similar to a TextBox, however, a TextField has a capacity (or a maximum size), which is the number of characters that can be stored in the object. Again, the MIDP implementation may place a boundary on the maximum size, which could be smaller than the size the application requested. The maximum size imposed by the implementation can be retrieved using getMaxSize( ). But, as mentioned earlier, in Sun's MIDP reference implementation, the getMaxSize( ) method returns the size requested by the application.

Use a TextField object if your MIDlet requires input from the user. A TextField object can be created as an instance of the TextField class, which has the following constructor:

public TextField(String label, String text, int maxSize, int

This constructor is used to create a new TextField object with the given label, initial contents, maximum size in characters, and constraints. The constraints field is used to limit the user's input. The constraints are the TextField's static constants, which are shared with TextBox as discussed earlier, and they are: TextField.ANY, TextField.EMAILADDR, TextField.NUMBER, TextField.PASSWD, TextField.PHONENUMBER, and TextField.URL. Again, if you use a constraint other than TextField.ANY, the TextField will perform a simple validation to make sure that the characters that are input are of the requested type.

If you wish to set or retrieve the current constraints that are active for the TextField, use the following methods:

public int getConstraints(  );
public void setConstrants(int c);

The maximum size imposed by the implementation can be retrieved using the getMaxSize( ) method, and (potentially) reset using the setMaxSize( ) method.

public int getMaxSize(  );
public void setMaxSize(int size);

You can set or retrieve the entire text in the TextField with the setString( ) and getString( ) methods:

public String getString(  );
public void setString(String s);

In addition, if you would like to see the number of characters in the text that has been entered, use the size( ) method, which returns an integer:

public int size(  );

The methods to delete, insert, or replace the current text are identical to TextBox:

public void delete(int offset, int length);
public void insert(char[] data, int offset, int length, int position);
public void insert(String src, int position);
public void setChars(char[] data, int offset, int length);

Finally, if you want to find out which position the caret, also known as the insertion beam, is currently in front of, TextField includes the following method:

public int getCaretPosition(  );

The following code shows this component in action. It creates a login form with two text fields, one for loginID and the other for the password. Once started, you can enter your username and a password, as shown in Figure 20.

Screen shot.
Figure 20. Example of TextField.

Display display = Display.getDisplay(this);
TextField userName = new TextField("LoginID:", "", 10,
TextField password = new TextField("Password:", "", 10,
Form form = new Form("Sign in");

In next week's final installment from this chapter, you'll learn how to create Low-Level GUI Components.

Read the first excerpt in this series.

View catalog information for Learning Wireless Java

Return to ONJava.com.