|
|||||||||
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:
startApp()
- the application is moving 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 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 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. 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 its 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 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. 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 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 through 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
applications's current screen, not the system screen. The value returned by
isShown()
returns false while the
current Displayable
is obscured by a system screen.
If the 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 Runnable.run() method
called later, serialized with the event stream. |
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 alert be made current, and that nextDisplayable be made current after the Alert is dismissed. |
void |
setCurrent(Displayable next)
Requests that a different Displayable object be made visible on the display. |
Methods inherited from class java.lang.Object |
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Method Detail |
public void callSerially(Runnable r)
Runnable
object r to have
its Runnable.run()
method
called later, serialized with the event stream. As noted in the
event delivery section of Canvas
, 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 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 */ ) {
// update to the next frame
repaint();
callSerially(this);
}
}
}
r
- instance of interface Runnable to be calledpublic Displayable getCurrent()
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 static Display getDisplay(MIDlet m)
m
- Midlet of the applicationpublic boolean isColor()
public int numColors()
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.
public void setCurrent(Alert alert, Displayable nextDisplayable)
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
dismissedAlert
public void setCurrent(Displayable next)
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 screen to be shown
after an Alert is dismissed, the application should use
setCurrent(Alert, Displayable)
.
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.
next
- the Displayable requested to be made current
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |