# 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(java.lang.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(java.lang.Object o)`
  `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
  `java.lang.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()`
  `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()`

  ### Methods inherited from class Layout

  `cloneConstraint, isOverlapSupported, obscuresPotential, updateTabIndices`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, 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(java.lang.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 java.lang.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()
    Overrides:
      `toString` in class `java.lang.Object`

  - ### equals

    public boolean equals(java.lang.Object o)
    Overrides:
      `equals` in class `Layout`

  - ### hashCode

    public int hashCode()
    Description copied from class: `Layout`
    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`