/*

 * Copyright 1997-2006 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.swing;

import javax.swing.event.*;

/**

 * Defines the data model used by components like <code>Slider</code>s

 * and <code>ProgressBar</code>s.

 * Defines four interrelated integer properties: minimum, maximum, extent

 * and value.  These four integers define two nested ranges like this:

 * <pre>

 * minimum <= value <= value+extent <= maximum

 * </pre>

 * The outer range is <code>minimum,maximum</code> and the inner

 * range is <code>value,value+extent</code>.  The inner range

 * must lie within the outer one, i.e. <code>value</code> must be

 * less than or equal to <code>maximum</code> and <code>value+extent</code>

 * must greater than or equal to <code>minimum</code>, and <code>maximum</code>

 * must be greater than or equal to <code>minimum</code>.

 * There are a few features of this model that one might find a little

 * surprising.  These quirks exist for the convenience of the

 * Swing BoundedRangeModel clients, such as <code>Slider</code> and

 * <code>ScrollBar</code>.

 * <ul>

 * <li>

 *   The minimum and maximum set methods "correct" the other

 *   three properties to accommodate their new value argument.  For

 *   example setting the model's minimum may change its maximum, value,

 *   and extent properties (in that order), to maintain the constraints

 *   specified above.

 *

 * <li>

 *   The value and extent set methods "correct" their argument to

 *   fit within the limits defined by the other three properties.

 *   For example if <code>value == maximum</code>, <code>setExtent(10)</code>

 *   would change the extent (back) to zero.

 *

 * <li>

 *   The four BoundedRangeModel values are defined as Java Beans properties

 *   however Swing ChangeEvents are used to notify clients of changes rather

 *   than PropertyChangeEvents. This was done to keep the overhead of monitoring

 *   a BoundedRangeModel low. Changes are often reported at MouseDragged rates.

 * </ul>

 *

 * <p>

 *

 * For an example of specifying custom bounded range models used by sliders,

 * see <a

 href="http://java.sun.com/docs/books/tutorial/uiswing/overview/anatomy.html">The Anatomy of a Swing-Based Program</a>

 * in <em>The Java Tutorial.</em>

 *

 * @author Hans Muller

 * @see DefaultBoundedRangeModel

 */

public interface BoundedRangeModel

{

    /**

     * Returns the minimum acceptable value.

     *

     * @return the value of the minimum property

     * @see #setMinimum

     */

    int getMinimum();

    /**

     * Sets the model's minimum to <I>newMinimum</I>.   The

     * other three properties may be changed as well, to ensure

     * that:

     * <pre>

     * minimum <= value <= value+extent <= maximum

     * </pre>

     * <p>

     * Notifies any listeners if the model changes.

     *

     * @param newMinimum the model's new minimum

     * @see #getMinimum

     * @see #addChangeListener

     */

    void setMinimum(int newMinimum);

    /**

     * Returns the model's maximum.  Note that the upper

     * limit on the model's value is (maximum - extent).

     *

     * @return the value of the maximum property.

     * @see #setMaximum

     * @see #setExtent

     */

    int getMaximum();

    /**

     * Sets the model's maximum to <I>newMaximum</I>. The other

     * three properties may be changed as well, to ensure that

     * <pre>

     * minimum <= value <= value+extent <= maximum

     * </pre>

     * <p>

     * Notifies any listeners if the model changes.

     *

     * @param newMaximum the model's new maximum

     * @see #getMaximum

     * @see #addChangeListener

     */

    void setMaximum(int newMaximum);

    /**

     * Returns the model's current value.  Note that the upper

     * limit on the model's value is <code>maximum - extent</code>

     * and the lower limit is <code>minimum</code>.

     *

     * @return  the model's value

     * @see     #setValue

     */

    int getValue();

    /**

     * Sets the model's current value to <code>newValue</code> if <code>newValue</code>

     * satisfies the model's constraints. Those constraints are:

     * <pre>

     * minimum <= value <= value+extent <= maximum

     * </pre>

     * Otherwise, if <code>newValue</code> is less than <code>minimum</code>

     * it's set to <code>minimum</code>, if its greater than

     * <code>maximum</code> then it's set to <code>maximum</code>, and

     * if it's greater than <code>value+extent</code> then it's set to

     * <code>value+extent</code>.

     * <p>

     * When a BoundedRange model is used with a scrollbar the value

     * specifies the origin of the scrollbar knob (aka the "thumb" or

     * "elevator").  The value usually represents the origin of the

     * visible part of the object being scrolled.

     * <p>

     * Notifies any listeners if the model changes.

     *

     * @param newValue the model's new value

     * @see #getValue

     */

    void setValue(int newValue);

    /**

     * This attribute indicates that any upcoming changes to the value

     * of the model should be considered a single event. This attribute

     * will be set to true at the start of a series of changes to the value,

     * and will be set to false when the value has finished changing.  Normally

     * this allows a listener to only take action when the final value change in

     * committed, instead of having to do updates for all intermediate values.

     * <p>

     * Sliders and scrollbars use this property when a drag is underway.

     *

     * @param b true if the upcoming changes to the value property are part of a series

     */

    void setValueIsAdjusting(boolean b);

    /**

     * Returns true if the current changes to the value property are part

     * of a series of changes.

     *

     * @return the valueIsAdjustingProperty.

     * @see #setValueIsAdjusting

     */

    boolean getValueIsAdjusting();

    /**

     * Returns the model's extent, the length of the inner range that

     * begins at the model's value.

     *

     * @return  the value of the model's extent property

     * @see     #setExtent

     * @see     #setValue

     */

    int getExtent();

    /**

     * Sets the model's extent.  The <I>newExtent</I> is forced to

     * be greater than or equal to zero and less than or equal to

     * maximum - value.

     * <p>

     * When a BoundedRange model is used with a scrollbar the extent

     * defines the length of the scrollbar knob (aka the "thumb" or

     * "elevator").  The extent usually represents how much of the

     * object being scrolled is visible. When used with a slider,

     * the extent determines how much the value can "jump", for

     * example when the user presses PgUp or PgDn.

     * <p>

     * Notifies any listeners if the model changes.

     *

     * @param  newExtent the model's new extent

     * @see #getExtent

     * @see #setValue

     */

    void setExtent(int newExtent);

    /**

     * This method sets all of the model's data with a single method call.

     * The method results in a single change event being generated. This is

     * convenient when you need to adjust all the model data simultaneously and

     * do not want individual change events to occur.

     *

     * @param value  an int giving the current value

     * @param extent an int giving the amount by which the value can "jump"

     * @param min    an int giving the minimum value

     * @param max    an int giving the maximum value

     * @param adjusting a boolean, true if a series of changes are in

     *                    progress

     *

     * @see #setValue

     * @see #setExtent

     * @see #setMinimum

     * @see #setMaximum

     * @see #setValueIsAdjusting

     */

    void setRangeProperties(int value, int extent, int min, int max, boolean adjusting);

    /**

     * Adds a ChangeListener to the model's listener list.

     *

     * @param x the ChangeListener to add

     * @see #removeChangeListener

     */

    void addChangeListener(ChangeListener x);

    /**

     * Removes a ChangeListener from the model's listener list.

     *

     * @param x the ChangeListener to remove

     * @see #addChangeListener

     */

    void removeChangeListener(ChangeListener x);

}