You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
269 lines
8.2 KiB
269 lines
8.2 KiB
/*
|
|
* Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
|
|
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*/
|
|
|
|
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://www.oracle.com/technetwork/java/architecture-142923.html#separable">Separable model architecture</a>
|
|
* in <em>A Swing Architecture Overview.</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);
|
|
|
|
}
|