# Class TableLayout

java.lang.Object
com.codename1.ui.layouts.Layout
com.codename1.ui.table.TableLayout

public class TableLayout extends Layout

TableLayout is a very elaborate constraint based layout manager that can arrange elements in rows/columns while defining constraints to control complex behavior such as spanning, alignment/weight etc.

Notice that the table layout is in the `com.codename1.ui.table` package and not in the layouts package.

This is due to the fact that `TableLayout` was originally designed for the `Table` class.

Despite being constraint based the table layout isn't strict about constraints and will implicitly add a constraint when one is missing. However, unlike grid layout table layout won't implicitly add a row if the row/column count is incorrect

E.g this creates a 2x2 table but adds 5 elements. The 5th element won't show:

    Form hi = new Form("Table Layout 2x2", new TableLayout(2, 2));
    hi.add(new Label("First")).
        add(new Label("Second")).
        add(new Label("Third")).
        add(new Label("Fourth")).
        add(new Label("Fifth"));
    hi.show();

Table layout supports the ability to grow the last column which can be enabled using the `setGrowHorizontally` method. You can also use a shortened terse syntax to construct a table layout however since the table layout is a constraint based layout you won't be able to utilize its full power with this syntax.

The default usage of the encloseIn below uses the `setGrowHorizontally` flag.

    Container tl = TableLayout.encloseIn(2, new Label("First"),
                    new Label("Second"),
                    new Label("Third"),
                    new Label("Fourth"),
                    new Label("Fifth"));

The Full Potential

To truly appreciate the `TableLayout` we need to use the constraint syntax which allows us to span, align and set width/height for the rows & columns.

Table layout works with a `Constraint` instance that can communicate our intentions into the layout manager. Such constraints can include more than one attribute e.g. span and height.

Notice that table layout constraints can't be reused for more than one component.

The constraint class supports the following attributes:

column The column for the table cell. This defaults to -1 which will just place the component in the next available cell

row Similar to column, defaults to -1 as well

width The column width in percentages, -1 will use the preferred size. -2 for width will take up the rest of the available space

height The row height in percentages, -1 will use the preferred size. -2 for height will take up the rest of the available space

spanHorizontal The cells that should be occupied horizontally defaults to 1 and can't exceed the column count - current offset.

spanVertical Similar to spanHorizontal with the same limitations

horizontalAlign The horizontal alignment of the content within the cell, defaults to the special case -1 value to take up all the cell space can be either `-1`, `Component.LEFT`, `Component.RIGHT` or `Component.CENTER`

verticalAlign Similar to horizontalAlign can be one of `-1`, `Component.TOP`, `Component.BOTTOM` or `Component.CENTER`

Notice that you only need to set `width`/`height` to one cell in a column/row.

The table layout constraint sample tries to demonstrate some of the unique things you can do with constraints.

We go into further details on this in the developer guide so check that out.

    TableLayout tl = new TableLayout(2, 3);
    Form hi = new Form("Table Layout Cons", tl);
    hi.setScrollable(false);
    hi.add(tl.createConstraint().
                widthPercentage(20),
                    new Label("AAA")).

            add(tl.createConstraint().
                horizontalSpan(2).
                heightPercentage(80).
                verticalAlign(Component.CENTER).
                horizontalAlign(Component.CENTER),
                    new Label("Span H")).

            add(new Label("BBB")).

            add(tl.createConstraint().
                widthPercentage(60).
                heightPercentage(20),
                    new Label("CCC")).

            add(tl.createConstraint().
                widthPercentage(20),
                    new Label("DDD"));

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `TableLayout.Constraint`
  Represents the layout constraint for an entry within the table indicating the desired position/behavior of the component.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TableLayout(int rows, int columns)`
  A table must declare the amount of rows and columns in advance

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addLayoutComponent(Object value, Component comp, Container c)`
  Some layouts can optionally track the addition of elements with meta-data that allows the user to "hint" on object positioning.
  `TableLayout.Constraint`
  `cc()`
  Creates a new Constraint instance to add to the layout, same as `createConstraint` only shorter syntax
  `TableLayout.Constraint`
  `cc(int row, int column)`
  Creates a new Constraint instance to add to the layout, same as `createConstraint` only shorter syntax
  `TableLayout.Constraint`
  `createConstraint()`
  Creates a new Constraint instance to add to the layout
  `TableLayout.Constraint`
  `createConstraint(int row, int column)`
  Creates a new Constraint instance to add to the layout
  `static Container`
  `encloseIn(int columns, boolean growHorizontally, Component... cmps)`
  Creates a table layout container, the number of rows is automatically calculated based on the number of columns.
  `static Container`
  `encloseIn(int columns, Component... cmps)`
  Creates a table layout container that grows the last column horizontally, the number of rows is automatically calculated based on the number of columns.
  `boolean`
  `equals(Object o)`
  Indicates whether some other object is "equal to" this one.
  `int`
  `getCellHorizontalSpan(int row, int column)`
  Returns the spanning for the table cell at the given coordinate
  `int`
  `getCellVerticalSpan(int row, int column)`
  Returns the spanning for the table cell at the given coordinate
  `protected Component[]`
  `getChildrenInTraversalOrder(Container parent)`
  Gets the children of the parent container in the order that they should be traversed when tabbing through a form.
  `int`
  `getColumnPosition(int col)`
  Returns the position of the given table column.
  `int`
  `getColumns()`
  Get the number of columns
  `Component`
  `getComponentAt(int row, int column)`
  Returns the component at the given row/column
  `Object`
  `getComponentConstraint(Component comp)`
  Returns the optional component constraint
  `static int`
  `getDefaultColumnWidth()`
  Indicates the default (in percentage) for the column width, -1 indicates automatic sizing
  `static int`
  `getDefaultRowHeight()`
  Indicates the default (in percentage) for the row height, -1 indicates automatic sizing
  `static int`
  `getMinimumSizePerColumn()`
  Indicates the minimum size for a column in the table, this is applicable for tables that are not scrollable on the X axis.
  `int`
  `getNextColumn()`
  Returns the column where the next operation of add will appear
  `int`
  `getNextRow()`
  Returns the row where the next operation of add will appear
  `Dimension`
  `getPreferredSize(Container parent)`
  Returns the container preferred size
  `int`
  `getRowPosition(int row)`
  Returns the position of the given table row.
  `int`
  `getRows()`
  Get the number of rows
  `int`
  `hashCode()`
  Returns a hash code value for the object.
  `boolean`
  `hasHorizontalSpanning()`
  Indicates whether there is spanning within this layout
  `boolean`
  `hasVerticalSpanning()`
  Indicates whether there is spanning within this layout
  `boolean`
  `isCellSpannedThroughHorizontally(int row, int column)`
  Returns true if the cell at the given position is spanned through horizontally
  `boolean`
  `isCellSpannedThroughVertically(int row, int column)`
  Returns true if the cell at the given position is spanned through vertically
  `boolean`
  `isConstraintTracking()`
  If this method returns true, the addLayoutComponent method will be called when replacing a layout for every component within the container
  `boolean`
  `isGrowHorizontally()`
  Indicates whether the table layout should grow horizontally to take up available space by stretching the last column
  `boolean`
  `isTruncateHorizontally()`
  Indicates whether the table should be truncated if it do not have enough available horizontal space to display all its content.
  `boolean`
  `isTruncateVertically()`
  Indicates whether the table should be truncated if it do not have enough available vertical space to display all its content.
  `void`
  `layoutContainer(Container parent)`
  Layout the given parent container children
  `boolean`
  `overridesTabIndices(Container parent)`
  If a layout specifies a different traversal order of its components than the component index, then it should override this method to return true, and it should also override `#getChildrenInTraversalOrder(com.codename1.ui.Container)` to set the tab indices of a container's children.
  `void`
  `removeLayoutComponent(Component comp)`
  Removes the component from the layout this operation is only useful if the layout maintains references to components within it
  `static void`
  `setDefaultColumnWidth(int w)`
  Indicates the default (in percentage) for the column width, -1 indicates automatic sizing
  `static void`
  `setDefaultRowHeight(int h)`
  Indicates the default (in percentage) for the row height, -1 indicates automatic sizing
  `void`
  `setGrowHorizontally(boolean growHorizontally)`
  Indicates whether the table layout should grow horizontally to take up available space by stretching the last column
  `static void`
  `setMinimumSizePerColumn(int minimumSize)`
  Sets the minimum size for a column in the table, this is applicable for tables that are not scrollable on the X axis.
  `void`
  `setTruncateHorizontally(boolean truncateHorizontally)`
  Indicates whether the table should be truncated if it do not have enough available horizontal space to display all its content.
  `void`
  `setTruncateVertically(boolean truncateVertically)`
  Indicates whether the table should be truncated if it do not have enough available vertical space to display all its content.
  `String`
  `toString()`
  Returns a string representation of the object.

  ### Methods inherited from class Layout

  `cloneConstraint, isOverlapSupported, obscuresPotential, updateTabIndices`

  ### Methods inherited from class Object

  `clone, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### TableLayout

    public TableLayout(int rows, int columns)

    A table must declare the amount of rows and columns in advance

    ###### Parameters

    - `rows`: rows of the table

    - `columns`: columns of the table

- ## Method Details

  - ### getMinimumSizePerColumn

    public static int getMinimumSizePerColumn()

    Indicates the minimum size for a column in the table, this is applicable for tables that are not scrollable on the X axis. This will force the earlier columns to leave room for the latter columns.

    ###### Returns

    the minimum width of the column

  - ### setMinimumSizePerColumn

    public static void setMinimumSizePerColumn(int minimumSize)

    Sets the minimum size for a column in the table, this is applicable for tables that are not scrollable on the X axis. This will force the earlier columns to leave room for the latter columns.

    ###### Parameters

    - `minimumSize`: the minimum width of the column

  - ### getDefaultColumnWidth

    public static int getDefaultColumnWidth()

    Indicates the default (in percentage) for the column width, -1 indicates automatic sizing

    ###### Returns

    width in percentage

  - ### setDefaultColumnWidth

    public static void setDefaultColumnWidth(int w)

    Indicates the default (in percentage) for the column width, -1 indicates automatic sizing

    ###### Parameters

    - `w`: width in percentage

  - ### getDefaultRowHeight

    public static int getDefaultRowHeight()

    Indicates the default (in percentage) for the row height, -1 indicates automatic sizing

    ###### Returns

    height in percentage

  - ### setDefaultRowHeight

    public static void setDefaultRowHeight(int h)

    Indicates the default (in percentage) for the row height, -1 indicates automatic sizing

    ###### Parameters

    - `h`: height in percentage

  - ### encloseIn

    public static Container encloseIn(int columns, Component... cmps)

    Creates a table layout container that grows the last column horizontally, the number of rows is automatically calculated based on the number of columns. See usage:

        Container tl = TableLayout.encloseIn(2, new Label("First"),
                        new Label("Second"),
                        new Label("Third"),
                        new Label("Fourth"),
                        new Label("Fifth"));

    ###### Parameters

    - `columns`: the number of columns

    - `cmps`: components to add

    ###### Returns

    a newly created table layout container with the components in it

  - ### encloseIn

    public static Container encloseIn(int columns, boolean growHorizontally, Component... cmps)

    Creates a table layout container, the number of rows is automatically calculated based on the number of columns. See usage:

        Container tl = TableLayout.encloseIn(2, new Label("First"),
                        new Label("Second"),
                        new Label("Third"),
                        new Label("Fourth"),
                        new Label("Fifth"));

    ###### Parameters

    - `columns`: the number of columns

    - `growHorizontally`: true to grow the last column to fit available width

    - `cmps`: components to add

    ###### Returns

    a newly created table layout container with the components in it

  - ### getRows

    public int getRows()

    Get the number of rows

    ###### Returns

    number of rows

  - ### getColumns

    public int getColumns()

    Get the number of columns

    ###### Returns

    number of columns

  - ### getComponentAt

    public Component getComponentAt(int row, int column)

    Returns the component at the given row/column

    ###### Parameters

    - `row`: the row of the component

    - `column`: the column of the component

    ###### Returns

    the component instance

  - ### layoutContainer

    public void layoutContainer(Container parent)

    Layout the given parent container children

    ###### Parameters

    - `parent`: the given parent container
    Specified by:
      `layoutContainer` in class `Layout`

  - ### getRowPosition

    public int getRowPosition(int row)

    Returns the position of the given table row. A valid value is only returned after the layout occurred.

    ###### Parameters

    - `row`: the row in the table

    ###### Returns

    the Y position in pixels or -1 if layout hasn't occured/row is too large etc.

  - ### getColumnPosition

    public int getColumnPosition(int col)

    Returns the position of the given table column. A valid value is only returned after the layout occurred.

    ###### Parameters

    - `col`: the column in the table

    ###### Returns

    the X position in pixels or -1 if layout hasn't occured/column is too large etc.

  - ### getPreferredSize

    public Dimension getPreferredSize(Container parent)

    Returns the container preferred size

    ###### Parameters

    - `parent`: the parent container

    ###### Returns

    the container preferred size

    Specified by:
      `getPreferredSize` in class `Layout`

  - ### getNextRow

    public int getNextRow()

    Returns the row where the next operation of add will appear

    ###### Returns

    the row where the next operation of add will appear

  - ### getNextColumn

    public int getNextColumn()

    Returns the column where the next operation of add will appear

    ###### Returns

    the column where the next operation of add will appear

  - ### addLayoutComponent

    public void addLayoutComponent(Object value, Component comp, Container c)

    Some layouts can optionally track the addition of elements with meta-data that allows the user to "hint" on object positioning.

    ###### Parameters

    - `value`: optional meta data information, like alignment orientation

    - `comp`: the added component to the layout

    - `c`: the parent container

    Overrides:
      `addLayoutComponent` in class `Layout`

  - ### getCellHorizontalSpan

    public int getCellHorizontalSpan(int row, int column)

    Returns the spanning for the table cell at the given coordinate

    ###### Parameters

    - `row`: row in the table

    - `column`: column within the table

    ###### Returns

    the amount of spanning 1 for no spanning

  - ### getCellVerticalSpan

    public int getCellVerticalSpan(int row, int column)

    Returns the spanning for the table cell at the given coordinate

    ###### Parameters

    - `row`: row in the table

    - `column`: column within the table

    ###### Returns

    the amount of spanning 1 for no spanning

  - ### isCellSpannedThroughVertically

    public boolean isCellSpannedThroughVertically(int row, int column)

    Returns true if the cell at the given position is spanned through vertically

    ###### Parameters

    - `row`: cell row

    - `column`: cell column

    ###### Returns

    true if the cell is a part of a span for another cell

  - ### isCellSpannedThroughHorizontally

    public boolean isCellSpannedThroughHorizontally(int row, int column)

    Returns true if the cell at the given position is spanned through horizontally

    ###### Parameters

    - `row`: cell row

    - `column`: cell column

    ###### Returns

    true if the cell is a part of a span for another cell

  - ### hasVerticalSpanning

    public boolean hasVerticalSpanning()

    Indicates whether there is spanning within this layout

    ###### Returns

    true if the layout makes use of spanning

  - ### hasHorizontalSpanning

    public boolean hasHorizontalSpanning()

    Indicates whether there is spanning within this layout

    ###### Returns

    true if the layout makes use of spanning

  - ### removeLayoutComponent

    public void removeLayoutComponent(Component comp)

    Removes the component from the layout this operation is only useful if the layout maintains references to components within it

    ###### Parameters

    - `comp`: the removed component from layout
    Overrides:
      `removeLayoutComponent` in class `Layout`

  - ### getComponentConstraint

    public Object getComponentConstraint(Component comp)

    Returns the optional component constraint

    ###### Parameters

    - `comp`: the component whose constraint should be returned

    ###### Returns

    the optional component constraint

    Overrides:
      `getComponentConstraint` in class `Layout`

  - ### createConstraint

    public TableLayout.Constraint createConstraint()

    Creates a new Constraint instance to add to the layout

    ###### Returns

    the default constraint

  - ### cc

    public TableLayout.Constraint cc()

    Creates a new Constraint instance to add to the layout, same as `createConstraint` only shorter syntax

    ###### Returns

    the default constraint

  - ### cc

    public TableLayout.Constraint cc(int row, int column)

    Creates a new Constraint instance to add to the layout, same as `createConstraint` only shorter syntax

    ###### Parameters

    - `row`: the row for the table starting with 0

    - `column`: the column for the table starting with 0

    ###### Returns

    the new constraint

  - ### createConstraint

    public TableLayout.Constraint createConstraint(int row, int column)

    Creates a new Constraint instance to add to the layout

    ###### Parameters

    - `row`: the row for the table starting with 0

    - `column`: the column for the table starting with 0

    ###### Returns

    the new constraint

  - ### toString

    public String toString()
    Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + '@' + Integer.toHexString(hashCode())
    Overrides:
      `toString` in class `Object`

  - ### equals

    public boolean equals(Object o)
    Indicates whether some other object is "equal to" this one. The equals method implements an equivalence relation: It is reflexive: for any reference value x, x.equals(x) should return true. It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true. It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true. It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified. For any non-null reference value x, x.equals(null) should return false. The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).
    Overrides:
      `equals` in class `Layout`

  - ### hashCode

    public int hashCode()
    Description copied from class: `Layout`
    Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable. The general contract of hashCode is: Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables. As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)
    Overrides:
      `hashCode` in class `Layout`

  - ### isConstraintTracking

    public boolean isConstraintTracking()

    If this method returns true, the addLayoutComponent method will be called when replacing a layout for every component within the container

    ###### Returns

    false by default

    Overrides:
      `isConstraintTracking` in class `Layout`

  - ### isGrowHorizontally

    public boolean isGrowHorizontally()

    Indicates whether the table layout should grow horizontally to take up available space by stretching the last column

    ###### Returns

    the growHorizontally

  - ### setGrowHorizontally

    public void setGrowHorizontally(boolean growHorizontally)

    Indicates whether the table layout should grow horizontally to take up available space by stretching the last column

    ###### Parameters

    - `growHorizontally`: the growHorizontally to set

  - ### isTruncateHorizontally

    public boolean isTruncateHorizontally()

    Indicates whether the table should be truncated if it do not have enough available horizontal space to display all its content. If not, will shrink

    ###### Returns

    the truncateHorizontally

  - ### setTruncateHorizontally

    public void setTruncateHorizontally(boolean truncateHorizontally)

    Indicates whether the table should be truncated if it do not have enough available horizontal space to display all its content. If not, will shrink

    ###### Parameters

    - `truncateHorizontally`: the truncateHorizontally to set

  - ### isTruncateVertically

    public boolean isTruncateVertically()

    Indicates whether the table should be truncated if it do not have enough available vertical space to display all its content. If not, will shrink

    ###### Returns

    the truncateVertically

  - ### setTruncateVertically

    public void setTruncateVertically(boolean truncateVertically)

    Indicates whether the table should be truncated if it do not have enough available vertical space to display all its content. If not, will shrink

    ###### Parameters

    - `truncateVertically`: the truncateVertically to set

  - ### overridesTabIndices

    public boolean overridesTabIndices(Container parent)
    Description copied from class: `Layout`

    If a layout specifies a different traversal order of its components than the component index, then it should override this method to return true, and it should also override `#getChildrenInTraversalOrder(com.codename1.ui.Container)` to set the tab indices of a container's children.

    ###### Parameters

    - `parent`: The parent component.

    ###### Returns

    True if this layout overrides tab traversal order.

    Overrides:
      `overridesTabIndices` in class `Layout`

  - ### getChildrenInTraversalOrder

    protected Component[] getChildrenInTraversalOrder(Container parent)
    Description copied from class: `Layout`

    Gets the children of the parent container in the order that they should be traversed when tabbing through a form.

    This should only be overridden if the Layout defines a different traversal order than the standard index order.

    Layouts that implement this method, should override the `#overridesTabIndices(com.codename1.ui.Container)` method to return true.

    ###### Parameters

    - `parent`

    ###### Returns

    Array of Components in the order

    Overrides:
      `getChildrenInTraversalOrder` in class `Layout`