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
26package java.awt.event;
27
28import java.awt.Adjustable;
29import java.awt.AWTEvent;
30import 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 */
59public 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} 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} 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} 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} object with the
151     * specified {@code Adjustable} source, event type,
152     * adjustment type, and value.
153     * <p> This method throws an
154     * {@code IllegalArgumentException} if {@code source}
155     * is {@code null}.
156     *
157     * @param source The {@code Adjustable} 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} is null
167     * @see #getSource()
168     * @see #getID()
169     * @see #getAdjustmentType()
170     * @see #getValue()
171     */
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} object with the
178     * specified Adjustable source, event type, adjustment type, and value.
179     * <p> This method throws an
180     * {@code IllegalArgumentException} if {@code source}
181     * is {@code null}.
182     *
183     * @param source The {@code Adjustable} 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} if the event is one
193     *               of a series of multiple adjusting events,
194     *               otherwise {@code false}
195     * @throws IllegalArgumentException if {@code source} is null
196     * @since 1.4
197     * @see #getSource()
198     * @see #getID()
199     * @see #getAdjustmentType()
200     * @see #getValue()
201     * @see #getValueIsAdjusting()
202     */
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} object where this event originated.
213     *
214     * @return the {@code Adjustable} object where this event originated
215     */
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     */
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     */
241    public int getAdjustmentType() {
242        return adjustmentType;
243    }
244
245    /**
246     * Returns {@code true} if this is one of multiple
247     * adjustment events.
248     *
249     * @return {@code true} if this is one of multiple
250     *         adjustment events, otherwise returns {@code false}
251     * @since 1.4
252     */
253    public boolean getValueIsAdjusting() {
254        return isAdjusting;
255    }
256
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