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.

This class contains methods to retrieve the prevailing foreground and background colors of the high-level user interface. These methods are useful for creating CustomItem objects that match the user interface of other items and for creating user interfaces within Canvas that match the user interface of the rest of the system. Implementations are not restricted to using foreground and background colors in their user interfaces (for example, they might use highlight and shadow colors for a beveling effect) but the colors returned are those that match reasonably well with the implementation's color scheme. An application implementing a custom item should use the background color to clear its region and then paint text and geometric graphics (lines, arcs, rectangles) in the foreground color.

RIM Implementation Notes

On BlackBerry devices running handheld software version 4.7 or greater, the Display object returned by Display.getDisplay(MIDlet) can be cast to a Controllable object which can be used to access BlackBerry-specific Control classes.

For instance, on devices which support multiple screen orientations, the Display class may return an DirectionControl which can be used to control the orientation of the foreground MIDlet.

Since:

MIDP 1.0

Field Summary
static int	ALERT Image type for Alert image.
static int	CHOICE_GROUP_ELEMENT Image type for ChoiceGroup element image.
static int	COLOR_BACKGROUND A color specifier for use with getColor.
static int	COLOR_BORDER A color specifier for use with getColor.
static int	COLOR_FOREGROUND A color specifier for use with getColor.
static int	COLOR_HIGHLIGHTED_BACKGROUND A color specifier for use with getColor.
static int	COLOR_HIGHLIGHTED_BORDER A color specifier for use with getColor.
static int	COLOR_HIGHLIGHTED_FOREGROUND A color specifier for use with getColor.
static int	LIST_ELEMENT Image type for List element image.

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.
boolean	flashBacklight(int duration) Requests a flashing effect for the device's backlight.
int	getBestImageHeight(int imageType) Returns the best image height for a given image type.
int	getBestImageWidth(int imageType) Returns the best image width for a given image type.
int	getBorderStyle(boolean highlighted) Returns the stroke style used for border drawing depending on the state of the component (highlighted/non-highlighted).
int	getColor(int colorSpecifier) Returns one of the colors from the high level user interface color scheme, in the form 0x00RRGGBB based on the colorSpecifier passed in.
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	numAlphaLevels() Gets the number of alpha transparency levels supported by this implementation.
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.
void	setCurrentItem(Item item) Requests that the Displayable that contains this Item be made current, scrolls the Displayable so that this Item is visible, and possibly assigns the focus to this Item.
boolean	vibrate(int duration) Requests operation of the device's vibrator.

Methods inherited from class java.lang.Object

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

Field Detail

LIST_ELEMENT

public static final int LIST_ELEMENT

Image type for List element image.

The value of LIST_ELEMENT is 1.

See Also:

Display.getBestImageWidth(int imageType), Display.getBestImageHeight(int imageType), Constant Field Values

Since:

BlackBerry API 4.0.0, MIDP 2.0

CHOICE_GROUP_ELEMENT

public static final int CHOICE_GROUP_ELEMENT

Image type for ChoiceGroup element image.

The value of CHOICE_GROUP_ELEMENT is 2.

See Also:

Display.getBestImageWidth(int imageType), Display.getBestImageHeight(int imageType), Constant Field Values

Since:

BlackBerry API 4.0.0, MIDP 2.0

ALERT

public static final int ALERT

Image type for Alert image.

The value of ALERT is 3.

See Also:

Display.getBestImageWidth(int imageType), Display.getBestImageHeight(int imageType), Constant Field Values

Since:

BlackBerry API 4.0.0, MIDP 2.0

COLOR_BACKGROUND

public static final int COLOR_BACKGROUND

A color specifier for use with getColor. COLOR_BACKGROUND specifies the background color of the screen. The background color will always contrast with the foreground color.

COLOR_BACKGROUND has the value 0.

See Also:

Display.getColor(int), Constant Field Values

Since:

BlackBerry API 4.0.0, MIDP 2.0

COLOR_FOREGROUND

public static final int COLOR_FOREGROUND

A color specifier for use with getColor. COLOR_FOREGROUND specifies the foreground color, for text characters and simple graphics on the screen. Static text or user-editable text should be drawn with the foreground color. The foreground color will always constrast with background color.

COLOR_FOREGROUND has the value 1.

See Also:

Display.getColor(int), Constant Field Values

Since:

BlackBerry API 4.0.0, MIDP 2.0

COLOR_HIGHLIGHTED_BACKGROUND

public static final int COLOR_HIGHLIGHTED_BACKGROUND

A color specifier for use with getColor. COLOR_HIGHLIGHTED_BACKGROUND identifies the color for the focus, or focus highlight, when it is drawn as a filled in rectangle. The highlighted background will always constrast with the highlighted foreground.

COLOR_HIGHLIGHTED_BACKGROUND has the value 2.

See Also:

Display.getColor(int), Constant Field Values

Since:

BlackBerry API 4.0.0, MIDP 2.0

COLOR_HIGHLIGHTED_FOREGROUND

public static final int COLOR_HIGHLIGHTED_FOREGROUND

A color specifier for use with getColor. COLOR_HIGHLIGHTED_FOREGROUND identifies the color for text characters and simple graphics when they are highlighted. Highlighted foreground is the color to be used to draw the highlighted text and graphics against the highlighted background. The highlighted foreground will always constrast with the highlighted background.

COLOR_HIGHLIGHTED_FOREGROUND has the value 3.

See Also:

Display.getColor(int), Constant Field Values

Since:

BlackBerry API 4.0.0, MIDP 2.0

COLOR_BORDER

public static final int COLOR_BORDER

A color specifier for use with getColor. COLOR_BORDER identifies the color for boxes and borders when the object is to be drawn in a non-highlighted state. The border color is intended to be used with the background color and will contrast with it. The application should draw its borders using the stroke style returned by getBorderStyle().

COLOR_BORDER has the value 4.

See Also:

Display.getColor(int), Constant Field Values

Since:

BlackBerry API 4.0.0, MIDP 2.0

COLOR_HIGHLIGHTED_BORDER

public static final int COLOR_HIGHLIGHTED_BORDER

A color specifier for use with getColor. COLOR_HIGHLIGHTED_BORDER identifies the color for boxes and borders when the object is to be drawn in a highlighted state. The highlighted border color is intended to be used with the background color (not the highlighted background color) and will contrast with it. The application should draw its borders using the stroke style returned by getBorderStyle().

COLOR_HIGHLIGHTED_BORDER has the value 5.

See Also:

Display.getColor(int), Constant Field Values

Since:

BlackBerry API 4.0.0, MIDP 2.0

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

getColor

public int getColor(int colorSpecifier)

Returns one of the colors from the high level user interface color scheme, in the form 0x00RRGGBB based on the colorSpecifier passed in.

Parameters:

colorSpecifier - the predefined color specifier; must be one of Display.COLOR_BACKGROUND, Display.COLOR_FOREGROUND, Display.COLOR_HIGHLIGHTED_BACKGROUND, Display.COLOR_HIGHLIGHTED_FOREGROUND, Display.COLOR_BORDER, or Display.COLOR_HIGHLIGHTED_BORDER

Returns:

color in the form of 0x00RRGGBB

Throws:

IllegalArgumentException - if colorSpecifier is not a valid color specifier

Since:

BlackBerry API 4.0.0, MIDP 2.0

getBorderStyle

public int getBorderStyle(boolean highlighted)

Returns the stroke style used for border drawing depending on the state of the component (highlighted/non-highlighted). For example, on a monochrome system, the border around a non-highlighted item might be drawn with a DOTTED stroke style while the border around a highlighted item might be drawn with a SOLID stroke style.

Parameters:

highlighted - true if the border style being requested is for the highlighted state, false if the border style being requested is for the non-highlighted state

Returns:

Graphics.DOTTED or Graphics.SOLID

Since:

BlackBerry API 4.0.0, MIDP 2.0

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

numAlphaLevels

public int numAlphaLevels()

Gets the number of alpha transparency levels supported by this implementation. The minimum legal return value is 2, which indicates support for full transparency and full opacity and no blending. Return values greater than 2 indicate that alpha blending is supported. For further information, see Alpha Processing.

Returns:

number of alpha levels supported

Since:

BlackBerry API 4.0.0, MIDP 2.0

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

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

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.

The automatic advance to nextDisplayable occurs only when the Alert's default listener is present on the Alert when it is dismissed. See Alert Commands and Listeners for details.

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

setCurrentItem

public void setCurrentItem(Item item)

Requests that the Displayable that contains this Item be made current, scrolls the Displayable so that this Item is visible, and possibly assigns the focus to this Item. The containing Displayable is first made current as if setCurrent(Displayable) had been called. When the containing Displayable becomes current, or if it is already current, it is scrolled if necessary so that the requested Item is made visible. Then, if the implementation supports the notion of input focus, and if the Item accepts the input focus, the input focus is assigned to the Item.

This method always returns immediately, without waiting for the switching of the Displayable, the scrolling, and the assignment of input focus to take place.

It is an error for the Item not to be contained within a container. It is also an error if the Item is contained within an Alert.

Parameters:

item - the item that should be made visible

Throws:

IllegalStateException - if the item is not owned by a container

IllegalStateException - if the item is owned by an Alert

NullPointerException - if item is null

Since:

BlackBerry API 4.0.0, MIDP 2.0

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

flashBacklight

public boolean flashBacklight(int duration)

Requests a flashing effect for the device's backlight. The flashing effect is intended to be used to attract the user's attention or as a special effect for games. Examples of flashing are cycling the backlight on and off or from dim to bright repeatedly. The return value indicates if the flashing of the backlight can be controlled by the application.

The flashing effect occurs for the requested duration, or it is switched off if the requested duration is zero. This method returns immediately; that is, it must not block the caller while the flashing effect is running.

Calls to this method are honored only if the Display is in the foreground. This method MUST perform no action and return false if the Display is in the background.

The device MAY limit or override the duration. For devices that do not include a controllable backlight, calls to this method return false.

Parameters:

duration - the number of milliseconds the backlight should be flashed, or zero if the flashing should be stopped

Returns:

true if the backlight can be controlled by the application and this display is in the foreground, false otherwise

Throws:

IllegalArgumentException - if duration is negative

Since:

BlackBerry API 4.0.0, MIDP 2.0

vibrate

public boolean vibrate(int duration)

Requests operation of the device's vibrator. The vibrator is intended to be used to attract the user's attention or as a special effect for games. The return value indicates if the vibrator can be controlled by the application.

This method switches on the vibrator for the requested duration, or switches it off if the requested duration is zero. If this method is called while the vibrator is still activated from a previous call, the request is interpreted as setting a new duration. It is not interpreted as adding additional time to the original request. This method returns immediately; that is, it must not block the caller while the vibrator is running.

Calls to this method are honored only if the Display is in the foreground. This method MUST perform no action and return false if the Display is in the background.

The device MAY limit or override the duration. For devices that do not include a controllable vibrator, calls to this method return false.

Parameters:

duration - the number of milliseconds the vibrator should be run, or zero if the vibrator should be turned off

Returns:

true if the vibrator can be controlled by the application and this display is in the foreground, false otherwise

Throws:

IllegalArgumentException - if duration is negative

Since:

BlackBerry API 4.0.0, MIDP 2.0

getBestImageWidth

public int getBestImageWidth(int imageType)

Returns the best image width for a given image type. The image type must be one of Display.LIST_ELEMENT, Display.CHOICE_GROUP_ELEMENT, or Display.ALERT.

Parameters:

imageType - the image type

Returns:

the best image width for the image type, may be zero if there is no best size; must not be negative

Throws:

IllegalArgumentException - if imageType is illegal

Since:

BlackBerry API 4.0.0, MIDP 2.0

getBestImageHeight

public int getBestImageHeight(int imageType)

Returns the best image height for a given image type. The image type must be one of Display.LIST_ELEMENT, Display.CHOICE_GROUP_ELEMENT, or Display.ALERT.

Parameters:

imageType - the image type

Returns:

the best image height for the image type, may be zero if there is no best size; must not be negative

Throws:

IllegalArgumentException - if imageType is illegal

Since:

BlackBerry API 4.0.0, MIDP 2.0