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.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} 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="https://docs.oracle.com/javase/tutorial/uiswing/events/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 @SuppressWarnings("serial") // Not statically typed as Serializable 99 Object item; 100 101 /** 102 * {@code stateChange} indicates whether the {@code item} 103 * was selected or deselected. 104 * 105 * @serial 106 * @see #getStateChange() 107 */ 108 int stateChange; 109 110 /* 111 * JDK 1.1 serialVersionUID 112 */ 113 private static final long serialVersionUID = -608708132447206933L; 114 115 /** 116 * Constructs an {@code ItemEvent} object. 117 * <p> This method throws an 118 * {@code IllegalArgumentException} if {@code source} 119 * is {@code null}. 120 * 121 * @param source The {@code ItemSelectable} object 122 * that originated the event 123 * @param id The integer that identifies the event type. 124 * For information on allowable values, see 125 * the class description for {@link ItemEvent} 126 * @param item An object -- the item affected by the event 127 * @param stateChange An integer that indicates whether the item was 128 * selected or deselected. 129 * For information on allowable values, see 130 * the class description for {@link ItemEvent} 131 * @throws IllegalArgumentException if {@code source} is null 132 * @see #getItemSelectable() 133 * @see #getID() 134 * @see #getStateChange() 135 */ 136 public ItemEvent(ItemSelectable source, int id, Object item, int stateChange) { 137 super(source, id); 138 this.item = item; 139 this.stateChange = stateChange; 140 } 141 142 /** 143 * Returns the originator of the event. 144 * 145 * @return the ItemSelectable object that originated the event. 146 */ 147 public ItemSelectable getItemSelectable() { 148 return (ItemSelectable)source; 149 } 150 151 /** 152 * Returns the item affected by the event. 153 * 154 * @return the item (object) that was affected by the event 155 */ 156 public Object getItem() { 157 return item; 158 } 159 160 /** 161 * Returns the type of state change (selected or deselected). 162 * 163 * @return an integer that indicates whether the item was selected 164 * or deselected 165 * 166 * @see #SELECTED 167 * @see #DESELECTED 168 */ 169 public int getStateChange() { 170 return stateChange; 171 } 172 173 /** 174 * Returns a parameter string identifying this item event. 175 * This method is useful for event-logging and for debugging. 176 * 177 * @return a string identifying the event and its attributes 178 */ 179 public String paramString() { 180 String typeStr; 181 switch(id) { 182 case ITEM_STATE_CHANGED: 183 typeStr = "ITEM_STATE_CHANGED"; 184 break; 185 default: 186 typeStr = "unknown type"; 187 } 188 189 String stateStr; 190 switch(stateChange) { 191 case SELECTED: 192 stateStr = "SELECTED"; 193 break; 194 case DESELECTED: 195 stateStr = "DESELECTED"; 196 break; 197 default: 198 stateStr = "unknown type"; 199 } 200 return typeStr + ",item="+item + ",stateChange="+stateStr; 201 } 202 203 }