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://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 }