Showing the changes to java/pkg/javax/swing/BoundedRangeModel.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,268 @@ | |||
| 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 | } | ||