1 /*
2 * Copyright 1996-2007 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.awt.event;
27
28 import java.awt.AWTEvent;
29 import 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</code> object which
36 * registered to receive such events using the component's
37 * <code>addItemListener</code> method.
38 * <P>
39 * The object that implements the <code>ItemListener</code> interface gets
40 * this <code>ItemEvent</code> 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://java.sun.com/docs/books/tutorial/post1.0/ui/itemlistener.html">Tutorial: Writing an Item Listener</a>
62 *
63 * @since 1.1
64 */
65 public 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</code> indicates whether the <code>item</code>
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</code> object.
116 * <p> This method throws an
117 * <code>IllegalArgumentException</code> if <code>source</code>
118 * is <code>null</code>.
119 *
120 * @param source The <code>ItemSelectable</code> 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</code> 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 }
Save This Page