Class CellConstraints

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

    public final class CellConstraints
    extends java.lang.Object
    implements java.lang.Cloneable, java.io.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 $
    Author:
    Karsten Lentzsch
    See Also:
    CC, Serialized Form
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  CellConstraints.Alignment
      An ordinal-based serializable typesafe enumeration for component alignment types as used by the FormLayout.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.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, 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 rc​(int row, int col, java.lang.String encodedAlignments)
      Sets row and column origins; sets height and width to 1; decodes vertical and horizontal alignments from the given string.
      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, CellConstraints.Alignment rowAlign, CellConstraints.Alignment colAlign)
      Sets the row, column, height, and width; sets the vertical and horizontal alignment using the specified alignment objects.
      CellConstraints rchw​(int row, int col, int rowSpan, int colSpan, java.lang.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)
      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, CellConstraints.Alignment rowAlign, CellConstraints.Alignment colAlign)
      Sets the row, column, height, and width; sets the vertical and horizontal alignment using the specified alignment objects.
      CellConstraints rcw​(int row, int col, int colSpan, java.lang.String encodedAlignments)
      Sets the row, column, height, and width; decodes the vertical and horizontal alignments from the given string.
      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 column and row 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 column and row 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 column and row 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 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, CellConstraints.Alignment colAlign, CellConstraints.Alignment rowAlign)
      Sets the column, row, 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 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)
      Sets the column, row, width, and height; uses default alignments.
      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.
      CellConstraints xywh​(int col, int row, int colSpan, int rowSpan, java.lang.String encodedAlignments)
      Sets the column, row, width, and height; decodes the horizontal and vertical alignments from the given string.
      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • 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).
      • insets

        public java.awt.Insets insets
        Describes the component's Insets in it's display area.
    • Constructor Detail

      • 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,
                               java.awt.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:
        java.lang.IndexOutOfBoundsException - if the grid origin or extent is negative
        java.lang.NullPointerException - if the horizontal or vertical alignment is null
        java.lang.IllegalArgumentException - if an alignment orientation is invalid
      • CellConstraints

        public CellConstraints​(java.lang.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 Detail

      • 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,
                                  java.lang.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:
        java.lang.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,
                                   java.lang.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:
        java.lang.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:
        java.lang.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,
                                    java.lang.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:
        java.lang.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:
        java.lang.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,
                                  java.lang.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:
        java.lang.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,
                                   java.lang.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:
        java.lang.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:
        java.lang.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,
                                    java.lang.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:
        java.lang.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:
        java.lang.IllegalArgumentException - if an alignment orientation is invalid
        Since:
        1.1
      • clone

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

        public java.lang.String toString()
        Constructs and returns a string representation of this constraints object.
        Overrides:
        toString in class java.lang.Object
        Returns:
        string representation of this constraints object
      • toShortString

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

        public java.lang.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