Image and ImageItem
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.
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
ImageItem must be immutable, since the implementation will use them to update the display without notifying the application. Otherwise, the containing
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
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"); form.append(image);
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.
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
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
- 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_DEFAULTcannot be combined with any other directive.
ImageItem.LAYOUT_CENTERare mutually exclusive.
- You can combine
ImageItem.LAYOUT_RIGHT, and I
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.
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
Image img = Image.createImage("/Duke.png"); ImageItem imageItem = new ImageItem("Image", img, ImageItem.LAYOUT_CENTER, "img"); Form form = new Form("Duke"); form.append(imageItem);
This example would produce a screen similar to that in Figure 18, except that this one would have a title for the
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);
StringItem object is easy:
StringItem si = new StringItem("label", "contents");
getText( ) methods are used to set and get the
StringItem contents; the
getLabel( ) methods, which are defined in the
Item abstract class, are used to set and get the label of the
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.
Display display = display.getDisplay(this); StringItem si = new StringItem("String item:\n", "Hello World!"); Form form = new Form("Greetings"); form.append(si); display.setCurrent(form);
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.
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 constraints);
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.URL. Again, if you use a constraint other than
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
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.
Display display = Display.getDisplay(this); TextField userName = new TextField("LoginID:", "", 10, TextField.ANY); TextField password = new TextField("Password:", "", 10, TextField.PASSWORD); Form form = new Form("Sign in"); form.append(userName); form.append(password); display.setCurrent(form);
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.