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 }