Programming Wireless Devices with the Java2 Platform

8.3 Display

The Display class is the central controller of the display of a MIDP application. An application gets a Display instance by calling the static method getDisplay and by passing the MIDlet instance to the method:

Display midletDisplay = Display.getDisplay(myMIDlet);

When the Display instance is obtained, the application can change the Displayables presented on the device using the methods of the Display class. There are three methods in class Display that allow the application to set the current Displayable instance presented on the device display. The most commonly used method is:

public void setCurrent(Displayable nextDisplayable)

The two other methods are provided for more specialized use:

public void setCurrent(Alert alert, Displayable nextDisplayable)
public void setCurrentItem(Item item)

The first of these specialized methods sets an Alert to be displayed and also provides the Displayable that is presented after the Alert is dismissed. See Section 9.3, "Alert." The second of these specialized methods presents a specific Item attached to a Form instance. The Form that has the Item is set as the current displayable, and it is scrolled so that the Item becomes visible. Focus, if supported by device, moves to this Item.

8.3.1 Current Displayable

Technically, the methods just discussed set only the current displayable of class Display. During the lifecycle of the application the current Displayable never again is null after it has been initially set at application startup. The current Displayable is made visible by the device software referred to as application management software (AMS) in MIDP Specification (see Section 19.2, "MIDP System Software.") The current Displayable is visible when the application is in the foreground.

There often are, however, situations when the application management software moves the application to the background, and thus the current Displayable is not actually visible. The current Displayable does not change in these cases. Applications are commonly moved to background upon system events such as incoming calls in a phone device or upon certain other system notifications. When the application management software decides that the application can again be brought to the foreground, the current Displayable is simply made visible.

The application can determine whether a Displayable is visible on the display by calling the method isShown. In the case of Canvas and CustomItem, the showNotify and hideNotify methods are called when the component is made visible and is hidden, respectively. Applications need to override showNotify and hideNotify methods in Canvas or CustomItem subclasses to be able receive these notifications.

Some devices may have the capability to run multiple applications simultaneously. If multiple applications are actually running simultaneously, some of the applications are in background. For such devices there is a feature in class Display that allows the application to request to be sent to background. The method call setCurrent(null) does not set the current Displayable to null, but instead does the background request and the current Displayable remains unchanged. It should be noted that in many devices this request is simply ignored, but those that can support background applications may move the application to the background. The application management software decides which application should be presented if this request is honored. Similarly, for background applications, any non-null call to setCurrent methods is treated as a request to return the application to the foreground. Conversely, since the current Displayable is unchanged when an application is in the background, the method call d.setCurrent(d.getCurrent()) can be used to request a return to the foreground without changing the Displayable.

8.3.2 Screen Backlight and Device Vibrator

In MIDP 2.0, class Display has methods to control the screen backlight and vibrator often found in mobile devices:

public boolean vibrate(int duration)
public boolean flashBacklight(int duration)

Both methods take a parameter that indicates the duration of the action in milliseconds. These methods work only if there is a controllable backlight and vibrator present in a device. The methods return false if no such feature is available. Applications should use these methods with care, as they both consume battery significantly and may be irritating to some users or in specific situations. Devices commonly also have general native settings for turning off these features, in which case the methods also return false.

The Display class also includes methods for retrieving some device properties, such as the color capabilities of the device. See Section 8.6.2, "Adaptation to Device-Specific User Interface Style," for a more detailed discussion of these methods.