org.j4me.ui
Class DeviceScreen

java.lang.Object
  extended by org.j4me.ui.DeviceScreen
Direct Known Subclasses:
Dialog

public abstract class DeviceScreen
extends java.lang.Object

The DeviceScreen class is a base class for any screen that needs complete control over how it is painted. It is based on and similar to the MIDP Canvas class.

This class removes the following methods from the MIDP Canvas class:

See Also:
Canvas

Field Summary
static int DOWN
          Constant for the DOWN game action.
static int FIRE
          Constant for the FIRE game action.
static int GAME_A
          Constant for the general purpose "A" game action.
static int GAME_B
          Constant for the general purpose "B" game action.
static int GAME_C
          Constant for the general purpose "C" game action.
static int GAME_D
          Constant for the general purpose "D" game action.
static int KEY_NUM0
          keyCode for ITU-T key 0.
static int KEY_NUM1
          keyCode for ITU-T key 1.
static int KEY_NUM2
          keyCode for ITU-T key 2.
static int KEY_NUM3
          keyCode for ITU-T key 3.
static int KEY_NUM4
          keyCode for ITU-T key 4.
static int KEY_NUM5
          keyCode for ITU-T key 5.
static int KEY_NUM6
          keyCode for ITU-T key 6.
static int KEY_NUM7
          keyCode for ITU-T key 7.
static int KEY_NUM8
          keyCode for ITU-T key 8.
static int KEY_NUM9
          keyCode for ITU-T key 9.
static int KEY_POUND
          keyCode for ITU-T key "pound" (#).
static int KEY_STAR
          keyCode for ITU-T key "star" (*).
static int LEFT
          Constant for the LEFT game action.
static int MENU_LEFT
          Constant for the left soft menu key found on MIDP 2.0 devices.
static int MENU_RIGHT
          Constant for the right soft menu key found on MIDP 2.0 devices.
static int RIGHT
          Constant for the RIGHT game action.
static int UP
          Constant for the UP game action.
 
Constructor Summary
DeviceScreen()
          Implicitly called by derived classes to setup a new J4ME canvas.
 
Method Summary
protected  void acceptNotify()
          Method called by the framework when the user clicks the right menu button.
protected  void declineNotify()
          Method called by the framework when the user clicks on the left menu button.
 javax.microedition.lcdui.Canvas getCanvas()
          Returns the LCDUI Canvas wrapped by this screen.
 int getHeight()
          Returns the height of the usuable portion of this canvas.
 java.lang.String getLeftMenuText()
          Returns the text for the left menu button.
 java.lang.String getRightMenuText()
          Returns the text for the right menu button.
 int getScreenHeight()
          Gets the height of the entire screen in pixels.
 int getScreenWidth()
          Gets the width of the entire screen in pixels.
 java.lang.String getTitle()
          Gets the title of this screen.
 int getWidth()
          Returns the width of the usuable portion of this canvas.
 boolean hasMenuBar()
          Returns if this screen displays a menu bar at the bottom.
 boolean hasTitleBar()
          Returns if this screen displays a title bar at the top.
 void hideNotify()
          The implementation calls hideNotify() shortly after the Canvas has been removed from the display.
static boolean intersects(javax.microedition.lcdui.Graphics g, int x, int y, int w, int h)
          Returns if the clip area of g intersects the given rectangle.
 boolean isFullScreenMode()
          Returns if the title bar and menu bar are hidden or not.
 boolean isShown()
          Checks if this screen is actually visible on the display.
protected  void keyPressed(int keyCode)
          Called when a key is pressed.
protected  void keyReleased(int keyCode)
          Called when a key is released.
protected  void keyRepeated(int keyCode)
          Called when a key is repeated (held down).
protected abstract  void paint(javax.microedition.lcdui.Graphics g)
          Paints the main section of the screen.
protected  void paintBackground(javax.microedition.lcdui.Graphics g)
          Paints the background of the main section of the screen.
protected  void paintMenuBar(javax.microedition.lcdui.Graphics g, java.lang.String left, boolean highlightLeft, java.lang.String right, boolean highlightRight, int width, int height)
          Paints the menu bar at the bottom of the canvas.
protected  void paintTitleBar(javax.microedition.lcdui.Graphics g, java.lang.String title, int width, int height)
          Paints the title bar of the canvas.
protected  void pointerDragged(int x, int y)
          Called when the pointer is dragged.
protected  void pointerPressed(int x, int y)
          Called when the pointer is pressed.
protected  void pointerReleased(int x, int y)
          Called when the pointer is released.
 void repaint()
          Requests a repaint for the entire Canvas.
 void repaint(int x, int y, int width, int height)
          Requests a repaint for the specified region of the Canvas.
 void serviceRepaints()
          Forces any pending repaint requests to be serviced immediately.
 void setFullScreenMode(boolean mode)
          Shows or hides the menu bar at the bottom of the screen.
 void setMenuText(java.lang.String left, java.lang.String right)
          Sets the menu bar text.
 void setTitle(java.lang.String title)
          Sets the title of this screen.
 void show()
          Makes this object take over the device's screen.
 void showNotify()
          The implementation calls showNotify() immediately prior to this Canvas being made visible on the display.
 java.lang.String toString()
          Returns the title of this screen.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LEFT

public static final int LEFT
Constant for the LEFT game action.

See Also:
Constant Field Values

RIGHT

public static final int RIGHT
Constant for the RIGHT game action.

See Also:
Constant Field Values

UP

public static final int UP
Constant for the UP game action.

See Also:
Constant Field Values

DOWN

public static final int DOWN
Constant for the DOWN game action.

See Also:
Constant Field Values

FIRE

public static final int FIRE
Constant for the FIRE game action.

See Also:
Constant Field Values

GAME_A

public static final int GAME_A
Constant for the general purpose "A" game action.

See Also:
Constant Field Values

GAME_B

public static final int GAME_B
Constant for the general purpose "B" game action.

See Also:
Constant Field Values

GAME_C

public static final int GAME_C
Constant for the general purpose "C" game action.

See Also:
Constant Field Values

GAME_D

public static final int GAME_D
Constant for the general purpose "D" game action.

See Also:
Constant Field Values

KEY_NUM0

public static final int KEY_NUM0
keyCode for ITU-T key 0.

Constant value 48 is set to KEY_NUM0.

See Also:
Constant Field Values

KEY_NUM1

public static final int KEY_NUM1
keyCode for ITU-T key 1.

Constant value 49 is set to KEY_NUM1.

See Also:
Constant Field Values

KEY_NUM2

public static final int KEY_NUM2
keyCode for ITU-T key 2.

Constant value 50 is set to KEY_NUM2.

See Also:
Constant Field Values

KEY_NUM3

public static final int KEY_NUM3
keyCode for ITU-T key 3.

Constant value 51 is set to KEY_NUM3.

See Also:
Constant Field Values

KEY_NUM4

public static final int KEY_NUM4
keyCode for ITU-T key 4.

Constant value 52 is set to KEY_NUM4.

See Also:
Constant Field Values

KEY_NUM5

public static final int KEY_NUM5
keyCode for ITU-T key 5.

Constant value 53 is set to KEY_NUM5.

See Also:
Constant Field Values

KEY_NUM6

public static final int KEY_NUM6
keyCode for ITU-T key 6.

Constant value 54 is set to KEY_NUM6.

See Also:
Constant Field Values

KEY_NUM7

public static final int KEY_NUM7
keyCode for ITU-T key 7.

Constant value 55 is set to KEY_NUM7.

See Also:
Constant Field Values

KEY_NUM8

public static final int KEY_NUM8
keyCode for ITU-T key 8.

Constant value 56 is set to KEY_NUM8.

See Also:
Constant Field Values

KEY_NUM9

public static final int KEY_NUM9
keyCode for ITU-T key 9.

Constant value 57 is set to KEY_NUM9.

See Also:
Constant Field Values

KEY_POUND

public static final int KEY_POUND
keyCode for ITU-T key "pound" (#).

Constant value 35 is set to KEY_POUND.

See Also:
Constant Field Values

KEY_STAR

public static final int KEY_STAR
keyCode for ITU-T key "star" (*).

Constant value 42 is set to KEY_STAR.

See Also:
Constant Field Values

MENU_LEFT

public static final int MENU_LEFT
Constant for the left soft menu key found on MIDP 2.0 devices.

See Also:
Constant Field Values

MENU_RIGHT

public static final int MENU_RIGHT
Constant for the right soft menu key found on MIDP 2.0 devices.

See Also:
Constant Field Values
Constructor Detail

DeviceScreen

public DeviceScreen()
Implicitly called by derived classes to setup a new J4ME canvas.

Method Detail

getCanvas

public javax.microedition.lcdui.Canvas getCanvas()
Returns the LCDUI Canvas wrapped by this screen. This is required for some APIs.

Returns:
The javax.microedition.lcdui.Canvas wrapped by this screen.

show

public void show()
Makes this object take over the device's screen.

The previous screen will have its hideNotify method called. Then this screen's showNotify method will be invoked followed by the paint method.


isShown

public boolean isShown()
Checks if this screen is actually visible on the display. In order for a screen to be visible, all of the following must be true: the MIDlet must be running in the foreground, the screen must be the current one, and the screen must not be obscured by a system screen.

Returns:
true if this screen is currently visible; false otherwise.

showNotify

public void showNotify()
The implementation calls showNotify() immediately prior to this Canvas being made visible on the display. Canvas subclasses may override this method to perform tasks before being shown, such as setting up animations, starting timers, etc. The default implementation of this method in class Canvas is empty.


hideNotify

public void hideNotify()
The implementation calls hideNotify() shortly after the Canvas has been removed from the display. Canvas subclasses may override this method in order to pause animations, revoke timers, etc. The default implementation of this method in class Canvas is empty.


setFullScreenMode

public void setFullScreenMode(boolean mode)
Shows or hides the menu bar at the bottom of the screen.

Parameters:
mode - is true if the DeviceScreen is to be in full screen mode, false otherwise.

isFullScreenMode

public boolean isFullScreenMode()
Returns if the title bar and menu bar are hidden or not.

Returns:
true if in full screen mode (title bar and menu bar are hidden); false otherwise.

getTitle

public java.lang.String getTitle()
Gets the title of this screen. If this returns null the screen has no title.

Returns:
The title of this screen.

setTitle

public void setTitle(java.lang.String title)
Sets the title of this screen. The default is null meaning no title.

For the title to be visible full screen mode must be off. This can be done with the setFullScreenMode method.

Parameters:
title - is the new title for the screen.

hasTitleBar

public boolean hasTitleBar()
Returns if this screen displays a title bar at the top. Title bars require both setting a title (through setTitle) and that full screen mode is off (setFullScreenMode(false)).

Returns:
true if the screen has a title bar; false if it does not.

toString

public java.lang.String toString()
Returns the title of this screen.

Overrides:
toString in class java.lang.Object
Returns:
The title of this screen. If no title is set this returns the empty string "".

setMenuText

public void setMenuText(java.lang.String left,
                        java.lang.String right)
Sets the menu bar text.

For the menu to be visible full screen mode must be off. This can be done with the setFullScreenMode method.

Parameters:
left - is the text for the negative menu option or null to remove the button. Negative menu options are things like canceling a form and moving back to a previous screen.
right - is the text for the positive menu option or null to remove the button. Positive menu options are things like accepting a form, advancing to the next screen, or displaying a menu.
See Also:
declineNotify(), acceptNotify()

getLeftMenuText

public java.lang.String getLeftMenuText()
Returns the text for the left menu button. The left menu button is for negative operations such as canceling a form and going back to a previous screen.

Returns:
The text for the left menu button. If there is no button this returns null.

getRightMenuText

public java.lang.String getRightMenuText()
Returns the text for the right menu button. The right menu button is for positive operations such as accepting a form and opening a menu.

Returns:
The text for the right menu button. If there is no button this returns null.

hasMenuBar

public boolean hasMenuBar()
Returns if this screen displays a menu bar at the bottom. Menu bars require both setting at least one menu option (through setMenuText) and that full screen mode is off (setFullScreenMode(false)).

Returns:
true if the screen has a menu bar; false if it does not.

getWidth

public int getWidth()
Returns the width of the usuable portion of this canvas. The usable portion excludes anything on the sides of the screen such as scroll bars.

Returns:
The number of pixels wide the usable portion of the canvas is.

getHeight

public int getHeight()
Returns the height of the usuable portion of this canvas. The usable portion excludes the title area and menu bar unless this canvas has been set to full screen mode.

Returns:
The number of pixels high the usable portion of the canvas is.

getScreenWidth

public int getScreenWidth()
Gets the width of the entire screen in pixels.

Platform bug note. Motorola and early Nokia phones return the incorrect size until after the first screen has actually been displayed. So, for example, calling this from a constructor before any screen has been displayed will give incorrect data. The workaround is to put up another screen first, such as a splash screen.

Returns:
The number of pixels wide the entire screen is.

getScreenHeight

public int getScreenHeight()
Gets the height of the entire screen in pixels. This includes the title area at the top of the screen and menu bar at the bottom. Use getHeight to get the actual usable area of the canvas.

Platform bug note. Motorola and early Nokia phones return the incorrect size until after the first screen has actually been displayed. So, for example, calling this from a constructor before any screen has been displayed will give incorrect data. The workaround is to put up another screen first, such as a splash screen.

Returns:
The number of pixels high the entire screen is.

declineNotify

protected void declineNotify()
Method called by the framework when the user clicks on the left menu button. The default implementation does nothing.

See Also:
getLeftMenuText()

acceptNotify

protected void acceptNotify()
Method called by the framework when the user clicks the right menu button. The default implementation does nothing.

See Also:
getRightMenuText()

keyPressed

protected void keyPressed(int keyCode)
Called when a key is pressed. It can be identified using the constants defined in this class.

Special keys, like the joystick and menu buttons, have negative values. Input characters, like the number keys, are positive.

Unlike the MIDP Canvas class which requires tranlation of game keys this implementation does not. The keyCode value will match the constants of this class.

Parameters:
keyCode - is the key code of the key that was pressed. Negative values are special keys like the joystick and menu buttons.

keyRepeated

protected void keyRepeated(int keyCode)
Called when a key is repeated (held down). It can be identified using the constants defined in this class.

Special keys, like the joystick and menu buttons, have negative values. Input characters, like the number keys, are positive.

Unlike the MIDP Canvas class which requires tranlation of game keys this implementation does not. The keyCode value will match the constants of this class.

Also unlike the MIDP Canvas class, this implementation always supports this method and does so the same across all devices.

Parameters:
keyCode - is the key code of the key that was held down. Negative values are special keys like the joystick and menu buttons.

keyReleased

protected void keyReleased(int keyCode)
Called when a key is released. It can be identified using the constants defined in this class.

Special keys, like the joystick and menu buttons, have negative values. Input characters, like the number keys, are positive.

Unlike the MIDP Canvas class which requires tranlation of game keys this implementation does not. The keyCode value will match the constants of this class.

Parameters:
keyCode - is the key code of the key that was released. Negative values are special keys like the joystick and menu buttons.

pointerPressed

protected void pointerPressed(int x,
                              int y)
Called when the pointer is pressed.

Parameters:
x - is the horizontal location where the pointer was pressed relative to the canvas area (i.e. does not include the title or menu bars).
y - is the vertical location where the pointer was pressed relative to the canvas area (i.e. does not include the title or menu bars).

pointerReleased

protected void pointerReleased(int x,
                               int y)
Called when the pointer is released.

Parameters:
x - is the horizontal location where the pointer was pressed relative to the canvas area (i.e. does not include the title or menu bars).
y - is the vertical location where the pointer was pressed relative to the canvas area (i.e. does not include the title or menu bars).

pointerDragged

protected void pointerDragged(int x,
                              int y)
Called when the pointer is dragged.

Parameters:
x - is the horizontal location where the pointer was pressed relative to the canvas area (i.e. does not include the title or menu bars).
y - is the vertical location where the pointer was pressed relative to the canvas area (i.e. does not include the title or menu bars).

repaint

public void repaint()
Requests a repaint for the entire Canvas. The effect is identical to repaint(0, 0, getWidth(), getHeight());.


repaint

public void repaint(int x,
                    int y,
                    int width,
                    int height)
Requests a repaint for the specified region of the Canvas. Calling this method may result in subsequent call to paint(), where the passed Graphics object's clip region will include at least the specified region.

If the canvas is not visible, or if width and height are zero or less, or if the rectangle does not specify a visible region of the display, this call has no effect.

The call to paint() occurs asynchronously of the call to repaint(). That is, repaint() will not block waiting for paint() to finish. The paint() method will either be called after the caller of repaint() returns to the implementation (if the caller is a callback) or on another thread entirely.

To synchronize with its paint() routine applications can use serviceRepaints(), or they can code explicit synchronization into their paint() routine.

The origin of the coordinate system is above and to the left of the pixel in the upper left corner of the displayable area of the Canvas. The X-coordinate is positive right and the Y-coordinate is positive downwards.

Parameters:
x - is the x coordinate of the rectangle to be repainted.
y - is the y coordinate of the rectangle to be repainted.
width - is the width of the rectangle to be repainted.
height - is the height of the rectangle to be repainted.
See Also:
Canvas.serviceRepaints()

serviceRepaints

public void serviceRepaints()
Forces any pending repaint requests to be serviced immediately. This method blocks until the pending requests have been serviced. If there are no pending repaints, or if this canvas is not visible on the display, this call does nothing and returns immediately.


paintBackground

protected void paintBackground(javax.microedition.lcdui.Graphics g)
Paints the background of the main section of the screen. This includes everything except for the title bar at the top and menu bar at the bottom. However, if this canvas is in full screen mode, then this method paints the entire screen.

After this method is called, the paintCanvas method will be.

Override this method to change the background for just this screen. Override Theme.paintBackground to change the background for the entire application.

Parameters:
g - is the Graphics object to paint with.
See Also:
paint(Graphics)

paint

protected abstract void paint(javax.microedition.lcdui.Graphics g)
Paints the main section of the screen. This includes everything except for the title bar at the top and menu bar at the bottom. However, if this canvas is in full screen mode, then this method paints the entire screen.

Before this method is called, the paintBackground method will be. Any painting done here will go over the background.

Override this method to paint the main area of the screen.

Parameters:
g - is the Graphics object to paint with.
See Also:
paintBackground(Graphics)

paintTitleBar

protected void paintTitleBar(javax.microedition.lcdui.Graphics g,
                             java.lang.String title,
                             int width,
                             int height)
Paints the title bar of the canvas. This method is called only when the title has been set through setTitle and the canvas is not in full screen mode.

Override this method to change the appearance of the title bar for just this canvas. To change them for the entire application, override Theme.paintTitleBar.

Parameters:
g - is the Graphics object to paint with.
title - is the text for the title bar as defined by the canvas class.
width - is the width of the title bar in pixels.
height - is the height of the title bar in pixels.

paintMenuBar

protected void paintMenuBar(javax.microedition.lcdui.Graphics g,
                            java.lang.String left,
                            boolean highlightLeft,
                            java.lang.String right,
                            boolean highlightRight,
                            int width,
                            int height)
Paints the menu bar at the bottom of the canvas. This method is not called if the canvas is in full screen mode.

Override this method to change the appearance or functionality of the menu for just this canvas. To change them for the entire application, override Theme.paintMenuBar. Be careful not to write strings that are too long and will not fit on the menu bar.

Parameters:
g - is the Graphics object to paint with.
left - is the text to write on the left side of the menu bar. The left side is associated with dimissing input such as a "Cancel" button.
highlightLeft - is true if the menu text left should be highlighted to indicate the left menu button is currently pressed.
right - is the text to write on the right side of the menu bar. The right side is associated with accepting input such as an "OK" button.
highlightRight - is true if the menu text right should be highlighted to indicate the right menu button is currently pressed.
width - is the width of the menu bar in pixels.
height - is the height of the menu bar in pixels.

intersects

public static boolean intersects(javax.microedition.lcdui.Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h)
Returns if the clip area of g intersects the given rectangle.

Parameters:
g - is the current Graphics object for a paint operation.
x - is the pixel at the left edge of the rectangle.
y - is the pixel at the top edge of the rectangle.
w - is width of the rectangle in pixels.
h - is height of the rectangle in pixels.
Returns:
true if the rectangle is to be painted by g; false otherwise.