BoundedRangeModel


1   /*
2    * @(#)BoundedRangeModel.java   1.28 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.swing;
9   
10  import javax.swing.event.*;
11  
12  
13  /**
14   * Defines the data model used by components like <code>Slider</code>s
15   * and <code>ProgressBar</code>s.
16   * Defines four interrelated integer properties: minimum, maximum, extent
17   * and value.  These four integers define two nested ranges like this:
18   * <pre>
19   * minimum <= value <= value+extent <= maximum
20   * </pre>
21   * The outer range is <code>minimum,maximum</code> and the inner
22   * range is <code>value,value+extent</code>.  The inner range
23   * must lie within the outer one, i.e. <code>value</code> must be 
24   * less than or equal to <code>maximum</code> and <code>value+extent</code>
25   * must greater than or equal to <code>minimum</code>, and <code>maximum</code>
26   * must be greater than or equal to <code>minimum</code>.
27   * There are a few features of this model that one might find a little 
28   * surprising.  These quirks exist for the convenience of the
29   * Swing BoundedRangeModel clients, such as <code>Slider</code> and
30   * <code>ScrollBar</code>.
31   * <ul>
32   * <li> 
33   *   The minimum and maximum set methods "correct" the other 
34   *   three properties to accommodate their new value argument.  For 
35   *   example setting the model's minimum may change its maximum, value,
36   *   and extent properties (in that order), to maintain the constraints
37   *   specified above.  
38   * 
39   * <li>
40   *   The value and extent set methods "correct" their argument to 
41   *   fit within the limits defined by the other three properties.  
42   *   For example if <code>value == maximum</code>, <code>setExtent(10)</code>
43   *   would change the extent (back) to zero.
44   * 
45   * <li> 
46   *   The four BoundedRangeModel values are defined as Java Beans properties
47   *   however Swing ChangeEvents are used to notify clients of changes rather
48   *   than PropertyChangeEvents. This was done to keep the overhead of monitoring
49   *   a BoundedRangeModel low. Changes are often reported at MouseDragged rates. 
50   * </ul>
51   *
52   * <p>
53   * 
54   * For an example of specifying custom bounded range models used by sliders,
55   * see <a
56   href="http://java.sun.com/docs/books/tutorial/uiswing/overview/anatomy.html">The Anatomy of a Swing-Based Program</a>
57   * in <em>The Java Tutorial.</em>
58   * 
59   * @version 1.28 12/19/03
60   * @author Hans Muller
61   * @see DefaultBoundedRangeModel
62   */
63  public interface BoundedRangeModel
64  {
65      /**
66       * Returns the minimum acceptable value.
67       *
68       * @return the value of the minimum property
69       * @see #setMinimum
70       */
71      int getMinimum();
72  
73  
74      /**
75       * Sets the model's minimum to <I>newMinimum</I>.   The 
76       * other three properties may be changed as well, to ensure 
77       * that:
78       * <pre>
79       * minimum <= value <= value+extent <= maximum
80       * </pre>
81       * <p>
82       * Notifies any listeners if the model changes.
83       *
84       * @param newMinimum the model's new minimum
85       * @see #getMinimum
86       * @see #addChangeListener
87       */
88      void setMinimum(int newMinimum);
89  
90  
91      /**
92       * Returns the model's maximum.  Note that the upper
93       * limit on the model's value is (maximum - extent).
94       *
95       * @return the value of the maximum property.
96       * @see #setMaximum
97       * @see #setExtent
98       */
99      int getMaximum();
100 
101 
102     /**
103      * Sets the model's maximum to <I>newMaximum</I>. The other 
104      * three properties may be changed as well, to ensure that
105      * <pre>
106      * minimum <= value <= value+extent <= maximum
107      * </pre>
108      * <p>
109      * Notifies any listeners if the model changes.
110      *
111      * @param newMaximum the model's new maximum
112      * @see #getMaximum
113      * @see #addChangeListener
114      */
115     void setMaximum(int newMaximum);
116 
117 
118     /**
119      * Returns the model's current value.  Note that the upper
120      * limit on the model's value is <code>maximum - extent</code> 
121      * and the lower limit is <code>minimum</code>.
122      *
123      * @return  the model's value
124      * @see     #setValue
125      */
126     int getValue();
127 
128 
129     /**
130      * Sets the model's current value to <code>newValue</code> if <code>newValue</code>
131      * satisfies the model's constraints. Those constraints are:
132      * <pre>
133      * minimum <= value <= value+extent <= maximum
134      * </pre>
135      * Otherwise, if <code>newValue</code> is less than <code>minimum</code> 
136      * it's set to <code>minimum</code>, if its greater than 
137      * <code>maximum</code> then it's set to <code>maximum</code>, and 
138      * if it's greater than <code>value+extent</code> then it's set to 
139      * <code>value+extent</code>.
140      * <p>
141      * When a BoundedRange model is used with a scrollbar the value
142      * specifies the origin of the scrollbar knob (aka the "thumb" or
143      * "elevator").  The value usually represents the origin of the 
144      * visible part of the object being scrolled.
145      * <p>
146      * Notifies any listeners if the model changes.
147      *
148      * @param newValue the model's new value
149      * @see #getValue
150      */
151     void setValue(int newValue);
152 
153 
154     /**
155      * This attribute indicates that any upcoming changes to the value
156      * of the model should be considered a single event. This attribute
157      * will be set to true at the start of a series of changes to the value,
158      * and will be set to false when the value has finished changing.  Normally
159      * this allows a listener to only take action when the final value change in
160      * committed, instead of having to do updates for all intermediate values.
161      * <p>
162      * Sliders and scrollbars use this property when a drag is underway.
163      * 
164      * @param b true if the upcoming changes to the value property are part of a series
165      */
166     void setValueIsAdjusting(boolean b);
167 
168 
169     /**
170      * Returns true if the current changes to the value property are part 
171      * of a series of changes.
172      * 
173      * @return the valueIsAdjustingProperty.  
174      * @see #setValueIsAdjusting
175      */
176     boolean getValueIsAdjusting();
177 
178 
179     /**
180      * Returns the model's extent, the length of the inner range that
181      * begins at the model's value.  
182      *
183      * @return  the value of the model's extent property
184      * @see     #setExtent
185      * @see     #setValue
186      */
187     int getExtent();
188 
189 
190     /**
191      * Sets the model's extent.  The <I>newExtent</I> is forced to 
192      * be greater than or equal to zero and less than or equal to
193      * maximum - value.   
194      * <p>
195      * When a BoundedRange model is used with a scrollbar the extent
196      * defines the length of the scrollbar knob (aka the "thumb" or
197      * "elevator").  The extent usually represents how much of the 
198      * object being scrolled is visible. When used with a slider,
199      * the extent determines how much the value can "jump", for
200      * example when the user presses PgUp or PgDn.
201      * <p>
202      * Notifies any listeners if the model changes.
203      *
204      * @param  newExtent the model's new extent
205      * @see #getExtent
206      * @see #setValue
207      */
208     void setExtent(int newExtent);
209 
210 
211 
212     /**
213      * This method sets all of the model's data with a single method call.
214      * The method results in a single change event being generated. This is
215      * convenient when you need to adjust all the model data simultaneously and
216      * do not want individual change events to occur.
217      *
218      * @param value  an int giving the current value 
219      * @param extent an int giving the amount by which the value can "jump"
220      * @param min    an int giving the minimum value
221      * @param max    an int giving the maximum value
222      * @param adjusting a boolean, true if a series of changes are in
223      *                    progress
224      * 
225      * @see #setValue
226      * @see #setExtent
227      * @see #setMinimum
228      * @see #setMaximum
229      * @see #setValueIsAdjusting
230      */
231     void setRangeProperties(int value, int extent, int min, int max, boolean adjusting);
232 
233 
234     /**
235      * Adds a ChangeListener to the model's listener list.
236      *
237      * @param x the ChangeListener to add
238      * @see #removeChangeListener
239      */
240     void addChangeListener(ChangeListener x);
241 
242 
243     /**
244      * Removes a ChangeListener from the model's listener list.
245      *
246      * @param x the ChangeListener to remove
247      * @see #addChangeListener
248      */
249     void removeChangeListener(ChangeListener x);
250 
251 }
252
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags