com.jgoodies.forms.layout

Class CellConstraints

Implemented Interfaces:
Cloneable, Serializable

public final class CellConstraints
extends Object
implements Cloneable, Serializable

Defines constraints for components that are layed out with the FormLayout. Defines the components display area: grid x, grid y, grid width (column span), grid height (row span), horizontal alignment and vertical alignment.

Most methods return this object to enable method chaining.

You can set optional insets in a constructor. This is useful if you need to use a pixel-size insets to align perceived component bounds with pixel data, for example an icon. Anyway, this is rarely used. The insets don't affect the size computation for columns and rows. I consider renaming the insets to offsets to better indicate the motivation for this option.

Examples:
The following cell constraints locate a component in the third column of the fifth row; column and row span are 1; the component will be aligned with the column's right-hand side and the row's bottom.

 CellConstraints cc = new CellConstraints();
 cc.xy  (3, 5);
 cc.xy  (3, 5, CellConstraints.RIGHT, CellConstraints.BOTTOM);
 cc.xy  (3, 5, "right, bottom");
 
 cc.xyw (3, 5, 1);
 cc.xyw (3, 5, 1, CellConstraints.RIGHT, CellConstraints.BOTTOM);
 cc.xyw (3, 5, 1, "right, bottom");
  
 cc.xywh(3, 5, 1, 1);
 cc.xywh(3, 5, 1, 1, CellConstraints.RIGHT, CellConstraints.BOTTOM);
 cc.xywh(3, 5, 1, 1, "right, bottom"); 
 
See also the examples in the FormLayout class comment.

Note: The new method sets #rc, #rcw, and #rchw are experimental and maybe removed from the 1.1 final.

TODO: Remove the above comment in the 1.1 final.

TODO: Explain in the JavaDocs that the insets are actually offsets. And describe that these offsets are not taken into account when FormLayout computes the column and row sizes.

TODO: Rename the inset to offsets.

TODO: In the Forms 1.0.x invisible components are not taken into account when the FormLayout lays out the container. Add an optional setting for this on both the container-level and component-level. So one can specify that invisible components shall be taken into account, but may exclude individual components. Or the other way round, exclude invisible components, and include individual components. The API of both the FormLayout and CellConstraints classes shall be extended to support this option. This feature is planned for the Forms version 1.1 and is described in issue #28 of the Forms' issue tracker where you can track the progress.

Version:
$Revision: 1.4 $
Author:
Karsten Lentzsch

Nested Class Summary

static class
CellConstraints.Alignment
An ordinal-based serializable typesafe enumeration for component alignment types as used by the FormLayout.

Field Summary

static CellConstraints.Alignment
BOTTOM
Put the component in the bottom.
static CellConstraints.Alignment
CENTER
Put the component in the center.
static CellConstraints.Alignment
DEFAULT
Use the column's or row's default alignment.
static CellConstraints.Alignment
FILL
Fill the cell either horizontally or vertically.
static CellConstraints.Alignment
LEFT
Put the component in the left.
static CellConstraints.Alignment
RIGHT
Put the component in the right.
static CellConstraints.Alignment
TOP
Put the component in the top.
int
gridHeight
Describes the component's vertical grid extent (number of cells).
int
gridWidth
Describes the component's horizontal grid extend (number of cells).
int
gridX
Describes the component's horizontal grid origin (starts at 1).
int
gridY
Describes the component's vertical grid origin (starts at 1).
CellConstraints.Alignment
hAlign
Describes the component's horizontal alignment.
Insets
insets
Describes the component's Insets in it's display area.
CellConstraints.Alignment
vAlign
Describes the component's vertical alignment.

Constructor Summary

CellConstraints()
Constructs a default instance of CellConstraints.
CellConstraints(String encodedConstraints)
Constructs an instance of CellConstraints from the given encoded string properties.
CellConstraints(int gridX, int gridY)
Constructs an instance of CellConstraints for the given cell position.
CellConstraints(int gridX, int gridY, CellConstraints.Alignment hAlign, CellConstraints.Alignment vAlign)
Constructs an instance of CellConstraints for the given cell position, anchor, and fill.
CellConstraints(int gridX, int gridY, int gridWidth, int gridHeight)
Constructs an instance of CellConstraints for the given cell position and size.
CellConstraints(int gridX, int gridY, int gridWidth, int gridHeight, CellConstraints.Alignment hAlign, CellConstraints.Alignment vAlign)
Constructs an instance of CellConstraints for the given cell position and size, anchor, and fill.
CellConstraints(int gridX, int gridY, int gridWidth, int gridHeight, CellConstraints.Alignment hAlign, CellConstraints.Alignment vAlign, Insets insets)
Constructs an instance of CellConstraints for the complete set of available properties.

Method Summary

Object
clone()
Creates a copy of this cell constraints object.
CellConstraints
rc(int row, int col)
Sets row and column origins; sets height and width to 1; uses the default alignments.
CellConstraints
rc(int row, int col, String encodedAlignments)
Sets row and column origins; sets height and width to 1; decodes vertical and horizontal alignments from the given string.
CellConstraints
rc(int row, int col, CellConstraints.Alignment rowAlign, CellConstraints.Alignment colAlign)
Sets the row and column origins; sets width and height to 1; set horizontal and vertical alignment using the specified objects.
CellConstraints
rchw(int row, int col, int rowSpan, int colSpan)
Sets the row, column, height, and width; uses default alignments.
CellConstraints
rchw(int row, int col, int rowSpan, int colSpan, String encodedAlignments)
Sets the row, column, height, and width; decodes the vertical and horizontal alignments from the given string.
CellConstraints
rchw(int row, int col, int rowSpan, int colSpan, CellConstraints.Alignment rowAlign, CellConstraints.Alignment colAlign)
Sets the row, column, height, and width; sets the vertical and horizontal aligment using the specified alignment objects.
CellConstraints
rcw(int row, int col, int colSpan)
Sets the row, column, height, and width; uses a height (row span) of 1 and the vertical and horizontal default alignments.
CellConstraints
rcw(int row, int col, int colSpan, String encodedAlignments)
Sets the row, column, height, and width; decodes the vertical and horizontal alignments from the given string.
CellConstraints
rcw(int row, int col, int colSpan, CellConstraints.Alignment rowAlign, CellConstraints.Alignment colAlign)
Sets the row, column, height, and width; sets the vertical and horizontalaligment using the specified alignment objects.
String
toShortString()
Returns a short string representation of this constraints object.
String
toShortString(FormLayout layout)
Returns a short string representation of this constraints object.
String
toString()
Constructs and returns a string representation of this constraints object.
CellConstraints
xy(int col, int row)
Sets column and row origins; sets width and height to 1; uses the default alignments.
CellConstraints
xy(int col, int row, String encodedAlignments)
Sets column and row origins; sets width and height to 1; decodes horizontal and vertical alignments from the given string.
CellConstraints
xy(int col, int row, CellConstraints.Alignment colAlign, CellConstraints.Alignment rowAlign)
Sets the column and row origins; sets width and height to 1; set horizontal and vertical alignment using the specified objects.
CellConstraints
xyw(int col, int row, int colSpan)
Sets the column, row, width, and height; uses a height (row span) of 1 and the horizontal and vertical default alignments.
CellConstraints
xyw(int col, int row, int colSpan, String encodedAlignments)
Sets the column, row, width, and height; decodes the horizontal and vertical alignments from the given string.
CellConstraints
xyw(int col, int row, int colSpan, CellConstraints.Alignment colAlign, CellConstraints.Alignment rowAlign)
Sets the column, row, width, and height; sets the horizontal and vertical aligment using the specified alignment objects.
CellConstraints
xywh(int col, int row, int colSpan, int rowSpan)
Sets the column, row, width, and height; uses default alignments.
CellConstraints
xywh(int col, int row, int colSpan, int rowSpan, String encodedAlignments)
Sets the column, row, width, and height; decodes the horizontal and vertical alignments from the given string.
CellConstraints
xywh(int col, int row, int colSpan, int rowSpan, CellConstraints.Alignment colAlign, CellConstraints.Alignment rowAlign)
Sets the column, row, width, and height; sets the horizontal and vertical aligment using the specified alignment objects.

Field Details

BOTTOM

public static final CellConstraints.Alignment BOTTOM
Put the component in the bottom.

CENTER

public static final CellConstraints.Alignment CENTER
Put the component in the center.

DEFAULT

public static final CellConstraints.Alignment DEFAULT
Use the column's or row's default alignment.

FILL

public static final CellConstraints.Alignment FILL
Fill the cell either horizontally or vertically.

LEFT

public static final CellConstraints.Alignment LEFT
Put the component in the left.

RIGHT

public static final CellConstraints.Alignment RIGHT
Put the component in the right.

TOP

public static final CellConstraints.Alignment TOP
Put the component in the top.

gridHeight

public int gridHeight
Describes the component's vertical grid extent (number of cells).

gridWidth

public int gridWidth
Describes the component's horizontal grid extend (number of cells).

gridX

public int gridX
Describes the component's horizontal grid origin (starts at 1).

gridY

public int gridY
Describes the component's vertical grid origin (starts at 1).

hAlign

public CellConstraints.Alignment hAlign
Describes the component's horizontal alignment.

insets

public Insets insets
Describes the component's Insets in it's display area.

vAlign

public CellConstraints.Alignment vAlign
Describes the component's vertical alignment.

Constructor Details

CellConstraints

public CellConstraints()
Constructs a default instance of CellConstraints.

CellConstraints

public CellConstraints(String encodedConstraints)
Constructs an instance of CellConstraints from the given encoded string properties.

Examples:

 new CellConstraints("1, 3");
 new CellConstraints("1, 3, left, bottom");
 new CellConstraints("1, 3, 2, 1, left, bottom");
 new CellConstraints("1, 3, 2, 1, l, b");
 
Parameters:
encodedConstraints - the constraints encoded as string

CellConstraints

public CellConstraints(int gridX,
                       int gridY)
Constructs an instance of CellConstraints for the given cell position.

Examples:

 new CellConstraints(1, 3);
 new CellConstraints(1, 3);
 
Parameters:
gridX - the component's horizontal grid origin
gridY - the component's vertical grid origin

CellConstraints

public CellConstraints(int gridX,
                       int gridY,
                       CellConstraints.Alignment hAlign,
                       CellConstraints.Alignment vAlign)
Constructs an instance of CellConstraints for the given cell position, anchor, and fill.

Examples:

 new CellConstraints(1, 3, CellConstraints.LEFT,   CellConstraints.BOTTOM);
 new CellConstraints(1, 3, CellConstraints.CENTER, CellConstraints.FILL);
 
Parameters:
gridX - the component's horizontal grid origin
gridY - the component's vertical grid origin
hAlign - the component's horizontal alignment
vAlign - the component's vertical alignment

CellConstraints

public CellConstraints(int gridX,
                       int gridY,
                       int gridWidth,
                       int gridHeight)
Constructs an instance of CellConstraints for the given cell position and size.

Examples:

 new CellConstraints(1, 3, 2, 1);
 new CellConstraints(1, 3, 7, 3);
 
Parameters:
gridX - the component's horizontal grid origin
gridY - the component's vertical grid origin
gridWidth - the component's horizontal extent
gridHeight - the component's vertical extent

CellConstraints

public CellConstraints(int gridX,
                       int gridY,
                       int gridWidth,
                       int gridHeight,
                       CellConstraints.Alignment hAlign,
                       CellConstraints.Alignment vAlign)
Constructs an instance of CellConstraints for the given cell position and size, anchor, and fill.

Examples:

 new CellConstraints(1, 3, 2, 1, CellConstraints.LEFT,   CellConstraints.BOTTOM);
 new CellConstraints(1, 3, 7, 3, CellConstraints.CENTER, CellConstraints.FILL);
 
Parameters:
gridX - the component's horizontal grid origin
gridY - the component's vertical grid origin
gridWidth - the component's horizontal extent
gridHeight - the component's vertical extent
hAlign - the component's horizontal alignment
vAlign - the component's vertical alignment

CellConstraints

public CellConstraints(int gridX,
                       int gridY,
                       int gridWidth,
                       int gridHeight,
                       CellConstraints.Alignment hAlign,
                       CellConstraints.Alignment vAlign,
                       Insets insets)
Constructs an instance of CellConstraints for the complete set of available properties.

Examples:

 new CellConstraints(1, 3, 2, 1, CellConstraints.LEFT,   CellConstraints.BOTTOM, new Insets(0, 1, 0, 3));
 new CellConstraints(1, 3, 7, 3, CellConstraints.CENTER, CellConstraints.FILL,   new Insets(0, 1, 0, 0));
 
Parameters:
gridX - the component's horizontal grid origin
gridY - the component's vertical grid origin
gridWidth - the component's horizontal extent
gridHeight - the component's vertical extent
hAlign - the component's horizontal alignment
vAlign - the component's vertical alignment
insets - the component's display area Insets

Method Details

clone

public Object clone()
Creates a copy of this cell constraints object.
Returns:
a copy of this cell constraints object

rc

public CellConstraints rc(int row,
                          int col)
Sets row and column origins; sets height and width to 1; uses the default alignments.

Examples:

 cc.rc(1, 1);
 cc.rc(3, 1);
 
Parameters:
row - the new row index
col - the new column index
Returns:
this
Since:
1.1

rc

public CellConstraints rc(int row,
                          int col,
                          String encodedAlignments)
Sets row and column origins; sets height and width to 1; decodes vertical and horizontal alignments from the given string.

Examples:

 cc.rc(3, 1, "bottom, left");
 cc.rc(3, 1, "b, l");
 cc.rc(3, 1, "fill, center");
 cc.rc(3, 1, "f, c");
 
Parameters:
row - the new row index
col - the new column index
encodedAlignments - describes the vertical and horizontal alignments
Returns:
this
Since:
1.1

rc

public CellConstraints rc(int row,
                          int col,
                          CellConstraints.Alignment rowAlign,
                          CellConstraints.Alignment colAlign)
Sets the row and column origins; sets width and height to 1; set horizontal and vertical alignment using the specified objects.

Examples:

 cc.rc(3, 1, CellConstraints.BOTTOM, CellConstraints.LEFT);
 cc.rc(3, 1, CellConstraints.FILL,   CellConstraints.CENTER);
 
Parameters:
row - the new row index
col - the new column index
rowAlign - vertical component alignment
colAlign - horizontal component alignment
Returns:
this
Since:
1.1

rchw

public CellConstraints rchw(int row,
                            int col,
                            int rowSpan,
                            int colSpan)
Sets the row, column, height, and width; uses default alignments.

Examples:

 cc.rchw(1, 3, 2, 1);
 cc.rchw(1, 3, 7, 3);
 
Parameters:
row - the new row index
col - the new column index
rowSpan - the row span or grid height
colSpan - the column span or grid width
Returns:
this
Since:
1.1

rchw

public CellConstraints rchw(int row,
                            int col,
                            int rowSpan,
                            int colSpan,
                            String encodedAlignments)
Sets the row, column, height, and width; decodes the vertical and horizontal alignments from the given string.

Examples:

 cc.rchw(3, 1, 1, 2, "bottom, left");
 cc.rchw(3, 1, 1, 2, "b, l");
 cc.rchw(3, 1, 3, 7, "fill, center");
 cc.rchw(3, 1, 3, 7, "f, c");
 
Parameters:
row - the new row index
col - the new column index
rowSpan - the row span or grid height
colSpan - the column span or grid width
encodedAlignments - describes the vertical and horizontal alignments
Returns:
this
Since:
1.1

rchw

public CellConstraints rchw(int row,
                            int col,
                            int rowSpan,
                            int colSpan,
                            CellConstraints.Alignment rowAlign,
                            CellConstraints.Alignment colAlign)
Sets the row, column, height, and width; sets the vertical and horizontal aligment using the specified alignment objects.

Examples:

 cc.rchw(3, 1, 1, 2, CellConstraints.BOTTOM, CellConstraints.LEFT);
 cc.rchw(3, 1, 3, 7, CellConstraints.FILL,   CellConstraints.CENTER);
 
Parameters:
row - the new row index
col - the new column index
rowSpan - the row span or grid height
colSpan - the column span or grid width
rowAlign - vertical component alignment
colAlign - horizontal component alignment
Returns:
this
Since:
1.1

rcw

public CellConstraints rcw(int row,
                           int col,
                           int colSpan)
Sets the row, column, height, and width; uses a height (row span) of 1 and the vertical and horizontal default alignments.

Examples:

 cc.rcw(3, 1, 7);
 cc.rcw(3, 1, 2);
 
Parameters:
row - the new row index
col - the new column index
colSpan - the column span or grid width
Returns:
this
Since:
1.1

rcw

public CellConstraints rcw(int row,
                           int col,
                           int colSpan,
                           String encodedAlignments)
Sets the row, column, height, and width; decodes the vertical and horizontal alignments from the given string. The row span (height) is set to 1.

Examples:

 cc.rcw(3, 1, 7, "bottom, left");
 cc.rcw(3, 1, 7, "b, l");
 cc.rcw(3, 1, 2, "fill, center");
 cc.rcw(3, 1, 2, "f, c");
 
Parameters:
row - the new row index
col - the new column index
colSpan - the column span or grid width
encodedAlignments - describes the vertical and horizontal alignments
Returns:
this
Since:
1.1

rcw

public CellConstraints rcw(int row,
                           int col,
                           int colSpan,
                           CellConstraints.Alignment rowAlign,
                           CellConstraints.Alignment colAlign)
Sets the row, column, height, and width; sets the vertical and horizontalaligment using the specified alignment objects. The row span (height) is set to 1.

Examples:

 cc.rcw(3, 1, 2, CellConstraints.BOTTOM, CellConstraints.LEFT);
 cc.rcw(3, 1, 7, CellConstraints.FILL,   CellConstraints.CENTER);
 
Parameters:
row - the new row index
col - the new column index
colSpan - the column span or grid width
rowAlign - vertical component alignment
colAlign - horizontal component alignment
Returns:
this
Since:
1.1

toShortString

public String toShortString()
Returns a short string representation of this constraints object.
Returns:
a short string representation of this constraints object

toShortString

public String toShortString(FormLayout layout)
Returns a short string representation of this constraints object. This method can use the given FormLayout to display extra information how default alignments are mapped to concrete alignments. Therefore it asks the related column and row as specified by this constraints object.
Parameters:
layout - the layout to be presented as a string
Returns:
a short string representation of this constraints object

toString

public String toString()
Constructs and returns a string representation of this constraints object.
Returns:
string representation of this constraints object

xy

public CellConstraints xy(int col,
                          int row)
Sets column and row origins; sets width and height to 1; uses the default alignments.

Examples:

 cc.xy(1, 1);
 cc.xy(1, 3);
 
Parameters:
col - the new column index
row - the new row index
Returns:
this

xy

public CellConstraints xy(int col,
                          int row,
                          String encodedAlignments)
Sets column and row origins; sets width and height to 1; decodes horizontal and vertical alignments from the given string.

Examples:

 cc.xy(1, 3, "left, bottom");
 cc.xy(1, 3, "l, b");
 cc.xy(1, 3, "center, fill");
 cc.xy(1, 3, "c, f");
 
Parameters:
col - the new column index
row - the new row index
encodedAlignments - describes the horizontal and vertical alignments
Returns:
this

xy

public CellConstraints xy(int col,
                          int row,
                          CellConstraints.Alignment colAlign,
                          CellConstraints.Alignment rowAlign)
Sets the column and row origins; sets width and height to 1; set horizontal and vertical alignment using the specified objects.

Examples:

 cc.xy(1, 3, CellConstraints.LEFT,   CellConstraints.BOTTOM);
 cc.xy(1, 3, CellConstraints.CENTER, CellConstraints.FILL);
 
Parameters:
col - the new column index
row - the new row index
colAlign - horizontal component alignment
rowAlign - vertical component alignment
Returns:
this

xyw

public CellConstraints xyw(int col,
                           int row,
                           int colSpan)
Sets the column, row, width, and height; uses a height (row span) of 1 and the horizontal and vertical default alignments.

Examples:

 cc.xyw(1, 3, 7);
 cc.xyw(1, 3, 2);
 
Parameters:
col - the new column index
row - the new row index
colSpan - the column span or grid width
Returns:
this

xyw

public CellConstraints xyw(int col,
                           int row,
                           int colSpan,
                           String encodedAlignments)
Sets the column, row, width, and height; decodes the horizontal and vertical alignments from the given string. The row span (height) is set to 1.

Examples:

 cc.xyw(1, 3, 7, "left, bottom");
 cc.xyw(1, 3, 7, "l, b");
 cc.xyw(1, 3, 2, "center, fill");
 cc.xyw(1, 3, 2, "c, f");
 
Parameters:
col - the new column index
row - the new row index
colSpan - the column span or grid width
encodedAlignments - describes the horizontal and vertical alignments
Returns:
this

xyw

public CellConstraints xyw(int col,
                           int row,
                           int colSpan,
                           CellConstraints.Alignment colAlign,
                           CellConstraints.Alignment rowAlign)
Sets the column, row, width, and height; sets the horizontal and vertical aligment using the specified alignment objects. The row span (height) is set to 1.

Examples:

 cc.xyw(1, 3, 2, CellConstraints.LEFT,   CellConstraints.BOTTOM);
 cc.xyw(1, 3, 7, CellConstraints.CENTER, CellConstraints.FILL);
 
Parameters:
col - the new column index
row - the new row index
colSpan - the column span or grid width
colAlign - horizontal component alignment
rowAlign - vertical component alignment
Returns:
this

xywh

public CellConstraints xywh(int col,
                            int row,
                            int colSpan,
                            int rowSpan)
Sets the column, row, width, and height; uses default alignments.

Examples:

 cc.xywh(1, 3, 2, 1);
 cc.xywh(1, 3, 7, 3);
 
Parameters:
col - the new column index
row - the new row index
colSpan - the column span or grid width
rowSpan - the row span or grid height
Returns:
this

xywh

public CellConstraints xywh(int col,
                            int row,
                            int colSpan,
                            int rowSpan,
                            String encodedAlignments)
Sets the column, row, width, and height; decodes the horizontal and vertical alignments from the given string.

Examples:

 cc.xywh(1, 3, 2, 1, "left, bottom");
 cc.xywh(1, 3, 2, 1, "l, b");
 cc.xywh(1, 3, 7, 3, "center, fill");
 cc.xywh(1, 3, 7, 3, "c, f");
 
Parameters:
col - the new column index
row - the new row index
colSpan - the column span or grid width
rowSpan - the row span or grid height
encodedAlignments - describes the horizontal and vertical alignments
Returns:
this

xywh

public CellConstraints xywh(int col,
                            int row,
                            int colSpan,
                            int rowSpan,
                            CellConstraints.Alignment colAlign,
                            CellConstraints.Alignment rowAlign)
Sets the column, row, width, and height; sets the horizontal and vertical aligment using the specified alignment objects.

Examples:

 cc.xywh(1, 3, 2, 1, CellConstraints.LEFT,   CellConstraints.BOTTOM);
 cc.xywh(1, 3, 7, 3, CellConstraints.CENTER, CellConstraints.FILL);
 
Parameters:
col - the new column index
row - the new row index
colSpan - the column span or grid width
rowSpan - the row span or grid height
colAlign - horizontal component alignment
rowAlign - vertical component alignment
Returns:
this

Copyright © 2002-2007 JGoodies Karsten Lentzsch. All Rights Reserved.