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.
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");
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);
gridX
- the component's horizontal grid origingridY
- 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);
gridX
- the component's horizontal grid origingridY
- the component's vertical grid originhAlign
- the component's horizontal alignmentvAlign
- 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);
gridX
- the component's horizontal grid origingridY
- the component's vertical grid origingridWidth
- the component's horizontal extentgridHeight
- 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);
gridX
- the component's horizontal grid origingridY
- the component's vertical grid origingridWidth
- the component's horizontal extentgridHeight
- the component's vertical extenthAlign
- the component's horizontal alignmentvAlign
- 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));
gridX
- the component's horizontal grid origingridY
- the component's vertical grid origingridWidth
- the component's horizontal extentgridHeight
- the component's vertical extenthAlign
- the component's horizontal alignmentvAlign
- the component's vertical alignmentinsets
- the component's display area Insets
clone
public Object clone()
Creates a copy of this cell constraints object.
- 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);
row
- the new row indexcol
- the new column index
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");
row
- the new row indexcol
- the new column indexencodedAlignments
- describes the vertical and horizontal alignments
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);
row
- the new row indexcol
- the new column indexrowAlign
- vertical component alignmentcolAlign
- horizontal component alignment
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);
row
- the new row indexcol
- the new column indexrowSpan
- the row span or grid heightcolSpan
- the column span or grid width
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");
row
- the new row indexcol
- the new column indexrowSpan
- the row span or grid heightcolSpan
- the column span or grid widthencodedAlignments
- describes the vertical and horizontal alignments
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);
row
- the new row indexcol
- the new column indexrowSpan
- the row span or grid heightcolSpan
- the column span or grid widthrowAlign
- vertical component alignmentcolAlign
- horizontal component alignment
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);
row
- the new row indexcol
- the new column indexcolSpan
- the column span or grid width
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");
row
- the new row indexcol
- the new column indexcolSpan
- the column span or grid widthencodedAlignments
- describes the vertical and horizontal alignments
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);
row
- the new row indexcol
- the new column indexcolSpan
- the column span or grid widthrowAlign
- vertical component alignmentcolAlign
- horizontal component alignment
toShortString
public String toShortString()
Returns a short string representation of this constraints object.
- 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.
layout
- the layout to be presented as a string
- a short string representation of this constraints object
toString
public String toString()
Constructs and returns a string representation of this constraints object.
- 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);
col
- the new column indexrow
- the new row index
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");
col
- the new column indexrow
- the new row indexencodedAlignments
- describes the horizontal and vertical alignments
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);
col
- the new column indexrow
- the new row indexcolAlign
- horizontal component alignmentrowAlign
- vertical component alignment
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);
col
- the new column indexrow
- the new row indexcolSpan
- the column span or grid width
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");
col
- the new column indexrow
- the new row indexcolSpan
- the column span or grid widthencodedAlignments
- describes the horizontal and vertical alignments
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);
col
- the new column indexrow
- the new row indexcolSpan
- the column span or grid widthcolAlign
- horizontal component alignmentrowAlign
- vertical component alignment
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);
col
- the new column indexrow
- the new row indexcolSpan
- the column span or grid widthrowSpan
- the row span or grid height
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");
col
- the new column indexrow
- the new row indexcolSpan
- the column span or grid widthrowSpan
- the row span or grid heightencodedAlignments
- describes the horizontal and vertical alignments
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);
col
- the new column indexrow
- the new row indexcolSpan
- the column span or grid widthrowSpan
- the row span or grid heightcolAlign
- horizontal component alignmentrowAlign
- vertical component alignment