com.motorola.iden.lcdui
Class ExternalDisplay

java.lang.Object
  |
  +--com.motorola.iden.lcdui.ExternalDisplay

public class ExternalDisplay

extends java.lang.Object

ExternalDisplay represents the manager of the external display and input devices of the system when the external display is active. It includes methods for retrieving properties of the device and for requesting that objects be displayed on the device. There is exactly one instance of Display per ExtDisplayEventHandler and the application can get a reference to that instance by calling the getDisplay() method. The application may call the getDisplay() method from anywhere until the destroyApp() call returns. The ExternalDisplay object returned by all calls to getDisplay() will remain the same during this time.

The user interface objects that are shown on the external 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 external display device and through which user interaction occurs. This Displayable is referred to as the current Displayable.

The ExternalDisplay class has a 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 implementation only supports two types of Displayables. The supported Displayables are Alert and Canvas. If the method setCurrent(Displayable) is called with a reference to a Displayable other than any of the supported types, the request to change the Displayable will be ignored.

The current Displayable is always significant, even for applications that do not have control over the external display device. The current Displayable is always the one that will be shown when the application gains control over the external display device. An 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.

See Also:

ExtDisplayEventHandler, javax.microedition.lcdui.Display

Method Summary

Displayable	getCurrent() Gets the current Displayable object associated with the external display for this MIDlet.
static ExternalDisplay	getDisplay(MIDlet m) Gets the ExternalDisplay object that is unique to this MIDlet.
boolean	getFlipState() Returns what the current state of the flip is.
static int	getHeight() Retrives the External Display's width
static int	getWidth() Retrives the External Display's width
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	releaseDisplay() Tells the AMS that the midlet no longer needs access to the External Display.
void	requestDisplay() Requests to the AMS to gain access to the external display.
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 external display.

Methods inherited from class java.lang.Object

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

Method Detail

requestDisplay

public void requestDisplay()

Requests to the AMS to gain access to the external display. If the ExternalDisplay object already has access to the external Display then nothing shall happen.

When the Displayable associated with the ExternalDisplay is a Canvas the Displayable is notified it has gained focus to the external Display by having it's showNotify called. There is no guarantee as to when if ever in the future the request shall be granted to the application.

If the Displayable associated with the ExternalDisplay is an Alert, the AMS shall try it's best to alert the user at the earliest opportunity it can.

releaseDisplay

public void releaseDisplay()

Tells the AMS that the midlet no longer needs access to the External Display. If the midlet made a request and it has not been serviced yet then the request shall be removed.

When the Displayable associated with the ExternalDisplay is a Canvas the Displayable is notified it has lost focus to the external Display by having it's hideNotify called.

getFlipState

public boolean getFlipState()

Returns what the current state of the flip is.

Returns:

true if the flip is currently closed, false if the flip is currently open.

getWidth

public static int getWidth()

Retrives the External Display's width

Returns:

the width of the External Display.

getHeight

public static int getHeight()

Retrives the External Display's width

Returns:

the height of the External Display.

getCurrent

public Displayable getCurrent()

Gets the current Displayable object associated with the external display for this MIDlet. The Displayable object returned may not actually be visible. The 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 associated with the external display

getDisplay

public static ExternalDisplay getDisplay(MIDlet m)

Gets the ExternalDisplay object that is unique to this MIDlet.

Parameters:

m - the midlet that this ExternalDisplay object belongs to

Returns:

the External Display object that the application can use for its user interface

Throws:

java.lang.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 that can be displayed on the device

setCurrent

public void setCurrent(Alert alert,
                       Displayable nextDisplayable)

Requests that 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. 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:

java.lang.NullPointerException - if alert or nextDisplayable is null

java.lang.IllegalArgumentException - if nextDisplayable is an Alert

java.lang.IllegalArgumentException - if nextDisplayable is not a subclass of ExternalDisplayCanvas

See Also:

Alert

setCurrent

public void setCurrent(Displayable next)

Requests that a different Displayable object be made visible on the external 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.

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 Displayable passed to setCurrent() is not of type ExternalDisplayCanvas then an IllegalArgumentException shall be thrown, due to the fact that the ExternalDisplay class only supports a displayable of ExternalDisplayCanvas.

Parameters:

next - the Displayable requested to be made current

Throws:

java.lang.NullPointerException - if next is null

java.lang.IllegalArgumentException - if next is not a subclass of ExternalDisplayCanvas