com.threerings.puzzle.drop.data

## Class DropBoard

- java.lang.Object
- - com.threerings.puzzle.data.Board
  - - com.threerings.puzzle.drop.data.DropBoard

All Implemented Interfaces:
  com.threerings.io.Streamable, DropPieceCodes, com.threerings.util.DirectionCodes, Cloneable

    public class DropBoard
    extends Board
    implements DropPieceCodes

A class that provides for various useful logical operations to be enacted on a two-dimensional board and provides an easier mechanism for referencing pieces by position.

### Nested Class Summary

Nested Classes
`static interface` `DropBoard.PieceOperation` An interface to be implemented by classes that would like to apply some operation to each piece in a column or row segment in the board.

### Nested classes/interfaces inherited from interface com.threerings.io.Streamable

`com.threerings.io.Streamable.Closure`

### Field Summary

Fields
`static DropBoard.PieceOperation` `CLEAR_OP` An operation that does naught but clear pieces, which proves to be generally useful.
`static int` `INPLACE_ROTATION` The rotation constant for rotation wherein the block occupies the same columns when rotating.
`static int` `RADIAL_ROTATION` The rotation constant for rotation around a central piece.

### Fields inherited from interface com.threerings.puzzle.drop.data.DropPieceCodes

`DROP_BLOCK_PIECE_COUNT, PIECE_NONE`

### Fields inherited from interface com.threerings.util.DirectionCodes

`CARDINAL_DIRECTIONS, CCW, CW, DIRECTION_COUNT, DOWN, EAST, EASTNORTHEAST, EASTSOUTHEAST, FINE_DIRECTION_COUNT, HORIZONTAL, LEFT, NONE, NORTH, NORTHEAST, NORTHNORTHEAST, NORTHNORTHWEST, NORTHWEST, RIGHT, SOUTH, SOUTHEAST, SOUTHSOUTHEAST, SOUTHSOUTHWEST, SOUTHWEST, UP, VERTICAL, WEST, WESTNORTHWEST, WESTSOUTHWEST`

### Constructor Summary

Constructors
Constructor and Description
`DropBoard()` Constructs an empty drop board for use when unserializing.
`DropBoard(int[] board, int bwid, int bhei)` Constructs a drop board with the given board and dimensions.
`DropBoard(int bwid, int bhei)` Constructs a drop board of the given dimensions with its pieces initialized to PIECE_NONE.
`DropBoard(int bwid, int bhei, int piece)` Constructs a drop board of the given dimensions with its pieces initialized to the given piece.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `applyOp(int col, int row, DropBoard.PieceOperation op)` Applies a specified `DropBoard.PieceOperation` to the specified piece in the board.
`void` `applyOp(int dir, int col, int row, DropBoard.PieceOperation op)` Applies a specified `DropBoard.PieceOperation` to all pieces in the specified row or column starting at the specified coordinates and spanning the remainder of the row or column (depending on the application direction) in the board.
`void` `applyOp(int dir, int col, int row, int len, DropBoard.PieceOperation op)` Applies a specified `DropBoard.PieceOperation` to all pieces in a row or column segment starting at the specified coordinates and of the specified length in the board.
`void` `applyRisingPieces(int[] pieces)` Called by the `DropControllerDelegate` when it's time to apply a rising row of pieces to the board.
`DropBoard` `clone()`
`void` `copyInto(DropBoard board)` Copies the contents of this board directly into the supplied board, overwriting the destination board in its entirety.
`void` `dump()` Outputs a string representation of the board contents.
`void` `dumpAndCompare(Board other)` Outputs a string representation of the board contents, interlaced with the supplied comparison board.
`boolean` `equals(Board other)` Returns whether this board is equal to the given comparison board.
`void` `fill(int piece)` Fills the board contents with the given piece.
`int[]` `getBoard()` Returns the raw board data associated with this board.
`Rectangle` `getBounds()` Returns the bounds of this board.
`void` `getColumnLevels(byte[] columns)` Populates the given array with the column levels for this board.
`int` `getDropDistance(int col, int row)` Returns the distance the piece at the given column and row can drop until it hits a non-empty piece (defined as `DropPieceCodes.PIECE_NONE`).
`Point` `getForgivingMove(int col, int row, int wid, int hei, int dx, int dy, float pctdone)` Returns a `Point` object containing the coordinates to place the bottom-left of the given block at after moving it the given distance on the x- and y-axes, or `null` if the move is not valid.
`int[]` `getForgivingRotation(int[] rows, int[] cols, int orient, int dir, int rtype, float pctdone, boolean canPopup)` Rotates the given block in the given direction and returns its final state as `(orient, col, row, popped)`, where `orient` is the final orientation of the drop block; `col` and `row` are the final column and row coordinates, respectively, of the central drop block piece.
`int` `getHeight()` Returns the height of the board in rows.
`int` `getNextPiece()` For boards that are always filled, this method is called to obtain pieces to fill the board.
`int` `getPiece(int col, int row)` Returns the piece at the given column and row in the board.
`int` `getWidth()` Returns the width of the board in columns.
`boolean` `inBounds(int col, int row)` Returns true if the specified coordinate is within the bounds of the board, false if it is not.
`boolean` `isBlockEmpty(int col, int row, int wid, int hei)` Returns whether the specified block in the board is empty.
`boolean` `isRowEmpty(int row)` Returns whether the given row in the board is empty.
`boolean` `isValidDrop(int[] rows, int[] cols, float pctdone)` Returns whether all of the pieces at the given coordinates can be dropped one row.
`boolean` `isValidPosition(int x, int y)` Returns whether the given coordinates are within the board bounds.
`boolean` `rowContainsPieces(int row, int blankPiece)` Returns true if the specified row (which count down, with zero at the top of the board) contains any pieces.
`void` `setBoard(int[] board)` Sets the board pieces.
`void` `setBoard(int[] board, int bwid, int bhei)` Sets the board data and board dimensions.
`boolean` `setPiece(int col, int row, int piece)` Sets the piece at the given coordinates.
`void` `setRect(int x, int y, int width, int height, int piece)` Sets the pieces within the specified rectangle to the given piece.
`void` `setSegment(int dir, int col, int row, int[] pieces)` Sets the pieces in the given board segment to the specified pieces.
`boolean` `setSegment(int dir, int col, int row, int len, int piece)` Sets the pieces in the given board segment to the specified piece.
`int` `size()` Returns the size of the board in pieces.
`String` `toString()`

### Methods inherited from class com.threerings.puzzle.data.Board

`getRandom, initializeSeed, seedFromEvent`

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Field Detail

#### RADIAL_ROTATION

    public static final int RADIAL_ROTATION

The rotation constant for rotation around a central piece.

See Also:
  Constant Field Values

#### INPLACE_ROTATION

    public static final int INPLACE_ROTATION

The rotation constant for rotation wherein the block occupies the same columns when rotating.

See Also:
  Constant Field Values

#### CLEAR_OP

    public static final DropBoard.PieceOperation CLEAR_OP

An operation that does naught but clear pieces, which proves to be generally useful.

### Constructor Detail

#### DropBoard

    public DropBoard()

Constructs an empty drop board for use when unserializing.

#### DropBoard

    public DropBoard(int bwid,
                     int bhei)

Constructs a drop board of the given dimensions with its pieces initialized to PIECE_NONE.

#### DropBoard

    public DropBoard(int bwid,
                     int bhei,
                     int piece)

Constructs a drop board of the given dimensions with its pieces initialized to the given piece.

#### DropBoard

    public DropBoard(int[] board,
                     int bwid,
                     int bhei)

Constructs a drop board with the given board and dimensions.

### Method Detail

#### getWidth

    public int getWidth()

Returns the width of the board in columns.

#### getHeight

    public int getHeight()

Returns the height of the board in rows.

#### getPiece

    public int getPiece(int col,
                        int row)

Returns the piece at the given column and row in the board.

#### getNextPiece

    public int getNextPiece()

For boards that are always filled, this method is called to obtain pieces to fill the board.

#### getDropDistance

    public int getDropDistance(int col,
                               int row)

Returns the distance the piece at the given column and row can drop until it hits a non-empty piece (defined as `DropPieceCodes.PIECE_NONE`).

#### isRowEmpty

    public boolean isRowEmpty(int row)

Returns whether the given row in the board is empty.

#### isValidDrop

    public boolean isValidDrop(int[] rows,
                               int[] cols,
                               float pctdone)

Returns whether all of the pieces at the given coordinates can be dropped one row.

#### inBounds

    public boolean inBounds(int col,
                            int row)

Returns true if the specified coordinate is within the bounds of the board, false if it is not.

#### isBlockEmpty

    public boolean isBlockEmpty(int col,
                                int row,
                                int wid,
                                int hei)

Returns whether the specified block in the board is empty. The block is allowed to occupy space off the top of the board as long as it is within the horizontal board bounds.

Parameters:
  `col` - the left coordinate of the block.
  `row` - the bottom coordinate of the block.
  `wid` - the width of the block.
  `hei` - the height of the block.

#### getForgivingRotation

    public int[] getForgivingRotation(int[] rows,
                                      int[] cols,
                                      int orient,
                                      int dir,
                                      int rtype,
                                      float pctdone,
                                      boolean canPopup)

Rotates the given block in the given direction and returns its final state as `(orient, col, row, popped)`, where `orient` is the final orientation of the drop block; `col` and `row` are the final column and row coordinates, respectively, of the central drop block piece. `popped` will be set to 1 if the piece was popped up, 0 otherwise.

#### getForgivingMove

    public Point getForgivingMove(int col,
                                  int row,
                                  int wid,
                                  int hei,
                                  int dx,
                                  int dy,
                                  float pctdone)

Returns a `Point` object containing the coordinates to place the bottom-left of the given block at after moving it the given distance on the x- and y-axes, or `null` if the move is not valid. Note that only the final block position is checked.

Parameters:
  `col` - the leftmost column of the block.
  `row` - the bottommost row of the block.
  `wid` - the width of the block.
  `hei` - the height of the block.
  `dx` - the distance to move the block in columns.
  `dy` - the distance to move the block in rows.
  `pctdone` - the percentage of the inter-block distance that the piece has fallen thus far.

#### getColumnLevels

    public void getColumnLevels(byte[] columns)

Populates the given array with the column levels for this board.

#### applyRisingPieces

    public void applyRisingPieces(int[] pieces)

Called by the `DropControllerDelegate` when it's time to apply a rising row of pieces to the board. Shifts all of the pieces in the given board up one row and places the given row of pieces at the bottom of the board.

#### rowContainsPieces

    public boolean rowContainsPieces(int row,
                                     int blankPiece)

Returns true if the specified row (which count down, with zero at the top of the board) contains any pieces.

Parameters:
  `row` - the row to check for pieces.
  `blankPiece` - the blank piece value, non-instances of which will be sought.

#### fill

    public void fill(int piece)

Fills the board contents with the given piece.

#### setPiece

    public boolean setPiece(int col,
                            int row,
                            int piece)

Sets the piece at the given coordinates.

Returns:
  true if the piece was set, false if it was invalid.

#### setRect

    public void setRect(int x,
                        int y,
                        int width,
                        int height,
                        int piece)

Sets the pieces within the specified rectangle to the given piece.

#### setSegment

    public boolean setSegment(int dir,
                              int col,
                              int row,
                              int len,
                              int piece)

Sets the pieces in the given board segment to the specified piece.

Parameters:
  `dir` - the direction of the segment; one of `DirectionCodes.HORIZONTAL` or `DirectionCodes.VERTICAL`.
  `col` - the starting column of the segment.
  `row` - the starting row of the segment.
  `len` - the length of the segment in pieces.
  `piece` - the piece to set in the segment.
Returns:
  false if the segment was only partially applied because some pieces were outside the bounds of the board, true if it was completely applied.

#### setSegment

    public void setSegment(int dir,
                           int col,
                           int row,
                           int[] pieces)

Sets the pieces in the given board segment to the specified pieces.

Parameters:
  `dir` - the direction of the segment; one of `DirectionCodes.HORIZONTAL` or `DirectionCodes.VERTICAL`.
  `col` - the starting column of the segment.
  `row` - the starting row of the segment.
  `pieces` - the pieces to set in the segment.

#### applyOp

    public void applyOp(int dir,
                        int col,
                        int row,
                        DropBoard.PieceOperation op)

Applies a specified `DropBoard.PieceOperation` to all pieces in the specified row or column starting at the specified coordinates and spanning the remainder of the row or column (depending on the application direction) in the board.

Parameters:
  `dir` - the direction to iterate in; one of `DirectionCodes.HORIZONTAL` or `DirectionCodes.VERTICAL`.
  `col` - the starting column of the segment.
  `row` - the starting row of the segment.
  `op` - the piece operation to apply to each piece.

#### applyOp

    public void applyOp(int dir,
                        int col,
                        int row,
                        int len,
                        DropBoard.PieceOperation op)

Applies a specified `DropBoard.PieceOperation` to all pieces in a row or column segment starting at the specified coordinates and of the specified length in the board.

Parameters:
  `dir` - the direction to iterate in; one of `DirectionCodes.HORIZONTAL` or `DirectionCodes.VERTICAL`.
  `col` - the starting leftmost column of the segment.
  `row` - the starting bottommost row of the segment.
  `len` - the number of pieces in the segment.
  `op` - the piece operation to apply to each piece.

#### applyOp

    public void applyOp(int col,
                        int row,
                        DropBoard.PieceOperation op)

Applies a specified `DropBoard.PieceOperation` to the specified piece in the board.

Parameters:
  `col` - the column of the piece.
  `row` - the row of the piece.
  `op` - the piece operation to apply to the piece.

#### dump

    public void dump()

Description copied from class: `Board`
Outputs a string representation of the board contents.

Specified by:
  `dump` in class `Board`

#### dumpAndCompare

    public void dumpAndCompare(Board other)

Description copied from class: `Board`
Outputs a string representation of the board contents, interlaced with the supplied comparison board.

Specified by:
  `dumpAndCompare` in class `Board`

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

#### equals

    public boolean equals(Board other)

Description copied from class: `Board`
Returns whether this board is equal to the given comparison board.

Specified by:
  `equals` in class `Board`

#### isValidPosition

    public boolean isValidPosition(int x,
                                   int y)

Returns whether the given coordinates are within the board bounds.

#### getBounds

    public Rectangle getBounds()

Returns the bounds of this board. Note that a single rectangle is re-used internally and so the caller should not modify the returned rectangle.

#### size

    public int size()

Returns the size of the board in pieces.

#### copyInto

    public void copyInto(DropBoard board)

Copies the contents of this board directly into the supplied board, overwriting the destination board in its entirety.

#### getBoard

    public int[] getBoard()

Returns the raw board data associated with this board. One shouldn't fiddle about with this unless one knows what one is doing.

#### setBoard

    public void setBoard(int[] board,
                         int bwid,
                         int bhei)

Sets the board data and board dimensions.

#### setBoard

    public void setBoard(int[] board)

Sets the board pieces.

#### clone

    public DropBoard clone()

Overrides:
  `clone` in class `Board`