View Javadoc
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</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 }