Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.lcdui.game
Class TiledLayer

    java.lang.Object
      javax.microedition.lcdui.game.Layer
          javax.microedition.lcdui.game.TiledLayer

public class TiledLayer
extends Layer

A TiledLayer is a visual element composed of a grid of cells that can be filled with a set of tile images. This class allows large virtual layers to be created without the need for an extremely large Image. This technique is commonly used in 2D gaming platforms to create very large scrolling backgrounds,

### Tiles

The tiles used to fill the TiledLayer's cells are provided in a single Image object which may be mutable or immutable. The Image is broken up into a series of equally-sized tiles; the tile size is specified along with the Image. As shown in the figure below, the same tile set can be stored in several different arrangements depending on what is the most convenient for the game developer.
Each tile is assigned a unique index number. The tile located in the upper-left corner of the Image is assigned an index of 1. The remaining tiles are then numbered consecutively in row-major order (indices are assigned across the first row, then the second row, and so on). These tiles are regarded as static tiles because there is a fixed link between the tile and the image data associated with it.

A static tile set is created when the TiledLayer is instantiated; it can also be updated at any time using the `setStaticTileSet(javax.microedition.lcdui.Image, int, int)` method.

In addition to the static tile set, the developer can also define several animated tiles. An animated tile is a virtual tile that is dynamically associated with a static tile; the appearance of an animated tile will be that of the static tile that it is currently associated with.

Animated tiles allow the developer to change the appearance of a group of cells very easily. With the group of cells all filled with the animated tile, the appearance of the entire group can be changed by simply changing the static tile associated with the animated tile. This technique is very useful for animating large repeating areas without having to explicitly change the contents of numerous cells.

Animated tiles are created using the `createAnimatedTile(int)` method, which returns the index to be used for the new animated tile. The animated tile indices are always negative and consecutive, beginning with -1. Once created, the static tile associated with an animated tile can be changed using the `setAnimatedTile(int, int)` method.

### Cells

The TiledLayer's grid is made up of equally sized cells; the number of rows and columns in the grid are specified in the constructor, and the physical size of the cells is defined by the size of the tiles.

The contents of each cell is specified by means of a tile index; a positive tile index refers to a static tile, and a negative tile index refers to an animated tile. A tile index of 0 indicates that the cell is empty; an empty cell is fully transparent and nothing is drawn in that area by the TiledLayer. By default, all cells contain tile index 0.

The contents of cells may be changed using `setCell(int, int, int)` and `fillCells(int, int, int, int, int)`. Several cells may contain the same tile; however, a single cell cannot contain more than one tile. The following example illustrates how a simple background can be created using a TiledLayer.

In this example, the area of water is filled with an animated tile having an index of -1, which is initially associated with static tile 5. The entire area of water may be animated by simply changing the associated static tile using `setAnimatedTile(-1, 7)`.

### Rendering a TiledLayer

A TiledLayer can be rendered by manually calling its paint method; it can also be rendered automatically using a LayerManager object.

The paint method will attempt to render the entire TiledLayer subject to the clip region of the Graphics object; the upper left corner of the TiledLayer is rendered at its current (x,y) position relative to the Graphics object's origin. The rendered region may be controlled by setting the clip region of the Graphics object accordingly.

Since:
  MIDP 2.0

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 numCols, int numRows, int tileIndex)` Fills a region cells with the specific tile.
`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 number of columns in the TiledLayer grid.
`int` | `getRows()` Gets the number of rows in 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
`equals, 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 `setCell(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 IllegalArgumentException 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` - the width of the `TiledLayer`, expressed as a number of cells
  `rows` - the height of the `TiledLayer`, expressed as a number of cells
  `image` - the `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:
  `NullPointerException` - if `image` is `null`
  `IllegalArgumentException` - if the number of `rows` or `columns` is less than `1`
  `IllegalArgumentException` - if `tileHeight` or `tileWidth` is less than `1`
  `IllegalArgumentException` - if the `image` width is not an integer multiple of the `tileWidth`
  `IllegalArgumentException` - if the `image` height is not an integer multiple of the `tileHeight`

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.

  Parameters:
    `staticTileIndex` - the index of the associated tile (must be `0` or a valid static tile index)
  Returns:
    the index of newly created animated tile
  Throws:
    `IndexOutOfBoundsException` - if the `staticTileIndex` is invalid

### setAnimatedTile

    public void setAnimatedTile(int animatedTileIndex,
                                int staticTileIndex)

  Associates an animated tile with the specified static tile.

  Parameters:
    `animatedTileIndex` - the index of the animated tile
    `staticTileIndex` - the index of the associated tile (must be `0` or a valid static tile index)
  Throws:
    `IndexOutOfBoundsException` - if the `staticTileIndex` is invalid
    `IndexOutOfBoundsException` - if the animated tile index is invalid
  See Also:
    `getAnimatedTile(int)`

### 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` - the index of the animated tile
  Returns:
    the index of the tile reference by the animated tile
  Throws:
    `IndexOutOfBoundsException` - if the animated tile index is invalid
  See Also:
    `setAnimatedTile(int, int)`

### 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 it may be left empty (index 0)

  Parameters:
    `col` - the column of cell to set
    `row` - the row of cell to set
    `tileIndex` - the index of tile to place in cell
  Throws:
    `IndexOutOfBoundsException` - if there is no tile with index `tileIndex`
    `IndexOutOfBoundsException` - if `row` or `col` is outside the bounds of the `TiledLayer` grid
  See Also:
    `getCell(int, int)`, `fillCells(int, int, int, int, int)`

### 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` - the column of cell to check
    `row` - the row of cell to check
  Returns:
    the index of tile in cell
  Throws:
    `IndexOutOfBoundsException` - if `row` or `col` is outside the bounds of the `TiledLayer` grid
  See Also:
    `setCell(int, int, int)`, `fillCells(int, int, int, int, int)`

### fillCells

    public void fillCells(int col,
                          int row,
                          int numCols,
                          int numRows,
                          int tileIndex)

  Fills a region cells with the specific tile. The cells may be filled with a static tile index, an animated tile index, or they may be left empty (index `0`).

  Parameters:
    `col` - the column of top-left cell in the region
    `row` - the row of top-left cell in the region
    `numCols` - the number of columns in the region
    `numRows` - the number of rows in the region
    `tileIndex` - the Index of the tile to place in all cells in the specified region
  Throws:
    `IndexOutOfBoundsException` - if the rectangular region defined by the parameters extends beyond the bounds of the `TiledLayer` grid
    `IllegalArgumentException` - if `numCols` is less than zero
    `IllegalArgumentException` - if `numRows` is less than zero
    `IndexOutOfBoundsException` - if there is no tile with index `tileIndex`
  See Also:
    `setCell(int, int, int)`, `getCell(int, int)`

### 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

### 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

### getColumns

    public final int getColumns()

  Gets the number of columns in the TiledLayer grid. The overall width of the TiledLayer, in pixels, may be obtained by calling `Layer.getWidth()`.

  Returns:
    the width in columns of the `TiledLayer` grid

### getRows

    public final int getRows()

  Gets the number of rows in the TiledLayer grid. The overall height of the TiledLayer, in pixels, may be obtained by calling `Layer.getHeight()`.

  Returns:
    the height in rows 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 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` - the `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:
    `NullPointerException` - if `image` is `null`
    `IllegalArgumentException` - if `tileHeight` or `tileWidth` is less than `1`
    `IllegalArgumentException` - if the `image` width is not an integer multiple of the `tileWidth`
    `IllegalArgumentException` - if the `image` height is not an integer multiple of the `tileHeight`

### 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 `Layer.getX()` and `Layer.getY()`. The appropriate use of a clip region and/or translation allows an arbitrary region of the TiledLayer to be rendered.

  If the TiledLayer's Image is mutable, the TiledLayer is rendered using the current contents of the Image.

  Specified by:
    `paint` in class `Layer`
  Parameters:
    `g` - the graphics object to draw the `TiledLayer`
  Throws:
    `NullPointerException` - if `g` is `null`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 2.0 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.