Form

Form

A form is a collections of instances of the Item interface.

An item is added to a form using the append(Item item) method, which simply tacks the added item to the bottom of the form and assigns it an index that represents its position in the form. The first added item is at index 0, the second at index 1, and so on. You can also use the insert(int index, Item newItem) method to insert an item at a particular position or use set(int index, Item newItem) to replace an item at a particular position specified by the index.

There are eight Item types that can be added to a form.

1. StringItem: A label that cannot be modified by the user. This item may contain a title and text, both of which may be null to allow it to act as a placeholder. The Form class provides a shortcut for adding a StringItem, without a title: append(String text)
2. DateField: Allows the user to enter date/time in one of three formats: DATE, TIME, or DATE_TIME.
3. TextField: Same as a TextBox.
4. ChoiceGroup: Same as a List.
5. Spacer: Used for positioning UI elements by putting some space between them. This element is an invisible UI element and can be set to a particular size.
6. Gauge: A gauge is used to simulate a progress bar. However, this progress bar look can also be used in an interactive mode by the user. For example, if you wanted to show the user a volume control, a gauge would be used to show an interactive knob.
7. ImageItem: An item that holds an image! Like the StringItem, the Form class provides a shortcut method for adding an image: append(Image image). More about images in a later section.
8. CustomItem: CustomItem is an abstract class that allows the creation of subclasses that have their own appearances, their own interactivity, and their own notification mechanisms. If you require a UI element that is different from the supplied elements, you can subclass CustomItem to create it for addition to a form.

These items (except CustomItem) can be seen in Figure 5, and the corresponding code is shown in Listing 4. (NOTE: The image, duke.gif, should be kept in the res folder of this MIDlet application.)

package com.j2me.part2;

import javax.microedition.lcdui.Form;
import javax.microedition.lcdui.Gauge;
import javax.microedition.lcdui.Spacer;
import javax.microedition.lcdui.ImageItem;
import javax.microedition.lcdui.TextField;
import javax.microedition.lcdui.DateField;
import javax.microedition.lcdui.StringItem;
import javax.microedition.lcdui.ChoiceGroup;

import javax.microedition.lcdui.Image;
import javax.microedition.lcdui.Choice;
import javax.microedition.lcdui.Display;
import javax.microedition.midlet.MIDlet;

public class FormExample extends MIDlet {

	private Form form;
	private Gauge gauge;
	private Spacer spacer;
	private ImageItem imageItem;
	private TextField txtField;
	private DateField dateField;
	private StringItem stringItem;
	private ChoiceGroup choiceGroup;

	public FormExample() {
		form = new Form("Your Details");

		// a StringItem is not editable
		stringItem = new StringItem("Your Id: ", "WXP-890");
		form.append(stringItem);

		// you can accept Date, Time or DateTime formats
		dateField = new DateField("Your DOB: ", DateField.DATE);
		form.append(dateField);

		// similar to using a TextBox
		txtField = new TextField(
			"Your Name: ", "", 50, TextField.ANY);
		form.append(txtField);

		// similar to using a List
		choiceGroup = new ChoiceGroup(
			"Your meals: ",
			Choice.EXCLUSIVE,
			new String[] {"Veg", "Non-Veg"},
			null);
		form.append(choiceGroup);

		// put some space between the items to segregate
		spacer = new Spacer(20, 20);
		form.append(spacer);

		// a gauge is used to show progress
		gauge = new Gauge("Step 1 of 3", false, 3, 1);
		form.append(gauge);

		// an image may not be found,
		// therefore the Exception must be handled
		// or ignored
		try {
			imageItem = new ImageItem(
				"Developed By: ",
				Image.createImage("/duke.gif"),
				ImageItem.LAYOUT_DEFAULT,
				"DuKe");
			form.append(imageItem);
		} catch(Exception e) {}
	}

	public void startApp() {
		Display display = Display.getDisplay(this);
		display.setCurrent(form);
	}

	public void pauseApp() {
	}

	public void destroyApp(boolean unconditional) {
	}
}

Listing 4. Using forms

Figure 5. The elements of a form