1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
/* * @(#)BoundedRangeModel.java 1.30 06/03/01 * * Copyright 2006 Sun Microsystems, Inc. All rights reserved. * SUN 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://java.sun.com/docs/books/tutorial/uiswing/overview/anatomy.html">The Anatomy of a Swing-Based Program</a> * in <em>The Java Tutorial.</em> * * @version 1.30 03/01/06 * @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); }