Class CellConstraints

java.lang.Object
com.jgoodies.forms.layout.CellConstraints
All Implemented Interfaces:
Serializable, Cloneable

public final class CellConstraints extends Object implements Cloneable, Serializable
Defines constraints for components that are laid 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.

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.

Version:
$Revision: 1.15 $
See Also:
  • Field Details

    • 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.
    • CENTER

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

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

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

      private static final CellConstraints.Alignment[] VALUES
      An array of all enumeration values used to canonicalize deserialized alignments.
    • EMPTY_INSETS

      private static final Insets EMPTY_INSETS
      A reusable Insets object to reduce object instantiation.
    • 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).
    • gridWidth

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

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

      Describes the component's horizontal alignment.
    • vAlign

      Describes the component's vertical alignment.
    • insets

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

      public Boolean honorsVisibility
      Describes whether individual components shall be taken into account by the FormLayout if 1) they are invisible and 2) the FormLayout does not honor the visibility. See FormLayout.setHonorsVisibility(boolean) and FormLayout.setHonorsVisibility(Component, Boolean) for a full description of this feature.
  • Constructor Details

    • CellConstraints

      public CellConstraints()
      Constructs a default instance of CellConstraints.
    • 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
      Throws:
      IndexOutOfBoundsException - if the grid origin or extent is negative
      NullPointerException - if the horizontal or vertical alignment is null
      IllegalArgumentException - if an alignment orientation is invalid
    • 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
  • Method Details

    • translate

      public CellConstraints translate(int dx, int dy)
      Creates and returns a new CellConstraints instance where the origin has been moved along the X and Y axis as specified by dx and dy respectively.
      Parameters:
      dx - the distance to move along the X axis
      dy - the distance to move along the Y axis
      Returns:
      the new CellConstraints instance with a translated grid origin
      Since:
      1.8
    • 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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
    • 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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
    • 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 alignment 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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
    • 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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
    • 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 alignment 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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
    • 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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
      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
    • 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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
      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 horizontal alignment 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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
      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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
      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 alignment 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
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
      Since:
      1.1
    • initFromConstraints

      private void initFromConstraints(String encodedConstraints)
      Decodes and returns the grid bounds and alignments for this constraints as an array of six integers. The string representation is a comma separated sequence, one of
       "x, y"
       "x, y, w, h"
       "x, y, hAlign, vAlign"
       "x, y, w, h, hAlign, vAlign"
       
      Parameters:
      encodedConstraints - represents horizontal and vertical alignment
      Throws:
      IllegalArgumentException - if the encoded constraints do not follow the constraint syntax
    • setAlignments

      private void setAlignments(String encodedAlignments, boolean horizontalThenVertical)
      Decodes a string description for the horizontal and vertical alignment and sets this CellConstraints' alignment values. If the boolean is true the horizontal alignment is the first token, and the vertical alignment is the second token. if the boolean is false the vertical alignment comes first.

      Valid horizontal alignments are: left, center, right, default, and fill. Valid vertical alignments are: top, center, bottom, default, and fill. The anchor's string representation abbreviates the alignment: l, c, r, d, f, t, and b.

      Anchor examples: "c, c" is centered, "l, t" is northwest, "c, t" is north, "r, c" east. "c, d" is horizontally centered and uses the row's default alignment. "d, t" is on top of the cell and uses the column's default alignment.

      Parameters:
      encodedAlignments - represents horizontal and vertical alignment
      Throws:
      IllegalArgumentException - if an alignment orientation is invalid
    • decodeInt

      private static Integer decodeInt(String token)
      Decodes an integer string representation and returns the associated Integer or null in case of an invalid number format.
      Parameters:
      token - the encoded integer
      Returns:
      the decoded Integer or null
    • decodeAlignment

      private static CellConstraints.Alignment decodeAlignment(String encodedAlignment)
      Parses an alignment string description and returns the corresponding alignment value.
      Parameters:
      encodedAlignment - the encoded alignment
      Returns:
      the associated Alignment instance
    • ensureValidGridBounds

      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.
      Parameters:
      colCount - number of columns in the grid
      rowCount - number of rows in the grid
      Throws:
      IndexOutOfBoundsException - if the display area described by this constraints object is not inside the grid
    • ensureValidOrientations

      private static void ensureValidOrientations(CellConstraints.Alignment horizontalAlignment, CellConstraints.Alignment verticalAlignment)
      Checks and verifies that the horizontal alignment is a horizontal and the vertical alignment is vertical.
      Parameters:
      horizontalAlignment - the horizontal alignment
      verticalAlignment - the vertical alignment
      Throws:
      IllegalArgumentException - if an alignment is invalid
    • setBounds

      void setBounds(Component c, FormLayout layout, 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.
      Parameters:
      c - the component to set bounds
      layout - the FormLayout instance that computes the bounds
      cellBounds - the cell's bounds
      minWidthMeasure - measures the minimum width
      minHeightMeasure - measures the minimum height
      prefWidthMeasure - measures the preferred width
      prefHeightMeasure - measures the preferred height
    • concreteAlignment

      private static CellConstraints.Alignment concreteAlignment(CellConstraints.Alignment cellAlignment, FormSpec formSpec)
      Computes and returns the concrete alignment. Takes into account the cell alignment and the FormSpec if applicable.

      If this constraints object doesn't belong to a single column or row, the formSpec parameter is null. In this case the cell alignment is answered, but DEFAULT is mapped to FILL.

      If the cell belongs to a single column or row, we use the cell alignment, unless it is DEFAULT, where the alignment is inherited from the column or row resp.

      Parameters:
      cellAlignment - this cell's alignment
      formSpec - the associated column or row specification
      Returns:
      the concrete alignment
    • usedAlignment

      private static CellConstraints.Alignment usedAlignment(CellConstraints.Alignment cellAlignment, FormSpec formSpec)
      Returns the alignment used for a given form constraints object. The cell alignment overrides the column or row default, unless it is DEFAULT. In the latter case, we use the column or row alignment.
      Parameters:
      cellAlignment - this cell constraint's alignment
      formSpec - the associated column or row specification
      Returns:
      the alignment used
    • componentSize

      private static int componentSize(Component component, FormSpec formSpec, int cellSize, FormLayout.Measure minMeasure, FormLayout.Measure prefMeasure)
      Computes and returns the pixel size of the given component using the given form specification, measures, and cell size.
      Parameters:
      component - the component to measure
      formSpec - the specification of the component's column/row
      minMeasure - the measure for the minimum size
      prefMeasure - the measure for the preferred size
      cellSize - the cell size
      Returns:
      the component size as measured or a constant
    • origin

      private static int origin(CellConstraints.Alignment alignment, int cellOrigin, int cellSize, int componentSize)
      Computes and returns the component's pixel origin.
      Parameters:
      alignment - the component's alignment
      cellOrigin - the origin of the display area
      cellSize - the extent of the display area
      componentSize - the component's size
      Returns:
      the component's pixel origin
    • extent

      private static int extent(CellConstraints.Alignment alignment, int cellSize, int componentSize)
      Returns the component's pixel extent.
      Parameters:
      alignment - the component's alignment
      cellSize - the size of the display area
      componentSize - the component's size
      Returns:
      the component's pixel extent
    • clone

      public Object clone()
      Creates a copy of this cell constraints object.
      Overrides:
      clone in class Object
      Returns:
      a copy of this cell constraints object
    • toString

      public String toString()
      Constructs and returns a string representation of this constraints object.
      Overrides:
      toString in class Object
      Returns:
      string representation of this constraints object
    • 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
    • formatInt

      private static String formatInt(int number)
      Returns an integer that has a minimum of two characters.
      Parameters:
      number - the number to format
      Returns:
      a string representation for a number with a minimum of two chars