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 <= value <= value+extent <= 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 <= value <= value+extent <= 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 <= value <= value+extent <= 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 <= value <= value+extent <= 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 }