1 /* 2 * Copyright (c) 1996, 2008, 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</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://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 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 }