< prev index next >

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

Print this page




  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.swing;
  27 
  28 import javax.swing.event.*;
  29 
  30 
  31 /**
  32  * Defines the data model used by components like <code>Slider</code>s
  33  * and <code>ProgressBar</code>s.
  34  * Defines four interrelated integer properties: minimum, maximum, extent
  35  * and value.  These four integers define two nested ranges like this:
  36  * <pre>
  37  * minimum &lt;= value &lt;= value+extent &lt;= maximum
  38  * </pre>
  39  * The outer range is <code>minimum,maximum</code> and the inner
  40  * range is <code>value,value+extent</code>.  The inner range
  41  * must lie within the outer one, i.e. <code>value</code> must be
  42  * less than or equal to <code>maximum</code> and <code>value+extent</code>
  43  * must greater than or equal to <code>minimum</code>, and <code>maximum</code>
  44  * must be greater than or equal to <code>minimum</code>.
  45  * There are a few features of this model that one might find a little
  46  * surprising.  These quirks exist for the convenience of the
  47  * Swing BoundedRangeModel clients, such as <code>Slider</code> and
  48  * <code>ScrollBar</code>.
  49  * <ul>
  50  * <li>
  51  *   The minimum and maximum set methods "correct" the other
  52  *   three properties to accommodate their new value argument.  For
  53  *   example setting the model's minimum may change its maximum, value,
  54  *   and extent properties (in that order), to maintain the constraints
  55  *   specified above.
  56  *
  57  * <li>
  58  *   The value and extent set methods "correct" their argument to
  59  *   fit within the limits defined by the other three properties.
  60  *   For example if <code>value == maximum</code>, <code>setExtent(10)</code>
  61  *   would change the extent (back) to zero.
  62  *
  63  * <li>
  64  *   The four BoundedRangeModel values are defined as Java Beans properties
  65  *   however Swing ChangeEvents are used to notify clients of changes rather
  66  *   than PropertyChangeEvents. This was done to keep the overhead of monitoring
  67  *   a BoundedRangeModel low. Changes are often reported at MouseDragged rates.
  68  * </ul>
  69  *
  70  * <p>
  71  *
  72  * For an example of specifying custom bounded range models used by sliders,
  73  * see <a
  74  href="http://www.oracle.com/technetwork/java/architecture-142923.html#separable">Separable model architecture</a>
  75  * in <em>A Swing Architecture Overview.</em>
  76  *
  77  * @author Hans Muller
  78  * @see DefaultBoundedRangeModel
  79  * @since 1.2
  80  */


 118 
 119 
 120     /**
 121      * Sets the model's maximum to <I>newMaximum</I>. The other
 122      * three properties may be changed as well, to ensure that
 123      * <pre>
 124      * minimum &lt;= value &lt;= value+extent &lt;= maximum
 125      * </pre>
 126      * <p>
 127      * Notifies any listeners if the model changes.
 128      *
 129      * @param newMaximum the model's new maximum
 130      * @see #getMaximum
 131      * @see #addChangeListener
 132      */
 133     void setMaximum(int newMaximum);
 134 
 135 
 136     /**
 137      * Returns the model's current value.  Note that the upper
 138      * limit on the model's value is <code>maximum - extent</code>
 139      * and the lower limit is <code>minimum</code>.
 140      *
 141      * @return  the model's value
 142      * @see     #setValue
 143      */
 144     int getValue();
 145 
 146 
 147     /**
 148      * Sets the model's current value to <code>newValue</code> if <code>newValue</code>
 149      * satisfies the model's constraints. Those constraints are:
 150      * <pre>
 151      * minimum &lt;= value &lt;= value+extent &lt;= maximum
 152      * </pre>
 153      * Otherwise, if <code>newValue</code> is less than <code>minimum</code>
 154      * it's set to <code>minimum</code>, if its greater than
 155      * <code>maximum</code> then it's set to <code>maximum</code>, and
 156      * if it's greater than <code>value+extent</code> then it's set to
 157      * <code>value+extent</code>.
 158      * <p>
 159      * When a BoundedRange model is used with a scrollbar the value
 160      * specifies the origin of the scrollbar knob (aka the "thumb" or
 161      * "elevator").  The value usually represents the origin of the
 162      * visible part of the object being scrolled.
 163      * <p>
 164      * Notifies any listeners if the model changes.
 165      *
 166      * @param newValue the model's new value
 167      * @see #getValue
 168      */
 169     void setValue(int newValue);
 170 
 171 
 172     /**
 173      * This attribute indicates that any upcoming changes to the value
 174      * of the model should be considered a single event. This attribute
 175      * will be set to true at the start of a series of changes to the value,
 176      * and will be set to false when the value has finished changing.  Normally
 177      * this allows a listener to only take action when the final value change in




  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.swing;
  27 
  28 import javax.swing.event.*;
  29 
  30 
  31 /**
  32  * Defines the data model used by components like {@code Slider}s
  33  * and {@code ProgressBar}s.
  34  * Defines four interrelated integer properties: minimum, maximum, extent
  35  * and value.  These four integers define two nested ranges like this:
  36  * <pre>
  37  * minimum &lt;= value &lt;= value+extent &lt;= maximum
  38  * </pre>
  39  * The outer range is {@code minimum,maximum} and the inner
  40  * range is {@code value,value+extent}.  The inner range
  41  * must lie within the outer one, i.e. {@code value} must be
  42  * less than or equal to {@code maximum} and {@code value+extent}
  43  * must greater than or equal to {@code minimum}, and {@code maximum}
  44  * must be greater than or equal to {@code minimum}.
  45  * There are a few features of this model that one might find a little
  46  * surprising.  These quirks exist for the convenience of the
  47  * Swing BoundedRangeModel clients, such as {@code Slider} and
  48  * {@code ScrollBar}.
  49  * <ul>
  50  * <li>
  51  *   The minimum and maximum set methods "correct" the other
  52  *   three properties to accommodate their new value argument.  For
  53  *   example setting the model's minimum may change its maximum, value,
  54  *   and extent properties (in that order), to maintain the constraints
  55  *   specified above.
  56  *
  57  * <li>
  58  *   The value and extent set methods "correct" their argument to
  59  *   fit within the limits defined by the other three properties.
  60  *   For example if {@code value == maximum}, {@code setExtent(10)}
  61  *   would change the extent (back) to zero.
  62  *
  63  * <li>
  64  *   The four BoundedRangeModel values are defined as Java Beans properties
  65  *   however Swing ChangeEvents are used to notify clients of changes rather
  66  *   than PropertyChangeEvents. This was done to keep the overhead of monitoring
  67  *   a BoundedRangeModel low. Changes are often reported at MouseDragged rates.
  68  * </ul>
  69  *
  70  * <p>
  71  *
  72  * For an example of specifying custom bounded range models used by sliders,
  73  * see <a
  74  href="http://www.oracle.com/technetwork/java/architecture-142923.html#separable">Separable model architecture</a>
  75  * in <em>A Swing Architecture Overview.</em>
  76  *
  77  * @author Hans Muller
  78  * @see DefaultBoundedRangeModel
  79  * @since 1.2
  80  */


 118 
 119 
 120     /**
 121      * Sets the model's maximum to <I>newMaximum</I>. The other
 122      * three properties may be changed as well, to ensure that
 123      * <pre>
 124      * minimum &lt;= value &lt;= value+extent &lt;= maximum
 125      * </pre>
 126      * <p>
 127      * Notifies any listeners if the model changes.
 128      *
 129      * @param newMaximum the model's new maximum
 130      * @see #getMaximum
 131      * @see #addChangeListener
 132      */
 133     void setMaximum(int newMaximum);
 134 
 135 
 136     /**
 137      * Returns the model's current value.  Note that the upper
 138      * limit on the model's value is {@code maximum - extent}
 139      * and the lower limit is {@code minimum}.
 140      *
 141      * @return  the model's value
 142      * @see     #setValue
 143      */
 144     int getValue();
 145 
 146 
 147     /**
 148      * Sets the model's current value to {@code newValue} if {@code newValue}
 149      * satisfies the model's constraints. Those constraints are:
 150      * <pre>
 151      * minimum &lt;= value &lt;= value+extent &lt;= maximum
 152      * </pre>
 153      * Otherwise, if {@code newValue} is less than {@code minimum}
 154      * it's set to {@code minimum}, if its greater than
 155      * {@code maximum} then it's set to {@code maximum}, and
 156      * if it's greater than {@code value+extent} then it's set to
 157      * {@code value+extent}.
 158      * <p>
 159      * When a BoundedRange model is used with a scrollbar the value
 160      * specifies the origin of the scrollbar knob (aka the "thumb" or
 161      * "elevator").  The value usually represents the origin of the
 162      * visible part of the object being scrolled.
 163      * <p>
 164      * Notifies any listeners if the model changes.
 165      *
 166      * @param newValue the model's new value
 167      * @see #getValue
 168      */
 169     void setValue(int newValue);
 170 
 171 
 172     /**
 173      * This attribute indicates that any upcoming changes to the value
 174      * of the model should be considered a single event. This attribute
 175      * will be set to true at the start of a series of changes to the value,
 176      * and will be set to false when the value has finished changing.  Normally
 177      * this allows a listener to only take action when the final value change in


< prev index next >