Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.swing
Class Spring

    java.lang.Object
      |
      +--javax.swing.Spring

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 `Spring`s, the behavior of a collection of `Spring`s can be reduced to that of an ordinary (non-compound) `Spring`. We define the "+", "-", max, and min operators on `Spring`s 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 `Spring`s as `[a, b, c]`, where `a <= b <= c`, we can define the same arithmetic operators on `Spring`s:

              [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 `Spring`s 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
See Also:
  `SpringLayout`, `SpringLayout.Constraints`

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.
`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`.
`abstract int` | `getValue()` Returns the current value of this `Spring`.
`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`.
`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()`

### 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`

### 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`

### 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`

### 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`

### 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.