1 /*
   2  * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  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://java.sun.com/docs/books/tutorial/uiswing/overview/anatomy.html">The Anatomy of a Swing-Based Program</a>
  75  * in <em>The Java Tutorial.</em>
  76  *
  77  * @author Hans Muller
  78  * @see DefaultBoundedRangeModel
  79  */
  80 public interface BoundedRangeModel
  81 {
  82     /**
  83      * Returns the minimum acceptable value.
  84      *
  85      * @return the value of the minimum property
  86      * @see #setMinimum
  87      */
  88     int getMinimum();
  89 
  90 
  91     /**
  92      * Sets the model's minimum to <I>newMinimum</I>.   The
  93      * other three properties may be changed as well, to ensure
  94      * that:
  95      * <pre>
  96      * minimum &lt;= value &lt;= value+extent &lt;= maximum
  97      * </pre>
  98      * <p>
  99      * Notifies any listeners if the model changes.
 100      *
 101      * @param newMinimum the model's new minimum
 102      * @see #getMinimum
 103      * @see #addChangeListener
 104      */
 105     void setMinimum(int newMinimum);
 106 
 107 
 108     /**
 109      * Returns the model's maximum.  Note that the upper
 110      * limit on the model's value is (maximum - extent).
 111      *
 112      * @return the value of the maximum property.
 113      * @see #setMaximum
 114      * @see #setExtent
 115      */
 116     int getMaximum();
 117 
 118 
 119     /**
 120      * Sets the model's maximum to <I>newMaximum</I>. The other
 121      * three properties may be changed as well, to ensure that
 122      * <pre>
 123      * minimum &lt;= value &lt;= value+extent &lt;= maximum
 124      * </pre>
 125      * <p>
 126      * Notifies any listeners if the model changes.
 127      *
 128      * @param newMaximum the model's new maximum
 129      * @see #getMaximum
 130      * @see #addChangeListener
 131      */
 132     void setMaximum(int newMaximum);
 133 
 134 
 135     /**
 136      * Returns the model's current value.  Note that the upper
 137      * limit on the model's value is <code>maximum - extent</code>
 138      * and the lower limit is <code>minimum</code>.
 139      *
 140      * @return  the model's value
 141      * @see     #setValue
 142      */
 143     int getValue();
 144 
 145 
 146     /**
 147      * Sets the model's current value to <code>newValue</code> if <code>newValue</code>
 148      * satisfies the model's constraints. Those constraints are:
 149      * <pre>
 150      * minimum &lt;= value &lt;= value+extent &lt;= maximum
 151      * </pre>
 152      * Otherwise, if <code>newValue</code> is less than <code>minimum</code>
 153      * it's set to <code>minimum</code>, if its greater than
 154      * <code>maximum</code> then it's set to <code>maximum</code>, and
 155      * if it's greater than <code>value+extent</code> then it's set to
 156      * <code>value+extent</code>.
 157      * <p>
 158      * When a BoundedRange model is used with a scrollbar the value
 159      * specifies the origin of the scrollbar knob (aka the "thumb" or
 160      * "elevator").  The value usually represents the origin of the
 161      * visible part of the object being scrolled.
 162      * <p>
 163      * Notifies any listeners if the model changes.
 164      *
 165      * @param newValue the model's new value
 166      * @see #getValue
 167      */
 168     void setValue(int newValue);
 169 
 170 
 171     /**
 172      * This attribute indicates that any upcoming changes to the value
 173      * of the model should be considered a single event. This attribute
 174      * will be set to true at the start of a series of changes to the value,
 175      * and will be set to false when the value has finished changing.  Normally
 176      * this allows a listener to only take action when the final value change in
 177      * committed, instead of having to do updates for all intermediate values.
 178      * <p>
 179      * Sliders and scrollbars use this property when a drag is underway.
 180      *
 181      * @param b true if the upcoming changes to the value property are part of a series
 182      */
 183     void setValueIsAdjusting(boolean b);
 184 
 185 
 186     /**
 187      * Returns true if the current changes to the value property are part
 188      * of a series of changes.
 189      *
 190      * @return the valueIsAdjustingProperty.
 191      * @see #setValueIsAdjusting
 192      */
 193     boolean getValueIsAdjusting();
 194 
 195 
 196     /**
 197      * Returns the model's extent, the length of the inner range that
 198      * begins at the model's value.
 199      *
 200      * @return  the value of the model's extent property
 201      * @see     #setExtent
 202      * @see     #setValue
 203      */
 204     int getExtent();
 205 
 206 
 207     /**
 208      * Sets the model's extent.  The <I>newExtent</I> is forced to
 209      * be greater than or equal to zero and less than or equal to
 210      * maximum - value.
 211      * <p>
 212      * When a BoundedRange model is used with a scrollbar the extent
 213      * defines the length of the scrollbar knob (aka the "thumb" or
 214      * "elevator").  The extent usually represents how much of the
 215      * object being scrolled is visible. When used with a slider,
 216      * the extent determines how much the value can "jump", for
 217      * example when the user presses PgUp or PgDn.
 218      * <p>
 219      * Notifies any listeners if the model changes.
 220      *
 221      * @param  newExtent the model's new extent
 222      * @see #getExtent
 223      * @see #setValue
 224      */
 225     void setExtent(int newExtent);
 226 
 227 
 228 
 229     /**
 230      * This method sets all of the model's data with a single method call.
 231      * The method results in a single change event being generated. This is
 232      * convenient when you need to adjust all the model data simultaneously and
 233      * do not want individual change events to occur.
 234      *
 235      * @param value  an int giving the current value
 236      * @param extent an int giving the amount by which the value can "jump"
 237      * @param min    an int giving the minimum value
 238      * @param max    an int giving the maximum value
 239      * @param adjusting a boolean, true if a series of changes are in
 240      *                    progress
 241      *
 242      * @see #setValue
 243      * @see #setExtent
 244      * @see #setMinimum
 245      * @see #setMaximum
 246      * @see #setValueIsAdjusting
 247      */
 248     void setRangeProperties(int value, int extent, int min, int max, boolean adjusting);
 249 
 250 
 251     /**
 252      * Adds a ChangeListener to the model's listener list.
 253      *
 254      * @param x the ChangeListener to add
 255      * @see #removeChangeListener
 256      */
 257     void addChangeListener(ChangeListener x);
 258 
 259 
 260     /**
 261      * Removes a ChangeListener from the model's listener list.
 262      *
 263      * @param x the ChangeListener to remove
 264      * @see #addChangeListener
 265      */
 266     void removeChangeListener(ChangeListener x);
 267 
 268 }