BenQ Mobile

javax.microedition.lcdui
Class Display

java.lang.Object
  extended byjavax.microedition.lcdui.Display

public class Display
extends java.lang.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:

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.


Field Summary
static int ALERT
           
static int CHOICE_GROUP_ELEMENT
           
static int COLOR_BACKGROUND
           
static int COLOR_BORDER
           
static int COLOR_FOREGROUND
           
static int COLOR_HIGHLIGHTED_BACKGROUND
           
static int COLOR_HIGHLIGHTED_BORDER
           
static int COLOR_HIGHLIGHTED_FOREGROUND
           
static int LIST_ELEMENT
           
 
Method Summary
 void callSerially(java.lang.Runnable c)
           Causes the Callable object c to have its call() method called later, serialized with the event stream.
 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/nonhighlighted).
 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 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 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)
          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.
 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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COLOR_BACKGROUND

public static final int COLOR_BACKGROUND
See Also:
Constant Field Values

COLOR_FOREGROUND

public static final int COLOR_FOREGROUND
See Also:
Constant Field Values

COLOR_HIGHLIGHTED_BACKGROUND

public static final int COLOR_HIGHLIGHTED_BACKGROUND
See Also:
Constant Field Values

COLOR_HIGHLIGHTED_FOREGROUND

public static final int COLOR_HIGHLIGHTED_FOREGROUND
See Also:
Constant Field Values

COLOR_BORDER

public static final int COLOR_BORDER
See Also:
Constant Field Values

COLOR_HIGHLIGHTED_BORDER

public static final int COLOR_HIGHLIGHTED_BORDER
See Also:
Constant Field Values

LIST_ELEMENT

public static final int LIST_ELEMENT
See Also:
Constant Field Values

CHOICE_GROUP_ELEMENT

public static final int CHOICE_GROUP_ELEMENT
See Also:
Constant Field Values

ALERT

public static final int ALERT
See Also:
Constant Field Values
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

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:
java.lang.IllegalArgumentException - if duration is negative
Since:
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 LIST_ELEMENT, CHOICE_GROUP_ELEMENT, or 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:
java.lang.IllegalArgumentException - if imageType is illegal
Since:
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 LIST_ELEMENT, CHOICE_GROUP_ELEMENT, or 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:
java.lang.IllegalArgumentException - if imageType is illegal
Since:
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/nonhighlighted).

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:
MIDP 2.0

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 COLOR_BACKGROUND, COLOR_FOREGROUND, COLOR_HIGHLIGHTED_BACKGROUND, COLOR_HIGHLIGHTED_FOREGROUND, COLOR_BORDER, or COLOR_HIGHLIGHTED_BORDER
Returns:
color in the form of 0x00RRGGBB
Throws:
java.lang.IllegalArgumentException - if colorSpecifier is not a valid color specifier
Since:
MIDP 2.0

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:
MIDP 2.0

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 nextDisplayable)
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
nextDisplayable - the screen to which to advance after this alert is shown
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:
java.lang.IllegalStateException - if the item is not owned by a container
java.lang.IllegalStateException - if the item is owned by an Alert
java.lang.NullPointerException - if item is null
Since:
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:
java.lang.IllegalArgumentException - if duration is negative
Since:
MIDP 2.0

callSerially

public void callSerially(java.lang.Runnable c)

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:
c - instance of interface Callable that is called by the implementation

BenQ Mobile

Copyright © 2006 BenQ Mobile GmbH & Co. OHG or respective copyright owner.
All Rights Reserved.
BenQ Corp. is a trademark licensee of Siemens AG.


For further information about Mobility Toolkit (MTK) visit our Developer Portal.