org.freixas.tablelayout
Class TableLayout

java.lang.Object
  org.freixas.tablelayout.TableLayout

All Implemented Interfaces:

LayoutManager, LayoutManager2

public class TableLayout
extends Object
implements LayoutManager2

This layout was inspired by the HTML table: it lays out components much like the HTML table lays out table data. It is as capable as the GridBagLayout, but much easier to use.

Attributes

When you create a TableLayout, you pass in a String which defines a set of attributes for the table. The TableLayout is then assigned to a Container. As you add each Component to the Container, you can also associate the Component with its own set of attributes.

The format of the attributes is similar to HTML attributes. The attributes are case insensitive and can be separated with any whitespace. Attributes which take a value are followed by an '=' and then an integer. Here's an example: "cols=6 rgap=2 cgap=5 w".

Attributes are evaluated from left to right. If you duplicate an attribute, the right-most one wins.

All attributes can be specified for both the table and the individual Components. Some attributes are only used by the table, some are only used by the Components and some are used by both: the table instance is the default which each Component can override.

Rows and Columns

When you create a table, you will almost always specify the number of columns in it. The default is 1. Columns are filled from left to right. When all columns are filled, a new row is automatically created.

You can override the default Component placement somewhat with "col" and "skip". col takes as a value, the column number in which the Component should be placed. Column numbers begin with 0. The default is to place the Component in the next available table cell. One caveat when using col is that if you have already passed the given column, the layout adds another row and places the Component in the column on that new row.

"skip" allows you to skip a number of cells. The default is 0. If the layout reaches the end of the row, skipping continues on the next row.

You can make a Component span multiple rows or columns with rspan and cspan. The default value for these is 1. Later components will skip over any occupied cells, which is particularly important to note for row spanning.

Spacing

The space the TableLayout works with is inside the Container's insets. Some Containers have insets of 0 (e.g. JPanel) and most don't allow you to alter the insets. Since you will often want to control the space between the table and the edges of the Container, an "extra" table inset can be given: titop, tibottom, tileft and tiright. Each of these takes a value, the pixel offset from the top, bottom, etc. The default value of each is 0.

You can create some space between cells in the table. This space is only placed between cells; never along the edges of the table. This allows you to nest table layouts and keep consistent cell spacing. The attributes used are rgap and cgap and their default value is 0.

Within a cell, you can also create some space between the cells edges and the Component in the cell. The attributes are itop, ibottom, ileft and iright. Their default value is 0.

Placement and Filling

Given that you have something to draw and a space to draw it in, you have some choices as to where to place it and how to fill it, particularly when the drawing area is bigger than required.

Placement attributes allow you to place the item in one of eight compass directions or centered. The entire table can be placed within the container using tn, tne, te, tse, ts, tsw, tw, tnw and tc. Components can be placed within their cell using n, ne, e, se, s, sw, w, nw and c.

Fill attributes allow you to fill the item to cover all available space. Horizontal and vertical filling are handled separately. For tables, the attributes are tfh, tfv and tf. "tf" fills in both directions. For Components, use fh, fv and f.

Placement attributes turn off all filling. Fill attributes turn off placement, but only in the fill direction. So "n fh" will stretch a Component horizontally, but will place it at the "north" position (at the top of the cell).

The default value for both the table and the individual Components is to fill in both directions. You will almost always want to specify your own values.

Weighting

When a table is filled, if the available space exceeds the space required, we stretch the table to fill the space. This implies that we have to stretch each cell. How much each cell should be filled is what weighting is all about. The attributes are rweight and cweight which take an integer weight factor. The default is 0.

Note that stretching a cell is not the same as stretching the Component inside the cell unless the component uses filling.

If you'd like some simple rules of thumbs, use these:

• Assign a weight of 1 to rows or columns that you want to stretch (Also set the "f" attribute for the Components in that row or column!). Other rows and columns won't.
• In some cases, you may want the table to fill while the components inside it don't. For example, you may want a JPanel's TitledBorder to fill the available space while the components in the JPanel stay at their preferred sizes. The solution is to fill the table, but set the component at the highest row and column position to have row and column weights of 1. Use "nw" position on all components in the last row or column. There are alternate solutions using nested layouts.

Ok, here are the dirty details.

If the available size is greater than the table's preferred size and table filling is enabled, weighting is used (they are otherwise ignored).

Weights are obtained by looking at each row and column and locating the largest weight; this becomes the row or column weight. If all weights are 0, we treat them as though they are all 1. We create a sum for all row weights and one for all column weights. This number defines the number of units into which the excess space will be divided.

For example, with three column weights of 1, 1, and 1, the space is divided into 3 units. If the excess space is 30 pixels, each unit is 10 pixels, which is the extra space each column receives. If the column weights were 0, 2, and 1, the space is still divided into 3 units. But the column weights specify how many units each column receives. So, column 0 will receive nothing, column 1, 20 pixels and column 2, 10 pixels.

Keep in mind that rows and columns are handled separately. One may need filling and the other not.

When we don't have enough space for the preferred row or column sizes, we ignore the user-defined weights and treat each row or column as having equal weight. The approach then, is as above except that we are reducing cell sizes. Another difference is that no cell will be made smaller than its minimum size.

Special Spanning Issues

There are some special issues with row and column spanning. When determining minimum or preferred sizes, we need to know what portion of the Component's size to assign to each row and column that it spans. We solve this by doing two passes. In the first, we ignore spanning cells and determine row and column sizes without them. In the second pass, we look to see if the spanning Component will fit within the row and column sizes we determined. If not, we currently distribute the extra space based on the row or column weights of the rows or columns spanned. Someday, we may need to add attributes to provide more control.

The row and column weights given are applied to the row or column in which the Component begins.

Summary

This table summarizes the attribute information:

Name	Description	Has Value?	Default	Scope
cols	Number of columns	Yes	1	Table
col	Place Component in this column	Yes	Next empty column	Component
skip	Skip a number of columns	Yes	0	Component
rspan, cspan	Row and column spanning	Yes	1	Component
titop, tibottom, tileft, tiright	Table insets	Yes	0	Table
rgap, cgap	Row and column gaps	Yes	0	Table
itop, ibottom, ileft, iright	Component insets	Yes	0	Table/Component
tn, tne, te, tse, ts, tsw, tw, tnw, tc, tf, tfh, tfv	Table placement and fill	No	tf	Table
n, ne, e, se, s, sw, w, nw, c, f, fh, fv	Component placement and fill	No	f	Table/Component
rweight, cweight	Row and column weights	Yes	0	Table/Component

Author:

Antonio Freixas

Constructor Summary

TableLayout()
Construct a new TableLayout.

TableLayout(String attributes)
Construct a new TableLayout with the given attributes.

Method Summary

void	addLayoutComponent(Component comp, Object constraints) Adds the specified component to the layout, using the specified constraint object (which we expect to be a String of attributes).
void	addLayoutComponent(String attributes, Component comp) Adds the component with the specified attributes to the layout.
float	getLayoutAlignmentX(Container parent) Returns the alignment along the x axis.
float	getLayoutAlignmentY(Container parent) Returns the alignment along the y axis.
void	invalidateLayout(Container parent) Invalidates the layout.
void	layoutContainer(Container parent) Lays out the components in the given container.
Dimension	maximumLayoutSize(Container parent) Calculates the maximum size dimensions for the layout given the components in a parent container.
Dimension	minimumLayoutSize(Container parent) Calculates the minimum size dimensions for the layout given the components in the a parent container.
Dimension	preferredLayoutSize(Container parent) Calculates the preferred size dimensions for the layout given the components in a parent container.
void	removeLayoutComponent(Component comp) Removes the specified component from the layout.
void	setAttributes(Component comp, String attributes) Reset the attributes for a component in the layout.
void	setTableAttributes(String attributes) Reset the table attributes for the layout.

Methods inherited from class java.lang.Object

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

Constructor Detail

TableLayout

public TableLayout()

Construct a new TableLayout.

TableLayout

public TableLayout(String attributes)

Construct a new TableLayout with the given attributes.

Parameters:

attributes - A list of attributes for the table. The list is described in the class documentation above. Cell-only attributes are ignored.

Method Detail

setTableAttributes

public void setTableAttributes(String attributes)

Reset the table attributes for the layout.

Parameters:

attributes - The new table attributes.

setAttributes

public void setAttributes(Component comp,
                          String attributes)

Reset the attributes for a component in the layout. The component must already have been added to the container or else this call has no effect.

Parameters:

comp - The component to alter.

attributes - The new attributes for the component.

addLayoutComponent

public void addLayoutComponent(String attributes,
                               Component comp)

Adds the component with the specified attributes to the layout.

Specified by:

addLayoutComponent in interface LayoutManager

Parameters:

attributes - A list of attributes for the component. The list is described in the class documentation above. Table-only attributes are ignored.

comp - The component to be added.

addLayoutComponent

public void addLayoutComponent(Component comp,
                               Object constraints)

Adds the specified component to the layout, using the specified constraint object (which we expect to be a String of attributes).

Specified by:

addLayoutComponent in interface LayoutManager2

Parameters:

comp - The component to be added.

constraints - A list of attributes for the component. The list is described in the class documentation above. Table-only attributes are ignored.

removeLayoutComponent

public void removeLayoutComponent(Component comp)

Removes the specified component from the layout.

Specified by:

removeLayoutComponent in interface LayoutManager

Parameters:

comp - The component to be removed.

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)

Calculates the minimum size dimensions for the layout given the components in the a parent container.

Specified by:

minimumLayoutSize in interface LayoutManager

Parameters:

parent - The container to be laid out.

Returns:

The minimum layout size.

See Also:

preferredLayoutSize(Container), maximumLayoutSize(Container)

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)

Calculates the preferred size dimensions for the layout given the components in a parent container.

Specified by:

preferredLayoutSize in interface LayoutManager

Parameters:

parent - The container to be laid out.

Returns:

The preferred layout size.

See Also:

minimumLayoutSize(Container), maximumLayoutSize(Container)

maximumLayoutSize

public Dimension maximumLayoutSize(Container parent)

Calculates the maximum size dimensions for the layout given the components in a parent container.

Specified by:

maximumLayoutSize in interface LayoutManager2

Parameters:

parent - The container parent.

Returns:

The maximum layout size.

See Also:

minimumLayoutSize(Container), preferredLayoutSize(Container)

getLayoutAlignmentX

public float getLayoutAlignmentX(Container parent)

Returns the alignment along the x axis. This always returns 0.5.

Specified by:

getLayoutAlignmentX in interface LayoutManager2

Parameters:

parent - The container whose alignment we want.

Returns:

The alignment along the x axis.

getLayoutAlignmentY

public float getLayoutAlignmentY(Container parent)

Returns the alignment along the y axis. This always returns 0.5.

Specified by:

getLayoutAlignmentY in interface LayoutManager2

Parameters:

parent - The container whose alignment we want.

Returns:

The alignment along the y axis.

invalidateLayout

public void invalidateLayout(Container parent)

Invalidates the layout. Cached information will be discarded.

Specified by:

invalidateLayout in interface LayoutManager2

Parameters:

parent - The container whose alignment we want.

layoutContainer

public void layoutContainer(Container parent)

Lays out the components in the given container.

Specified by:

layoutContainer in interface LayoutManager

Parameters:

parent - The container which needs to be laid out.