com.gargoylesoftware.base.gui

Class TableLayout

public class TableLayout extends Object implements LayoutManager2, SwingConstants, Serializable

The TableLayout lays out items based on a table of rows and columns.

If you are doing simple layout, you can specify constraints as strings of the format "row,column". If you want the component to stretch over multiple rows/columns then you can specify the constraint as "row+rowspan,column+columnspan" as shown in the sample below.

 final TableLayout layout = new TableLayout();
 final JPanel panel = new JPanel(layout);

 panel.add( new JLabel("squirrel"), "1,1" );
 panel.add( new JLabel("raccoon"), "1,2" );
 panel.add( new JLabel("bluejay"), "2,1" );
 panel.add( new JLabel("goldfish"), "2,2" );
 panel.add( new JLabel("marshhawk"), "3,1+3" );
 
If you want more flexibility over the layout then this, use a TableLayoutConstraints object instead of a string. Here is a more complicated sample that uses TableLayoutConstraints to customize the layout a bit more. Note the use of TableLayoutDebuggingPanel - this will draw lines on layout boundaries to help debug layout problems.
 final TableLayout layout = new TableLayout();
 final JPanel panel = new TableLayoutDebuggingPanel(layout);

 TableLayoutConstraints constraints;

 layout.setRowExpandable(1, true);

 constraints = new TableLayoutConstraints(1,1);
 constraints.setVerticalStretch(true);
 panel.add( new JButton("squirrel"), constraints );

 constraints = new TableLayoutConstraints(1,2);
 constraints.setVerticalAlignment(TableLayout.TOP);
 panel.add( new JButton("raccoon"), constraints );

 panel.add( new JButton("bluejay"), "2,1" );
 panel.add( new JButton("goldfish"), "2,2" );
 panel.add( new JButton("marshhawk"), "3,1+3" );
 
Debugging tip: Most layout problems become obvious if you use a TableLayoutDebuggingPanel to see where the layout boundaries are. In those rare cases where this doesn't give you enough information, try calling setTraceChannel with a non-null TraceChannel such as Trace.out or Trace.err. This will dump quite a bit of diagnostic information.
 layout.setTraceChannel(Trace.out)
 

Version: $Revision: 1.5 $

Author: Mike Bowler

Nested Class Summary
classTableLayout.Entry
A convenience class to attach the constraints to a component.
classTableLayout.Header
A convenience class to hold information specific to a row or column.
classTableLayout.HeaderPermanentInfo
Contains the information that the user has specified for the specific row or column.
Field Summary
DimensionactualSize_
intcolumnCount_
SetcolumnHeaderPermanentInfos_
Listconstraints_
inthorizontalAlignment_
booleanignoreInvisibleComponents_
DimensionmaximumSize_
DimensionminimumSize_
Containerparent_
DimensionpreferredSize_
introwCount_
SetrowHeaderPermanentInfos_
static longserialVersionUID
TableLayout.Header[]tempColumnHeaders_
TableLayout.Header[]tempRowHeaders_
booleantempSizesAreValid_
TraceChanneltraceChannel_
intverticalAlignment_
Constructor Summary
TableLayout()
Create a new TableLayout.
Method Summary
voidaddLayoutComponent(String name, Component comp)
Add the specified component to the layout with the specified constraints.
voidaddLayoutComponent(Component comp, Object constraints)
Add the specified component to the layout with the specified constraints.
voidadjustHeaderSizes(TableLayout.Header[] sizes)
Fix up all the headers such that minimum <= preferred <= maximum
voidadjustSizesForSpanning(int start, int span, TableLayout.Header[] sizes, int minSize, int preferredSize, int maxSize)
Adjust the various sizes to account for components than span multiple columns/rows.
booleanareAnyExpandable(Set permanentInfos)
Return true if any of the infos are expandable.
protected voidassertNotNull(String fieldName, Object fieldValue)
Verify that the specified value is not null.
voidcalculateActualSizes(Dimension parentSize)
Calculate the actual sizes to be used based on the actual dimension of the parent container.
intcalculateActualSizes(TableLayout.Header[] sizes, int preferredLength, int clipLength)
Calculate the actual sizes for the specified row or column headers.
voidcalculateMinMaxPreferredSizes()
Calculate the various sizes.
voidcalculatePositions(Container parent, Dimension parentSize)
Calculate all the positions of the various rows/columns
voidcalculateRowAndColumnCount()
The list of constraints has been modified.
voidcalculateSizes()
Calculate all the various sizing information required for this layout.
voiddrawOutlines(Graphics graphics)
A debugging method that draws lines on the parent component to show where the table cell boundaries are.
voidexpandToFit(TableLayout.Header[] sizes, int clipLength)
Expand the specified sizes to fit within the specified clipLength.
DimensiongetComponentMaximumSize(Component component)
Return the minimum size of the specified component.
DimensiongetComponentMinimumSize(Component component)
Return the minimum size of the specified component.
DimensiongetComponentPreferredSize(Component component)
Return the minimum size of the specified component.
TableLayoutConstraintsgetConstraints(Component component)
Return the TableLayoutConstraints object that corresponds to the specified component or null if this component could not be found.
TableLayout.Header[]getExpandableHeaders(int first, int last, TableLayout.Header[] headers)
Return an array containing all the headers that are expandable.
intgetHorizontalAlignment()
Return the horizontal alignment.
booleangetIgnoreInvisibleComponents()
Get whether or not we should ignore an components that are not visible.
floatgetLayoutAlignmentX(Container target)
I don't really understand what this method is supposed to return so I always return 0F.
floatgetLayoutAlignmentY(Container target)
I don't really understand what this method is supposed to return so I always return 0F.
intgetMinimumColumnWidth(int index)
Return the minimum column width.
intgetMinimumRowHeight(int index)
Return the minimum row height.
TableLayout.HeaderPermanentInfogetPermanentInfo(Set infoList, int index, boolean createIfNeeded)
TODO: Provide comments
TraceChannelgetTraceChannel()
Return the trace channel.
intgetVerticalAlignment()
Return the vertical alignment.
voidinitTempSizes()
Initialize the temporary arrays (tempRowHeaders_ and tempColumnHeaders_) for use in a calculation.
voidinvalidateLayout(Container target)
Invalidate the layout and throw away and temporary calculations.
voidinvalidateLayout()
Invalidate the layout.
booleanisColumnExpandable(int index)
Return true if this column can be expanded beyond its preferred size.
booleanisRowExpandable(int index)
Return true if this row can be expanded beyond its preferred size.
voidlayoutContainer(Container parent)
Layout all the components in this container.
DimensionmaximumLayoutSize(Container target)
Return the maximum layout size.
DimensionminimumLayoutSize(Container parent)
Get the minimum size of this layout.
voidpositionComponent(TableLayout.Entry entry, int x, int y, int width, int height)
Position one component given the bounding coordinates
DimensionpreferredLayoutSize(Container parent)
Return the preferred layout size.
voidremoveLayoutComponent(Component comp)
Remove the specified component from the layout.
voidsetColumnExpandable(int index, boolean isExpandable)
Set whether this column can be expanded beyond its preferred size.
voidsetHorizontalAlignment(int alignment)
Set the vertical alignment.
voidsetIgnoreInvisibleComponents(boolean ignore)
Set whether or not we should ignore an components that are not visible.
voidsetMinimumColumnWidth(int index, int size)
Set the minimum column width for a specific column.
voidsetMinimumRowHeight(int index, int size)
Set the minimum row height for a specific row.
voidsetParent(Container newParent)
Set the parent container for this layout.
voidsetRowExpandable(int index, boolean isExpandable)
Set whether this row can be expanded beyond its preferred size.
voidsetTraceChannel(TraceChannel channel)
Set the trace channel used for printing diagnostic information.
voidsetVerticalAlignment(int alignment)
Set the vertical alignment.
voidshrinkToFit(TableLayout.Header[] sizes, int clipLength)
Shrink the specified sizes to fit within the specified clipLength.
static StringtoString(Dimension dimension)
Convenience method to create a string from a Dimension object.

Field Detail

actualSize_

private Dimension actualSize_

columnCount_

private int columnCount_

columnHeaderPermanentInfos_

private final Set columnHeaderPermanentInfos_

constraints_

private final List constraints_

horizontalAlignment_

private int horizontalAlignment_

ignoreInvisibleComponents_

private boolean ignoreInvisibleComponents_

maximumSize_

private Dimension maximumSize_

minimumSize_

private Dimension minimumSize_

parent_

private Container parent_

preferredSize_

private Dimension preferredSize_

rowCount_

private int rowCount_

rowHeaderPermanentInfos_

private final Set rowHeaderPermanentInfos_

serialVersionUID

private static final long serialVersionUID

tempColumnHeaders_

private TableLayout.Header[] tempColumnHeaders_

tempRowHeaders_

private TableLayout.Header[] tempRowHeaders_

tempSizesAreValid_

private boolean tempSizesAreValid_

traceChannel_

private TraceChannel traceChannel_

verticalAlignment_

private int verticalAlignment_

Constructor Detail

TableLayout

public TableLayout()
Create a new TableLayout.

Method Detail

addLayoutComponent

public void addLayoutComponent(String name, Component comp)
Add the specified component to the layout with the specified constraints. This method should never be called as Container.addImpl() should call addLayoutComponent(Component,Object) instead. Not implemented.

Parameters: name The constraints string. comp the component that is being added.

Throws: UnsupportedOperationException If called.

addLayoutComponent

public void addLayoutComponent(Component comp, Object constraints)
Add the specified component to the layout with the specified constraints. Throw an IllegalArgumentException if the same component is specified twice. The constraints object can be either an instance of TableLayoutConstraints or a String. If it is a string then an instance of TableLayoutConstraints will be created with the method TableLayoutConstraints.makeConstraints(String).

Parameters: comp The component that is being added. constraints The constraints object.

See Also: makeConstraints

adjustHeaderSizes

private void adjustHeaderSizes(TableLayout.Header[] sizes)
Fix up all the headers such that minimum <= preferred <= maximum

Parameters: sizes Description of Parameter

adjustSizesForSpanning

private void adjustSizesForSpanning(int start, int span, TableLayout.Header[] sizes, int minSize, int preferredSize, int maxSize)
Adjust the various sizes to account for components than span multiple columns/rows.

Parameters: start The starting index of the component. span The number of columns/rows that the component spans. sizes The headers that we are adjusting. minSize The minimum size of the component. preferredSize The preferred size of the component. maxSize The maximum size of the component.

areAnyExpandable

private boolean areAnyExpandable(Set permanentInfos)
Return true if any of the infos are expandable.

Parameters: permanentInfos The infos.

Returns: Description of the Returned Value

assertNotNull

protected final void assertNotNull(String fieldName, Object fieldValue)
Verify that the specified value is not null. If it is then throw an exception

Parameters: fieldName The name of the field to check fieldValue The value of the field to check

Throws: DetailedNullPointerException If fieldValue is null

calculateActualSizes

private void calculateActualSizes(Dimension parentSize)
Calculate the actual sizes to be used based on the actual dimension of the parent container.

Parameters: parentSize Description of Parameter

calculateActualSizes

private int calculateActualSizes(TableLayout.Header[] sizes, int preferredLength, int clipLength)
Calculate the actual sizes for the specified row or column headers. Return the actual length.

Parameters: sizes Description of Parameter preferredLength Description of Parameter clipLength Description of Parameter

Returns: Description of the Returned Value

calculateMinMaxPreferredSizes

private void calculateMinMaxPreferredSizes()
Calculate the various sizes.

calculatePositions

private void calculatePositions(Container parent, Dimension parentSize)
Calculate all the positions of the various rows/columns

Parameters: parent Description of Parameter parentSize Description of Parameter

calculateRowAndColumnCount

private void calculateRowAndColumnCount()
The list of constraints has been modified. Update the row and column counts according to the new constraints.

calculateSizes

private void calculateSizes()
Calculate all the various sizing information required for this layout. Called by layoutContainer(), minimumLayoutSize(), maximumLayoutSize()

drawOutlines

public void drawOutlines(Graphics graphics)
A debugging method that draws lines on the parent component to show where the table cell boundaries are. The lines will be drawn in the current colour.

Parameters: graphics The graphics object.

See Also: TableLayoutDebuggingPanel

expandToFit

private void expandToFit(TableLayout.Header[] sizes, int clipLength)
Expand the specified sizes to fit within the specified clipLength.

Parameters: sizes Description of Parameter clipLength Description of Parameter

getComponentMaximumSize

private final Dimension getComponentMaximumSize(Component component)
Return the minimum size of the specified component. If the component is not visible and we are ignoring invisible components then return a size of 0,0

Parameters: component The component that we will be querying

Returns: The size

getComponentMinimumSize

private final Dimension getComponentMinimumSize(Component component)
Return the minimum size of the specified component. If the component is not visible and we are ignoring invisible components then return a size of 0,0

Parameters: component The component that we will be querying

Returns: The size

getComponentPreferredSize

private final Dimension getComponentPreferredSize(Component component)
Return the minimum size of the specified component. If the component is not visible and we are ignoring invisible components then return a size of 0,0

Parameters: component The component that we will be querying

Returns: The size

getConstraints

private TableLayoutConstraints getConstraints(Component component)
Return the TableLayoutConstraints object that corresponds to the specified component or null if this component could not be found.

Parameters: component Description of Parameter

Returns: The constraints value

getExpandableHeaders

private TableLayout.Header[] getExpandableHeaders(int first, int last, TableLayout.Header[] headers)
Return an array containing all the headers that are expandable.

Parameters: first Description of Parameter last Description of Parameter headers Description of Parameter

Returns: The expandableHeaders value

getHorizontalAlignment

public int getHorizontalAlignment()
Return the horizontal alignment.

Returns: The horizontal alignment.

getIgnoreInvisibleComponents

public boolean getIgnoreInvisibleComponents()
Get whether or not we should ignore an components that are not visible.

Returns: True if we should ignore them.

getLayoutAlignmentX

public float getLayoutAlignmentX(Container target)
I don't really understand what this method is supposed to return so I always return 0F. If you can explain this one to me then send me an email at mbowler@GargoyleSoftware.com and I'll fix this method up appropriately.

Parameters: target The container that this layout is managing.

Returns: Zero.

getLayoutAlignmentY

public float getLayoutAlignmentY(Container target)
I don't really understand what this method is supposed to return so I always return 0F. If you can explain this one to me then send me an email at mbowler@GargoyleSoftware.com and I'll fix this method up appropriately.

Parameters: target The container that this layout is managing.

Returns: Zero.

getMinimumColumnWidth

private int getMinimumColumnWidth(int index)
Return the minimum column width. The default is 0.

Parameters: index The column index.

Returns: The minimum column width for the specified column.

getMinimumRowHeight

private int getMinimumRowHeight(int index)
Return the minimum row height. The default is 0.

Parameters: index Description of Parameter

Returns: The minimumRowHeight value

getPermanentInfo

private TableLayout.HeaderPermanentInfo getPermanentInfo(Set infoList, int index, boolean createIfNeeded)
TODO: Provide comments

Parameters: infoList Description of Parameter index Description of Parameter createIfNeeded Description of Parameter

Returns: The permanentInfo value

getTraceChannel

public TraceChannel getTraceChannel()
Return the trace channel.

Returns: The trace channel or null if one wasn't set.

getVerticalAlignment

public int getVerticalAlignment()
Return the vertical alignment.

Returns: The vertical alignment.

See Also: TableLayout

initTempSizes

private void initTempSizes()
Initialize the temporary arrays (tempRowHeaders_ and tempColumnHeaders_) for use in a calculation.

invalidateLayout

public void invalidateLayout(Container target)
Invalidate the layout and throw away and temporary calculations.

Parameters: target The container that this layout is managing.

invalidateLayout

private void invalidateLayout()
Invalidate the layout.

isColumnExpandable

public boolean isColumnExpandable(int index)
Return true if this column can be expanded beyond its preferred size. The default is false.

Parameters: index The column.

Returns: true if the column is expandable.

isRowExpandable

public boolean isRowExpandable(int index)
Return true if this row can be expanded beyond its preferred size. The default is false.

Parameters: index The row index

Returns: true if the specified row is expandable.

layoutContainer

public void layoutContainer(Container parent)
Layout all the components in this container.

Parameters: parent The container that this layout is managing.

maximumLayoutSize

public Dimension maximumLayoutSize(Container target)
Return the maximum layout size.

Parameters: target The container that this layout is managing.

Returns: The maximum layout size.

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Get the minimum size of this layout.

Parameters: parent The container that this layout is managing.

Returns: The minimum size required for this layout.

positionComponent

private void positionComponent(TableLayout.Entry entry, int x, int y, int width, int height)
Position one component given the bounding coordinates

Parameters: entry Description of Parameter x Description of Parameter y Description of Parameter width Description of Parameter height Description of Parameter

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
Return the preferred layout size.

Parameters: parent The container that this layout is managing.

Returns: The preferred layout size.

removeLayoutComponent

public void removeLayoutComponent(Component comp)
Remove the specified component from the layout.

Parameters: comp The component to remove.

setColumnExpandable

public void setColumnExpandable(int index, boolean isExpandable)
Set whether this column can be expanded beyond its preferred size.

Parameters: index The column index. isExpandable true if the column is to be expandable.

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)
Set the vertical alignment. Legal values are:

Parameters: alignment The new horizontal alignment.

setIgnoreInvisibleComponents

public void setIgnoreInvisibleComponents(boolean ignore)
Set whether or not we should ignore an components that are not visible.

Parameters: ignore True if we should ignore them.

setMinimumColumnWidth

public void setMinimumColumnWidth(int index, int size)
Set the minimum column width for a specific column.

Parameters: index The column that we are setting the width for. size The new width.

setMinimumRowHeight

public void setMinimumRowHeight(int index, int size)
Set the minimum row height for a specific row.

Parameters: index The row that we are setting the height for. size The new minimum height.

setParent

private void setParent(Container newParent)
Set the parent container for this layout.

Parameters: newParent The new parent value

setRowExpandable

public void setRowExpandable(int index, boolean isExpandable)
Set whether this row can be expanded beyond its preferred size.

Parameters: index The row index. isExpandable true if the row is to be expandable.

setTraceChannel

public void setTraceChannel(TraceChannel channel)
Set the trace channel used for printing diagnostic information. If the channel is null then no tracing will be done.

Parameters: channel The new trace channel.

setVerticalAlignment

public void setVerticalAlignment(int alignment)
Set the vertical alignment. Legal values are:

Parameters: alignment The new vertical alignment.

shrinkToFit

private void shrinkToFit(TableLayout.Header[] sizes, int clipLength)
Shrink the specified sizes to fit within the specified clipLength. Do not shrink beyond the minimum size.

Parameters: sizes Description of Parameter clipLength Description of Parameter

toString

private static String toString(Dimension dimension)
Convenience method to create a string from a Dimension object.

Parameters: dimension Description of Parameter

Returns: Description of the Returned Value