1 /* 2 Copyright aswing.org, see the LICENCE.txt. 3 */ 4 5 import org.aswing.*; 6 7 /** 8 * Defines the data model used by components like <code>Slider</code>s 9 * and <code>ProgressBar</code>s. 10 * Defines four interrelated integer properties: minimum, maximum, extent 11 * and value. These four integers define two nested ranges like this: 12 * <pre> 13 * minimum <= value <= value+extent <= maximum 14 * </pre> 15 * The outer range is <code>minimum,maximum</code> and the inner 16 * range is <code>value,value+extent</code>. The inner range 17 * must lie within the outer one, i.e. <code>value</code> must be 18 * less than or equal to <code>maximum</code> and <code>value+extent</code> 19 * must greater than or equal to <code>minimum</code>, and <code>maximum</code> 20 * must be greater than or equal to <code>minimum</code>. 21 * There are a few features of this model that one might find a little 22 * surprising. These quirks exist for the convenience of the 23 * Swing BoundedRangeModel clients, such as <code>Slider</code> and 24 * <code>ScrollBar</code>. 25 * <ul> 26 * <li> 27 * The minimum and maximum set methods "correct" the other 28 * three properties to accommodate their new value argument. For 29 * example setting the model's minimum may change its maximum, value, 30 * and extent properties (in that order), to maintain the constraints 31 * specified above. 32 * 33 * <li> 34 * The value and extent set methods "correct" their argument to 35 * fit within the limits defined by the other three properties. 36 * For example if <code>value == maximum</code>, <code>setExtent(10)</code> 37 * would change the extent (back) to zero. 38 * 39 * <li> 40 * The four BoundedRangeModel values are defined as Java Beans style properties. 41 * </ul> 42 * 43 * @see DefaultBoundedRangeModel 44 * @author iiley 45 */ 46 interface org.aswing.BoundedRangeModel extends IEventDispatcher{ 47 /** 48 * Returns the minimum acceptable value. 49 * 50 * @return the value of the minimum property 51 * @see #setMinimum() 52 */ 53 public function getMinimum():Number; 54 55 /** 56 * Sets the model's minimum to <I>newMinimum</I>. The 57 * other three properties may be changed as well, to ensure 58 * that: 59 * <pre> 60 * minimum <= value <= value+extent <= maximum 61 * </pre> 62 * <p> 63 * Notifies any listeners if the model changes. 64 * 65 * @param newMinimum the model's new minimum 66 * @see #getMinimum() 67 * @see #addChangeListener() 68 */ 69 public function setMinimum(newMinimum:Number):Void; 70 71 /** 72 * Returns the model's maximum. Note that the upper 73 * limit on the model's value is (maximum - extent). 74 * 75 * @return the value of the maximum property. 76 * @see #setMaximum() 77 * @see #setExtent() 78 */ 79 public function getMaximum():Number; 80 81 /** 82 * Sets the model's maximum to <I>newMaximum</I>. The other 83 * three properties may be changed as well, to ensure that 84 * <pre> 85 * minimum <= value <= value+extent <= maximum 86 * </pre> 87 * <p> 88 * Notifies any listeners if the model changes. 89 * 90 * @param newMaximum the model's new maximum 91 * @see #getMaximum() 92 * @see #addChangeListener() 93 */ 94 public function setMaximum(newMaximum:Number):Void; 95 96 /** 97 * Returns the model's current value. Note that the upper 98 * limit on the model's value is <code>maximum - extent</code> 99 * and the lower limit is <code>minimum</code>. 100 * 101 * @return the model's value 102 * @see #setValue() 103 */ 104 public function getValue():Number; 105 106 /** 107 * Sets the model's current value to <code>newValue</code> if <code>newValue</code> 108 * satisfies the model's constraints. Those constraints are: 109 * <pre> 110 * minimum <= value <= value+extent <= maximum 111 * </pre> 112 * Otherwise, if <code>newValue</code> is less than <code>minimum</code> 113 * it's set to <code>minimum</code>, if its greater than 114 * <code>maximum</code> then it's set to <code>maximum</code>, and 115 * if it's greater than <code>value+extent</code> then it's set to 116 * <code>value+extent</code>. 117 * <p> 118 * When a BoundedRange model is used with a scrollbar the value 119 * specifies the origin of the scrollbar knob (aka the "thumb" or 120 * "elevator"). The value usually represents the origin of the 121 * visible part of the object being scrolled. 122 * <p> 123 * Notifies any listeners if the model changes. 124 * 125 * @param newValue the model's new value 126 * @see #getValue() 127 */ 128 public function setValue(newValue:Number):Void; 129 130 /** 131 * This attribute indicates that any upcoming changes to the value 132 * of the model should be considered a single event. This attribute 133 * will be set to true at the start of a series of changes to the value, 134 * and will be set to false when the value has finished changing. Normally 135 * this allows a listener to only take action when the final value change in 136 * committed, instead of having to do updates for all intermediate values. 137 * <p> 138 * Sliders and scrollbars use this property when a drag is underway. 139 * 140 * @param b true if the upcoming changes to the value property are part of a series 141 */ 142 public function setValueIsAdjusting(b:Boolean):Void; 143 144 /** 145 * Returns true if the current changes to the value property are part 146 * of a series of changes. 147 * 148 * @return the valueIsAdjustingProperty. 149 * @see #setValueIsAdjusting() 150 */ 151 public function getValueIsAdjusting():Boolean; 152 153 /** 154 * Returns the model's extent, the length of the inner range that 155 * begins at the model's value. 156 * 157 * @return the value of the model's extent property 158 * @see #setExtent() 159 * @see #setValue() 160 */ 161 public function getExtent():Number; 162 163 /** 164 * Sets the model's extent. The <I>newExtent</I> is forced to 165 * be greater than or equal to zero and less than or equal to 166 * maximum - value. 167 * <p> 168 * When a BoundedRange model is used with a scrollbar the extent 169 * defines the length of the scrollbar knob (aka the "thumb" or 170 * "elevator"). The extent usually represents how much of the 171 * object being scrolled is visible. When used with a slider, 172 * the extent determines how much the value can "jump", for 173 * example when the user presses PgUp or PgDn. 174 * <p> 175 * Notifies any listeners if the model changes. 176 * 177 * @param newExtent the model's new extent 178 * @see #getExtent() 179 * @see #setValue() 180 */ 181 public function setExtent(newExtent:Number):Void; 182 183 /** 184 * This method sets all of the model's data with a single method call. 185 * The method results in a single change event being generated. This is 186 * convenient when you need to adjust all the model data simultaneously and 187 * do not want individual change events to occur. 188 * 189 * @param value an int giving the current value 190 * @param extent an int giving the amount by which the value can "jump" 191 * @param min an int giving the minimum value 192 * @param max an int giving the maximum value 193 * @param adjusting a boolean, true if a series of changes are in 194 * progress 195 * 196 * @see #setValue() 197 * @see #setExtent() 198 * @see #setMinimum() 199 * @see #setMaximum() 200 * @see #setValueIsAdjusting() 201 */ 202 public function setRangeProperties(value:Number, extent:Number, min:Number, max:Number, adjusting:Boolean):Void; 203 204 /** 205 * addChangeListener(func:Function)<br> 206 * addChangeListener(func:Function, obj:Object) 207 * <p> 208 * Add a listener to listen the Model's change event. 209 * <p> 210 * The state is all about: 211 * <ul> 212 * <li>value 213 * <li>extent 214 * <li>min 215 * <li>max 216 * <li>adjusting 217 * </ul> 218 *<br> 219 * onStateChanged Event{source:BoundedRangeModel} 220 * @see org.aswing.Component#ON_STATE_CHANGED 221 * @return the listener added. 222 * @see EventDispatcher#addEventListener() 223 */ 224 public function addChangeListener(func:Function, obj:Object):Object; 225 } 226