< prev index next >

src/java.desktop/share/classes/javax/swing/Spring.java

Print this page

        

*** 25,40 **** package javax.swing; import java.awt.Component; /** ! * An instance of the <code>Spring</code> class holds three properties that * characterize its behavior: the <em>minimum</em>, <em>preferred</em>, and * <em>maximum</em> values. Each of these properties may be involved in * defining its fourth, <em>value</em>, property based on a series of rules. * <p> ! * An instance of the <code>Spring</code> 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 --- 25,40 ---- package javax.swing; import java.awt.Component; /** ! * An instance of the {@code Spring} class holds three properties that * characterize its behavior: the <em>minimum</em>, <em>preferred</em>, and * <em>maximum</em> values. Each of these properties may be involved in * defining its fourth, <em>value</em>, property based on a series of rules. * <p> ! * An instance of the {@code 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
*** 42,95 **** * equal and opposite force to that which is created when it is at its * maximum value. The difference between the <em>preferred</em> and * <em>minimum</em> values, therefore, represents the ease with which the * spring can be compressed and the difference between its <em>maximum</em> * and <em>preferred</em> values, indicates the ease with which the ! * <code>Spring</code> can be extended. * See the {@link #sum} method for details. * * <p> ! * By defining simple arithmetic operations on <code>Spring</code>s, ! * the behavior of a collection of <code>Spring</code>s ! * can be reduced to that of an ordinary (non-compound) <code>Spring</code>. We define * the "+", "-", <em>max</em>, and <em>min</em> operators on ! * <code>Spring</code>s so that, in each case, the result is a <code>Spring</code> * whose characteristics bear a useful mathematical relationship to its constituent * springs. * * <p> ! * A <code>Spring</code> 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 ! * (<code>[a, b]</code> refers to the interval ! * from <code>a</code> ! * to <code>b</code>, ! * where <code>a &lt;= b</code>). * * <pre> * [a1, b1] + [a2, b2] = [a1 + a2, b1 + b2] * * -[a, b] = [-b, -a] * * max([a1, b1], [a2, b2]) = [max(a1, a2), max(b1, b2)] * </pre> * <p> * ! * If we denote <code>Spring</code>s as <code>[a, b, c]</code>, ! * where <code>a &lt;= b &lt;= c</code>, we can define the same ! * arithmetic operators on <code>Spring</code>s: * * <pre> * [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)] * </pre> * <p> ! * With both intervals and <code>Spring</code>s we can define "-" and <em>min</em> * in terms of negation: * * <pre> * X - Y = X + (-Y) * --- 42,95 ---- * equal and opposite force to that which is created when it is at its * maximum value. The difference between the <em>preferred</em> and * <em>minimum</em> values, therefore, represents the ease with which the * spring can be compressed and the difference between its <em>maximum</em> * and <em>preferred</em> values, indicates the ease with which the ! * {@code Spring} can be extended. * See the {@link #sum} method for details. * * <p> ! * By defining simple arithmetic operations on {@code Spring}s, ! * the behavior of a collection of {@code Spring}s ! * can be reduced to that of an ordinary (non-compound) {@code Spring}. We define * the "+", "-", <em>max</em>, and <em>min</em> operators on ! * {@code Spring}s so that, in each case, the result is a {@code Spring} * whose characteristics bear a useful mathematical relationship to its constituent * springs. * * <p> ! * A {@code 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 ! * ({@code [a, b]} refers to the interval ! * from {@code a} ! * to {@code b}, ! * where {@code a <= b}). * * <pre> * [a1, b1] + [a2, b2] = [a1 + a2, b1 + b2] * * -[a, b] = [-b, -a] * * max([a1, b1], [a2, b2]) = [max(a1, a2), max(b1, b2)] * </pre> * <p> * ! * If we denote {@code Spring}s as {@code [a, b, c]}, ! * where {@code a <= b <= c}, we can define the same ! * arithmetic operators on {@code Spring}s: * * <pre> * [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)] * </pre> * <p> ! * With both intervals and {@code Spring}s we can define "-" and <em>min</em> * in terms of negation: * * <pre> * X - Y = X + (-Y) *
*** 98,114 **** * <p> * 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 <code>Spring</code> 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 <em>lazy value</em> * in a functional language. * <p> ! * If you are implementing a <code>SpringLayout</code> you * can find further information and examples in * <a href="http://docs.oracle.com/javase/tutorial/uiswing/layout/spring.html">How to Use SpringLayout</a>, * a section in <em>The Java Tutorial.</em> * <p> --- 98,114 ---- * <p> * 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 {@code 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 <em>lazy value</em> * in a functional language. * <p> ! * If you are implementing a {@code SpringLayout} you * can find further information and examples in * <a href="http://docs.oracle.com/javase/tutorial/uiswing/layout/spring.html">How to Use SpringLayout</a>, * a section in <em>The Java Tutorial.</em> * <p>
*** 116,126 **** * Serialized objects of this class will not be compatible with * future Swing releases. The current serialization support is * appropriate for short term storage or RMI between applications running * the same version of Swing. As of 1.4, support for long term storage * of all JavaBeans&trade; ! * has been added to the <code>java.beans</code> package. * Please see {@link java.beans.XMLEncoder}. * * @see SpringLayout * @see SpringLayout.Constraints * --- 116,126 ---- * Serialized objects of this class will not be compatible with * future Swing releases. The current serialization support is * appropriate for short term storage or RMI between applications running * the same version of Swing. As of 1.4, support for long term storage * of all JavaBeans&trade; ! * has been added to the {@code java.beans} package. * Please see {@link java.beans.XMLEncoder}. * * @see SpringLayout * @see SpringLayout.Constraints *
*** 134,144 **** * An integer value signifying that a property value has not yet been calculated. */ public static final int UNSET = Integer.MIN_VALUE; /** ! * Used by factory methods to create a <code>Spring</code>. * * @see #constant(int) * @see #constant(int, int, int) * @see #max * @see #minus --- 134,144 ---- * An integer value signifying that a property value has not yet been calculated. */ public static final int UNSET = Integer.MIN_VALUE; /** ! * Used by factory methods to create a {@code Spring}. * * @see #constant(int) * @see #constant(int, int, int) * @see #max * @see #minus
*** 146,188 **** * @see SpringLayout.Constraints */ protected Spring() {} /** ! * Returns the <em>minimum</em> value of this <code>Spring</code>. * ! * @return the <code>minimumValue</code> property of this <code>Spring</code> */ public abstract int getMinimumValue(); /** ! * Returns the <em>preferred</em> value of this <code>Spring</code>. * ! * @return the <code>preferredValue</code> of this <code>Spring</code> */ public abstract int getPreferredValue(); /** ! * Returns the <em>maximum</em> value of this <code>Spring</code>. * ! * @return the <code>maximumValue</code> property of this <code>Spring</code> */ public abstract int getMaximumValue(); /** ! * Returns the current <em>value</em> of this <code>Spring</code>. * ! * @return the <code>value</code> property of this <code>Spring</code> * * @see #setValue */ public abstract int getValue(); /** ! * Sets the current <em>value</em> of this <code>Spring</code> to <code>value</code>. * ! * @param value the new setting of the <code>value</code> property * * @see #getValue */ public abstract void setValue(int value); --- 146,188 ---- * @see SpringLayout.Constraints */ protected Spring() {} /** ! * Returns the <em>minimum</em> value of this {@code Spring}. * ! * @return the {@code minimumValue} property of this {@code Spring} */ public abstract int getMinimumValue(); /** ! * Returns the <em>preferred</em> value of this {@code Spring}. * ! * @return the {@code preferredValue} of this {@code Spring} */ public abstract int getPreferredValue(); /** ! * Returns the <em>maximum</em> value of this {@code Spring}. * ! * @return the {@code maximumValue} property of this {@code Spring} */ public abstract int getMaximumValue(); /** ! * Returns the current <em>value</em> of this {@code Spring}. * ! * @return the {@code value} property of this {@code Spring} * * @see #setValue */ public abstract int getValue(); /** ! * Sets the current <em>value</em> of this {@code Spring} to {@code value}. * ! * @param value the new setting of the {@code value} property * * @see #getValue */ public abstract void setValue(int value);
*** 512,545 **** } } /** * Returns a strut -- a spring whose <em>minimum</em>, <em>preferred</em>, and ! * <em>maximum</em> values each have the value <code>pref</code>. * * @param pref the <em>minimum</em>, <em>preferred</em>, and * <em>maximum</em> values of the new spring * @return a spring whose <em>minimum</em>, <em>preferred</em>, and ! * <em>maximum</em> values each have the value <code>pref</code> * * @see Spring */ public static Spring constant(int pref) { return constant(pref, pref, pref); } /** * Returns a spring whose <em>minimum</em>, <em>preferred</em>, and ! * <em>maximum</em> values have the values: <code>min</code>, <code>pref</code>, ! * and <code>max</code> respectively. * * @param min the <em>minimum</em> value of the new spring * @param pref the <em>preferred</em> value of the new spring * @param max the <em>maximum</em> value of the new spring * @return a spring whose <em>minimum</em>, <em>preferred</em>, and ! * <em>maximum</em> values have the values: <code>min</code>, <code>pref</code>, ! * and <code>max</code> respectively * * @see Spring */ public static Spring constant(int min, int pref, int max) { return new StaticSpring(min, pref, max); --- 512,545 ---- } } /** * Returns a strut -- a spring whose <em>minimum</em>, <em>preferred</em>, and ! * <em>maximum</em> values each have the value {@code pref}. * * @param pref the <em>minimum</em>, <em>preferred</em>, and * <em>maximum</em> values of the new spring * @return a spring whose <em>minimum</em>, <em>preferred</em>, and ! * <em>maximum</em> values each have the value {@code pref} * * @see Spring */ public static Spring constant(int pref) { return constant(pref, pref, pref); } /** * Returns a spring whose <em>minimum</em>, <em>preferred</em>, and ! * <em>maximum</em> values have the values: {@code min}, {@code pref}, ! * and {@code max} respectively. * * @param min the <em>minimum</em> value of the new spring * @param pref the <em>preferred</em> value of the new spring * @param max the <em>maximum</em> value of the new spring * @return a spring whose <em>minimum</em>, <em>preferred</em>, and ! * <em>maximum</em> values have the values: {@code min}, {@code pref}, ! * and {@code max} respectively * * @see Spring */ public static Spring constant(int min, int pref, int max) { return new StaticSpring(min, pref, max);
*** 557,569 **** public static Spring minus(Spring s) { return new NegativeSpring(s); } /** ! * Returns <code>s1+s2</code>: a spring representing <code>s1</code> and <code>s2</code> ! * in series. In a sum, <code>s3</code>, of two springs, <code>s1</code> and <code>s2</code>, ! * the <em>strains</em> of <code>s1</code>, <code>s2</code>, and <code>s3</code> are maintained * at the same level (to within the precision implied by their integer <em>value</em>s). * The strain of a spring in compression is: * <pre> * value - pref * ------------ --- 557,569 ---- public static Spring minus(Spring s) { return new NegativeSpring(s); } /** ! * Returns {@code s1+s2}: a spring representing {@code s1} and {@code s2} ! * in series. In a sum, {@code s3}, of two springs, {@code s1} and {@code s2}, ! * the <em>strains</em> of {@code s1}, {@code s2}, and {@code s3} are maintained * at the same level (to within the precision implied by their integer <em>value</em>s). * The strain of a spring in compression is: * <pre> * value - pref * ------------
*** 573,593 **** * <pre> * value - pref * ------------ * max - pref * </pre> ! * When <code>setValue</code> is called on the sum spring, <code>s3</code>, the strain ! * in <code>s3</code> is calculated using one of the formulas above. Once the strain of ! * the sum is known, the <em>value</em>s of <code>s1</code> and <code>s2</code> 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 <em>value</em>s of <code>s1</code> and <code>s2</code> is exactly equal to ! * the <em>value</em> of <code>s3</code>. * * @param s1 a {@code Spring} object * @param s2 a {@code Spring} object ! * @return <code>s1+s2</code>: a spring representing <code>s1</code> and <code>s2</code> in series * * @see Spring */ public static Spring sum(Spring s1, Spring s2) { return new SumSpring(s1, s2); --- 573,593 ---- * <pre> * value - pref * ------------ * max - pref * </pre> ! * When {@code setValue} is called on the sum spring, {@code s3}, the strain ! * in {@code s3} is calculated using one of the formulas above. Once the strain of ! * the sum is known, the <em>value</em>s of {@code s1} and {@code 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 <em>value</em>s of {@code s1} and {@code s2} is exactly equal to ! * the <em>value</em> of {@code s3}. * * @param s1 a {@code Spring} object * @param s2 a {@code Spring} object ! * @return {@code s1+s2}: a spring representing {@code s1} and {@code s2} in series * * @see Spring */ public static Spring sum(Spring s1, Spring s2) { return new SumSpring(s1, s2);
*** 621,643 **** */ /** * Returns a spring whose <em>minimum</em>, <em>preferred</em>, <em>maximum</em> * and <em>value</em> properties are each multiples of the properties of the ! * argument spring, <code>s</code>. Minimum and maximum properties are ! * swapped when <code>factor</code> is negative (in accordance with the * rules of interval arithmetic). * <p> * When factor is, for example, 0.5f the result represents 'the mid-point' * of its input - an operation that is useful for centering components in * a container. * * @param s the spring to scale * @param factor amount to scale by. ! * @return a spring whose properties are those of the input spring <code>s</code> ! * multiplied by <code>factor</code> ! * @throws NullPointerException if <code>s</code> is null * @since 1.5 */ public static Spring scale(Spring s, float factor) { checkArg(s); return new ScaleSpring(s, factor); --- 621,643 ---- */ /** * Returns a spring whose <em>minimum</em>, <em>preferred</em>, <em>maximum</em> * and <em>value</em> properties are each multiples of the properties of the ! * argument spring, {@code s}. Minimum and maximum properties are ! * swapped when {@code factor} is negative (in accordance with the * rules of interval arithmetic). * <p> * When factor is, for example, 0.5f the result represents 'the mid-point' * of its input - an operation that is useful for centering components in * a container. * * @param s the spring to scale * @param factor amount to scale by. ! * @return a spring whose properties are those of the input spring {@code s} ! * multiplied by {@code factor} ! * @throws NullPointerException if {@code s} is null * @since 1.5 */ public static Spring scale(Spring s, float factor) { checkArg(s); return new ScaleSpring(s, factor);
*** 654,664 **** * component and track them as they change. * * @param c Component used for calculating size * @return a spring whose properties are defined by the horizontal component * of the component's size methods. ! * @throws NullPointerException if <code>c</code> is null * @since 1.5 */ public static Spring width(Component c) { checkArg(c); return new WidthSpring(c); --- 654,664 ---- * component and track them as they change. * * @param c Component used for calculating size * @return a spring whose properties are defined by the horizontal component * of the component's size methods. ! * @throws NullPointerException if {@code c} is null * @since 1.5 */ public static Spring width(Component c) { checkArg(c); return new WidthSpring(c);
*** 675,695 **** * component and track them as they change. * * @param c Component used for calculating size * @return a spring whose properties are defined by the vertical component * of the component's size methods. ! * @throws NullPointerException if <code>c</code> is null * @since 1.5 */ public static Spring height(Component c) { checkArg(c); return new HeightSpring(c); } /** ! * If <code>s</code> is null, this throws an NullPointerException. */ private static void checkArg(Object s) { if (s == null) { throw new NullPointerException("Argument must not be null"); } --- 675,695 ---- * component and track them as they change. * * @param c Component used for calculating size * @return a spring whose properties are defined by the vertical component * of the component's size methods. ! * @throws NullPointerException if {@code c} is null * @since 1.5 */ public static Spring height(Component c) { checkArg(c); return new HeightSpring(c); } /** ! * If {@code s} is null, this throws an NullPointerException. */ private static void checkArg(Object s) { if (s == null) { throw new NullPointerException("Argument must not be null"); }
< prev index next >