|
MID Profile | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object | +--javax.microedition.lcdui.Display
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:
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.
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.
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 |
public static Display getDisplay(MIDlet m)
m - Midlet of the applicationpublic boolean isColor()
public int numColors()
Note that number of Colors for black and white display is 2.
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().
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.
nextDisplayable - the Displayable requested to be made current;
null is allowed
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).
alert - the alert to be shownnextDisplayable - the Displayable to be shown after this alert is
dismissedAlertpublic 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);
}
}
}
r - instance of interface Runnable to be called
|
MID Profile | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||