public final class CellConstraints
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable
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.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.
Modifier and Type | Class and Description |
---|---|
static class |
CellConstraints.Alignment
An ordinal-based serializable typesafe enumeration for component
alignment types as used by the
FormLayout . |
Modifier and Type | Field and Description |
---|---|
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.
|
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.
|
java.awt.Insets |
insets
Describes the component's
Insets in it's display area. |
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.
|
CellConstraints.Alignment |
vAlign
Describes the component's vertical alignment.
|
Constructor and Description |
---|
CellConstraints()
Constructs a default instance of
CellConstraints . |
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,
java.awt.Insets insets)
Constructs an instance of
CellConstraints for
the complete set of available properties. |
CellConstraints(java.lang.String encodedConstraints)
Constructs an instance of
CellConstraints from
the given encoded string properties. |
Modifier and Type | Method and Description |
---|---|
java.lang.Object |
clone()
Creates a copy of this cell constraints object.
|
(package private) void |
ensureValidGridBounds(int colCount,
int rowCount)
Checks and verifies that this constraints object has valid grid
index values, i. e. the display area cells are inside the form's grid.
|
(package private) void |
setBounds(java.awt.Component c,
FormLayout layout,
java.awt.Rectangle cellBounds,
FormLayout.Measure minWidthMeasure,
FormLayout.Measure minHeightMeasure,
FormLayout.Measure prefWidthMeasure,
FormLayout.Measure prefHeightMeasure)
Sets the component's bounds using the given component and cell bounds.
|
java.lang.String |
toShortString()
Returns a short string representation of this constraints object.
|
java.lang.String |
toShortString(FormLayout layout)
Returns a short string representation of this constraints object.
|
java.lang.String |
toString()
Constructs and returns a string representation of this constraints object.
|
CellConstraints |
xy(int col,
int row)
Sets row and column origins; sets width and height to 1;
uses the default alignments.
|
CellConstraints |
xy(int col,
int row,
CellConstraints.Alignment colAlign,
CellConstraints.Alignment rowAlign)
Sets the row and column origins; sets width and height to 1;
set horizontal and vertical alignment using the specified objects.
|
CellConstraints |
xy(int col,
int row,
java.lang.String encodedAlignments)
Sets row and column origins; sets width and height to 1;
decodes horizontal and vertical alignments from the given string.
|
CellConstraints |
xyw(int col,
int row,
int colSpan)
Sets the row, column, 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,
CellConstraints.Alignment colAlign,
CellConstraints.Alignment rowAlign)
Sets the row, column, width, and height; sets the horizontal
and vertical alignment using the specified alignment objects.
|
CellConstraints |
xyw(int col,
int row,
int colSpan,
java.lang.String encodedAlignments)
Sets the row, column, width, and height;
decodes the horizontal and vertical alignments from the given string.
|
CellConstraints |
xywh(int col,
int row,
int colSpan,
int rowSpan)
Sets the row, column, width, and height; uses default alignments.
|
CellConstraints |
xywh(int col,
int row,
int colSpan,
int rowSpan,
CellConstraints.Alignment colAlign,
CellConstraints.Alignment rowAlign)
Sets the row, column, width, and height; sets the horizontal
and vertical alignment using the specified alignment objects.
|
CellConstraints |
xywh(int col,
int row,
int colSpan,
int rowSpan,
java.lang.String encodedAlignments)
Sets the row, column, width, and height;
decodes the horizontal and vertical alignments from the given string.
|
public static final CellConstraints.Alignment DEFAULT
public static final CellConstraints.Alignment FILL
public static final CellConstraints.Alignment LEFT
public static final CellConstraints.Alignment RIGHT
public static final CellConstraints.Alignment CENTER
public static final CellConstraints.Alignment TOP
public static final CellConstraints.Alignment BOTTOM
public int gridX
public int gridY
public int gridWidth
public int gridHeight
public CellConstraints.Alignment hAlign
public CellConstraints.Alignment vAlign
public java.awt.Insets insets
Insets
in it's display area.public CellConstraints()
CellConstraints
.public CellConstraints(int gridX, int gridY)
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 originpublic CellConstraints(int gridX, int gridY, CellConstraints.Alignment hAlign, CellConstraints.Alignment vAlign)
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 alignmentpublic CellConstraints(int gridX, int gridY, int gridWidth, int gridHeight)
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 extentpublic CellConstraints(int gridX, int gridY, int gridWidth, int gridHeight, CellConstraints.Alignment hAlign, CellConstraints.Alignment vAlign)
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 alignmentpublic CellConstraints(int gridX, int gridY, int gridWidth, int gridHeight, CellConstraints.Alignment hAlign, CellConstraints.Alignment vAlign, java.awt.Insets insets)
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
java.lang.IndexOutOfBoundsException
- if the grid origin or extent is negativejava.lang.NullPointerException
- if the horizontal or vertical alignment is nulljava.lang.IllegalArgumentException
- if an alignment orientation is invalidpublic CellConstraints(java.lang.String encodedConstraints)
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 stringpublic CellConstraints xy(int col, int row)
Examples:
cc.xy(1, 1); cc.xy(1, 3);
col
- the new column indexrow
- the new row indexpublic CellConstraints xy(int col, int row, java.lang.String encodedAlignments)
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 alignmentsjava.lang.IllegalArgumentException
- if an alignment orientation is invalidpublic CellConstraints xy(int col, int row, CellConstraints.Alignment colAlign, CellConstraints.Alignment rowAlign)
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 alignmentpublic CellConstraints xyw(int col, int row, int colSpan)
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 widthpublic CellConstraints xyw(int col, int row, int colSpan, java.lang.String encodedAlignments)
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 alignmentsjava.lang.IllegalArgumentException
- if an alignment orientation is invalidpublic CellConstraints xyw(int col, int row, int colSpan, CellConstraints.Alignment colAlign, CellConstraints.Alignment rowAlign)
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 alignmentjava.lang.IllegalArgumentException
- if an alignment orientation is invalidpublic CellConstraints xywh(int col, int row, int colSpan, int rowSpan)
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 heightpublic CellConstraints xywh(int col, int row, int colSpan, int rowSpan, java.lang.String encodedAlignments)
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 alignmentsjava.lang.IllegalArgumentException
- if an alignment orientation is invalidpublic CellConstraints xywh(int col, int row, int colSpan, int rowSpan, CellConstraints.Alignment colAlign, CellConstraints.Alignment rowAlign)
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 alignmentjava.lang.IllegalArgumentException
- if an alignment orientation is invalidvoid ensureValidGridBounds(int colCount, int rowCount)
colCount
- number of columns in the gridrowCount
- number of rows in the gridjava.lang.IndexOutOfBoundsException
- if the display area described
by this constraints object is not inside the gridvoid setBounds(java.awt.Component c, FormLayout layout, java.awt.Rectangle cellBounds, FormLayout.Measure minWidthMeasure, FormLayout.Measure minHeightMeasure, FormLayout.Measure prefWidthMeasure, FormLayout.Measure prefHeightMeasure)
c
- the component to set boundslayout
- the FormLayout instance that computes the boundscellBounds
- the cell's boundsminWidthMeasure
- measures the minimum widthminHeightMeasure
- measures the minimum heightprefWidthMeasure
- measures the preferred widthprefHeightMeasure
- measures the preferred heightpublic java.lang.Object clone()
clone
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
public java.lang.String toShortString()
public java.lang.String toShortString(FormLayout layout)
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