1 /*
2 * Copyright (c) 1996, 2008, 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 java.awt.event;
27
28 import java.awt.Adjustable;
29 import java.awt.AWTEvent;
30 import javax.tools.annotation.GenerateNativeHeader;
31
32 import javax.tools.annotation.GenerateNativeHeader;
33
34 /**
35 * The adjustment event emitted by Adjustable objects like
36 * {@link java.awt.Scrollbar} and {@link java.awt.ScrollPane}.
37 * When the user changes the value of the scrolling component,
38 * it receives an instance of {@code AdjustmentEvent}.
39 * <p>
40 * An unspecified behavior will be caused if the {@code id} parameter
41 * of any particular {@code AdjustmentEvent} instance is not
42 * in the range from {@code ADJUSTMENT_FIRST} to {@code ADJUSTMENT_LAST}.
43 * <p>
44 * The {@code type} of any {@code AdjustmentEvent} instance takes one of the following
45 * values:
46 * <ul>
47 * <li> {@code UNIT_INCREMENT}
48 * <li> {@code UNIT_DECREMENT}
49 * <li> {@code BLOCK_INCREMENT}
50 * <li> {@code BLOCK_DECREMENT}
51 * <li> {@code TRACK}
52 * </ul>
53 * Assigning the value different from listed above will cause an unspecified behavior.
54 * @see java.awt.Adjustable
55 * @see AdjustmentListener
56 *
57 * @author Amy Fowler
58 * @since 1.1
59 */
60 /* No native methods here, but the constants are needed in the supporting JNI code */
61 @GenerateNativeHeader
62 public class AdjustmentEvent extends AWTEvent {
63
64 /**
65 * Marks the first integer id for the range of adjustment event ids.
66 */
67 public static final int ADJUSTMENT_FIRST = 601;
68
69 /**
70 * Marks the last integer id for the range of adjustment event ids.
71 */
72 public static final int ADJUSTMENT_LAST = 601;
73
74 /**
75 * The adjustment value changed event.
76 */
77 public static final int ADJUSTMENT_VALUE_CHANGED = ADJUSTMENT_FIRST; //Event.SCROLL_LINE_UP
78
79 /**
80 * The unit increment adjustment type.
81 */
82 public static final int UNIT_INCREMENT = 1;
83
84 /**
85 * The unit decrement adjustment type.
86 */
87 public static final int UNIT_DECREMENT = 2;
88
89 /**
90 * The block decrement adjustment type.
91 */
92 public static final int BLOCK_DECREMENT = 3;
93
94 /**
95 * The block increment adjustment type.
96 */
97 public static final int BLOCK_INCREMENT = 4;
98
99 /**
100 * The absolute tracking adjustment type.
101 */
102 public static final int TRACK = 5;
103
104 /**
105 * The adjustable object that fired the event.
106 *
107 * @serial
108 * @see #getAdjustable
109 */
110 Adjustable adjustable;
111
112 /**
113 * <code>value</code> will contain the new value of the
114 * adjustable object. This value will always be in a
115 * range associated adjustable object.
116 *
117 * @serial
118 * @see #getValue
119 */
120 int value;
121
122 /**
123 * The <code>adjustmentType</code> describes how the adjustable
124 * object value has changed.
125 * This value can be increased/decreased by a block or unit amount
126 * where the block is associated with page increments/decrements,
127 * and a unit is associated with line increments/decrements.
128 *
129 * @serial
130 * @see #getAdjustmentType
131 */
132 int adjustmentType;
133
134
135 /**
136 * The <code>isAdjusting</code> is true if the event is one
137 * of the series of multiple adjustment events.
138 *
139 * @since 1.4
140 * @serial
141 * @see #getValueIsAdjusting
142 */
143 boolean isAdjusting;
144
145
146 /*
147 * JDK 1.1 serialVersionUID
148 */
149 private static final long serialVersionUID = 5700290645205279921L;
150
151
152 /**
153 * Constructs an <code>AdjustmentEvent</code> object with the
154 * specified <code>Adjustable</code> source, event type,
155 * adjustment type, and value.
156 * <p> This method throws an
157 * <code>IllegalArgumentException</code> if <code>source</code>
158 * is <code>null</code>.
159 *
160 * @param source The <code>Adjustable</code> object where the
161 * event originated
162 * @param id An integer indicating the type of event.
163 * For information on allowable values, see
164 * the class description for {@link AdjustmentEvent}
165 * @param type An integer indicating the adjustment type.
166 * For information on allowable values, see
167 * the class description for {@link AdjustmentEvent}
168 * @param value The current value of the adjustment
169 * @throws IllegalArgumentException if <code>source</code> is null
170 * @see #getSource()
171 * @see #getID()
172 * @see #getAdjustmentType()
173 * @see #getValue()
174 */
175 public AdjustmentEvent(Adjustable source, int id, int type, int value) {
176 this(source, id, type, value, false);
177 }
178
179 /**
180 * Constructs an <code>AdjustmentEvent</code> object with the
181 * specified Adjustable source, event type, adjustment type, and value.
182 * <p> This method throws an
183 * <code>IllegalArgumentException</code> if <code>source</code>
184 * is <code>null</code>.
185 *
186 * @param source The <code>Adjustable</code> object where the
187 * event originated
188 * @param id An integer indicating the type of event.
189 * For information on allowable values, see
190 * the class description for {@link AdjustmentEvent}
191 * @param type An integer indicating the adjustment type.
192 * For information on allowable values, see
193 * the class description for {@link AdjustmentEvent}
194 * @param value The current value of the adjustment
195 * @param isAdjusting A boolean that equals <code>true</code> if the event is one
196 * of a series of multiple adjusting events,
197 * otherwise <code>false</code>
198 * @throws IllegalArgumentException if <code>source</code> is null
199 * @since 1.4
200 * @see #getSource()
201 * @see #getID()
202 * @see #getAdjustmentType()
203 * @see #getValue()
204 * @see #getValueIsAdjusting()
205 */
206 public AdjustmentEvent(Adjustable source, int id, int type, int value, boolean isAdjusting) {
207 super(source, id);
208 adjustable = source;
209 this.adjustmentType = type;
210 this.value = value;
211 this.isAdjusting = isAdjusting;
212 }
213
214 /**
215 * Returns the <code>Adjustable</code> object where this event originated.
216 *
217 * @return the <code>Adjustable</code> object where this event originated
218 */
219 public Adjustable getAdjustable() {
220 return adjustable;
221 }
222
223 /**
224 * Returns the current value in the adjustment event.
225 *
226 * @return the current value in the adjustment event
227 */
228 public int getValue() {
229 return value;
230 }
231
232 /**
233 * Returns the type of adjustment which caused the value changed
234 * event. It will have one of the following values:
235 * <ul>
236 * <li>{@link #UNIT_INCREMENT}
237 * <li>{@link #UNIT_DECREMENT}
238 * <li>{@link #BLOCK_INCREMENT}
239 * <li>{@link #BLOCK_DECREMENT}
240 * <li>{@link #TRACK}
241 * </ul>
242 * @return one of the adjustment values listed above
243 */
244 public int getAdjustmentType() {
245 return adjustmentType;
246 }
247
248 /**
249 * Returns <code>true</code> if this is one of multiple
250 * adjustment events.
251 *
252 * @return <code>true</code> if this is one of multiple
253 * adjustment events, otherwise returns <code>false</code>
254 * @since 1.4
255 */
256 public boolean getValueIsAdjusting() {
257 return isAdjusting;
258 }
259
260 public String paramString() {
261 String typeStr;
262 switch(id) {
263 case ADJUSTMENT_VALUE_CHANGED:
264 typeStr = "ADJUSTMENT_VALUE_CHANGED";
265 break;
266 default:
267 typeStr = "unknown type";
268 }
269 String adjTypeStr;
270 switch(adjustmentType) {
271 case UNIT_INCREMENT:
272 adjTypeStr = "UNIT_INCREMENT";
273 break;
274 case UNIT_DECREMENT:
275 adjTypeStr = "UNIT_DECREMENT";
276 break;
277 case BLOCK_INCREMENT:
278 adjTypeStr = "BLOCK_INCREMENT";
279 break;
280 case BLOCK_DECREMENT:
281 adjTypeStr = "BLOCK_DECREMENT";
282 break;
283 case TRACK:
284 adjTypeStr = "TRACK";
285 break;
286 default:
287 adjTypeStr = "unknown type";
288 }
289 return typeStr
290 + ",adjType="+adjTypeStr
291 + ",value="+value
292 + ",isAdjusting="+isAdjusting;
293 }
294 }