com.izforge.izpack.gui
Class TwoColumnLayout

java.lang.Object
  extended bycom.izforge.izpack.gui.TwoColumnLayout
All Implemented Interfaces:
java.awt.LayoutManager, java.awt.LayoutManager2

public class TwoColumnLayout
extends java.lang.Object
implements java.awt.LayoutManager2

This class implements a layout manager that generally lays out components in two columns.

The design goal for this layout manager was to lay out forms for data entry, where there are several rows of entry fields with associated labels. The goal was to have the beginning off all labels line up, as well as the left edge of all the data entry fields. This leads to a situation where all components are essentially laid out in two columns. The columns adjust to accommodate components of various sizes. This means that components that are added are laid out top to bottom, either in the left column, in the right column or straddling both columns. In addition to this general behavior, the following additional layout capabilities are supported:

The Layout Behavior

The left and right margin are absolute. This means that they can not be penetrated by components. All layout happens between the limits established by these margins. The purpose of these margins is to ensure that components are not laid out all the way to the edge of their container, without the need to set matching borders for each component.

The title margin at the top factors only into the layout behavior if there is a component set to be laid out in that region, otherwise it is ignored.

The vertical space available to each row of components depends on the space requirements of the tallest component in that row. Both components are placed vertically centered in their row.

All horizontal layout is based on the position of three vertical rules, the left rule, the right rule and the center rule.



The actual position of each rule depends on the alignment strategy, margin settings and component sizes. Regardless of these factors, components placed in the left column are always positioned with their left edge aligned with the left rule. Components placed in the right column are always positioned with their left edge aligned with the center rule. If a component straddles both columns, it is always positioned with the left edge aligned with the left rule, but is allowed to extend all the way to the right rule. The only exception is a component that is specified with an indent. In this case the component is moved to the right of the respective rule by the indent amount.

The location of the rules is determined based on the alignment strategy as follows:
All components clump together vertically and are positioned right beneath the title margin. This is of course not a very appealing presentation. By setting how the remaining vertical space is distributed above and below the cluster of components the cluster can be positioned more favorably (see the shaded area in the illustration).

Version:
0.0.1 / 11/14/02
Author:
Elmar Grom
See Also:
TwoColumnConstraints

Field Summary
private  int alignment
           
static int CENTER
           
private  int centerRule
           
private  java.util.Vector[] components
          holds all the components and layout constraints.
private  int gap
          the gap between the two columns
private  int indent
          the indent setting in % of the conteiner's width
static int LEFT
           
private  int leftRule
           
private  int margin
          the margin setting in % of the container's width
static int RIGHT
           
private  int rightRule
           
private  TwoColumnConstraints title
          holds the component to be placed in the title region, including layout constraints.
private  int titleHeight
           
private  int topBuffer
          the setting for the buffer area on top of hte comonent cluster in % of the left over height.
 
Constructor Summary
TwoColumnLayout(int margin, int gap, int indent, int topBuffer, int alignment)
          Constructs a TwoColumnLayout layout manager.
 
Method Summary
 void addLayoutComponent(java.awt.Component comp, java.lang.Object constraints)
          Sets the constraints for the specified component in this layout.
 void addLayoutComponent(java.lang.String name, java.awt.Component comp)
          Adds the specified component with the specified name to the layout.
 float getLayoutAlignmentX(java.awt.Container parent)
          Returns the alignment along the x axis.
 float getLayoutAlignmentY(java.awt.Container parent)
          Returns the alignment along the y axis.
private  int height(int row, int column)
          Measures and returns the minimum height required to render the component in the indicated row and column.
 void invalidateLayout(java.awt.Container parent)
          Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
 void layoutContainer(java.awt.Container parent)
          Lays out the container in the specified panel.
private  int margin(java.awt.Container parent)
          Computes the margin value based on the container width and the margin setting.
 java.awt.Dimension maximumLayoutSize(java.awt.Container parent)
          Calculates the maximum size dimensions for the specified panel given the components in the specified parent container.
private  int minimumBothColumnsWidth(java.awt.Container parent)
          Retrunds the minimum width both columns together should have based on the minimum widths of all the components that straddle both columns and the minimum width of the title component.
private  int minimumClusterHeight()
           
private  int minimumColumnWidth(int column, java.awt.Container parent)
          Returns the minimum width of the column requested.
 java.awt.Dimension minimumLayoutSize(java.awt.Container parent)
          Calculates the minimum size dimensions for the specified panel given the components in the specified parent container.
private  void positionComponent(int y, int row, int column, java.awt.Container parent)
          Positiones one component as instructed.
private  void positionComponents(java.awt.Container parent)
          Positions all components in the container.
private  void positionRules(java.awt.Container parent)
          Positions the three rules in preparation for layout.
private  void positionTitle(java.awt.Container parent)
          Positions the title component and sets the variable titleHeight.
 java.awt.Dimension preferredLayoutSize(java.awt.Container parent)
          Calculates the preferred size dimensions for the specified panel given the components in the specified parent container.
 void removeLayoutComponent(java.awt.Component comp)
          This functionality is not supported
private  int rowHeight(int row)
          Measures and returns the minimum height required to render the components in the indicated row.
private  int rows()
          Returns the number of rows that need to be laid out.
 void showRules(java.awt.Graphics2D graphics, java.awt.Color color)
          This method is provided for conveninence of debugging layout problems.
private  int topBuffer(int usedHeight, java.awt.Container parent)
          Computes the top buffer value based on the container width and the setting for the top buffer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LEFT

public static final int LEFT
See Also:
Constant Field Values

RIGHT

public static final int RIGHT
See Also:
Constant Field Values

CENTER

public static final int CENTER
See Also:
Constant Field Values

components

private java.util.Vector[] components
holds all the components and layout constraints.


title

private TwoColumnConstraints title
holds the component to be placed in the title region, including layout constraints.


margin

private int margin
the margin setting in % of the container's width


topBuffer

private int topBuffer
the setting for the buffer area on top of hte comonent cluster in % of the left over height.


indent

private int indent
the indent setting in % of the conteiner's width


gap

private int gap
the gap between the two columns


alignment

private int alignment

leftRule

private int leftRule

rightRule

private int rightRule

centerRule

private int centerRule

titleHeight

private int titleHeight
Constructor Detail

TwoColumnLayout

public TwoColumnLayout(int margin,
                       int gap,
                       int indent,
                       int topBuffer,
                       int alignment)
Constructs a TwoColumnLayout layout manager. To add components use the container's add(comp, constraints) method with a TwoColumnConstraints object.

Parameters:
margin - the margin width to use on the left and right side in % of the total container width. Values less than 0% and greater than 50% are not accepted.
gap - the gap between the two columns.
indent - the indent to use for components that have that constraint set. This is a value in pixels.
topBuffer - the percentage of left over vertical space to place on top of the component cluster. Values between 0% and 100% are accepted.
alignment - how to align the overall layout. Legal values are LEFT, CENTER, RIGHT.
Method Detail

addLayoutComponent

public void addLayoutComponent(java.awt.Component comp,
                               java.lang.Object constraints)
Sets the constraints for the specified component in this layout. null is a legal value for a component, but not for a constraints object.

Specified by:
addLayoutComponent in interface java.awt.LayoutManager2
Parameters:
comp - the component to be modified.
constraints - the constraints to be applied.

layoutContainer

public void layoutContainer(java.awt.Container parent)
Lays out the container in the specified panel.

Specified by:
layoutContainer in interface java.awt.LayoutManager
Parameters:
parent - the component which needs to be laid out.

positionRules

private void positionRules(java.awt.Container parent)
Positions the three rules in preparation for layout. Sets the variables:

Parameters:
parent - the component which needs to be laid out.

positionTitle

private void positionTitle(java.awt.Container parent)
Positions the title component and sets the variable titleHeight. Note: this method depends on the fact that the rules are set to their correct layout position.

Parameters:
parent - the component which needs to be laid out.

positionComponents

private void positionComponents(java.awt.Container parent)
Positions all components in the container.

Parameters:
parent - the component which needs to be laid out.

positionComponent

private void positionComponent(int y,
                               int row,
                               int column,
                               java.awt.Container parent)
Positiones one component as instructed. Constraints for each component, such as stretch, BOTH and indent are taken into account. In addition, empty comonents are handled properly.

Parameters:
y - the y location within the continer, where the component should be positioned.
row - the row of the component
column - the column of the component
parent - the container which needs to be laid out.

minimumColumnWidth

private int minimumColumnWidth(int column,
                               java.awt.Container parent)
Returns the minimum width of the column requested.

Parameters:
column - the columns to measure (LEFT / RIGHT)
parent - the component which needs to be laid out.
Returns:
the minimum width required to fis the components in this column

minimumBothColumnsWidth

private int minimumBothColumnsWidth(java.awt.Container parent)
Retrunds the minimum width both columns together should have based on the minimum widths of all the components that straddle both columns and the minimum width of the title component.

Parameters:
parent - the component which needs to be laid out.
Returns:
the minimum width required to fis the components in this column

minimumClusterHeight

private int minimumClusterHeight()

rows

private int rows()
Returns the number of rows that need to be laid out.


rowHeight

private int rowHeight(int row)
Measures and returns the minimum height required to render the components in the indicated row.

Parameters:
row - the index of the row to measure

height

private int height(int row,
                   int column)
Measures and returns the minimum height required to render the component in the indicated row and column.

Parameters:
row - the index of the row to measure
column - the column of the component to measure (LEFT or RIGHT)

margin

private int margin(java.awt.Container parent)
Computes the margin value based on the container width and the margin setting.

Parameters:
parent - the component which needs to be laid out.

topBuffer

private int topBuffer(int usedHeight,
                      java.awt.Container parent)
Computes the top buffer value based on the container width and the setting for the top buffer

Parameters:
usedHeight - the amount of the parent component's height that is already in use (height of the title and the combined height of all rows).
parent - the component which needs to be laid out.

preferredLayoutSize

public java.awt.Dimension preferredLayoutSize(java.awt.Container parent)
Calculates the preferred size dimensions for the specified panel given the components in the specified parent container.

Specified by:
preferredLayoutSize in interface java.awt.LayoutManager
Parameters:
parent - the component to be laid out

minimumLayoutSize

public java.awt.Dimension minimumLayoutSize(java.awt.Container parent)
Calculates the minimum size dimensions for the specified panel given the components in the specified parent container.

Specified by:
minimumLayoutSize in interface java.awt.LayoutManager
Parameters:
parent - the component to be laid out

maximumLayoutSize

public java.awt.Dimension maximumLayoutSize(java.awt.Container parent)
Calculates the maximum size dimensions for the specified panel given the components in the specified parent container.

Specified by:
maximumLayoutSize in interface java.awt.LayoutManager2
Parameters:
parent - the component to be laid out

getLayoutAlignmentX

public float getLayoutAlignmentX(java.awt.Container parent)
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Specified by:
getLayoutAlignmentX in interface java.awt.LayoutManager2
Parameters:
parent - the component to be laid out

getLayoutAlignmentY

public float getLayoutAlignmentY(java.awt.Container parent)
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Specified by:
getLayoutAlignmentY in interface java.awt.LayoutManager2
Parameters:
parent - the component to be laid out

invalidateLayout

public void invalidateLayout(java.awt.Container parent)
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.

Specified by:
invalidateLayout in interface java.awt.LayoutManager2
Parameters:
parent - the component to be laid out

addLayoutComponent

public void addLayoutComponent(java.lang.String name,
                               java.awt.Component comp)
Adds the specified component with the specified name to the layout. This version is not supported, use addLayoutComponent with layout contsraints.

Specified by:
addLayoutComponent in interface java.awt.LayoutManager
Parameters:
name - the component name
comp - the component to be added

removeLayoutComponent

public void removeLayoutComponent(java.awt.Component comp)
This functionality is not supported

Specified by:
removeLayoutComponent in interface java.awt.LayoutManager
Parameters:
comp - the component to be removed

showRules

public void showRules(java.awt.Graphics2D graphics,
                      java.awt.Color color)
This method is provided for conveninence of debugging layout problems. It renders the three rules and the limit of the title marign visible after these positions have been computed. In addition, the indent locations are shown as dashed lines. To use this functionality do the following:


Note: cast the graphics object received in the paint() method to Graphics2D when making the call.

Parameters:
graphics - the graphics context used for drawing.
color - the color to use for rendering the layout grid