Source for java.awt.event.MouseWheelEvent

   1: /* MouseWheelEvent.java -- a mouse wheel event
   2:    Copyright (C) 2002, 2005  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.awt.event;
  40: 
  41: import java.awt.Adjustable;
  42: import java.awt.Component;
  43: import java.awt.Rectangle;
  44: import java.awt.ScrollPane;
  45: 
  46: import javax.swing.JScrollPane;
  47: import javax.swing.Scrollable;
  48: 
  49: /**
  50:  * This event is generated for a mouse wheel rotation. The wheel (the middle
  51:  * mouse button on most modern mice) can be rotated towards or away from the
  52:  * user, and is often used for scrolling.
  53:  *
  54:  * <p>Because of the special use for scrolling components, MouseWheelEvents
  55:  * often affect a different component than the one located at the point of
  56:  * the event. If the component under the mouse cursor does not accept wheel
  57:  * events, the event is passed to the first ancestor container which does. This
  58:  * is often a ScrollPane, which knows how to scroll. If an AWT component is
  59:  * built from a native widget that knows how to use mouse wheel events, that
  60:  * component will consume the event.
  61:  *
  62:  * <p>The two most common scroll types are "units" (lines at a time) or
  63:  * "blocks" (pages at a time). The initial setting is taken from the platform,
  64:  * although the user can adjust the setting at any time.
  65:  *
  66:  * @author Eric Blake (ebb9@email.byu.edu)
  67:  * @see MouseWheelListener
  68:  * @see ScrollPane
  69:  * @see ScrollPane#setWheelScrollingEnabled(boolean)
  70:  * @see JScrollPane
  71:  * @see JScrollPane#setWheelScrollingEnabled(boolean)
  72:  * @since 1.4
  73:  * @status updated to 1.4
  74:  */
  75: public class MouseWheelEvent extends MouseEvent
  76: {
  77:   /**
  78:    * Compatible with JDK 1.4+.
  79:    */
  80:   private static final long serialVersionUID = 6459879390515399677L;
  81: 
  82:   /**
  83:    * Indicates scrolling by units (lines).
  84:    *
  85:    * @see #getScrollType()
  86:    */
  87:   public static final int WHEEL_UNIT_SCROLL = 0;
  88: 
  89:   /**
  90:    * Indicates scrolling by blocks (pages).
  91:    *
  92:    * @see #getScrollType()
  93:    */
  94:   public static final int WHEEL_BLOCK_SCROLL = 1;
  95: 
  96:   /**
  97:    * Indicates what scroll type should take place. This should be limited
  98:    * to {@link #WHEEL_UNIT_SCROLL} and {@link #WHEEL_BLOCK_SCROLL}.
  99:    *
 100:    * @serial the scroll type
 101:    */
 102:   private final int scrollType;
 103: 
 104:   /**
 105:    * Indicates the scroll amount. This is only meaningful if scrollType is
 106:    * WHEEL_UNIT_SCROLL.
 107:    *
 108:    * @serial the number of lines to scroll
 109:    */
 110:   private final int scrollAmount;
 111: 
 112:   /**
 113:    * Indicates how far the mouse wheel was rotated.
 114:    *
 115:    * @serial the rotation amount
 116:    */
 117:   private final int wheelRotation;
 118: 
 119:   /**
 120:    * Initializes a new instance of <code>MouseWheelEvent</code> with the
 121:    * specified information. Note that an invalid id leads to unspecified
 122:    * results.
 123:    *
 124:    * @param source the source of the event
 125:    * @param id the event id
 126:    * @param when the timestamp of when the event occurred
 127:    * @param modifiers any modifier bits for this event
 128:    * @param x the X coordinate of the mouse point
 129:    * @param y the Y coordinate of the mouse point
 130:    * @param clickCount the number of mouse clicks for this event
 131:    * @param popupTrigger true if this event triggers a popup menu
 132:    * @param scrollType one of {@link #WHEEL_UNIT_SCROLL},
 133:    *        {@link #WHEEL_BLOCK_SCROLL}
 134:    * @param scrollAmount the number of units to scroll, ignored for block type
 135:    * @param wheelRotation the number of rotation "clicks"
 136:    * @throws IllegalArgumentException if source is null
 137:    * @see MouseEvent#MouseEvent(Component, int, long, int, int, int, int,
 138:    *      boolean) 
 139:    */
 140:   public MouseWheelEvent(Component source, int id, long when, int modifiers,
 141:                          int x, int y, int clickCount, boolean popupTrigger,
 142:                          int scrollType, int scrollAmount, int wheelRotation)
 143:   {
 144:     super(source, id, when, modifiers, x, y, clickCount, popupTrigger);
 145:     this.scrollType = scrollType;
 146:     this.scrollAmount = scrollAmount;
 147:     this.wheelRotation = wheelRotation;
 148:   }
 149: 
 150:   /**
 151:    * This method returns the scrolling pattern this event requests. Legal
 152:    * values are {@link #WHEEL_UNIT_SCROLL} and {@link #WHEEL_BLOCK_SCROLL}.
 153:    *
 154:    * @return the scroll type
 155:    * @see Adjustable#getUnitIncrement()
 156:    * @see Adjustable#getBlockIncrement()
 157:    * @see Scrollable#getScrollableUnitIncrement(Rectangle, int, int)
 158:    * @see Scrollable#getScrollableBlockIncrement(Rectangle, int, int)
 159:    */
 160:   public int getScrollType()
 161:   {
 162:     return scrollType;
 163:   }
 164: 
 165:   /**
 166:    * Returns the number of units to scroll in response to this event. This
 167:    * only makes sense when the scroll type is WHEEL_UNIT_SCROLL.
 168:    *
 169:    * @return the number of scroll units, if defined
 170:    * @see #getScrollType()
 171:    */
 172:   public int getScrollAmount()
 173:   {
 174:     return scrollAmount;
 175:   }
 176: 
 177:   /**
 178:    * Gets the number of "clicks" the wheel was rotated. Negative values move
 179:    * up (away) from the user, positive values move down (towards) the user.
 180:    *
 181:    * @return the number of rotation clicks
 182:    */
 183:   public int getWheelRotation()
 184:   {
 185:     return wheelRotation;
 186:   }
 187: 
 188:   /**
 189:    * This is a convenience method which aids in a common listener for scrolling
 190:    * a scrollpane (although this is already built into ScrollPane and
 191:    * JScrollPane). This method only makes sense when getScrollType() returns
 192:    * WHEEL_UNIT_SCROLL.
 193:    *
 194:    * <p>This accounts for direction of scroll and amount of wheel movement, as
 195:    * interpreted by the platform settings.
 196:    *
 197:    * @return the number of units to scroll
 198:    * @see #getScrollType()
 199:    * @see #getScrollAmount()
 200:    * @see MouseWheelListener
 201:    * @see Adjustable
 202:    * @see Adjustable#getUnitIncrement()
 203:    * @see Scrollable
 204:    * @see Scrollable#getScrollableUnitIncrement(Rectangle, int, int)
 205:    * @see ScrollPane
 206:    * @see ScrollPane#setWheelScrollingEnabled(boolean)
 207:    * @see JScrollPane
 208:    * @see JScrollPane#setWheelScrollingEnabled(boolean)
 209:    */
 210:   public int getUnitsToScroll()
 211:   {
 212:     return wheelRotation * scrollAmount;
 213:   }
 214: 
 215:   /**
 216:    * Returns a string identifying this event. For mouse wheel events, this
 217:    * is <code>super.paramString() + ",scrollType=WHEEL_" +
 218:    * (getScrollType() == WHEEL_UNIT_SCROLL ? "UNIT" : "BLOCK")
 219:    * + "_SCROLL,scrollAmount=" + getScrollAmount() + ",wheelRotation="
 220:    * + getWheelRotation()</code>.
 221:    *
 222:    * @return a string identifying this event
 223:    */
 224:   public String paramString()
 225:   {
 226:     return super.paramString() + ",scrollType="
 227:       + (scrollType == WHEEL_UNIT_SCROLL ? "WHEEL_UNIT_SCROLL"
 228:          : scrollType == WHEEL_BLOCK_SCROLL ? "WHEEL_BLOCK_SCROLL"
 229:          : "unknown scroll type")
 230:       + ",scrollAmount=" + scrollAmount + ",wheelRotation=" + wheelRotation;
 231:   }
 232: } // class MouseWheelEvent