BenQ Mobile

javax.microedition.lcdui.game
Class TiledLayer

java.lang.Object
  extended byjavax.microedition.lcdui.game.Layer
      extended byjavax.microedition.lcdui.game.TiledLayer

public class TiledLayer
extends Layer

Description:

A TiledLayer is a visual element comprised of a grid of cells that can be filled with a set of tiles. This class allows large virtual layers, such as a very wide scrolling background, to be created without the need for an extremely large Image. This technique is commonly used in 2D gaming platforms.

Tiles:

The tiles used to fill the TiledLayer’s cells are provided in a single Image object. The Image is broken up into a series of equally-sized tiles; the tile size is specified along with the Image. The same tile set can be stored in several different arrangements depending on what is the most convenient for the game developer.


Constructor Summary
TiledLayer(int columns, int rows, Image image, int tileWidth, int tileHeight)
          Creates a new TiledLayer.
 
Method Summary
 int createAnimatedTile(int staticTileIndex)
          Creates a new animated tile and returns the index that refers to the new animated tile.
 void fillCells(int col, int row, int width, int height, int tileIndex)
          Fills an area of cells.
 int getAnimatedTile(int animatedTileIndex)
          Gets the tile referenced by an animated tile.
 int getCell(int col, int row)
          Gets the contents of a cell.
 int getCellHeight()
          Gets the height of a single cell, in pixels.
 int getCellWidth()
          Gets the width of a single cell, in pixels.
 int getColumns()
          Gets the width of the TiledLayer grid.
 int getRows()
          Gets the height of the TiledLayer grid.
 void paint(Graphics g)
          Draws the TiledLayer.
 void setAnimatedTile(int animatedTileIndex, int staticTileIndex)
          Associates an animated tile with the specified static tile.
 void setCell(int col, int row, int tileIndex)
          Sets the contents of a cell.
 void setStaticTileSet(Image image, int tileWidth, int tileHeight)
          Change the static tile set.
 
Methods inherited from class javax.microedition.lcdui.game.Layer
getHeight, getWidth, getX, getY, isVisible, move, setPosition, setVisible
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TiledLayer

public TiledLayer(int columns,
                  int rows,
                  Image image,
                  int tileWidth,
                  int tileHeight)
Creates a new TiledLayer.
The TiledLayer’s grid will be rows cells high and columns cells wide. All cells in the grid are initially empty (i.e. they contain tile index 0). The contents of the grid may be modified through the use of set- Cell(int, int, int) and fillCells(int, int, int, int, int).

The static tile set for the TiledLayer is created from the specified Image with each tile having the dimensions of tileWidth x tileHeight. The width of the source image must be an integer multiple of the tile width, and the height of the source image must be an integer multiple of the tile height; otherwise, an Illegal- ArgumentException is thrown;

The entire static tile set can be changed using setStaticTileSet(Image, int, int). These methods should be used sparingly since they are both memory and time consuming. Where possible, animated tiles should be used instead to animate tile appearance.

Parameters:
columns - Width of the TiledLayer, expressed as a number of cells
rows - Height of the TiledLayer, expressed as a number of cells
image - Image to use for creating the static tile set
tileWidth - The width, in pixels, of a single tile
tileHeight - The height, in pixels, of a single tile
Throws:
java.lang.NullPointerException - if image is null
java.lang.IllegalArgumentException - if the number of rows or columns is less than 1
java.lang.IllegalArgumentException - if tileHeight or tileWidth is less than 1
java.lang.IllegalArgumentException - if the image width is not an integer multiple of the tileWidth
java.lang.IllegalArgumentException - if the image height is not an integer multiple of the tileHeight
java.lang.IllegalArgumentException - if the resulting number if tiles exceeds 32,767
java.lang.OutOfMemoryError - if the request exceeds the resource availability of the device
Method Detail

createAnimatedTile

public int createAnimatedTile(int staticTileIndex)
Creates a new animated tile and returns the index that refers to the new animated tile. It is initially associated with the specified tile index (either a static tile or 0).
The indices for animated tiles are always negative. The first animated tile shall have the index -1, the second, -2, etc. Up to 32,767 animated tiles can be created, although the resource availability will be the limiting factor on most devices.

Parameters:
staticTileIndex - Index of the associated tile (must be 0 or a valid static tile index)
Returns:
Index of newly created animated tile
Throws:
java.lang.IndexOutOfBoundsException - If the staticTileIndex is invalid
java.lang.IllegalArgumentException - if the request will result in more than 32,767 animated tiles.

fillCells

public void fillCells(int col,
                      int row,
                      int width,
                      int height,
                      int tileIndex)
Fills an area of cells. The cells may be filled with a static tile index, an animated tile index, or they may be left empty (index 0)

Parameters:
col - Column of top-left cell in the area
row - Row of top-left cell in the area
width - The width of the area, expressed as a number of cells
height - The height of the area, expressed as a number of cells
tileIndex - The Index of the tile to place in all cells in the specified area
Throws:
java.lang.IndexOutOfBoundsException - if the rectangular region defined by the parameters extends beyond the bounds of the TiledLayer grid
java.lang.IndexOutOfBoundsException - if there is no tile with index tileIndex

getAnimatedTile

public int getAnimatedTile(int animatedTileIndex)
Gets the tile referenced by an animated tile. Returns the tile index currently associated with the animated tile.

Parameters:
animatedTileIndex - Index of the animated tile
Returns:
Index of the tile reference by the animated tile
Throws:
java.lang.IndexOutOfBoundsException - If the animated tile index is invalid

getCell

public int getCell(int col,
                   int row)
Gets the contents of a cell. Gets the index of the static or animated tile currently displayed in a cell. The returned index will be 0 if the cell is empty.

Parameters:
col - Column of cell to check
row - Row of cell to check
Returns:
Index of tile in cell
Throws:
java.lang.IndexOutOfBoundsException - if row or col is outside the bounds of the TiledLayer grid

getCellHeight

public final int getCellHeight()
Gets the height of a single cell, in pixels.

Returns:
The height, in pixels, of a single cell in the TiledLayer grid

getCellWidth

public final int getCellWidth()
Gets the width of a single cell, in pixels.

Returns:
The width, in pixels, of a single cell in the TiledLayer grid

getColumns

public final int getColumns()
Gets the width of the TiledLayer grid. The width is expressed in terms of the number of columns. The overall width of the TiledLayer, in pixels, may be obtained by calling getWidth().

Returns:
The width, in columns, of the TiledLayer grid

getRows

public final int getRows()
Gets the height of the TiledLayer grid. The height is expressed in terms of the number of rows. The overall height of the TiledLayer, in pixels, may be obtained by calling getHeight().

Returns:
The height, in rows, of the TiledLayer grid

paint

public final void paint(Graphics g)
Draws the TiledLayer.
The entire TiledLayer is rendered subject to the clip region of the Graphics object. The TiledLayer’s upper left corner is rendered at the TiledLayer’s current position relative to the origin of the Graphics object. The current position of the TiledLayer’s upper-left corner can be retrieved by calling getX() and getY(). The appropriate use of a clip region and/or translation allows an arbitrary region of the TiledLayer to be rendered.

Specified by:
paint in class Layer
Parameters:
g - Graphics object to draw the TiledLayer
Throws:
java.lang.NullPointerException - if g is null

setAnimatedTile

public void setAnimatedTile(int animatedTileIndex,
                            int staticTileIndex)
Associates an animated tile with the specified static tile.

Parameters:
animatedTileIndex - Index of the animated tile
staticTileIndex - Index of the associated tile (must be 0 or a valid static tile index)
Throws:
java.lang.IndexOutOfBoundsException - If the staticTileIndex is invalid java.lang.IndexOutOfBoundsException If the animated tile index is invalid

setCell

public void setCell(int col,
                    int row,
                    int tileIndex)
Sets the contents of a cell. The contents may be set to a static tile index, an animated tile index, or or it may be left empty (index 0)

Parameters:
col - Column of cell to set
row - Row of cell to set
tileIndex - Index of tile to place in cell
Throws:
java.lang.IndexOutOfBoundsException - if there is no tile with index tileIndex
java.lang.IndexOutOfBoundsException - if row or col is outside the bounds of the TiledLayer grid

setStaticTileSet

public void setStaticTileSet(Image image,
                             int tileWidth,
                             int tileHeight)
Change the static tile set. Replaces the current static tile set with a new static tile set. See the constructor TiledLayer(int, int, Image, int, int) for information on how the tiles are created from the image.

If the new static tile set has as many or more tiles than the previous static tile set, the animated tiles and cell contents will be preserve. If not, the contents of the grid will be cleared (all cells will contain index 0) and all animated tiles will be deleted.

Parameters:
image - Image to use for creating the static tile set
tileWidth - The width, in pixels, of a single tile
tileHeight - The height, in pixels, of a single tile
Throws:
java.lang.NullPointerException - if image is null
java.lang.IllegalArgumentException - if tileHeight or tileWidth is less than 1
java.lang.IllegalArgumentException - if the image width is not an integer multiple of the tileWidth
java.lang.IllegalArgumentException - if the image height is not an integer multiple of the tileHeight
java.lang.IllegalArgumentException - if the resulting number if tiles exceeds 32,767

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.