thinSoft.ui
Class ChessLayout

java.lang.Object
  |
  +--thinSoft.ui.ChessLayout

All Implemented Interfaces:

java.awt.LayoutManager, java.awt.LayoutManager2

public class ChessLayout

extends java.lang.Object

implements java.awt.LayoutManager2

A layout modeled after a stretched chessboard.

The chessboard contains N rows by M columns, where the intersection of each row and column is called a square, and may hold one or more Components.

The initial number of rows and columns may be set in the constructor, or may be explicitly set at any time. References to rows and columns outside the current chessboard cause the board to be automatically expanded.

All the squares on the same row have the same height, and all the squares on the same column have the same width. However the rows, columns and squares are stretched to meet the size requiments of the Components placed on them.

The position and attributes of each Component are specified by association with a ChessPiece object. Components not bound to ChessPieces are ignored during the layout and may be manipulated independently.

A piece may be multiple columns across, and/or multiple columns down. Multiple pieces may be placed on the same square in any combination. Two visible pieces sharing the same square may partially obscure each other.

Each piece may be individually aligned to the top/bottom/left/right edge of is space, or centered or stretched to fit. Horizontal and Vertical positioning are independent.

An Insets structure may be specified to place a border around the entire board, or around any Component.

Gaps between rows and columns may be set.

Any combination of Minimum Height/Width and Preferred Height/Width may be specified for each Component, and these limits override the getMinimumSize() and getPreferredSize() values requested by the Component. If desired a Height dimension may be non-zero, while its corresponding Width dimension is not. (or vice-versa) If a Minimum dimension has a non-zero value and the corresponding Preferred dimension is zero, the Preferred dimension will be taken from the Component, but will be constrained to be at least as large as the Minimum. Conversely if a Preferred dimension is non-zero, but the corresponding Minimum is zero, the Minimum dimension will be taken from the Component, but will be constrained to be less/equal to the corresponding Preferred dimension.

When the container is smaller than the minimumSize() of the board, then the board is sized to the minimumSize() and the bottom and/or right corner of the board is obscured outside the container.

When the container is greater-equal the minumumSize() of the board, but smaller than the preferredSize(), then the chessboard is sized evenly between its minimumSize() and preferredSize() so that it fits the Container dimensions.

When the board is greater-equal its preferredSize(), the board is stretched according to the caller-specified row/column elasticity vector and is fit to the container dimensions. The default elasticity value for each row and column is intially zero (unstretchable). Rows and Columns assigned non-zero elasticity values stretch proportional to their value. The author recommends this Layout in preference to the java.awt.GridBagLayout for any purpose.

See Also:

ChessPiece

Field Summary

int	debugLevel Debuggging print level (deprecated)

Constructor Summary

ChessLayout()
Constructs a new ChessLayout of size 1.

ChessLayout(java.awt.Insets border, int[] colElasticity, int[] rowElasticity, int[] colGap, int[] rowGap)
Constructs a new ChessLayout with all LayoutManager parameters.

ChessLayout(int[] colElasticity, int[] rowElasticity)
Constructs a new ChessLayout from a row elasticity vector and a column elasticity vector.

ChessLayout(int cols, int rows)
Constructs a new ChessLayout with the specified number initial number of rows and columns.

Method Summary

void	add(java.awt.Component comp, ChessPiece piece) Adds the Component to the Container, binding it to a copy of the ChessPiece given.
void	add(java.awt.Component comp, ChessPiece piece, int col, int row) Adds the Component to the Container, binding it to a copy of the ChessPiece given, but with the row and column set to the specified values.
void	add(java.awt.Component comp, ChessPiece piece, int col, int row, int cols, int rows) Adds the Component to the Container, binding it to a copy of the ChessPiece given, but with the row, column, number of rows and number of columns set to the specified values.
void	addLayoutComponent(java.awt.Component comp, java.lang.Object constraints) Adds the specified component to the layout, binding it to a copy of the ChessPiece given.
void	addLayoutComponent(java.lang.String name, java.awt.Component comp) Adds the specified named Component to the layout.
protected void	adjustBoardSize() Adjusts the size of the ChessBoard if necessary to include all the current Components.
protected void	bindPiece(java.awt.Component comp, ChessPiece piece) Binds a ChessPiece to a Component.
protected int	computeTop(int[] top, int[] cons, int[] gap) Computes the top row/column height/width based on the row/column constraints.
java.awt.Insets	getBorder() Gets border insets.
int[]	getColElasticity() Gets the current column elasticities.
int[]	getColGap() Returns the current column gaps.
int	getCols() Gets the current number of columns.
protected void	getConstraints(int[] colDim, int[] rowDim, int[] colCons, int[] rowCons, int whichSize) Gets the set of constraints imposed by the Component minimumSize or preferredSize.
java.awt.Container	getContainer() Gets the Container associated with this layout.
float	getLayoutAlignmentX(java.awt.Container target) Returns the current X axis alignment, indicating how this component should be centered on the X axis relative to other components.
float	getLayoutAlignmentY(java.awt.Container target) Returns the current X axis alignment, indicating how this component should be centered on the Y axis relative to other components.
ChessPiece	getPiece(java.awt.Component comp) Returns a clone() of the ChessPiece associated with the given Component.
int[]	getRowElasticity() Gets the current row elasticities.
int[]	getRowGap() Gets the current row gaps.
int	getRows() Gets the current number of rows.
protected void	interpolate(int[] v1, int[] v2, int mult, int div) Interpolates between the two vectors, returning a third vector with the interpolated value.
void	invalidateLayout(java.awt.Container target) Is called to invalidate the current layout.
void	layoutContainer(java.awt.Container target) Lays out the container.
protected java.awt.Dimension	layoutSize(java.awt.Container target, int whichSize) Returns the dimensions needed to layout this container.
java.awt.Dimension	maximumLayoutSize(java.awt.Container target) Returns the maximum size of the container.
java.awt.Dimension	minimumLayoutSize(java.awt.Container target) Returns the minimum size of the container.
java.awt.Dimension	preferredLayoutSize(java.awt.Container target) Returns the preferred size of the container.
void	removeLayoutComponent(java.awt.Component comp) Removes the specified Component from the layout.
void	setBorder(java.awt.Insets border) Sets border insets.
void	setColElasticity(int elasticity) Sets all column elasticities to the given value.
void	setColElasticity(int[] elasticity) Sets all column elasticities from the array given.
void	setColElasticity(int elasticity, int col) Sets the elasticity of a given column to the value given.
void	setColElasticity(int elasticity, int lowCol, int highCol) Sets the elasticity of a given range of columns to the value specified.
void	setColGap(int gap) Sets all column gaps to a constant value.
void	setColGap(int[] gap) Sets all column gaps and the number of chessboard columns from the array given.
void	setColGap(int gap, int col) Sets the gap after a single column.
void	setColGap(int gap, int lowCol, int highCol) Sets the gaps between a range of columns to a constant value.
void	setCols(int n) Changes the number of columns on the chessboard.
void	setContainer(java.awt.Container target) Binds this LayoutManager to the specified Container.
void	setLayoutAlignmentX(java.awt.Container target, float x) Sets the X axis alignment.
void	setLayoutAlignmentY(java.awt.Container target, float y) Sets the Y axis alignment.
void	setPiece(java.awt.Component comp, ChessPiece piece) Binds a ChessPiece to a Component.
void	setRowElasticity(int elasticity) Sets all row elasticities to the given value.
void	setRowElasticity(int[] elasticity) Sets all row elasticities from the array given.
void	setRowElasticity(int elasticity, int row) Sets the elasticity of a row.
void	setRowElasticity(int elasticity, int lowRow, int highRow) Sets the elasticity of a given range of rows to the value specified.
void	setRowGap(int gap) Sets all row Gaps to a constant value.
void	setRowGap(int[] gap) Sets all row gaps and the number of chessboard rows from the array given.
void	setRowGap(int gap, int row) Sets the gap after a single row.
void	setRowGap(int gap, int lowRow, int highRow) Sets the gaps between a range of rows to a constant value.
void	setRows(int n) Changes the number of rows on the chessboard.
protected int	shrinkTop(int[] top, int[] cons, int[] gap, int[] dim, int[] minCons, int[] minDim, int adjust) Reduces the size of the layout below the PreferredSize by adjusting the Component sizes from the PreferredSize Dimensions to the the MinimumSize Dimensions.
protected void	stretchTop(int[] top, int[] cons, int[] gap, int[] elast, int amount) Stretches the vector of row/column positions to fit the container according to the elasticity array given.
java.lang.String	toString() Returns the String representation of this ChessLayout's values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

debugLevel

public int debugLevel

Debuggging print level (deprecated)

Constructor Detail

ChessLayout

public ChessLayout()

Constructs a new ChessLayout of size 1.

ChessLayout

public ChessLayout(int cols,
                   int rows)

Constructs a new ChessLayout with the specified number initial number of rows and columns.

Parameters:

cols - initial number of columns.

rows - initial number of rows.

ChessLayout

public ChessLayout(int[] colElasticity,
                   int[] rowElasticity)

Constructs a new ChessLayout from a row elasticity vector and a column elasticity vector.

Parameters:

rowElasticity - Row elasticity array (may be null)

colElasticity - Column elasticity vector (may be null)

ChessLayout

public ChessLayout(java.awt.Insets border,
                   int[] colElasticity,
                   int[] rowElasticity,
                   int[] colGap,
                   int[] rowGap)

Constructs a new ChessLayout with all LayoutManager parameters. This constructor is provided to avoid all calls to the layout manager directly.

Parameters:

border - outside border (may be null)

rowElasticity - Row elasticity array (may be null)

colElasticity - Column elasticity array (may be null)

rowGap - Row gap array (may be null)

colGap - Column gap array (may be null)

Method Detail

getBorder

public java.awt.Insets getBorder()

Gets border insets.

setBorder

public void setBorder(java.awt.Insets border)

Sets border insets.

Parameters:

border - Insets for top/left/bottom/right borders.

getRows

public int getRows()

Gets the current number of rows.

setRows

public void setRows(int n)

Changes the number of rows on the chessboard. Bad things happen if there are pieces outside the new size.

Parameters:

n - new number of rows.

getCols

public int getCols()

Gets the current number of columns.

setCols

public void setCols(int n)

Changes the number of columns on the chessboard. Bad things happen if there are pieces outside the new size.

Parameters:

n - new number of columns.

getRowGap

public int[] getRowGap()

Gets the current row gaps.

setRowGap

public void setRowGap(int[] gap)

Sets all row gaps and the number of chessboard rows from the array given. The array must be length (rows-1), where rowGap[i] is the gap between row (i) and row (i+1).

Parameters:

gap - array of row gaps.

setRowGap

public void setRowGap(int gap,
                      int lowRow,
                      int highRow)

Sets the gaps between a range of rows to a constant value.

Parameters:

gap - row gap value.

lowRow - low row number (inclusive)

highRow - high row number (inclusive)

setRowGap

public void setRowGap(int gap,
                      int row)

Sets the gap after a single row.

Parameters:

gap - the desired gap

row - the row number.

setRowGap

public void setRowGap(int gap)

Sets all row Gaps to a constant value.

Parameters:

gap - the fixed row gap.

getColGap

public int[] getColGap()

Returns the current column gaps.

setColGap

public void setColGap(int[] gap)

Sets all column gaps and the number of chessboard columns from the array given. The array must be length cols-1, where colGap[i] is the gap between column (i) and column (i+1).

Parameters:

gap - array of column gaps.

setColGap

public void setColGap(int gap,
                      int lowCol,
                      int highCol)

Sets the gaps between a range of columns to a constant value.

Parameters:

gap - the column gap.

lowCol - Low column number (inclusive)

highCol - High column number (inclusive)

setColGap

public void setColGap(int gap,
                      int col)

Sets the gap after a single column.

Parameters:

gap - the desired gap

col - the column number.

setColGap

public void setColGap(int gap)

Sets all column gaps to a constant value.

Parameters:

gap - the constant gap value.

getRowElasticity

public int[] getRowElasticity()

Gets the current row elasticities.

setRowElasticity

public void setRowElasticity(int[] elasticity)

Sets all row elasticities from the array given. gap[i] sets the elasticity of row (i).

Parameters:

elasticity - the row elasticity vector.

setRowElasticity

public void setRowElasticity(int elasticity)

Sets all row elasticities to the given value.

Parameters:

elasticity - the constant elasticity value.

setRowElasticity

public void setRowElasticity(int elasticity,
                             int lowRow,
                             int highRow)

Sets the elasticity of a given range of rows to the value specified.

Parameters:

elasticity - the row elasticity value.

lowRow - the low row number (inclusive)

highRow - the high row number (inclusive)

setRowElasticity

public void setRowElasticity(int elasticity,
                             int row)

Sets the elasticity of a row.

Parameters:

elasticity - desired row elasticity.

row - row index.

getColElasticity

public int[] getColElasticity()

Gets the current column elasticities.

setColElasticity

public void setColElasticity(int[] elasticity)

Sets all column elasticities from the array given. gap[i] sets the elasticity of col (i).

Parameters:

elasticity - array of elasticity values.

setColElasticity

public void setColElasticity(int elasticity)

Sets all column elasticities to the given value.

Parameters:

elasticity - elasticity value for all columns.

setColElasticity

public void setColElasticity(int elasticity,
                             int lowCol,
                             int highCol)

Sets the elasticity of a given range of columns to the value specified.

Parameters:

elasticity - column elasticity value.

lowCol - low column number (inclusive)

highCol - high column number (inclusive)

setColElasticity

public void setColElasticity(int elasticity,
                             int col)

Sets the elasticity of a given column to the value given.

Parameters:

elasticity - column elasticity value.

col - column index.

bindPiece

protected void bindPiece(java.awt.Component comp,
                         ChessPiece piece)

Binds a ChessPiece to a Component.

The piece must be cloned prior to this call.

Parameters:

comp - A Component.

piece - Its associated ChessPiece.

getPiece

public ChessPiece getPiece(java.awt.Component comp)

Returns a clone() of the ChessPiece associated with the given Component.

Parameters:

comp - An AWT Component.

Returns:

the associated ChessPiece.

setPiece

public void setPiece(java.awt.Component comp,
                     ChessPiece piece)

Binds a ChessPiece to a Component.

Parameters:

comp - An AWT Component.

piece - Its associated ChessPiece.

getContainer

public java.awt.Container getContainer()

Gets the Container associated with this layout.

setContainer

public void setContainer(java.awt.Container target)

Binds this LayoutManager to the specified Container. This call is needed only if you wish to use the convenience ChessLayout.add() methods.

Parameters:

target - Container to bind to.

add

public void add(java.awt.Component comp,
                ChessPiece piece)

Adds the Component to the Container, binding it to a copy of the ChessPiece given.

Parameters:

comp - Component to add to the Layout.

piece - Associated ChessPiece.

add

public void add(java.awt.Component comp,
                ChessPiece piece,
                int col,
                int row)

Adds the Component to the Container, binding it to a copy of the ChessPiece given, but with the row and column set to the specified values.

Parameters:

comp - Component to add to the Layout.

piece - Associated ChessPiece.

row - upper row coordinate.

col - left column coordinate.

add

public void add(java.awt.Component comp,
                ChessPiece piece,
                int col,
                int row,
                int cols,
                int rows)

Adds the Component to the Container, binding it to a copy of the ChessPiece given, but with the row, column, number of rows and number of columns set to the specified values.

Parameters:

comp - Component to add to the Layout.

piece - Associated ChessPiece.

row - upper row coordinate.

col - left column coordinate.

rows - number of rows.

cols - number of columns.

addLayoutComponent

public void addLayoutComponent(java.awt.Component comp,
                               java.lang.Object constraints)

Adds the specified component to the layout, binding it to a copy of the ChessPiece given.

Specified by:

addLayoutComponent in interface java.awt.LayoutManager2

addLayoutComponent

public void addLayoutComponent(java.lang.String name,
                               java.awt.Component comp)

Adds the specified named Component to the layout. Not that if the Component is not associated with a ChessPiece, it will be ignored in the layout process, and the application may position and size it independently.

Specified by:

addLayoutComponent in interface java.awt.LayoutManager

Parameters:

name - the String name

comp - the Component to be added

removeLayoutComponent

public void removeLayoutComponent(java.awt.Component comp)

Removes the specified Component from the layout.

Specified by:

removeLayoutComponent in interface java.awt.LayoutManager

Parameters:

comp - the Component to be removed

getLayoutAlignmentX

public float getLayoutAlignmentX(java.awt.Container target)

Returns the current X axis alignment, indicating how this component should be centered on the X axis relative to other components.

Specified by:

getLayoutAlignmentX in interface java.awt.LayoutManager2

setLayoutAlignmentX

public void setLayoutAlignmentX(java.awt.Container target,
                                float x)

Sets the X axis alignment.

getLayoutAlignmentY

public float getLayoutAlignmentY(java.awt.Container target)

Returns the current X axis alignment, indicating how this component should be centered on the Y axis relative to other components.

Specified by:

getLayoutAlignmentY in interface java.awt.LayoutManager2

setLayoutAlignmentY

public void setLayoutAlignmentY(java.awt.Container target,
                                float y)

Sets the Y axis alignment.

invalidateLayout

public void invalidateLayout(java.awt.Container target)

Is called to invalidate the current layout. However this LayoutManager does not keep cached information, so this is a null operation.

Specified by:

invalidateLayout in interface java.awt.LayoutManager2

adjustBoardSize

protected void adjustBoardSize()

Adjusts the size of the ChessBoard if necessary to include all the current Components.

getConstraints

protected void getConstraints(int[] colDim,
                              int[] rowDim,
                              int[] colCons,
                              int[] rowCons,
                              int whichSize)

Gets the set of constraints imposed by the Component minimumSize or preferredSize.

computeTop

protected int computeTop(int[] top,
                         int[] cons,
                         int[] gap)

Computes the top row/column height/width based on the row/column constraints.

Parameters:

n - number of rows/columns

constraint - height/width conss.

gap - vertical/horizontal gap.

shrinkTop

protected int shrinkTop(int[] top,
                        int[] cons,
                        int[] gap,
                        int[] dim,
                        int[] minCons,
                        int[] minDim,
                        int adjust)

Reduces the size of the layout below the PreferredSize by adjusting the Component sizes from the PreferredSize Dimensions to the the MinimumSize Dimensions.

Parameters:

top - row/column top/right position

cons - initial (PreferredSize) height/width constraints

gap - vertical/horizontal gap

dim - initial (PreferredSize) dimensions

minCons - MinimumSize height/width constraints

minDim - MinimumSize dimensions

stretchTop

protected void stretchTop(int[] top,
                          int[] cons,
                          int[] gap,
                          int[] elast,
                          int amount)

Stretches the vector of row/column positions to fit the container according to the elasticity array given.

Parameters:

top - array of row/column top coordinates.

cons - array of row/column constraints.

gap - array of row/column gaps.

elast - elasticity array.

amount - to stretch.

layoutSize

protected java.awt.Dimension layoutSize(java.awt.Container target,
                                        int whichSize)

Returns the dimensions needed to layout this container.

Parameters:

target - container to lay out.

pref - true for preferred size, false for minimum size

minimumLayoutSize

public java.awt.Dimension minimumLayoutSize(java.awt.Container target)

Returns the minimum size of the container.

In the case of the ChessLayout, this is the smallest size that allows all the enclosed components to be at least their MaximumSize.

Specified by:

minimumLayoutSize in interface java.awt.LayoutManager

preferredLayoutSize

public java.awt.Dimension preferredLayoutSize(java.awt.Container target)

Returns the preferred size of the container.

In the case of the ChessLayout, this is the smallest size that allows all the enclosed components to be at least their PreferredSize.

Specified by:

preferredLayoutSize in interface java.awt.LayoutManager

maximumLayoutSize

public java.awt.Dimension maximumLayoutSize(java.awt.Container target)

Returns the maximum size of the container.

In the case of the ChessLayout, this is the smallest size that allows all the enclosed components to be at least their MaximumSize.

Specified by:

maximumLayoutSize in interface java.awt.LayoutManager2

interpolate

protected void interpolate(int[] v1,
                           int[] v2,
                           int mult,
                           int div)

Interpolates between the two vectors, returning a third vector with the interpolated value.

layoutContainer

public void layoutContainer(java.awt.Container target)

Lays out the container. In no case will any of the Components be resized smaller than their minimum size.

Specified by:

layoutContainer in interface java.awt.LayoutManager

Parameters:

target - container to lay out.

toString

public java.lang.String toString()

Returns the String representation of this ChessLayout's values.

Overrides:

toString in class java.lang.Object