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