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)
    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()
    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 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(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()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(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