javax.microedition.lcdui
Class Display

java.lang.Object
  |
  +--javax.microedition.lcdui.Display

public class Display

extends Object

Display represents the manager of the display and input devices of the system. It includes methods for retrieving properties of the device and for requesting that objects be displayed on the device. Other methods that deal with device attributes are primarily used with Canvas objects and are thus defined there instead of here.

There is exactly one instance of Display per MIDlet and the application can get a reference to that instance by calling the getDisplay() method. The application may call the getDisplay() method from the beginning of the startApp() call until the destroyApp() call returns. The Display object returned by all calls to getDisplay() will remain the same during this time.

A typical application will perform the following actions in response to calls to its MIDlet methods:

• startApp - the application is moving from the paused state to the active state. Initialization of objects needed while the application is active should be done. The application may call setCurrent() for the first screen if that has not already been done. Note that startApp() can be called several times if pauseApp() has been called in between. This means that one-time initialization should not take place here but instead should occur within the MIDlet's constructor.
• pauseApp - the application may pause its threads. Also, if it is desirable to start with another screen when the application is re-activated, the new screen should be set with setCurrent().
• destroyApp - the application should free resources, terminate threads, etc. The behavior of method calls on user interface objects after destroyApp() has returned is undefined.

The user interface objects that are shown on the display device are contained within a Displayable object. At any time the application may have at most one Displayable object that it intends to be shown on the display device and through which user interaction occurs. This Displayable is referred to as the current Displayable.

The Display class has a setCurrent() method for setting the current Displayable and a getCurrent() method for retrieving the current Displayable. The application has control over its current Displayable and may call setCurrent() at any time. Typically, the application will change the current Displayable in response to some user action. This is not always the case, however. Another thread may change the current Displayable in response to some other stimulus. The current Displayable will also be changed when the timer for an Alert elapses.

The application's current Displayable may not physically be drawn on the screen, nor will user events (such as keystrokes) that occur necessarily be directed to the current Displayable. This may occur because of the presence of other MIDlet applications running simultaneously on the same device.

An application is said to be in the foreground if its current Displayable is actually visible on the display device and if user input device events will be delivered to it. If the application is not in the foreground, it lacks access to both the display and input devices, and it is said to be in the background. The policy for allocation of these devices to different MIDlet applications is outside the scope of this specification and is under the control of an external agent referred to as the application management software.

As mentioned above, the application still has a notion of its current Displayable even if it is in the background. The current Displayable is significant, even for background applications, because the current Displayable is always the one that will be shown the next time the application is brought into the foreground. The application can determine whether a Displayable is actually visible on the display by calling isShown(). In the case of Canvas, the showNotify() and hideNotify() methods are called when the Canvas is made visible and is hidden, respectively.

Each MIDlet application has its own current Displayable. This means that the getCurrent() method returns the MIDlet's current Displayable, regardless of the MIDlet's foreground/background state. For example, suppose a MIDlet running in the foreground has current Displayable F, and a MIDlet running in the background has current Displayable B. When the foreground MIDlet calls getCurrent(), it will return F, and when the background MIDlet calls getCurrent(), it will return B. Furthermore, if either MIDlet changes its current Displayable by calling setCurrent(), this will not affect the any other MIDlet's current Displayable.

It is possible for getCurrent() to return null. This may occur at startup time, before the MIDlet application has called setCurrent() on its first screen. The getCurrent() method will never return a reference to a Displayable object that was not passed in a prior call to setCurrent() call by this MIDlet.

System Screens

Typically, the current screen of the foreground MIDlet will be visible on the display. However, under certain circumstances, the system may create a screen that temporarily obscures the application's current screen. These screens are referred to as system screens. This may occur if the system needs to show a menu of commands or if the system requires the user to edit text on a separate screen instead of within a text field inside a Form. Even though the system screen obscures the application's screen, the notion of the current screen does not change. In particular, while a system screen is visible, a call to getCurrent() will return the application's current screen, not the system screen. The value returned by isShown() is false while the current Displayable is obscured by a system screen.

If system screen obscures a canvas, its hideNotify() method is called. When the system screen is removed, restoring the canvas, its showNotify() method and then its paint() method are called. If the system screen was used by the user to issue a command, the commandAction() method is called after showNotify() is called.

Method Summary

void	callSerially(Runnable r) Causes the Runnable object r to have its run() method called later, serialized with the event stream, soon after completion of the repaint cycle.
Displayable	getCurrent() Gets the current Displayable object for this MIDlet.
static Display	getDisplay(MIDlet m) Gets the Display object that is unique to this MIDlet.
boolean	isColor() Gets information about color support of the device.
int	numColors() Gets the number of colors (if isColor() is true) or graylevels (if isColor() is false) that can be represented on the device.
void	setCurrent(Alert alert, Displayable nextDisplayable) Requests that this Alert be made current, and that nextDisplayable be made current after the Alert is dismissed.
void	setCurrent(Displayable nextDisplayable) Requests that a different Displayable object be made visible on the display.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getDisplay

public static Display getDisplay(MIDlet m)

Gets the Display object that is unique to this MIDlet.

Parameters:

m - Midlet of the application

Returns:

the display object that application can use for its user interface

Throws:

NullPointerException - if m is null

isColor

public boolean isColor()

Gets information about color support of the device.

Returns:

true if the display supports color, false otherwise

numColors

public int numColors()

Gets the number of colors (if isColor() is true) or graylevels (if isColor() is false) that can be represented on the device.

Note that number of Colors for black and white display is 2.

Returns:

number of colors

getCurrent

public Displayable getCurrent()

Gets the current Displayable object for this MIDlet. The Displayable object returned may not actually be visible on the display if the MIDlet is running in the background, or if the Displayable is obscured by a system screen. The Displayable.isShown() method may be called to determine whether the Displayable is actually visible on the display.

The value returned by getCurrent() may be null. This occurs after the application has been initialized but before the first call to setCurrent().

Returns:

the MIDlet's current Displayable object

See Also:

setCurrent(javax.microedition.lcdui.Displayable)

setCurrent

public void setCurrent(Displayable nextDisplayable)

Requests that a different Displayable object be made visible on the display. The change will typically not take effect immediately. It may be delayed so that it occurs between event delivery method calls, although it is not guaranteed to occur before the next event delivery method is called. The setCurrent() method returns immediately, without waiting for the change to take place. Because of this delay, a call to getCurrent() shortly after a call to setCurrent() is unlikely to return the value passed to setCurrent().

Calls to setCurrent() are not queued. A delayed request made by a setCurrent() call may be superseded by a subsequent call to setCurrent(). For example, if screen S1 is current, then

    d.setCurrent(S2);
    d.setCurrent(S3);
 

may eventually result in S3 being made current, bypassing S2 entirely.

When a MIDlet application is first started, there is no current Displayable object. It is the responsibility of the application to ensure that a Displayable is visible and can interact with the user at all times. Therefore, the application should always call setCurrent() as part of its initialization.

The application may pass null as the argument to setCurrent(). This does not have the effect of setting the current Displayable to null; instead, the current Displayable remains unchanged. However, the application management software may interpret this call as a hint from the application that it is requesting to be placed into the background. Similarly, if the application is in the background, passing a non-null reference to setCurrent() may be interpreted by the application management software as a hint that the application is requesting to be brought to the foreground. The request should be considered to be made even if the current Displayable is passed to the setCurrent(). For example, the code

    d.setCurrent(d.getCurrent());
 

generally will have no effect other than requesting that the application be brought to the foreground. These requests are only hints, and there is no requirement that the application management software comply with these requests in a timely fashion if at all.

If the Displayable passed to setCurrent() is an Alert, the previous Displayable is restored after the Alert has been dismissed. The effect is as if setCurrent(Alert, getCurrent()) had been called. Note that this will result in an exception being thrown if the current Displayable is already an alert. To specify the Displayable to be shown after an Alert is dismissed, the application should use the setCurrent(Alert, Displayable) method. If the application calls setCurrent() while an Alert is current, the Alert is removed from the display and any timer it may have set is cancelled.

If the application calls setCurrent() while a system screen is active, the effect may be delayed until after the system screen is dismissed. The implementation may choose to interpret setCurrent() in such a situation as a request to cancel the effect of the system screen, regardless of whether setCurrent() has been delayed.

Parameters:

nextDisplayable - the Displayable requested to be made current; null is allowed

See Also:

getCurrent()

setCurrent

public void setCurrent(Alert alert,
                       Displayable nextDisplayable)

Requests that this Alert be made current, and that nextDisplayable be made current after the Alert is dismissed. This call returns immediately regardless of the Alert's timeout value or whether it is a modal alert. The nextDisplayable must not be an Alert, and it must not be null.

In other respects, this method behaves identically to setCurrent(Displayable).

Parameters:

alert - the alert to be shown

nextDisplayable - the Displayable to be shown after this alert is dismissed

Throws:

NullPointerException - if alert or nextDisplayable is null

IllegalArgumentException - if nextDisplayable is an Alert

See Also:

Alert, getCurrent()

callSerially

public void callSerially(Runnable r)

Causes the Runnable object r to have its run() method called later, serialized with the event stream, soon after completion of the repaint cycle. As noted in section on event delivery in the Canvas class, the methods that deliver event notifications to the current canvas are all called serially. The call to r.run() will be serialized along with the event calls on the current canvas. The run() method will be called exactly once for each call to callSerially(). Calls to run() will occur in the order in which they were requested by calls to callSerially().

If there is a repaint pending at the time of a call to callSerially(), the current Canvas's paint() method will be called and will return, and a buffer switch will occur (if double buffering is in effect), before the Runnable's run() method is called. Calls to the run() method will occur in a timely fashion, but they are not guaranteed to occur immediately after the repaint cycle finishes, or even before the next event is delivered.

The callSerially() method may be called from any thread. The call to the run() method will occur independently of the call to callSerially(). In particular, callSerially() will never block waiting for r.run() to return.

As with other callbacks, the call to r.run() must return quickly. If it is necessary to perform a long-running operation, it may be initiated from within the run() method. The operation itself should be performed within another thread, allowing run() to return.

The callSerially() facility may be used by applications to run an animation that is properly synchronized with the repaint cycle. A typical application will set up a frame to be displayed and then call repaint(). The application must then wait until the frame is actually displayed, after which the setup for the next frame may occur. The call to run() notifies the application that the previous frame has finished painting. The example below shows callSerially() being used for this purpose.

    class Animation extends Canvas implements Runnable {

        void paint(Graphics g) { ... } // paint the current frame

        void startAnimation() {
            // set up initial frame
            repaint();
            callSerially(this);
        }

        void run() { // called after previous repaint is finished
            if ( /* there are more frames */ ) {
                // set up the next frame
                repaint();
                callSerially(this);
            }
        }
     }
 

Parameters:

r - instance of interface Runnable to be called