attachlayout
Class AttachLayout

java.lang.Object
  |
  +--attachlayout.AttachLayout

All Implemented Interfaces:

AttachConstants, java.awt.LayoutManager, java.awt.LayoutManager2

public class AttachLayout

extends java.lang.Object

implements java.awt.LayoutManager2, AttachConstants

LayoutManager that allows to organize components in a container by defining attachments for every side of a component (See also Sample included). An attachment is defined by specifying an anchor, connection type and offset.

Anchors

Possible anchors are the container's layout borders, other components in the same container, relative positions (percentages of container width or height), virtual boxes defined in the container's layout or no anchor at all.

Container's layout borders as anchor:

The container's layout borders are defined by the edge of the container minus container insets. When the TOP side of a component is attached, the anchor will be the container's top layout border, for the LEFT side the anchor is the container's left layout border, etc.

Components as anchor:

A component's side can be attached to any side of the same direction (horizontal or vertical) of any other component in the same container. A side of the horizontal direction (LEFT or RIGHT) can only be attached to another component's side of the horizontal direction (LEFT or RIGHT side). The same principle holds for sides of the vertical direction (TOP or BOTTOM).

Relative position as anchor:

A relative position is defined as a percentage of the container's layout area size. The layout area is the area inside the layout borders. For example, a relative position of 50 for the left side of a component, will attach the component's left side to the left-right center of the area in the container's layout borders.

Virtual box as anchor:

It is possible to add virtual boxes to the container's layout. These can be regarded as non-existing components. When a box is added, its position and size is determined by the attachments defined for that box as if the box where a component. Added boxes can be used as anchor, similar to using components as anchors.

No anchor:

Not specifying an anchor for a side, allows a component to choose its own size in the direction of the unattached side. The component's size will be set to its preferred size in that direction or to the preferred size specified in the attachment of that component. The preferred size for a direction (width or height), if specified in an attachment for a component, always overrules the component's own preferred size in that direction. Invisible components are always treated as having a preferred size of 0 in both directions.

Connection types

Two connection types can be set when attached to an anchor: elastic or fixed. When set to fixed, the specified offset is interpreted as the exact distance (both minimum and maximum distance) between the anchor and the attached side. When set to elastic, the offset is interpreted as the minimum distance between anchor and attached side.

Offsets

Offsets can be specified depending on the anchor type: when attached to no anchor, no offset can be set.
The offset is the minimum distance in pixels between the anchor and the attached component's side. A positive offset always moves a component away from the anchor, a negative offset moves the component the opposite way. For example, when attaching a component's left side to another component (it does not matter to which side, left or right), a positive offset will move the attached component to the right. When attaching a component's right side to another component (left or right side), a positive offset will move the attached component to the left.
Invisible components are treated as having size and offsets 0 for all sides.

Resizing policy

By cleverly combining different attachments, it is very easy to also control the resizing policy of every component in both horizontal and vertical directions individually. See Sample included for details.

Since:

JDK 1.1

Version:

2.5

Inner Class Summary

static class

AttachLayout.Constraints Defines constraints by specifying an anchor, connection type and offset for every side of the component to lay out.

Fields inherited from interface attachlayout.AttachConstants

BOTTOM, COMPONENT_PREFERRED, ELASTIC, FIXED, LEFT, RIGHT, TOP

Constructor Summary

AttachLayout()
Creates a new AttachLayout instance.

Method Summary

void	addLayoutComponent(java.awt.Component comp, java.lang.Object constraints) Adds the specified component to the layout, using the specified constraint object.
void	addLayoutComponent(java.lang.String name, java.awt.Component comp) Deprecated. replaced by addLayoutComponent(Component, Object). This method is not implemented.
void	checkSolvable() Checks if the current structure of constraints can be solved.
void	defineBox(java.lang.String name, AttachLayout.Constraints cts) Defines and adds a box to this layout.
void	defineColumn(java.lang.String name, AttachLayout.Constraints cts) Defines and adds a box to this layout.
void	defineRow(java.lang.String name, AttachLayout.Constraints cts) Defines and adds a box to this layout.
static int	getBackSide(int side) Returns the back side of the given side.
AttachLayout.Constraints	getConstraints() Returns a new Constraints instance.
static int	getFrontSide(int side) Returns the front side of the given side.
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.
static int	getOppositeSide(int side) Returns the opposite side of the given side.
void	invalidateLayout(java.awt.Container target) Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
static boolean	isFrontSide(int side) Returns true if the given side is LEFT or TOP side.
void	layoutContainer(java.awt.Container target) Lays out the container argument using this layout.
static void	main(java.lang.String[] args)
java.awt.Dimension	maximumLayoutSize(java.awt.Container target) Returns the maximum dimensions for this layout given the components in the specified target container.
java.awt.Dimension	minimumLayoutSize(java.awt.Container target) Determines the minimum size of the container using this layout manager.
java.awt.Dimension	preferredLayoutSize(java.awt.Container target) Determines the preferred size of the container using this layout manager, based on the components in the container.
void	removeLayoutComponent(java.awt.Component comp) Removes the specified component from this layout.

Methods inherited from class java.lang.Object

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

Constructor Detail

AttachLayout

public AttachLayout()

Creates a new AttachLayout instance.

Method Detail

getConstraints

public AttachLayout.Constraints getConstraints()

Returns a new Constraints instance. All sides (top, left, bottom and right) are set to "not connected" and all offsets are set to 0.
Constraint instances may be reused to define the attachments for several different components. Their settings are copied by the layout manager when the component is added.

addLayoutComponent

public void addLayoutComponent(java.awt.Component comp,
                               java.lang.Object constraints)

Adds the specified component to the layout, using the specified constraint object. The constraint must be an instance of Constraints. Most applications do not call this method directly. This method is called when a component is added to a container using the Container.add method with the same argument types.

Specified by:

addLayoutComponent in interface java.awt.LayoutManager2

Parameters:

comp - the component to be added.

constraints - an object that specifies how and where the component is added to the layout.

Throws:

java.lang.IllegalArgumentException - if the constraint object is not an instance of Constraints or if it does not pass number of integrity checks.

See Also:

Container.add(java.awt.Component, java.lang.Object)

addLayoutComponent

public void addLayoutComponent(java.lang.String name,
                               java.awt.Component comp)

Deprecated. replaced by addLayoutComponent(Component, Object). This method is not implemented.

Specified by:

addLayoutComponent in interface java.awt.LayoutManager

Throws:

java.lang.RuntimeException - always.

removeLayoutComponent

public void removeLayoutComponent(java.awt.Component comp)

Removes the specified component from this layout. This method is called when a container calls its remove or removeAll methods. Most applications do not call this method directly.

Specified by:

removeLayoutComponent in interface java.awt.LayoutManager

Parameters:

comp - the component to be removed.

See Also:

Container.remove(java.awt.Component), Container.removeAll()

minimumLayoutSize

public java.awt.Dimension minimumLayoutSize(java.awt.Container target)

Determines the minimum size of the container using this layout manager.

Most applications do not call this method directly. This method is called when a container calls its getMinimumSize method.

Specified by:

minimumLayoutSize in interface java.awt.LayoutManager

Parameters:

target - the container in which to do the layout.

Returns:

the minimum dimensions needed to lay out the subcomponents of the specified container.

See Also:

Container, java.awt.BorderLayout#preferredLayoutSize, Container.getMinimumSize()

preferredLayoutSize

public java.awt.Dimension preferredLayoutSize(java.awt.Container target)

Determines the preferred size of the container using this layout manager, based on the components in the container.

Most applications do not call this method directly. This method is called when a container calls its getPreferredSize method.

Specified by:

preferredLayoutSize in interface java.awt.LayoutManager

Parameters:

target - the container in which to do the layout.

Returns:

the preferred dimensions to lay out the subcomponents of the specified container.

See Also:

Container, java.awt.BorderLayout#minimumLayoutSize, Container.getPreferredSize()

maximumLayoutSize

public java.awt.Dimension maximumLayoutSize(java.awt.Container target)

Returns the maximum dimensions for this layout given the components in the specified target container.

Specified by:

maximumLayoutSize in interface java.awt.LayoutManager2

Parameters:

target - the component which needs to be laid out.

See Also:

Container, minimumLayoutSize(java.awt.Container), preferredLayoutSize(java.awt.Container)

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

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

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

layoutContainer

public void layoutContainer(java.awt.Container target)

Lays out the container argument using this layout.

This method actually reshapes the components in the specified container in order to satisfy the constraints of this layout.

Most applications do not call this method directly. This method is called when a container calls its doLayout method.

Specified by:

layoutContainer in interface java.awt.LayoutManager

Parameters:

target - the container in which to do the layout.

See Also:

Container, Container.doLayout()

defineBox

public void defineBox(java.lang.String name,
                      AttachLayout.Constraints cts)

Defines and adds a box to this layout. The box is regarded as a virtual component laid out by the constraints specified. It can be used as an anchor for attaching other components or boxes.

Parameters:

name - a valid string representing the boxe's name, must not be null.

cts - the constraints to layout the box in the container, must not be null.

defineColumn

public void defineColumn(java.lang.String name,
                         AttachLayout.Constraints cts)

Defines and adds a box to this layout. The added box is attached to the container's top and bottom edge with an offset of 0. Left and right attachements of the box are defined by the specified constraints.

Parameters:

name - a valid string representing the boxe's name, must not be null.

cts - the constraints to layout the box in the container, must not be null.

defineRow

public void defineRow(java.lang.String name,
                      AttachLayout.Constraints cts)

Defines and adds a box to this layout. The added box is attached to the container's left and right edge with an offset of 0. Top and bottom attachements of the box are defined by the specified constraints.

Parameters:

name - a valid string representing the boxe's name, must not be null.

cts - the constraints to layout the box in the container, must not be null.

checkSolvable

public void checkSolvable()

Checks if the current structure of constraints can be solved. Particularly looks for circular dependencies and missing references.

Throws:

java.lang.RuntimeException - when the structure cannot be solved. The message of the exception indicates the kind of problem.

getOppositeSide

public static int getOppositeSide(int side)

Returns the opposite side of the given side.

Parameters:

side - 0 for TOP, 1 for LEFT, 2 for BOTTOM or 3 for RIGHT.

isFrontSide

public static boolean isFrontSide(int side)

Returns true if the given side is LEFT or TOP side.

Parameters:

side - 0 for TOP, 1 for LEFT, 2 for BOTTOM or 3 for RIGHT.

getFrontSide

public static int getFrontSide(int side)

Returns the front side of the given side. When side is LEFT or RIGHT, LEFT is returned, when TOP or BOTTOM, TOP is returned.

Parameters:

side - 0 for TOP, 1 for LEFT, 2 for BOTTOM or 3 for RIGHT.

getBackSide

public static int getBackSide(int side)

Returns the back side of the given side. When side is LEFT or RIGHT, RIGHT is returned, when TOP or BOTTOM, BOTTOM is returned.

Parameters:

side - 0 for TOP, 1 for LEFT, 2 for BOTTOM or 3 for RIGHT.

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception