javax.microedition.lcdui
Class TableLayoutPolicy

java.lang.Object
  javax.microedition.lcdui.FormLayoutPolicy
      javax.microedition.lcdui.TableLayoutPolicy

public final class TableLayoutPolicy
extends FormLayoutPolicy

TableLayoutPolicy displays the Items in a Form aligned in columns. The Items in the Form are placed in columns filling rows either from left-to-right or right-to-left depending on the platform's layout direction. When each column in a row is full, the next Item is placed in the next row. If there are not enough Items to fill the last row the cells are left empty. All but the last row will have an Item in every column.

The width of each column is determined based on the minimum and preferred width of items given the layout directives for shrink and expand. When calculating table column width, the smallest column width is used that accommodates every item in the column. The minimum width of each item in a column is the Item's minimum width, if it has the layout directive LAYOUT_SHRINK, otherwise it is the Item's preferred width. The column's width is the largest of those widths. When the sum of the column widths is less than the width of the display, the additional space is evenly distributed to columns that contain any item with LAYOUT_EXPAND. Individual Items are expanded to the column width if they have the layout directive LAYOUT_EXPAND.

The height of each row is determined based on the minimum and preferred height of items given the layout directives for vertical shrink and expand. When calculating table row height, the smallest row height is used that accommodates every item in the row. The minimum height of each item in a row is the Item's minimum height, if it has the layout directive LAYOUT_VSHRINK, otherwise it is the Item's preferred height. The row's height is the largest of those heights. Individual Items are expanded to the row height if they have the layout directive LAYOUT_VEXPAND.

The layout directives from each Item.getLayout are used as follows:

Item.LAYOUT_SHRINK

The item's initial width is its minimum width and is expanded to as much as its preferred width if additional horizontal space is available. Otherwise, the preferred width is used. See LAYOUT_SHRINK for the details of the computation.

Item.LAYOUT_EXPAND

The item may be expanded with its share of the available horizontal space. See LAYOUT_EXPAND for the details of the computation.

Item.LAYOUT_VSHRINK

The item's initial height is its minimum height and is expanded to as much as its preferred height if additional vertical space is available. See LAYOUT_VSHRINK for the details of the computation.

Item.LAYOUT_VEXPAND

The item may be expanded with its share of the available vertical space. See LAYOUT_VEXPAND for the details of the computation.

Item.LAYOUT_LEFT

Is ignored.

Item.LAYOUT_CENTER

Is ignored.

Item.LAYOUT_RIGHT

Is ignored.

Item.LAYOUT_TOP

Is ignored.

Item.LAYOUT_BOTTOM

Is ignored.

Item.LAYOUT_VCENTER

Is ignored.

Item.LAYOUT_NEWLINE_BEFORE

Is ignored.

Item.LAYOUT_NEWLINE_AFTER

Is ignored.

TableLayoutPolicy only uses the layout directives above and does not introduce any ItemLayoutHints.

Since:

MIDP 3.0

See Also:

FormLayoutPolicy

Field Summary

Fields inherited from class javax.microedition.lcdui.FormLayoutPolicy

DIRECTION_LTR, DIRECTION_RTL

Constructor Summary

TableLayoutPolicy(Form form, int columns)
Creates a new instance of TableLayoutPolicy.

Method Summary

protected void	doLayout(int viewportX, int viewportY, int viewportWidth, int viewportHeight, int[] totalSize) Compute or update the position and size of each Item in the Form.
int	getColumns() Gets the number of columns in this TableLayoutPolicy.
protected Item	getTraverse(Item item, int dir) Gets the Item logically adjacent to an existing Item in the traversal direction.

Methods inherited from class javax.microedition.lcdui.FormLayoutPolicy

getForm, getHeight, getLayoutDirection, getWidth, getX, getY, isValid, setPosition, setSize, setValid

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableLayoutPolicy

public TableLayoutPolicy(Form form,
                         int columns)

Creates a new instance of TableLayoutPolicy. Items are arranged in a fixed number of columns.

Parameters:

form - the Form bound to this table layout policy.

columns - the number of columns for the Table layout.

Throws:

java.lang.IllegalArgumentException - if columns is less than 1.

java.lang.NullPointerException - if form is null.

Since:

MIDP 3.0

Method Detail

getColumns

public int getColumns()

Gets the number of columns in this TableLayoutPolicy. The number of columns is fixed when the TableLayoutPolicy is created.

Returns:

the number of columns.

Since:

MIDP 3.0

doLayout

protected void doLayout(int viewportX,
                        int viewportY,
                        int viewportWidth,
                        int viewportHeight,
                        int[] totalSize)

Compute or update the position and size of each Item in the Form. Items are placed in rows based on the number of columns. The horizontal order of the items in the Form is determined by the layout direction of the platform. The vertical direction is always top to bottom. The width of each column is determined based on the minimum and preferred width of items given the layout directives for shrink and expand.

The algorithm makes a first pass over the items to determine the width of each column. Then the height of each row is determined. Another pass is used to set the width, height, and validity of each item in the column and to compute and set the height.

Specified by:

doLayout in class FormLayoutPolicy

Parameters:

viewportX - The x offset of the viewport on the form.

viewportY - The y offset of the viewport on the form.

viewportWidth - the width of the viewport

viewportHeight - the height of the viewport

totalSize - an output parameter to be set to the full width and height required for all items in the form. The width is stored in totalSize[0] and the height is stored in totalSize[1].

Throws:

java.lang.ArrayIndexOutOfBoundsException - is thrown if the length of the totalSize array is less than 2.

Since:

MIDP 3.0

See Also:

FormLayoutPolicy.isValid(javax.microedition.lcdui.Item), FormLayoutPolicy.setValid(javax.microedition.lcdui.Item, boolean), FormLayoutPolicy.getWidth(javax.microedition.lcdui.Item), FormLayoutPolicy.getHeight(javax.microedition.lcdui.Item), FormLayoutPolicy.getX(javax.microedition.lcdui.Item), FormLayoutPolicy.getY(javax.microedition.lcdui.Item), FormLayoutPolicy.setSize(javax.microedition.lcdui.Item, int, int), FormLayoutPolicy.setPosition(javax.microedition.lcdui.Item, int, int), FormLayoutPolicy.getLayoutDirection()

getTraverse

protected Item getTraverse(Item item,
                           int dir)

Gets the Item logically adjacent to an existing Item in the traversal direction.

The next item depends on the traversal direction requested:

• Canvas.UP: The item in the same column in the previous row wrapping around as necessary from the first row to the highest row that contains an item in that column.
• Canvas.DOWN: The item in the same column in the next row wrapping around as necessary from the highest row that contains an item in that column to the first row.
• Canvas.LEFT: For left-to-right layout direction, this is the previous item in the sequence of items, wrapping around from zero to form.size()-1 as necessary. For right-to-left layout direction, this is the next item in the sequence of items, wrapping around from form.size()-1 to zero as necessary.
• Canvas.RIGHT: For left-to-right layout direction, this is the next item in the sequence of items, wrapping around from form.size()-1 to zero as necessary. For right-to-left layout direction, this is the previous item in the sequence of items, wrapping around from 0 to form.size()-1 as necessary.

Specified by:

getTraverse in class FormLayoutPolicy

Parameters:

item - a current Item

dir - the traversal direction from the item to the adjacent item

Returns:

the item in the traversal direction requested; may be null.

Throws:

java.lang.IllegalArgumentException - if dir is not one of Canvas.UP, Canvas.DOWN, Canvas.LEFT, or Canvas.RIGHT.

Since:

MIDP 3.0