kirk.gui.layout
Class GridSpanLayout

java.lang.Object
  extended bykirk.gui.layout.GridSpanLayout
All Implemented Interfaces:
LayoutManager, LayoutManager2

public class GridSpanLayout
extends Object
implements LayoutManager2

This class is a custom LayoutManager that is kinda like a mix of GridLayout and GridBagLayout. For me, it's not as confusing as GridBagLayout, but it offers more functionality than GridLayout.

GridSpanLayout is contructed with width and height in cells, much like GridLayout. The cells are proportional to the total width and height of the Container using this LayoutManager. Also, there are horizontal and vertical gaps between Components, that default to 5 pixels, but can be specified during construction time or later on by calling the mutator methods for them.

Components are layed out on the grid much like with GridBagLayout: they are allowed to span multiple cells. However, the difference is that GridSpanLayout has a preset amount of cells, and that the sizes of all the cells are the same. Also, there are no weights to worry about. Any resizing is done exactly like GridLayout and GridLineLayout: all cells are resized equivalently, and remain relatively on the same position.

This LayoutManager is one that uses constraints to lay out its Components, much like GridBagLayout. The constraints are in the form of GridSpanConstraints objects, which contain the values needed for laying out the Component. Each Component has an associated constraints object.

These are the settings you can give a GridSpanConstraints object.

Like GridBagLayout, the GridSpanConstraints objects are copied. This because when you add or set a constraint, this class checks whether it is allowed. So you can't get to the inner GridSpanConstraints objects because otherwise you could (accidentally) break this LayoutManager.
This class does not check for conflicts among GridSpanConstraints, simply because it can't (it has no knowledge of a parent Container when setting constraints, it can be effectively used to lay out multiple Containers, as the interface prescribes), but for easeness sake there can be only one Component per cell. So, if there are multiple Components that are on the same cell, only the one that comes first in the list of the parent Container (Container.getComponent(int n)) will be displayed. So, take care when adding Components (just like you would with GridBagLayout... I still don't know what that class' behaviour is in this case. I still don't know/understand a lot about it actually... What is it with those weights :^P).

Version:
1
Author:
Berend "Kirk" Wouda
See Also:
GridBagLayout, GridLayout, GridSpanConstraints

Field Summary
protected  HashMap componentmap
          The Map that links the Components to their constraints objects.
protected  int height
          The height of the grid in cells.
protected  int horizontalgap
          The horizontal gap.
protected  int verticalgap
          The vertical gap.
protected  int width
          The width of the grid in cells.
 
Constructor Summary
GridSpanLayout(int width, int height)
          Creates a new GridSpanLayout with the given width and height, and the default values (5) for the horizontal gap and vertical gap.
GridSpanLayout(int width, int height, int horizontalgap, int verticalgap)
          Creates a new GridSpanLayout with the given width, height, horizontal gap and vertical gap.
 
Method Summary
 void addLayoutComponent(Component comp, Object constraints)
          Adds the passed Component to the LayoutManager with the passed constraints.
 void addLayoutComponent(String name, Component comp)
          Adds the passed Component to the LayoutManager with the passed name.
 GridSpanConstraints getConstraints(Component component)
          Returns the GridSpanConstraints that is associated with the passed key.
protected  int getGridHeight(Integer[][] cellheights)
          Returns the total height of the passed Array with heights, taken into account only the largest height per row.
protected  int getGridWidth(Integer[][] cellwidths)
          Returns the total width of the passed Array with widths, taken into account only the largest width per column.
 int getHeight()
          Returns the height of this grid in cells.
 int getHorizontalGap()
          Returns the horizontal gap.
protected  int getLargestHeight(Integer[][] cellheights, int row)
          Return the largest height of the all the cells in the indicated row.
protected  int getLargestWidth(Integer[][] cellwidths, int column)
          Return the largest width of the all the cells in the indicated column.
 float getLayoutAlignmentX(Container target)
          Returns the alignment along the x-axis of the passed Container if it where to be layed out with this LayoutManager.
 float getLayoutAlignmentY(Container target)
          Returns the alignment along the y-axis of the passed Container if it where to be layed out with this LayoutManager.
 int getVerticalGap()
          Returns the vertical gap.
 int getWidth()
          Returns the width of this grid in cells.
 void invalidateLayout(Container target)
          Invalidates this LayoutManager, indicating that if this LayoutManager has cached information it should be discarded.
protected  boolean isFree(Component[][] componentgrid, int x, int y, int width, int height)
          Checks whether the given portion of the Component grid does not contain any Components.
 void layoutContainer(Container parent)
          Lays out the passed Container with this LayoutManager, and the constraints objects associated with the Components of this Container.
protected  Component[][] makeGrid(Container parent, boolean active)
          Returns the grid.
 Dimension maximumLayoutSize(Container target)
          Returns the size of the passed Container as this LayoutManager would like it to be at maximum when the passed Container where to be layed out with this LayoutManager.
 Dimension minimumLayoutSize(Container parent)
          Returns the size of the passed Container as this LayoutManager would like it to be at minimum when the passed Container where to be layed out with this LayoutManager.
 boolean outOfBounds(GridSpanConstraints constraints)
          Check whether the passed constraints are out of bounds.
 Dimension preferredLayoutSize(Container parent)
          Returns the size of the passed Container as this LayoutManager would like it best when the passed Container where to be layed out with this LayoutManager.
 GridSpanConstraints removeConstraints(Component component)
          Removes the association indicated by the component from the internal mapping.
 void removeLayoutComponent(Component comp)
          Removes the passed Component from the LayoutManager.
 GridSpanConstraints setConstraints(Component component, GridSpanConstraints constraints)
          Adds a new association to the internal mapping.
protected  void setHeight(int height)
          Sets the height of this grid in cells.
 void setHorizontalGap(int horizontalgap)
          Sets the horizontal gap.
protected  void setTaken(Component[][] componentgrid, int x, int y, int width, int height, Component component)
          Set the passed portion of the passed grid to the passed Component.
 void setVerticalGap(int verticalgap)
          Sets the vertical gap.
protected  void setWidth(int width)
          Sets the width of this grid in cells.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

width

protected int width
The width of the grid in cells.


height

protected int height
The height of the grid in cells.


horizontalgap

protected int horizontalgap
The horizontal gap.


verticalgap

protected int verticalgap
The vertical gap.


componentmap

protected HashMap componentmap
The Map that links the Components to their constraints objects.

Constructor Detail

GridSpanLayout

public GridSpanLayout(int width,
                      int height,
                      int horizontalgap,
                      int verticalgap)
Creates a new GridSpanLayout with the given width, height, horizontal gap and vertical gap.

Parameters:
width - The width of this grid in cells.
height - The height of this grid in cells.
horizontalgap - The horizontal gap between each cell and the cells and borders at the left and right of the screen.
verticalgap - The vertical gap between each cell and the cells and borders at the top and bottom of the screen.

GridSpanLayout

public GridSpanLayout(int width,
                      int height)
Creates a new GridSpanLayout with the given width and height, and the default values (5) for the horizontal gap and vertical gap.

Parameters:
width - The width of this grid in cells.
height - The height of this grid in cells.
Method Detail

getWidth

public int getWidth()
Returns the width of this grid in cells.

Returns:
The width of this grid in cells.

setWidth

protected void setWidth(int width)
Sets the width of this grid in cells. The width cannot be zero or negative.

Parameters:
width - The width of this grid in cells.

getHeight

public int getHeight()
Returns the height of this grid in cells.

Returns:
The height of this grid in cells.

setHeight

protected void setHeight(int height)
Sets the height of this grid in cells. The height cannot be zero or negative.

Parameters:
height - The height of this grid in cells.

getHorizontalGap

public int getHorizontalGap()
Returns the horizontal gap.

Returns:
The size of the horizontal gap.

setHorizontalGap

public void setHorizontalGap(int horizontalgap)
Sets the horizontal gap. The horizontal gap cannot be negative.

Parameters:
horizontalgap - The size the horizontal gap has to be set to.

getVerticalGap

public int getVerticalGap()
Returns the vertical gap.

Returns:
The size of the vertical gap.

setVerticalGap

public void setVerticalGap(int verticalgap)
Sets the vertical gap. The vertical gap cannot be negative.

Parameters:
verticalgap - The size the vertical gap has to be set to.

outOfBounds

public boolean outOfBounds(GridSpanConstraints constraints)
Check whether the passed constraints are out of bounds.

Parameters:
constraints - The constraints to be checked.
Returns:
true if the passed constraints are out of bounds, false otherwise.

getConstraints

public GridSpanConstraints getConstraints(Component component)
Returns the GridSpanConstraints that is associated with the passed key. If no such object exists, a default one is associated with the passed key, and returned. This because it is possible that key are passed that do not exist in the mapping. This happens when a Container sets this object as its LayoutManager after adding Components. null is not allowed as key.

Parameters:
component - The key that is associated with the GridSpanConstraints.
Returns:
The GridSpanConstraints that are associated with the given key.

setConstraints

public GridSpanConstraints setConstraints(Component component,
                                          GridSpanConstraints constraints)
Adds a new association to the internal mapping. Note that if null is passed as the associated GridSpanConstraints, a default GridSpanConstraints will be returned when the passed Component is given as key null is not allowed as key.

Parameters:
component - The key of the association.
constraints - The associated GridSpanConstraints.
Returns:
The previously associated GridSpanConstraints, if there was any.

removeConstraints

public GridSpanConstraints removeConstraints(Component component)
Removes the association indicated by the component from the internal mapping. null is not allowed as key.

Parameters:
component - The key of the association.
Returns:
The GridSpanConstraints that was associated with the key.

addLayoutComponent

public void addLayoutComponent(String name,
                               Component comp)
Adds the passed Component to the LayoutManager with the passed name.

Specified by:
addLayoutComponent in interface LayoutManager
See Also:
LayoutManager.addLayoutComponent(java.lang.String, java.awt.Component)

addLayoutComponent

public void addLayoutComponent(Component comp,
                               Object constraints)
Adds the passed Component to the LayoutManager with the passed constraints. These constraints must be an instance of GridSpanConstraints.

Specified by:
addLayoutComponent in interface LayoutManager2
Parameters:
comp - The Component to be added.
constraints - The constraints to be associated with the passed Component.
See Also:
LayoutManager2.addLayoutComponent(java.awt.Component, java.lang.Object)

removeLayoutComponent

public void removeLayoutComponent(Component comp)
Removes the passed Component from the LayoutManager.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
comp - The Component to be removed.
See Also:
LayoutManager.removeLayoutComponent(java.awt.Component)

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
Returns the size of the passed Container as this LayoutManager would like it best when the passed Container where to be layed out with this LayoutManager.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
parent - The Container who is te be checked for preferred size.
Returns:
The preferred size of this Container.
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Returns the size of the passed Container as this LayoutManager would like it to be at minimum when the passed Container where to be layed out with this LayoutManager.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
parent - The Container who is te be checked for minimum size.
Returns:
The minimum size of this Container.
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

maximumLayoutSize

public Dimension maximumLayoutSize(Container target)
Returns the size of the passed Container as this LayoutManager would like it to be at maximum when the passed Container where to be layed out with this LayoutManager.

Specified by:
maximumLayoutSize in interface LayoutManager2
Parameters:
target - The Container who is te be checked for maximum size.
Returns:
The maximum size of this Container.
See Also:
LayoutManager2.maximumLayoutSize(java.awt.Container)

getLayoutAlignmentX

public float getLayoutAlignmentX(Container target)
Returns the alignment along the x-axis of the passed Container if it where to be layed out with this LayoutManager. Always returns that it wants to be centered.

Specified by:
getLayoutAlignmentX in interface LayoutManager2
Parameters:
target - The Container who is te be checked for preference.
Returns:
0.5, to indicate it wants to be centered.
See Also:
LayoutManager2.getLayoutAlignmentX(java.awt.Container)

getLayoutAlignmentY

public float getLayoutAlignmentY(Container target)
Returns the alignment along the y-axis of the passed Container if it where to be layed out with this LayoutManager. Always returns that it wants to be centered.

Specified by:
getLayoutAlignmentY in interface LayoutManager2
Parameters:
target - The Container who is te be checked for preference.
Returns:
0.5, to indicate it wants to be centered.
See Also:
LayoutManager2.getLayoutAlignmentY(java.awt.Container)

invalidateLayout

public void invalidateLayout(Container target)
Invalidates this LayoutManager, indicating that if this LayoutManager has cached information it should be discarded.

Specified by:
invalidateLayout in interface LayoutManager2
Parameters:
target - The Container that has to invalidated.
See Also:
LayoutManager2.invalidateLayout(java.awt.Container)

layoutContainer

public void layoutContainer(Container parent)
Lays out the passed Container with this LayoutManager, and the constraints objects associated with the Components of this Container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
parent - The Container to be layed out.
See Also:
LayoutManager.layoutContainer(java.awt.Container)

makeGrid

protected Component[][] makeGrid(Container parent,
                                 boolean active)
Returns the grid. It is represented as an Array with Components. On each grid cell, there is one or no Component. If there are Components that span multiple cells, they have multiple entries in the grid. If there are multiple Components in one cell, only the one that appears first in the parent Container will appear. Note that only visible Components will appear in the grid.

Parameters:
parent - The Container that supplies the Component we make a grid of.
active - A boolean indicating whether this method should make unused Components invisible. layoutContainer() calls this as true, the size methods call this as false.
Returns:
A two-dimensional Array of Components that represents the grid.

isFree

protected boolean isFree(Component[][] componentgrid,
                         int x,
                         int y,
                         int width,
                         int height)
Checks whether the given portion of the Component grid does not contain any Components.

Parameters:
componentgrid - The grid with Components.
x - The left corner of the portion.
y - The upper corner of the portion.
width - The width of the portion.
height - The height of the portion.
Returns:
true when the given portion has only nulls, false otherwise.

setTaken

protected void setTaken(Component[][] componentgrid,
                        int x,
                        int y,
                        int width,
                        int height,
                        Component component)
Set the passed portion of the passed grid to the passed Component.

Parameters:
componentgrid - The grid with Components.
x - The left corner of the portion.
y - The upper corner of the portion.
width - The width of the portion.
height - The height of the portion.
component - The Component to be set in the postion's cells.

getGridWidth

protected int getGridWidth(Integer[][] cellwidths)
Returns the total width of the passed Array with widths, taken into account only the largest width per column.

Parameters:
cellwidths - The Array with the cell widths. null in the Array indicates spanned widths.
Returns:
The total width of this Array.

getLargestWidth

protected int getLargestWidth(Integer[][] cellwidths,
                              int column)
Return the largest width of the all the cells in the indicated column. This method is recursive, and will take into account the -1 values (spanned cells).

Parameters:
cellwidths - The Array with the cell widths. null in the Array indicates spanned widths.
column - The column to be searched.
Returns:
The largest width the the passed column.

getGridHeight

protected int getGridHeight(Integer[][] cellheights)
Returns the total height of the passed Array with heights, taken into account only the largest height per row.

Parameters:
cellheights - The Array with the cell heights. null in the Array indicates spanned heights.
Returns:
The total height of this Array.

getLargestHeight

protected int getLargestHeight(Integer[][] cellheights,
                               int row)
Return the largest height of the all the cells in the indicated row. This method is recursive, and will take into account the -1 values (spanned cells).

Parameters:
cellheights - The Array with the cell heights. null in the Array indicates spanned heights.
row - The row to be searched.
Returns:
The largest height the the passed row.