javax.swing
Class SpringLayout

java.lang.Object
  javax.swing.SpringLayout

All Implemented Interfaces:

LayoutManager, LayoutManager2

public class SpringLayout

extends Object

implements LayoutManager2

A SpringLayout lays out the children of its associated container according to a set of constraints. See How to Use SpringLayout in The Java Tutorial for examples of using SpringLayout.

Each constraint, represented by a Spring object, controls the vertical or horizontal distance between two component edges. The edges can belong to any child of the container, or to the container itself. For example, the allowable width of a component can be expressed using a constraint that controls the distance between the west (left) and east (right) edges of the component. The allowable y coordinates for a component can be expressed by constraining the distance between the north (top) edge of the component and the north edge of its container.

Every child of a SpringLayout-controlled container, as well as the container itself, has exactly one set of constraints associated with it. These constraints are represented by a SpringLayout.Constraints object. By default, SpringLayout creates constraints that make their associated component have the minimum, preferred, and maximum sizes returned by the component's Component.getMinimumSize(), Component.getPreferredSize(), and Component.getMaximumSize() methods. The x and y positions are initially not constrained, so that until you constrain them the Component will be positioned at 0,0 relative to the Insets of the parent Container.

You can change a component's constraints in several ways. You can use one of the putConstraint methods to establish a spring linking the edges of two components within the same container. Or you can get the appropriate SpringLayout.Constraints object using getConstraints and then modify one or more of its springs. Or you can get the spring for a particular edge of a component using getConstraint, and modify it. You can also associate your own SpringLayout.Constraints object with a component by specifying the constraints object when you add the component to its container (using Container.add(Component, Object)).

The Spring object representing each constraint has a minimum, preferred, maximum, and current value. The current value of the spring is somewhere between the minimum and maximum values, according to the formula given in the Spring.sum(javax.swing.Spring, javax.swing.Spring) method description. When the minimum, preferred, and maximum values are the same, the current value is always equal to them; this inflexible spring is called a strut. You can create struts using the factory method Spring.constant(int). The Spring class also provides factory methods for creating other kinds of springs, including springs that depend on other springs.

In a SpringLayout, the position of each edge is dependent on the position of just one other edge. If a constraint is subsequently added to create a new binding for an edge, the previous binding is discarded and the edge remains dependent on a single edge. Springs should only be attached between edges of the container and its immediate children; the behavior of the SpringLayout when presented with constraints linking the edges of components from different containers (either internal or external) is undefined.

SpringLayout vs. Other Layout Managers

Note: Unlike many layout managers, SpringLayout doesn't automatically set the location of the components it manages. If you hand-code a GUI that uses SpringLayout, remember to initialize component locations by constraining the west/east and north/south locations.

Depending on the constraints you use, you may also need to set the size of the container explicitly.

Despite the simplicity of SpringLayout, it can emulate the behavior of most other layout managers. For some features, such as the line breaking provided by FlowLayout, you'll need to create a special-purpose subclass of the Spring class.

SpringLayout also provides a way to solve many of the difficult layout problems that cannot be solved by nesting combinations of Boxes. That said, SpringLayout honors the LayoutManager2 contract correctly and so can be nested with other layout managers -- a technique that can be preferable to creating the constraints implied by the other layout managers.

The asymptotic complexity of the layout operation of a SpringLayout is linear in the number of constraints (and/or components).

Since:

1.4

Author:

Philip Milne, Joe Winchester

See Also:

SpringLayout.WidthSpring, SpringLayout.Constraints

Nested Class Summary

static class	SpringLayout.Constraints A Constraints object holds the constraints that govern the way a component's size and position change in a container controlled by a SpringLayout.
private static class	SpringLayout.HeightSpring
private static class	SpringLayout.SpringProxy
private static class	SpringLayout.WidthSpring

Field Summary

private Set	acyclicSprings
private Map	componentConstraints
private Spring	cyclicReference
private Set	cyclicSprings
static String	EAST Specifies the right edge of a component's bounding rectangle.
static String	NORTH Specifies the top edge of a component's bounding rectangle.
static String	SOUTH Specifies the bottom edge of a component's bounding rectangle.
static String	WEST Specifies the left edge of a component's bounding rectangle.

Constructor Summary

SpringLayout()
Constructs a new SpringLayout.

Method Summary

private Spring	abandonCycles(Spring s)
private static Dimension	addInsets(int width, int height, Container p)
void	addLayoutComponent(Component component, Object constraints) If constraints is an instance of SpringLayout.Constraints, associates the constraints with the specified component.
void	addLayoutComponent(String name, Component c) Has no effect, since this layout manager does not use a per-component string.
private SpringLayout.Constraints	applyDefaults(Component c, SpringLayout.Constraints constraints)
Spring	getConstraint(String edgeName, Component c) Returns the spring controlling the distance between the specified edge of the component and the top or left edge of its parent.
SpringLayout.Constraints	getConstraints(Component c) Returns the constraints for the specified component.
float	getLayoutAlignmentX(Container p) Returns 0.5f (centered).
float	getLayoutAlignmentY(Container p) Returns 0.5f (centered).
void	invalidateLayout(Container p) Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
(package private) boolean	isCyclic(Spring s)
void	layoutContainer(Container parent) Lays out the specified container.
Dimension	maximumLayoutSize(Container parent) Calculates the maximum size dimensions for the specified container, given the components it contains.
Dimension	minimumLayoutSize(Container parent) Calculates the minimum size dimensions for the specified container, given the components it contains.
Dimension	preferredLayoutSize(Container parent) Calculates the preferred size dimensions for the specified container, given the components it contains.
void	putConstraint(String e1, Component c1, int pad, String e2, Component c2) Links edge e1 of component c1 to edge e2 of component c2, with a fixed distance between the edges.
private void	putConstraint(String e, Component c, Spring s)
void	putConstraint(String e1, Component c1, Spring s, String e2, Component c2) Links edge e1 of component c1 to edge e2 of component c2.
private void	putConstraints(Component component, SpringLayout.Constraints constraints)
void	removeLayoutComponent(Component c) Removes the constraints associated with the specified component.
private void	resetCyclicStatuses()
private void	setParent(Container p)

Methods inherited from class java.lang.Object

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

Field Detail

componentConstraints

private Map componentConstraints

cyclicReference

private Spring cyclicReference

cyclicSprings

private Set cyclicSprings

acyclicSprings

private Set acyclicSprings

NORTH

public static final String NORTH

Specifies the top edge of a component's bounding rectangle.

See Also:

Constant Field Values

SOUTH

public static final String SOUTH

Specifies the bottom edge of a component's bounding rectangle.

See Also:

Constant Field Values

EAST

public static final String EAST

Specifies the right edge of a component's bounding rectangle.

See Also:

Constant Field Values

WEST

public static final String WEST

Specifies the left edge of a component's bounding rectangle.

See Also:

Constant Field Values

Constructor Detail

SpringLayout

public SpringLayout()

Constructs a new SpringLayout.

Method Detail

resetCyclicStatuses

private void resetCyclicStatuses()

setParent

private void setParent(Container p)

isCyclic

boolean isCyclic(Spring s)

abandonCycles

private Spring abandonCycles(Spring s)

addLayoutComponent

public void addLayoutComponent(String name,
                               Component c)

Has no effect, since this layout manager does not use a per-component string.

Specified by:

addLayoutComponent in interface LayoutManager

Parameters:

name - the string to be associated with the component

c - the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component c)

Removes the constraints associated with the specified component.

Specified by:

removeLayoutComponent in interface LayoutManager

Parameters:

c - the component being removed from the container

addInsets

private static Dimension addInsets(int width,
                                   int height,
                                   Container p)

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)

Description copied from interface: LayoutManager

Calculates the minimum size dimensions for the specified container, given the components it contains.

Specified by:

minimumLayoutSize in interface LayoutManager

Parameters:

parent - the component to be laid out

See Also:

LayoutManager.preferredLayoutSize(java.awt.Container)

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)

Description copied from interface: LayoutManager

Calculates the preferred size dimensions for the specified container, given the components it contains.

Specified by:

preferredLayoutSize in interface LayoutManager

Parameters:

parent - the container to be laid out

See Also:

LayoutManager.minimumLayoutSize(java.awt.Container)

maximumLayoutSize

public Dimension maximumLayoutSize(Container parent)

Description copied from interface: LayoutManager2

Calculates the maximum size dimensions for the specified container, given the components it contains.

Specified by:

maximumLayoutSize in interface LayoutManager2

See Also:

Component.getMaximumSize(), LayoutManager

addLayoutComponent

public void addLayoutComponent(Component component,
                               Object constraints)

If constraints is an instance of SpringLayout.Constraints, associates the constraints with the specified component.

Specified by:

addLayoutComponent in interface LayoutManager2

Parameters:

component - the component being added

constraints - the component's constraints

See Also:

SpringLayout.Constraints

getLayoutAlignmentX

public float getLayoutAlignmentX(Container p)

Returns 0.5f (centered).

Specified by:

getLayoutAlignmentX in interface LayoutManager2

getLayoutAlignmentY

public float getLayoutAlignmentY(Container p)

Returns 0.5f (centered).

Specified by:

getLayoutAlignmentY in interface LayoutManager2

invalidateLayout

public void invalidateLayout(Container p)

Description copied from interface: LayoutManager2

Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.

Specified by:

invalidateLayout in interface LayoutManager2

putConstraint

public void putConstraint(String e1,
                          Component c1,
                          int pad,
                          String e2,
                          Component c2)

Links edge e1 of component c1 to edge e2 of component c2, with a fixed distance between the edges. This constraint will cause the assignment

     value(e1, c1) = value(e2, c2) + pad

to take place during all subsequent layout operations.

Parameters:

e1 - the edge of the dependent

c1 - the component of the dependent

pad - the fixed distance between dependent and anchor

e2 - the edge of the anchor

c2 - the component of the anchor

See Also:

putConstraint(String, Component, Spring, String, Component)

putConstraint

public void putConstraint(String e1,
                          Component c1,
                          Spring s,
                          String e2,
                          Component c2)

Links edge e1 of component c1 to edge e2 of component c2. As edge (e2, c2) changes value, edge (e1, c1) will be calculated by taking the (spring) sum of (e2, c2) and s. Each edge must have one of the following values: SpringLayout.NORTH, SpringLayout.SOUTH, SpringLayout.EAST, SpringLayout.WEST.

Parameters:

e1 - the edge of the dependent

c1 - the component of the dependent

s - the spring linking dependent and anchor

e2 - the edge of the anchor

c2 - the component of the anchor

See Also:

putConstraint(String, Component, int, String, Component), NORTH, SOUTH, EAST, WEST

putConstraint

private void putConstraint(String e,
                           Component c,
                           Spring s)

applyDefaults

private SpringLayout.Constraints applyDefaults(Component c,
                                               SpringLayout.Constraints constraints)

putConstraints

private void putConstraints(Component component,
                            SpringLayout.Constraints constraints)

getConstraints

public SpringLayout.Constraints getConstraints(Component c)

Returns the constraints for the specified component. Note that, unlike the GridBagLayout getConstraints method, this method does not clone constraints. If no constraints have been associated with this component, this method returns a default constraints object positioned at 0,0 relative to the parent's Insets and its width/height constrained to the minimum, maximum, and preferred sizes of the component. The size characteristics are not frozen at the time this method is called; instead this method returns a constraints object whose characteristics track the characteristics of the component as they change.

Parameters:

c - the component whose constraints will be returned

Returns:

the constraints for the specified component

getConstraint

public Spring getConstraint(String edgeName,
                            Component c)

Returns the spring controlling the distance between the specified edge of the component and the top or left edge of its parent. This method, instead of returning the current binding for the edge, returns a proxy that tracks the characteristics of the edge even if the edge is subsequently rebound. Proxies are intended to be used in builder envonments where it is useful to allow the user to define the constraints for a layout in any order. Proxies do, however, provide the means to create cyclic dependencies amongst the constraints of a layout. Such cycles are detected internally by SpringLayout so that the layout operation always terminates.

Parameters:

edgeName - must be SpringLayout.NORTH, SpringLayout.SOUTH, SpringLayout.EAST, or SpringLayout.WEST

c - the component whose edge spring is desired

Returns:

a proxy for the spring controlling the distance between the specified edge and the top or left edge of its parent

See Also:

NORTH, SOUTH, EAST, WEST

layoutContainer

public void layoutContainer(Container parent)

Description copied from interface: LayoutManager

Lays out the specified container.

Specified by:

layoutContainer in interface LayoutManager

Parameters:

parent - the container to be laid out