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.AWTEvent;
29import java.awt.ItemSelectable;
30
31/**
32 * A semantic event which indicates that an item was selected or deselected.
33 * This high-level event is generated by an ItemSelectable object (such as a
34 * List) when an item is selected or deselected by the user.
35 * The event is passed to every {@code ItemListener} object which
36 * registered to receive such events using the component's
37 * {@code addItemListener} method.
38 * <P>
39 * The object that implements the {@code ItemListener} interface gets
40 * this {@code ItemEvent} when the event occurs. The listener is
41 * spared the details of processing individual mouse movements and mouse
42 * clicks, and can instead process a "meaningful" (semantic) event like
43 * "item selected" or "item deselected".
44 * <p>
45 * An unspecified behavior will be caused if the {@code id} parameter
46 * of any particular {@code ItemEvent} instance is not
47 * in the range from {@code ITEM_FIRST} to {@code ITEM_LAST}.
48 * <p>
49 * The {@code stateChange} of any {@code ItemEvent} instance takes one of the following
50 * values:
51 *                     <ul>
52 *                     <li> {@code ItemEvent.SELECTED}
53 *                     <li> {@code ItemEvent.DESELECTED}
54 *                     </ul>
55 * Assigning the value different from listed above will cause an unspecified behavior.
56 *
57 * @author Carl Quinn
58 *
59 * @see java.awt.ItemSelectable
60 * @see ItemListener
61 * @see <a href="http://docs.oracle.com/javase/tutorial/uiswing/events/itemlistener.html">Tutorial: Writing an Item Listener</a>
62 *
63 * @since 1.1
64 */
65public class ItemEvent extends AWTEvent {
66
67    /**
68     * The first number in the range of ids used for item events.
69     */
70    public static final int ITEM_FIRST          = 701;
71
72    /**
73     * The last number in the range of ids used for item events.
74     */
75    public static final int ITEM_LAST           = 701;
76
77    /**
78     * This event id indicates that an item's state changed.
79     */
80    public static final int ITEM_STATE_CHANGED  = ITEM_FIRST; //Event.LIST_SELECT
81
82    /**
83     * This state-change value indicates that an item was selected.
84     */
85    public static final int SELECTED = 1;
86
87    /**
88     * This state-change-value indicates that a selected item was deselected.
89     */
90    public static final int DESELECTED  = 2;
91
92    /**
93     * The item whose selection state has changed.
94     *
95     * @serial
96     * @see #getItem()
97     */
98    Object item;
99
100    /**
101     * {@code stateChange} indicates whether the {@code item}
102     * was selected or deselected.
103     *
104     * @serial
105     * @see #getStateChange()
106     */
107    int stateChange;
108
109    /*
110     * JDK 1.1 serialVersionUID
111     */
112    private static final long serialVersionUID = -608708132447206933L;
113
114    /**
115     * Constructs an {@code ItemEvent} object.
116     * <p> This method throws an
117     * {@code IllegalArgumentException} if {@code source}
118     * is {@code null}.
119     *
120     * @param source The {@code ItemSelectable} object
121     *               that originated the event
122     * @param id           The integer that identifies the event type.
123     *                     For information on allowable values, see
124     *                     the class description for {@link ItemEvent}
125     * @param item   An object -- the item affected by the event
126     * @param stateChange  An integer that indicates whether the item was
127     *               selected or deselected.
128     *                     For information on allowable values, see
129     *                     the class description for {@link ItemEvent}
130     * @throws IllegalArgumentException if {@code source} is null
131     * @see #getItemSelectable()
132     * @see #getID()
133     * @see #getStateChange()
134     */
135    public ItemEvent(ItemSelectable source, int id, Object item, int stateChange) {
136        super(source, id);
137        this.item = item;
138        this.stateChange = stateChange;
139    }
140
141    /**
142     * Returns the originator of the event.
143     *
144     * @return the ItemSelectable object that originated the event.
145     */
146    public ItemSelectable getItemSelectable() {
147        return (ItemSelectable)source;
148    }
149
150   /**
151    * Returns the item affected by the event.
152    *
153    * @return the item (object) that was affected by the event
154    */
155    public Object getItem() {
156        return item;
157    }
158
159   /**
160    * Returns the type of state change (selected or deselected).
161    *
162    * @return an integer that indicates whether the item was selected
163    *         or deselected
164    *
165    * @see #SELECTED
166    * @see #DESELECTED
167    */
168    public int getStateChange() {
169        return stateChange;
170    }
171
172    /**
173     * Returns a parameter string identifying this item event.
174     * This method is useful for event-logging and for debugging.
175     *
176     * @return a string identifying the event and its attributes
177     */
178    public String paramString() {
179        String typeStr;
180        switch(id) {
181          case ITEM_STATE_CHANGED:
182              typeStr = "ITEM_STATE_CHANGED";
183              break;
184          default:
185              typeStr = "unknown type";
186        }
187
188        String stateStr;
189        switch(stateChange) {
190          case SELECTED:
191              stateStr = "SELECTED";
192              break;
193          case DESELECTED:
194              stateStr = "DESELECTED";
195              break;
196          default:
197              stateStr = "unknown type";
198        }
199        return typeStr + ",item="+item + ",stateChange="+stateStr;
200    }
201
202}
203