Java Doc for GameCanvas.java in  » 6.0-JDK-Modules » j2me » javax » microedition » lcdui » game » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A dedicated buffer is created for each GameCanvas instance. Since a unique buffer is provided for each GameCanvas instance, it is preferable to re-use a single GameCanvas instance in the interests of minimizing heap usage. The developer can assume that the contents of this buffer are modified only by calls to the Graphics object(s) obtained from the GameCanvas instance; the contents are not modified by external sources such as other MIDlets or system-level notifications. The buffer is initially filled with white pixels.

The buffer's size is set to the maximum dimensions of the GameCanvas. However, the area that may be flushed is limited by the current dimensions of the GameCanvas (as influenced by the presence of a Ticker, Commands, etc.) when the flush is requested. The current dimensions of the GameCanvas may be obtained by calling javax.microedition.lcdui.Canvas.getWidth getWidth and javax.microedition.lcdui.Canvas.getHeight getHeight .

A game may provide its own thread to run the game loop. A typical loop will check for input, implement the game logic, and then render the updated user interface. The following code illustrates the structure of a typical game loop:

 // Get the Graphics object for the off-screen buffer
 Graphics g = getGraphics();
 while (true) {
 // Check user input and update positions if necessary
 int keyState = getKeyStates();
 if ((keyState & LEFT_PRESSED) != 0) {
 sprite.move(-1, 0);
 }
 else if ((keyState & RIGHT_PRESSED) != 0) {
 sprite.move(1, 0);
 }
 // Clear the background to white
 g.setColor(0xFFFFFF);
 g.fillRect(0,0,getWidth(), getHeight());
 // Draw the Sprite
 sprite.paint(g);
 // Flush the off-screen buffer
 flushGraphics();
 }
 

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 GameCanvas is shown. If not needed by the application, the suppression of key events may improve performance by eliminating unnecessary system calls to keyPressed, keyRepeated and keyReleased methods.

If requested, key event suppression for a given GameCanvas is started when it is shown (i.e. when showNotify 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 key events 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 regularkey event mechanism for game keys, otherwise false.

If the specified region extends beyond the current bounds of the GameCanvas, only the intersecting region is flushed. No pixels are flushed if the specified width or height is less than 1.

This method does nothing and returns immediately if the GameCanvas is not currently shown or the flush request cannot be honored because the system is busy.

See Also:   GameCanvas.flushGraphics()
Parameters:
  x - the left edge of the region to be flushed
Parameters:
  y - the top edge of the region to be flushed
Parameters:
  width - the width of the region to be flushed
Parameters:
  height - the height of the region to be flushed

This method does nothing and returns immediately if the GameCanvas is not currently shown or the flush request cannot be honored because the system is busy.

See Also:   GameCanvas.flushGraphics(int,int,int,int)

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 new Graphics object is created and returned each time this method is called; therefore, 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 objects will render to the same off-screen buffer.

The newly created Graphics object has the following properties:

• the destination is this GameCanvas' buffer;
• the clip region encompasses the entire buffer;
• the current color is black;
• the font is the same as the font returned by javax.microedition.lcdui.Font.getDefaultFontFont.getDefaultFont() ;
• the stroke style is Graphics.SOLID SOLID ; and
• the origin of the coordinate system is located at the upper-left corner of the buffer.

the Graphics object that renders to this GameCanvas' off-screen buffer
See Also:   GameCanvas.flushGraphics()
See Also:   GameCanvas.flushGraphics(int,int,int,int)

For example:

 // Get the key state and store it
 int keyState = getKeyStates();
 if ((keyState & LEFT_KEY) != 0) {
 positionX--;
 }
 else if ((keyState & RIGHT_KEY) != 0) {
 positionX++;
 }
 

Calling this method has the side effect of clearing any latched state. Another call to getKeyStates immediately after a prior call will therefore report the system's best idea of the current state of the keys, the latched bits having been cleared by the first call.

Some devices may not be able to query the keypad hardware directly and therefore, this method may be implemented by monitoring key press and release events instead. Thus the state reported by getKeyStates might lag the actual state of the physical keys since the timeliness of the key information is be subject to the capabilities of each device. Also, some devices may be incapable of detecting simultaneous presses of multiple keys.

This method returns 0 unless the GameCanvas is currently visible as reported by javax.microedition.lcdui.Displayable.isShown . Upon becoming visible, a GameCanvas will initially indicate that all keys are unpressed (0); if a key is held down while the GameCanvas is being shown, the key must be first released and then pressed in order for the key press to be reported by the GameCanvas.

See Also:   GameCanvas.UP_PRESSED
See Also:   GameCanvas.DOWN_PRESSED
See Also:   GameCanvas.LEFT_PRESSED
See Also:   GameCanvas.RIGHT_PRESSED
See Also:   GameCanvas.FIRE_PRESSED
See Also:   GameCanvas.GAME_A_PRESSED
See Also:   GameCanvas.GAME_B_PRESSED
See Also:   GameCanvas.GAME_C_PRESSED
See Also:   GameCanvas.GAME_D_PRESSED An integer containing the key state information (one bit per key), or 0 if the GameCanvas is not currently shown.