1 /*
2 * Copyright 1997-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 }
Save This Page