javax.swing
Class Spring

java.lang.Object
  extended byjavax.swing.Spring
Direct Known Subclasses:
Spring.AbstractSpring, Spring.NegativeSpring, SpringLayout.SpringProxy

public abstract class Spring
extends Object

An instance of the Spring class holds three properties that characterize its behavior: the minimum, preferred, and maximum values. Each of these properties may be involved in defining its fourth, value, property based on a series of rules.

An instance of the Spring class can be visualized as a mechanical spring that provides a corrective force as the spring is compressed or stretched away from its preferred value. This force is modelled as linear function of the distance from the preferred value, but with two different constants -- one for the compressional force and one for the tensional one. Those constants are specified by the minimum and maximum values of the spring such that a spring at its minimum value produces an equal and opposite force to that which is created when it is at its maximum value. The difference between the preferred and minimum values, therefore, represents the ease with which the spring can be compressed and the difference between its maximum and preferred values, indicates the ease with which the Spring can be extended. See the sum(javax.swing.Spring, javax.swing.Spring) method for details.

By defining simple arithmetic operations on Springs, the behavior of a collection of Springs can be reduced to that of an ordinary (non-compound) Spring. We define the "+", "-", max, and min operators on Springs so that, in each case, the result is a Spring whose characteristics bear a useful mathematical relationship to its constituent springs.

A Spring can be treated as a pair of intervals with a single common point: the preferred value. The following rules define some of the arithmetic operators that can be applied to intervals ([a, b] refers to the interval from a to b, where a <= b).

          [a1, b1] + [a2, b2] = [a1 + a2, b1 + b2]

                      -[a, b] = [-b, -a]

      max([a1, b1], [a2, b2]) = [max(a1, a2), max(b1, b2)]
  

If we denote Springs as [a, b, c], where a <= b <= c, we can define the same arithmetic operators on Springs:

          [a1, b1, c1] + [a2, b2, c2] = [a1 + a2, b1 + b2, c1 + c2]

                           -[a, b, c] = [-c, -b, -a]

      max([a1, b1, c1], [a2, b2, c2]) = [max(a1, a2), max(b1, b2), max(c1, c2)]
  

With both intervals and Springs we can define "-" and min in terms of negation:

      X - Y = X + (-Y)

      min(X, Y) = -max(-X, -Y)
  

For the static methods in this class that embody the arithmetic operators, we do not actually perform the operation in question as that would snapshot the values of the properties of the method's arguments at the time the static method is called. Instead, the static methods create a new Spring instance containing references to the method's arguments so that the characteristics of the new spring track the potentially changing characteristics of the springs from which it was made. This is a little like the idea of a lazy value in a functional language.

Since:
1.4
Author:
Philip Milne
See Also:
SpringLayout, SpringLayout.Constraints

Nested Class Summary
(package private) static class Spring.AbstractSpring
           
(package private) static class Spring.CompoundSpring
           
private static class Spring.MaxSpring
           
private static class Spring.NegativeSpring
           
private static class Spring.StaticSpring
           
private static class Spring.SumSpring
           
 
Field Summary
static int UNSET
          An integer value signifying that a property value has not yet been calculated.
 
Constructor Summary
protected Spring()
          Used by factory methods to create a Spring.
 
Method Summary
static Spring constant(int pref)
          Returns a strut -- a spring whose minimum, preferred, and maximum values each have the value pref.
static Spring constant(int min, int pref, int max)
          Returns a spring whose minimum, preferred, and maximum values have the values: min, pref, and max respectively.
(package private) static Spring difference(Spring s1, Spring s2)
           
abstract  int getMaximumValue()
          Returns the maximum value of this Spring.
abstract  int getMinimumValue()
          Returns the minimum value of this Spring.
abstract  int getPreferredValue()
          Returns the preferred value of this Spring.
(package private)  double getStrain()
           
abstract  int getValue()
          Returns the current value of this Spring.
(package private)  boolean isCyclic(SpringLayout l)
           
static Spring max(Spring s1, Spring s2)
          Returns max(s1, s2): a spring whose value is always greater than (or equal to) the values of both s1 and s2.
static Spring minus(Spring s)
          Returns -s: a spring running in the opposite direction to s.
private  double range(boolean contract)
           
(package private)  void setStrain(double strain)
           
abstract  void setValue(int value)
          Sets the current value of this Spring to value.
static Spring sum(Spring s1, Spring s2)
          Returns s1+s2: a spring representing s1 and s2 in series.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UNSET

public static final int UNSET
An integer value signifying that a property value has not yet been calculated.

See Also:
Constant Field Values
Constructor Detail

Spring

protected Spring()
Used by factory methods to create a Spring.

See Also:
constant(int), constant(int, int, int), max(javax.swing.Spring, javax.swing.Spring), minus(javax.swing.Spring), sum(javax.swing.Spring, javax.swing.Spring), SpringLayout.Constraints
Method Detail

getMinimumValue

public abstract int getMinimumValue()
Returns the minimum value of this Spring.

Returns:
the minimumValue property of this Spring

getPreferredValue

public abstract int getPreferredValue()
Returns the preferred value of this Spring.

Returns:
the preferredValue of this Spring

getMaximumValue

public abstract int getMaximumValue()
Returns the maximum value of this Spring.

Returns:
the maximumValue property of this Spring

getValue

public abstract int getValue()
Returns the current value of this Spring.

Returns:
the value property of this Spring
See Also:
setValue(int)

setValue

public abstract void setValue(int value)
Sets the current value of this Spring to value.

Parameters:
value - the new setting of the value property
See Also:
getValue()

range

private double range(boolean contract)

getStrain

double getStrain()

setStrain

void setStrain(double strain)

isCyclic

boolean isCyclic(SpringLayout l)

constant

public static Spring constant(int pref)
Returns a strut -- a spring whose minimum, preferred, and maximum values each have the value pref.

Parameters:
pref - the minimum, preferred, and maximum values of the new spring
Returns:
a spring whose minimum, preferred, and maximum values each have the value pref
See Also:
Spring.AbstractSpring

constant

public static Spring constant(int min,
                              int pref,
                              int max)
Returns a spring whose minimum, preferred, and maximum values have the values: min, pref, and max respectively.

Parameters:
min - the minimum value of the new spring
pref - the preferred value of the new spring
max - the maximum value of the new spring
Returns:
a spring whose minimum, preferred, and maximum values have the values: min, pref, and max respectively
See Also:
Spring.AbstractSpring

minus

public static Spring minus(Spring s)
Returns -s: a spring running in the opposite direction to s.

Returns:
-s: a spring running in the opposite direction to s
See Also:
Spring.AbstractSpring

sum

public static Spring sum(Spring s1,
                         Spring s2)
Returns s1+s2: a spring representing s1 and s2 in series. In a sum, s3, of two springs, s1 and s2, the strains of s1, s2, and s3 are maintained at the same level (to within the precision implied by their integer values). The strain of a spring in compression is:
         value - pref
         ------------
          pref - min
 
and the strain of a spring in tension is:
         value - pref
         ------------
          max - pref
 
When setValue is called on the sum spring, s3, the strain in s3 is calculated using one of the formulas above. Once the strain of the sum is known, the values of s1 and s2 are then set so that they are have a strain equal to that of the sum. The formulas are evaluated so as to take rounding errors into account and ensure that the sum of the values of s1 and s2 is exactly equal to the value of s3.

Returns:
s1+s2: a spring representing s1 and s2 in series
See Also:
Spring.AbstractSpring

max

public static Spring max(Spring s1,
                         Spring s2)
Returns max(s1, s2): a spring whose value is always greater than (or equal to) the values of both s1 and s2.

Returns:
max(s1, s2): a spring whose value is always greater than (or equal to) the values of both s1 and s2
See Also:
Spring.AbstractSpring

difference

static Spring difference(Spring s1,
                         Spring s2)