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 starting from the paused 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() is 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 at most one Displayable object will be shown on the display device. This Displayable is referred to as the current Displayable.

The Display class has a setCurrent() method for setting the currently shown 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. However, 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 shown on the actual 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 device and input devices and 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 when the application is next brought into the foreground. Calling setCurrent() by an application in the background may be interpreted by the application management software as a hint that the application is requesting to be placed into the foreground. This is true even if setCurrent() is called on the Displayable that is already current. An application calling setCurrent(null) may be interpreted by the application management software as a hint that the application is requesting to be placed into the background. 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.

The application can determine whether a Displayable is really shown by calling isShown(). In the case of Canvas, the showNotify() and hideNotify() methods are called when the Canvas is made current and is no longer current, respectively.

The getCurrent() method returns the current screen of the MIDlet application, regardless of its foreground/background status. The value returned by getCurrent() is on a per-MIDlet basis. If a MIDlet application's current screen is S and another MIDlet application residing within the same JAR file is running in the foreground, the getCurrent() call will still return S.

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. It may also occur if the system has switched to a system screen (see below). 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 a MIDlet application is one that it as created and made current using setCurrent(). However, under certain circumstances, the system may create a screen and make it current instead. These screens are referred to as system screens. This may occur if the system needs to generate 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.

If the implementation makes a system screen current, and the previous Displayable was a Canvas, hideNotify() is called just as if the application had called setCurrent() on one of its own Displayables. While the system screen is current, the system maintains a notion of the previous Displayable that will be restored when the user has finished with the system screen. When that previous Displayable is restored, and if it is a Canvas, showNotify() will be called as just as if the application had called setCurrent() on it. If the system screen was used by the user to select a command to be issued, the command is issued after showNotify() is called.

If the application calls setCurrent() while a system screen is active, it takes effect immediately. The effect as if the system screen were cancelled (no command is issued, no updates to any text fields occur, etc.) The system's notion of the previous Displayable is discarded, the newly requested Displayable is made current, and processing proceeds without being affected by the presence of the system screen.

Method Summary

void	callSerially(Runnable obj) Causes the Callable object c to have its call() method called later, serialized with the event stream.
Displayable	getCurrent() Gets the Displayable object currently shown on the screen.
static Display	getDisplay(MIDlet c) 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 next) Shows this alert for the amount of time specified by the value of the alert's timeout field.
void	setCurrent(Displayable next) setCurrent() is called whenever application wants a different Displayable object to be shown as the current screen.

Methods inherited from class java.lang.Object

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

Method Detail

getDisplay

public static Display getDisplay(MIDlet c)

Gets the Display object that is unique to this MIDlet.

Parameters:

c - MIDlet holding the display.

Returns:

the display object that application can use for its user interface

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 Displayable object currently shown on the screen.

Returns:

Displayable object currently displayed on the screen. Return null, if the application has not a control over the display, for example when the application is a background application or when the display have temporarily taken over by the implementation. An example of the latter case would be implementation of Commands as a menu.

setCurrent

public void setCurrent(Displayable next)

setCurrent() is called whenever application wants a different Displayable object to be shown as the current screen. The change will not occur instantaneously. It is not guaranteed to happen before any more events have been delivered, but it will occur in the near future, between event deliveries. The effect is immediate in a sense that it may override the screens used by the implementation. For example, if the implementation of Commands is based on a separate screen containing menu-options, the menu screen is overridden by the new screen.

The method setCurrent returns immediately.

The current screen may be null. This occurs after the application has been initialized but before the first call to setCurrent(), and it may also occur if the application calls setCurrent(null). It is the responsibility of the application to ensure that a Displayable is visible and can interact with the user.

If the current screen is null, the user has no access to display, any Commands or other interactable user interface elements. Such application is considered to be in background and the application manager may still let it continue running.

If the application sets the current screen to null, the application moves to background, and the application management software may use it has a hint and take over the display. Similarly, if application is in background, setCurrent() to non-null Displayable hint the application management software that the application wants to come to the foreground.

If the screen is Alert the previous screen is set back to current when the time-out of the Alert has expired. If it is necessary to specify the screen to be shown after Alert disappears setCurrent(Alert, Displayable) must be used.

Parameters:

next - the screen to which to advance after this alert is shown.

setCurrent

public void setCurrent(Alert alert,
                       Displayable next)

Shows this alert for the amount of time specified by the value of the alert's timeout field. The alert takes over the screen and keyboard for the time during which it is shown. When the time expires, the screen specified by nextDisplayable is shown.

This call returns immediately regardless of the Alert's timeout value. This is necessary because Alerts are typically called from CommandListener callbacks and these callbacks must return immediately.

If the application calls setCurrent while an alert is shown, the Alert disappears and timer is cancelled. If the application calls setCurrent, while an alert is shown, the Alert disappears and timer is cancelled.

Parameters:

alert - the alert screen

next - the screen to which to advance after this alert is shown

See Also:

Alert

callSerially

public void callSerially(Runnable obj)

Causes the Callable object c to have its call() method called later, serialized with the event stream. As noted in Canvas, the methods that deliver event notifications to the current canvas are all called serially. The call to c.call() will be serialized along with the event calls on the current canvas. The call() method will be called exactly once for each call to callSerially(). Calls to call() will occur in the order in which they were requested by calls to callSerially().

In addition, 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 before the callable's call() method is called.

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

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

The callSerially() facility may be used by applications to have themselves called back in a manner appropriate for running 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 - by the Canvas's paint call() - at which time the setup for the next frame may occur. The example below shows callSerially() being used for this purpose.

 class Animation extends Canvas implements Callable {

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

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

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

Parameters:

obj - instance of interface Callable that is called by the implementation