BenQ Mobile

javax.microedition.lcdui.game
Class GameCanvas

java.lang.Object
  extended byjavax.microedition.lcdui.Displayable
      extended byjavax.microedition.lcdui.Canvas
          extended byjavax.microedition.lcdui.game.GameCanvas

public abstract class GameCanvas
extends Canvas

This class is a subclass of LCDUI’s Canvas and provides the basic ’screen’ functionality for a game. In addition to the methods inherited from Canvas, this class also provides game-centric features such the ability to query the current state of the game keys and synchronous graphics flushing; these features simplify game development and improve performance.


Field Summary
static int DOWN_PRESSED
           
static int FIRE_PRESSED
           
static int GAME_A_PRESSED
           
static int GAME_B_PRESSED
           
static int GAME_C_PRESSED
           
static int GAME_D_PRESSED
           
static int LEFT_PRESSED
           
static int RIGHT_PRESSED
           
static int UP_PRESSED
           
 
Fields inherited from class javax.microedition.lcdui.Canvas
DOWN, FIRE, GAME_A, GAME_B, GAME_C, GAME_D, KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_POUND, KEY_STAR, LEFT, RIGHT, UP
 
Constructor Summary
protected GameCanvas(boolean suppressKeyEvents)
          Creates a new instance of a GameCanvas.
 
Method Summary
 void flushGraphics()
          Flushes the entire off-screen buffer to the display.
 void flushGraphics(int x, int y, int width, int height)
          Flushes the specified region of the off-screen buffer to the display.
protected  Graphics getGraphics()
          Obtains the Graphics object for rendering a GameCanvas.
 int getKeyStates()
          Gets the states of the physical game keys.
protected  void keyPressed(int keyCode)
          Called when a key is pressed.
protected  void keyRepeated(int keyCode)
          Called when a key is repeated (held down).
 void paint(Graphics g)
          Paints this GameCanvas.
 
Methods inherited from class javax.microedition.lcdui.Canvas
getGameAction, getHeight, getKeyCode, getKeyName, hasPointerEvents, hasPointerMotionEvents, hasRepeatEvents, hideNotify, isDoubleBuffered, keyReleased, pointerDragged, pointerPressed, pointerReleased, repaint, repaint, serviceRepaints, setFullScreenMode, showNotify, sizeChanged
 
Methods inherited from class javax.microedition.lcdui.Displayable
addCommand, getTicker, getTitle, getWidth, isShown, removeCommand, setCommandListener, setTicker, setTitle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UP_PRESSED

public static final int UP_PRESSED
See Also:
Constant Field Values

DOWN_PRESSED

public static final int DOWN_PRESSED
See Also:
Constant Field Values

LEFT_PRESSED

public static final int LEFT_PRESSED
See Also:
Constant Field Values

RIGHT_PRESSED

public static final int RIGHT_PRESSED
See Also:
Constant Field Values

FIRE_PRESSED

public static final int FIRE_PRESSED
See Also:
Constant Field Values

GAME_A_PRESSED

public static final int GAME_A_PRESSED
See Also:
Constant Field Values

GAME_B_PRESSED

public static final int GAME_B_PRESSED
See Also:
Constant Field Values

GAME_C_PRESSED

public static final int GAME_C_PRESSED
See Also:
Constant Field Values

GAME_D_PRESSED

public static final int GAME_D_PRESSED
See Also:
Constant Field Values
Constructor Detail

GameCanvas

protected GameCanvas(boolean suppressKeyEvents)
Creates a new instance of a GameCanvas.
If the developer only needs to query key status using the getKeyStates method, the regular key event mechanism can be suppressed for game keys while this GameScreen is shown. If not needed by the application, the suppression of key events may improve performance by eliminating unecessary system calls to key- Pressed, keyRepeated and keyReleased methods.

If requested, key event suppression for a given GameCanvas is started when it is shown (i.e. when show- Notify is called) and stopped when it is hidden (i.e. when hideNotify is called). Since the showing and hiding of screens is serialized with the event queue, this arrangement ensures that the suppression effects only those key events intended for the corresponding GameCanvas. Thus, if keys are being generated while another screen is still shown, those key events will continue to be queued and dispatched until that screen is hidden and the GameCanvas has replaced it.

Note that key events can be suppressed only for the defined game keys (UP, DOWN, FIRE, etc.); key events are always generated for all other keys.

Parameters:
suppressKeyEvents - True to suppress the regular key event mechanism for game keys, otherwise false.
Throws:
java.lang.OutOfMemoryError - if there is insufficient memory available to create this GameCanvas and its off-screen buffer.
Method Detail

flushGraphics

public void flushGraphics()
Flushes the entire off-screen buffer to the display. This method does not return until the buffer has been completely flushed. The contents of the off-screen buffer are not changed as a result of the flush operation. Upon returning from this method, the app may immediately begin to render the next frame to the same buffer.

If the specified region extends beyond the bounds of the buffer, only the intersecting region is flushed. This method does nothing and returns immediately if the GameCanvas is not currently shown or the flush request cannot be honored for some reason.


flushGraphics

public void flushGraphics(int x,
                          int y,
                          int width,
                          int height)
Flushes the specified region of the off-screen buffer to the display. This method does not return until that region of the buffer has been completely flushed. The contents of the off-screen buffer are not changed as a result of the flush operation. Upon returning from this method, the app may immediately begin to render the next frame to the same buffer.

If the specified region extends beyond the bounds of the buffer, only the intersecting region is flushed. This method does nothing and returns immediately if the GameCanvas is not currently shown or the flush request cannot be honored for some reason.

Parameters:
x - The left edge of the region to be flushed
y - The top edge of the region to be flushed
width - The width of the region to be flushed
height - The height of the region to be flushed

getGraphics

protected Graphics getGraphics()
Obtains the Graphics object for rendering a GameCanvas. The Graphics object renders to an off-screen buffer whose size is equal to that of the GameCanvas (use getWidth() and getHeight() to determine the size of the GameCanvas). The buffer is initially filled with white pixels. Rendering operations do not appear on the display until flushGraphics() is called; flushing the buffer does not change its contents (the pixels are not cleared as a result of the flushing operation).

A unique buffer is provided for each GameCanvas instance. Therefore, in the interests of minimizing heap usage, it is preferable to re-use a single GameCanvas instance instead of creating numerous instances.

A new Graphics object is created and returned each time this method is called; therfore, the needed Graphics object(s) should be obtained before the game starts then re-used while the game is running. For each GameCanvas instance, all of the provided graphics object will render to the same off-screen buffer.

Returns:
The Graphics object that renders to this GameCanvas’ off-screen buffer

getKeyStates

public int getKeyStates()
Gets the states of the physical game keys. Each bit in the returned integer represents a specific key on the device. A key’s bit will be set if the key is currently pressed or was pressed at least once since the last time this method was called. The bit will be 0 if the key is not currently pressed and was not pressed at all since the last time this method was called. This latching behavior the ensures that a rapid key press and release will always be caught by the game loop, regardless of how slowly the loop runs. This method may be called twice to check if a key is currently pressed; that is, calling this method twice effectively disables the latching behavior.

The lower bits are defined by UP_KEY, DOWN_KEY, LEFT_KEY, etc.; the remaining bits may be optionally mapped to device-specific keys.

For example

// Get the key state and store it
int keyState = getKeyStates();

if ((keyState & LEFT_KEY) != 0) { positionX--; }

Returns:
An integer containing the key state information (one bit per key)

keyPressed

protected void keyPressed(int keyCode)
Called when a key is pressed.
The getGameAction() method can be called to determine what game action, if any, is mapped to the key. Class Canvas has an empty implementation of this method, and the subclass has to redefine it if it wants to listen this method.

Overrides:
keyPressed in class Canvas
Parameters:
keyCode - The key code of the key that was pressed.

keyRepeated

protected void keyRepeated(int keyCode)
Called when a key is repeated (held down).

Overrides:
keyRepeated in class Canvas
Parameters:
keyCode - The key code of the key that was repeated.
See Also:
Canvas.hasRepeatEvents()

paint

public void paint(Graphics g)
Paints this GameCanvas.
By default, this method renders the off-screen buffer at (0,0). Rendering of the buffer is subject to the clip region and origin translation of the Graphics object.

Specified by:
paint in class Canvas
Parameters:
g - The Graphics object with which to render the screen.

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.