kirk.gui
Class GridSpanLayout

java.lang.Object
  |
  +--kirk.gui.GridSpanLayout

All Implemented Interfaces:

java.awt.LayoutManager, java.awt.LayoutManager2

public class GridSpanLayout

extends java.lang.Object

implements java.awt.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.

• setX(int) - Sets the horinzontal position of the left upper corner of the component, in cells.
• setY(int) - Sets the vertical position of the left upper corner of the component, in cells.
• setWidth(int) - Sets the width of the component, in cells.
• setHeight(int) - Sets the height of the component, in cells.
• setHorizontalFill(double) - Sets the relative width of the component. The number has to be between 0.0 and 1.0, where 0.0 indicates that the component has no width, 1.0 indicates to fully fill the available horizontal space, 0.5 indicates that the component is as wide as halve the available space, and so on. If you specify a value that is out of the 0.0-1.0 bounds(inclusive), then the preferred width of the component (specified by Component.getPreferredSize().width) will be used.
• setVerticalFill(double) - Sets the relative height of the component. The number has to be between 0.0 and 1.0, where 0.0 indicates that the component has no height, 1.0 indicates to fully fill the available vertical space, 0.5 indicates that the component is as high as halve the available space, and so on. If you specify a value that is out of the 0.0-1.0 bounds(inclusive), then the preferred height of the component (specified by Component.getPreferredSize().height) will be used.
• SetHorizontalAnchor(double) - Sets the relative position of the component on the x-axis. The number has to be between 0.0 and 1.0, where 0.0 (the default value) indicates that the component should be placed at the far most left side, 1.0 indicates that the component should be placed at the far most right side, 0.5 indicates that the component should be centered, and so on. If you specify a value that is out of the 0.0-1.0 bounds (inclusive), then the alignment value of the component (specified by Component.getAlignmentX()) will be used.
• SetVerticalAnchor(double) - Sets the relative position of the component on the y-axis. The number has to be between 0.0 and 1.0, where 0.0 (the default value) indicates that the component should be placed at the far most upper side, 1.0 indicates that the component should be placed at the far most lower side, 0.5 indicates that the component should be centered, and so on. If you specify a value that is out of the 0.0-1.0 bounds (inclusive), then the alignment value of the component (specified by Component.getAlignmentY()) will be used.

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, LineLayout, GridSpanConstraints

Field Summary

protected java.util.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(java.awt.Component comp, java.lang.Object constraints) Adds the passed Component to the LayoutManager with the passed constraints.
void	addLayoutComponent(java.lang.String name, java.awt.Component comp) Adds the passed Component to the LayoutManager with the passed name.
GridSpanConstraints	getConstraints(java.awt.Component component) Returns the GridSpanConstraints that is associated with the passed key.
protected int	getGridHeight(java.lang.Integer[][] cellheights) Returns the total height of the passed array with heights, taken into account only the largest height per row.
protected int	getGridWidth(java.lang.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(java.lang.Integer[][] cellheights, int row) Return the largest height of the all the cells in the indicated row.
protected int	getLargestWidth(java.lang.Integer[][] cellwidths, int column) Return the largest width of the all the cells in the indicated column.
float	getLayoutAlignmentX(java.awt.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(java.awt.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(java.awt.Container target) Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
protected boolean	isFree(java.awt.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(java.awt.Container parent) Lays out the passed container with this LayoutManager, and the constraints objects associated with the Components of this container.
protected java.awt.Component[][]	makeGrid(java.awt.Container parent, boolean active) Returns the grid.
java.awt.Dimension	maximumLayoutSize(java.awt.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.
java.awt.Dimension	minimumLayoutSize(java.awt.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.
protected boolean	outOfBounds(GridSpanConstraints constraints) Check whether the passed constraints are out of bounds.
java.awt.Dimension	preferredLayoutSize(java.awt.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(java.awt.Component component) Removes the association indicated by the component from the internal mapping.
void	removeLayoutComponent(java.awt.Component comp) Removes the passed Component from the LayoutManager.
GridSpanConstraints	setConstraints(java.awt.Component component, GridSpanConstraints constraints) Adds a new association to the internal mapping.
void	setHeight(int height) Sets the height of this grid in cells.
void	setHorizontalGap(int horizontalgap) Sets the horizontal gap.
protected void	setTaken(java.awt.Component[][] componentgrid, int x, int y, int width, int height, java.awt.Component component) Set the passed portion of the passed grid to the passed Component.
void	setVerticalGap(int verticalgap) Sets the vertical gap.
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 java.util.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

public 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

public 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.

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.

outOfBounds

protected 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(java.awt.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(java.awt.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(java.awt.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(java.lang.String name,
                               java.awt.Component comp)

Adds the passed Component to the LayoutManager with the passed name.

Specified by:

addLayoutComponent in interface java.awt.LayoutManager

See Also:

LayoutManager.addLayoutComponent(java.lang.String, java.awt.Component)

addLayoutComponent

public void addLayoutComponent(java.awt.Component comp,
                               java.lang.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 java.awt.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(java.awt.Component comp)

Removes the passed Component from the LayoutManager.

Specified by:

removeLayoutComponent in interface java.awt.LayoutManager

Parameters:

comp - The Component to be removed.

See Also:

LayoutManager.removeLayoutComponent(java.awt.Component)

preferredLayoutSize

public java.awt.Dimension preferredLayoutSize(java.awt.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 java.awt.LayoutManager

Returns:

The preferred size of this Container.

See Also:

LayoutManager.preferredLayoutSize(java.awt.Container)

minimumLayoutSize

public java.awt.Dimension minimumLayoutSize(java.awt.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 java.awt.LayoutManager

Returns:

The minimum size of this Container.

See Also:

LayoutManager.minimumLayoutSize(java.awt.Container)

maximumLayoutSize

public java.awt.Dimension maximumLayoutSize(java.awt.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 java.awt.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(java.awt.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 java.awt.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(java.awt.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 java.awt.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(java.awt.Container target)

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:

target - The Container that has to invalidated.

See Also:

LayoutManager2.invalidateLayout(java.awt.Container)

layoutContainer

public void layoutContainer(java.awt.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 java.awt.LayoutManager

See Also:

LayoutManager.layoutContainer(java.awt.Container)

makeGrid

protected java.awt.Component[][] makeGrid(java.awt.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(java.awt.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(java.awt.Component[][] componentgrid,
                        int x,
                        int y,
                        int width,
                        int height,
                        java.awt.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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.

Returns:

The largest height the the passed row.