Working with Forms
In addition to screen-based components, you also have the ability to use forms to combine multiple components into one screen. This section discusses the
Form class as well as the components that can be placed on a form.
Form object is a screen that contains an arbitrary mixture of items, including read-only and editable text fields, images, date fields, gauges, and choice groups. As we mentioned before, any subclass of the
Item class (which we'll discuss shortly) can be placed on a
Form object. The
Form class has the following two constructors:
public Form(String title); public Form(String title, Item items);
The first constructor is used to create a new empty form, specifying only its title. The second constructor is used to create a new form with a title and initial contents. As an example, the following line of code creates an empty form that has the title "Choose an Item", as shown in Figure 10. This is basically a regular screen.
Form form = new Form("Choose an Item");
Form object does not use any sort of layout manager. Instead, the
Form object will arrange its components much like a list, usually top to bottom. And like the choices within a list, items within a form can be edited using appropriate operations such as insert, append, and delete. The methods of the
Form class, along with their signatures, are listed below.
First, to append an image to the end of the form, you can use the following method:
public int append(Image img);
This method appends an object that subclasses the
public int append(Item item);
You can also append a generic string, using the following method:
public int append(String str);
This method deletes the item at the given position in the form, shrinking the size of the form by one.
public void delete(int itemNum):
You can access any item in the form at its given position using the following method. The contents of the form will be left unchanged.
public Item get(int itemNum);
This method inserts an item in the form just prior to the index specified:
public void insert(int itemNum, Item item);
The following method replaces the previous item by setting the item referenced by
itemNum to the specified
public int set(int itemNum, Item item);
Finally, in order to find the current number of items that are in the form, use the
size( ) method:
public int size( );
The GUI components that can be placed on a form are the following:
TextField. All of these items are subclasses of the
Item abstract class. We will see how to place these items on a form shortly. But first, let's introduce each one in turn.
Item abstract class acts as the base class for all components that can be placed either on a form or an alert. All
Item objects have a label (i.e., a string attached to the item), which can be accessed using the following methods:
public String getLabel( ); public void setLabel(String s);
These are the only two methods in this abstract class.
ChoiceGroup object represents a group of selectable choices to be placed on a
Form object. Similar to the
List class, it implements the
Choice interface. It also extends the
Item abstract class. This object may mandate that a single choice be made, or it may allow multiple choices. The
ChoiceGroup class has the following two constructors:
public ChoiceGroup(String label, int choiceType); public ChoiceGroup(String label, int choiceType, String stringElements, Image imageElements);
The first constructor is used to create an empty choice group, specifying its label and type. Since this class implements the
Choice interface, you might think that there are three types of choices you can use. However, when using a choice group, only two choices are available:
IMPLICIT type is not available for use with a choice group, like it was with the
List component. There is no need to have a "menu" like choice field inside of a form. (Remember that
EXCLUSIVE is a choice having exactly one choice selected at a time; and
MULTIPLE is a choice that can have an arbitrary number of choices selected at a time.)
ChoiceGroup constructor can be used to create a new choice group, specifying its title and type, as well as an array of strings and images to be used as its initial contents.
Once you have created an empty choice, you can insert, append, or replace choices in it, exactly as in a
List component. Again, each choice has an integer index that represents its position in the list. The first choice starts at 0 and extends to the current size of the list, minus one. The
ChoiceGroup class provides the following methods for these operations.
public int append(String stringElement, Image imageElement);
public void insert(int index, String stringElement, Image imageElement);
public void set(int index, String stringElement, Image imageElement);
Note that a choice is composed of a text string and an optional image. For example, here is how to add a couple of choices to the earlier list. Note that the
append( ) method returns the index that was assigned to the choice that was passed in, in case we might need it later.
int saveIndex = list.append("save", null); int deleteIndex = list.append("delete", null);
In addition, you can delete any index in the choice group using the following method:
public void delete(int index);
If you want to retrieve the string element or the image element for any index, the following methods are useful:
public String getString(int index); public Image getImage(int index);
If you want to set, unset, or retrieve the currently selected index in the choice group, or query any index to see if it is currently selected, use the following:
public int getSelectedIndex( ) public boolean isSelected(int index); public setSelectedIndex(int index, boolean selected);
Finally, just as with the
List component, you can use a boolean selection flags array to set the selection state of the entire choice group. Again, the
getSelectedFlags( ) method does not return a boolean array, but instead modifies one that has been passed in (and returns the number of elements that are selected as an integer as an optimization technique). The array must be at least as long as the number of elements in the list. If it is longer, then the array elements beyond it are set to
public int getSelectedFlags(boolean selectedArray); public void setSelectedFlags(boolean selectedArray);
For a list of type
setSelectedFlags( ) method sets the selected state of every element in the list. For a list of type
EXCLUSIVE, exactly one element in the boolean array must be set to
true; if no element is
true, then the first element will be selected. If two or more elements are
true, the implementation chooses the first
true element and selects it.
The following snippet of code creates a new empty
ChoiceGroup object whose title is "Selection", and whose type is
ChoiceGroup choices = new ChoiceGroup("Method of payment", Choice.EXCLUSIVE);
The following code adds several new choices to the choice group.
choices.append("Visa", null); choices.append("Master Card", null); choices.append("Amex", null);
Similar to choices within a list, choices within a choice group can be edited using the familiar insert, append, and delete methods. In addition, choices are referred to by their indexes. For example, to delete the last choice:
It is important to note that once a choice group has been created and populated, it cannot be displayed using
setCurrent( ), as a list can. A choice group is a subclass of item and has to be placed on a form, which can in turn be displayed using
Form form = new Form("Choose one"); form.append(choices); Display.setCurrent(form);
Figure 11 shows an example of an
EXCLUSIVE choice group, and Figure 12 shows an example of a
MULTIPLE choice group. Again, the
IMPLICIT choice is not available for use with the
ChoiceGroup class; if you attempt to use it, an
IllegalArgumentException will be thrown.
DateField object is an editable component for representing calendar date and time information that can be placed on a
Form object. It can be configured to accept date or time information, or both. A
DateField object can be created using one of the following two constructors:
public DateField(String label, int mode); public DateField(String label, int mode, TimeZone timeZone);
The first constructor is used to create a
DateField object with the specified label and mode. This mode can be specified providing one of the static fields:
DateField.DATE input mode allows you to set date information,
DateField.TIME allows for clock time information (hours and minutes), and
DateField.DATE_TIME allows for setting both.
DateField object has the following methods to access the properties added onto the
Form object (remember that the label property is defined in the
Item abstract class):
public Date getDate( ) public int getInputMode( ) public void setDate(Date date); public void setInputMode(int mode);
In addition, you can use the
toString( ) method to output a string-based copy of the date or time data.
public String toString( );
As an example, the following code creates a
DateField object with the label as "Today's date" and the mode as
DateField date = new DateField("Today's date", DateField.DATE);
To display a date field, first create a
Form object, and then use the
append( ) method of the form to add the date field.
Form form = new Form("Date Info"); form.append(date); Display.setCurrent(form);
In this example, since the
DATE input mode is selected, the MIDlet would display a <date> item for the user to select, as shown in Figure 13. Once selected, it will display the current calendar date, and you should be able to set a new date.
DateField.TIME input mode is used, the MIDlet would display a <time> item for the user to select, as shown in Figure 14. Once selected, the current clock time information will be displayed, and you can likewise set a new time.
Finally, if the
DateField.DATE_TIME input mode is used, the MIDlet would display the items <date> and <time> and you would be allowed to choose one at a time.
Note that you can initialize the date and time before displaying the component. You can do so using the following snippet of code:
d = new DateField("Today: ", DateField.DATE); d.setDate(new Date( )); form = new Form("Date & Time"); form.append(d); display.setCurrent(form);
At this point, the date field displays the current date and time, as shown in Figure 15.
DateField constructor is used to create a date field specifying its label, input mode, and time zone information. For example, the following snippet of code creates a
DateField object where the time zone is GMT:
DateField date = new DateField("date", DateField.DATE, TimeZone.getTimeZone("GMT"));
TimeZone field is
null, the default time zone (based on the time zone where the program is running) is used. Hence, the following two lines of code do exactly the same thing:
DateField date1 = new DateField("date", DateField.DATE);
DateField date2 = new DateField("date", DateField.DATE, TimeZone.getDefault( ));
TimeZone class is part of the
java.util package, which has been inherited from the J2SE.
Gauge object represents a bar graph display that can be used within a form. The
Gauge class has the following constructor:
public Gauge(String label, boolean interactive, int maxValue, int initialValue);
This constructor is used to create a new
Gauge object with the given label, in interactive or non-interactive mode, with the given maximum and initial values. In interactive mode, the user is allowed to modify the gauge's current value; in non-interactive mode, the user is not allowed to change the value at all (e.g., what you might see in a progress bar). You can query whether the gauge is currently in interactive mode with the following method:
public boolean isInteractive( );
Gauge object also provides the following methods to access the current value and maximum value properties that we saw in the constructor:
public int getMaxValue( ); public int getValue( ); public void setMaxValue(int maxValue); public void setValue(int value);
A gauge will always maintain a current value between zero and the maximum value specified. For example, the following snippet of code creates an interactive gauge where the maximum value is 20 and the initial value is 0:
Gauge gauge = new Gauge("graph", true, 20, 0);
Gauge object is created, it can be placed on a
Form component, like the other components that we've seen:
Form form = new Form("item"); form.append(gauge);
This interactive gauge is shown in Figure 16. Note that the style of the gauge is of an ascending arc from right to left, as you might see on a LED volume control.
If the gauge is used to reflect progress, the application will need to keep updating it. In this case, it will need to keep a reference to it handy and repeatedly call
setValue( ) to reflect the current progress.
The following snippet of code shows an example of a non-interactive gauge that reflects a progress bar:
Display display = Display.getDisplay(this); Gauge progressbar = new Gauge("Progress", false, 20, 9); Form form = new Form("Configuring App); form.append(progressbar);
This progress bar is shown in Figure 17. Note here that the non-interactive form of a gauge is level from right to left.