Sliders
* and ProgressBars.
* Defines four interrelated integer properties: minimum, maximum, extent
* and value. These four integers define two nested ranges like this:
* * minimum <= value <= value+extent <= maximum ** The outer range is
minimum,maximum and the inner
* range is value,value+extent. The inner range
* must lie within the outer one, i.e. value must be
* less than or equal to maximum and value+extent
* must greater than or equal to minimum, and maximum
* must be greater than or equal to minimum.
* 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 Slider and
* ScrollBar.
* value == maximum, setExtent(10)
* would change the extent (back) to zero.
*
* * * For an example of specifying custom bounded range models used by sliders, * see The Anatomy of a Swing-Based Program * in The Java Tutorial. * * @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 newMinimum. The * other three properties may be changed as well, to ensure * that: *
* minimum <= value <= value+extent <= maximum
*
* * 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 newMaximum. The other * three properties may be changed as well, to ensure that *
* minimum <= value <= value+extent <= maximum
*
*
* 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 maximum - extent
* and the lower limit is minimum.
*
* @return the model's value
* @see #setValue
*/
int getValue();
/**
* Sets the model's current value to newValue if newValue
* satisfies the model's constraints. Those constraints are:
*
* minimum <= value <= value+extent <= maximum
*
* Otherwise, if newValue is less than minimum
* it's set to minimum, if its greater than
* maximum then it's set to maximum, and
* if it's greater than value+extent then it's set to
* value+extent.
* * 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. *
* 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. *
* 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 newExtent is forced to * be greater than or equal to zero and less than or equal to * maximum - value. *
* 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. *
* 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); }