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

Alert

An alert is an ordinary screen that can contain text and an image. It informs the user about errors and other exceptional conditions. An alert can either be modal or timed.



A modal alert remains on the screen until the user dismisses it, at which point it returns to either the screen that was displayed before it, or a screen specifically chosen by the application. This is useful if you require the user to make a choice. For example, you might display a message such as "Are you sure?" and offer "Yes" and "No" options. Note that a MIDP implementation will automatically provide a way to dismiss a modal alert. Sun's reference implementation, for example, provides a Done command mapped to a soft button.

A timed alert, on the other hand, is displayed for a certain amount of time (typically a few seconds). It is useful for displaying an informative message that does not need to be acknowledged by the user. For example, you might want to display a message that says "Your message has been sent". However, note that if you specify a timed alert that has too much content to be displayed all at once, it automatically becomes a modal alert!

An alert can be created as an instance of the Alert class, which has the following two constructors:

public Alert(String title);
public Alert(String title, String alertText, Image alertImage,
    AlertType alertType);

The first constructor creates a timed alert. However, as you probably noticed, the timeout value is not specified in the constructor. Instead, the alert will use the default timeout value, which can be obtained for each device using the immutable getDefaultTimeout( ) method. If you want to change the alert's timeout, use the setTimeout( ) method with an integer that specifies the timeout in milliseconds. To obtain the current timeout for the alert, use the getTimeout( ) method.

public int getDefaultTimeout(  );
public int getTimeout(  );
public void setTimeout(int t);

For example, the following snippet of code creates a timed alert with a timeout value set to four seconds:

Alert alert = new Alert("title");
alert.setTimeout(4000);

You can also pass in the constant value Alert.FOREVER. This will keep the alert up indefinitely, which has the side effect of turning a timed dialog into a modal dialog.

alert.setTimeout(Alert.FOREVER);

You can create a more specialized alert using the second constructor. This constructor allows you to associate an icon with the alert, using an Image object. Also, an alert may have a type associated with it to provide an indication of the nature of the alert. The MIDP implementation may use this type to play an appropriate sound when the alert is presented to the user. The AlertType class provides five types of alerts: AlertType.ALARM, AlertType.CONFIRMATION, AlertType.ERROR, AlertType.INFO, and AlertType.WARNING. As an example, the following snippet of code creates an alert of type AlertType.CONFIRMATION, and it does not have an icon associated with it:

public Alert(String title, String messageString, Image alertImage,
    AlertType alertType);

Note that any or all of the parameters in the second constructor may be null if you wish to omit the image, the title, the text, or the alert type. The additional properties set in the constructor each has its own set of accessors within the Alert class:

public Image getImage(  );
public String getString(  );
public AlertType getType(  );
public void setImage(Image img);
public void setString(String str);
public void setType(AlertType type);

Now, let's see examples of both timed and modal alerts. The following snippets of code create a TextBox object and a timed alert. When the MIDlet is activated, the alert will be displayed, and after five seconds the text box will be displayed automatically, courtesy of the Display.setCurrent() method.

TextBox tb = new TextBox("text box",
    "Welcome to MIDP GUI Programming", 40, TextField.ANY);
Alert timedAlert = new Alert("Confirmation",
   "Your message has been sent!", null, AlertType.CONFIRMATION);
TimedAlert.setTimeout(5000);
Display display = Display.getDisplay(this);
Display.setCurrent(timedAlert, tb);

Figure 5 shows how the code above is displayed. The alert, which says "Your message has been sent!" is displayed first. After five seconds, the current display returns to the text box that says "Welcome to MIDP GUI Programming."

Diagram.
Figure 5. An example of a timed alert

As you can see from the previous example, timed alerts do not need user intervention. On the other hand, modal alerts stay up until the user dismisses them, as shown in the following example.

TextBox tb = new TextBox("text box", 
     "Welcome to MIDP Programming",
     40, Textfield.ANY);
Alert modalAert = new Alert("Error",
    "Network error. Please try again later.",
     null, AlertType.ERROR);
modalAlert.setTimeout(Alert.FOREVER);
Display display = Display.getDisplay(this);
display.setCurrent(modalAlert, tb);

In this case, the network error screen stays up until the user dismisses it, using the soft button that corresponds to the Done command, as shown in Figure 6. The Done command, for modal alerts, is provided automatically by Sun's MIDP reference implementation. In this example, the text box screen becomes the current screen only after the user dismisses the alert.

Diagram.
Figure 6. An example of a modal alert.

List

A list is a screen containing selectable choices. Both List and ChoiceGroup have common behavior defined by the Choice interface. The user can interact with a list by moving from element to element. Note that this high-level API interaction does not cause any programming events to be fired back to the application. That only occurs when a selection has been made.

A list can be created as an instance of the List class, which has the following two constructors:

public List(String title, int listType);
public List(String title, int listType, String[] stringElements, 
            Image[] imageElements);

The first constructor is used to create an empty list, specifying the title and the type of the list. There are three types of list choices that can be passed in for the second parameter: IMPLICIT, EXCLUSIVE, and MULTIPLE. These options can be specified using the constants provided in the Choice interface, which is implemented by the List class.

  • An EXCLUSIVE type of list has no more than one choice selected at a time, which is similar to a group of radio buttons in the AWT world.
  • An IMPLICIT type is an EXCLUSIVE choice where the focused choice is implicitly selected, much like a drop-down menu.
  • The MULTIPLE type is a list that can have arbitrary number of choices selected at a time, and presents itself as a series of checkboxes.

As an example, the following snippet of code creates a list of type EXCLUSIVE, the title of which is "Choose one".

List list = new List("Choose one", Choice.EXCLUSIVE);

Once you have created an empty list, you can insert, append, or replace choices in the list. 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 List 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);

You can delete any index in the list 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 will do the trick:

public String getString(int index);
public Image getImage(int index);

If you want to set, unset, or retrieve the currently selected index in the list, or query any index to see if it is currently selected, use the following methods:

public int getSelectedIndex(  )
public boolean isSelected(int index);
public setSelectedIndex(int index, boolean selected);

Finally, you can use a boolean array to set the selection state of the entire list. This is known as the selection flag, and can be accessed using the following methods. Note that 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); this is a common optimization technique that prevents the creation of a new array each time the method is called. 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 or IMPLICIT, 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.

Let's look at some examples of the List component. The following snippet of code shows an example where a list of type EXCLUSIVE is created and displayed:

Display display = Display.getDisplay(this);
List menu = new List("Edit", Choice.EXCLUSIVE);
menu.append("Save");
menu.append("Move to");
menu.append("delete");
display.setCurrent(menu);

In this list, only one choice can be selected, as shown in Figure 7.

Screen shot.
Figure 7. A list of an EXCLUSIVE choice.

If you change the type of the list to IMPLICIT, then the result would be similar to Figure 8. Note that the radio buttons have disappeared.

Diagram.
Figure 8. A list of an IMPLICIT choice.

Similar to an EXCLUSIVE type, only one choice can be selected at a time in this list; however, the focused choice will be implicitly selected, instead of having to select it to color in a circle on the left. The third type of list is MULTIPLE, where multiple selections can be made, as shown in Figure 9.

Diagram.
Figure 9. A list of a MULTIPLE choice.

As we mentioned before, choices in a list are referred to by indices, which are consecutive integers in the range zero to the size of the list, minus 1 (e.g., size( ) - 1). Zero (0) refers to the first choice and size( ) - 1 refers to the last choice. For example, to delete the "Move To" choice in Figure 8:

list.delete(1);

Here, we use the second List constructor to create a list, specifying its title, the type of the list, and an array of strings and images to be used as its initial contents. The following code creates a list with two initial choices and no images:

List list2 = new List("Make a selection", Choice.EXCLUSIVE,
   {"Add", "Delete"}, null);

The number of elements in the list is determined by the length of the stringElements array passed into the constructor, which cannot be null. The imageElements array, however, can be null. However, if it is non-null, it must be the same length as the stringElements array.

Pages: 1, 2, 3, 4

Next Pagearrow