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

advertisement

AddThis Social Bookmark Button

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

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

A 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.

Screen shot.
Figure 10. An empty form.

Form form = new Form("Choose an Item");

The 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 Item object:

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 Item given:

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: ChoiceGroup, DateField, Gauge, ImageItem, StringItem, and 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

The 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

A 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: EXCLUSIVE and MULTIPLE. The 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.)

The second 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 false.

public int getSelectedFlags(boolean[] selectedArray);
public void setSelectedFlags(boolean[] selectedArray);

For a list of type MULTIPLE, the 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 EXCLUSIVE:

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:

choices.delete(2);

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 setCurrent( ).

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.

Screen shot.
Figure 11. An EXCLUSIVE choice group.

Screen shot.
Figure 5-13. A MULTIPLE choice group.

DateField

A 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, DateField.TIME, or DateField.DATE_TIME. The 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.

The 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:

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.

Screen shot.
Figure 13. A date field representing the calendar date.

If the 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.

Screen shot.
Figure 14. A date field representing clock time information.

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.

Screen shot.
Figure 15. A date field represented with the DATE_TIME constant.

The second 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"));

If the 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( ));

The TimeZone class is part of the java.util package, which has been inherited from the J2SE.

Gauge

A 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(  );

The 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);

Once a 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.

Screen shot.
Figure 16. An example of an interactive gauge.

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.

Screen shot.
Figure 17. A non-interactive gauge representing a progress bar.


Pages: 1, 2, 3, 4

Next Pagearrow