home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / event / MouseEvent.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  9.7 KB  |  295 lines
  1. /*
  2.  * @(#)MouseEvent.java    1.16 98/03/18
  3.  *
  4.  * Copyright 1996, 1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.awt.event;
  16.  
  17. import java.awt.Component;
  18. import java.awt.Event;
  19. import java.awt.Point;
  20.  
  21. /**
  22. /**
  23.  * An event which indicates that a mouse action occurred in a component.
  24.  * This event is used both for mouse events (click, enter, exit) and mouse 
  25.  * motion events (moves and drags). 
  26.  * <P>
  27.  * This low-level event is generated by a component object for:
  28.  * <ul>
  29.  * <li>Mouse Events
  30.  *     <ul>
  31.  *     <li>a mouse button is pressed
  32.  *     <li>a mouse button is released
  33.  *     <li>a mouse button is clicked (pressed and released)
  34.  *     <li>the mouse cursor enters a component
  35.  *     <li>the mouse cursor exits a component
  36.  *     </ul>
  37.  * <li> Mouse Motion Events
  38.  *     <ul>
  39.  *     <li>the mouse is moved
  40.  *     <li>the mouse is dragged
  41.  *     </ul>
  42.  * </ul>
  43.  * <P>
  44.  * A MouseEvent object is passed to every <code>MouseListener</code>
  45.  * or <code>MouseAdapter</code> object which registered to receive 
  46.  * the "interesting" mouse events using the component's 
  47.  * <code>addMouseListener</code> method.
  48.  * (<code>MouseAdapter</code> objects implement the 
  49.  * <code>MouseListener</code> interface.) Each such listener object 
  50.  * gets a <code>MouseEvent</code> containing the mouse event.
  51.  * <P>
  52.  * A MouseEvent object is also passed to every <code>MouseMotionListener</code>
  53.  * or <code>MouseMotionAdapter</code> object which registered to receive 
  54.  * mouse motion events using the component's <code>addMouseMotionListener</code>
  55.  * method. (<code>MouseMotionAdapter</code> objects implement the 
  56.  * <code>MouseMotionListener</code> interface.) Each such listener object 
  57.  * gets a <code>MouseEvent</code> containing the mouse motion event.
  58.  * <P>
  59.  * When a mouse button is clicked, events are generated and sent to the
  60.  * registered MouseListeners, with the button mask set in the modifier field.
  61.  * For example, if the first mouse button is pressed, events are sent in the
  62.  * following order:
  63.  * <PRE>
  64.  *    MOUSE_PRESSED:  BUTTON1_MASK
  65.  *    MOUSE_RELEASED: BUTTON1_MASK
  66.  *    MOUSE_CLICKED:  BUTTON1_MASK
  67.  * </PRE>
  68.  * When multiple mouse buttons are pressed, each press, release, and click
  69.  * results in a separate event. The button mask in the modifier field reflects
  70.  * only the button that changed state, not the current state of all buttons.
  71.  * <P> 
  72.  * For example, if the user presses button 1 followed by button 2 and
  73.  * releases them in the same order, the following sequence of events is
  74.  * generated:
  75.  * <PRE>
  76.  *    MOUSE_PRESSED:  BUTTON1_MASK
  77.  *    MOUSE_PRESSED:  BUTTON2_MASK
  78.  *    MOUSE_RELEASED: BUTTON1_MASK
  79.  *    MOUSE_CLICKED:  BUTTON1_MASK
  80.  *    MOUSE_RELEASED: BUTTON2_MASK
  81.  *    MOUSE_CLICKED:  BUTTON2_MASK
  82.  * <PRE>
  83.  * If button2 is released first, the MOUSE_RELEASED/MOUSE_CLICKED pair
  84.  * for BUTTON2_MASK arrives first, followed by the pair for BUTTON1_MASK.
  85.  *   
  86.  * @see MouseAdapter
  87.  * @see MouseListener
  88.  * @see MouseMotionAdapter
  89.  * @see MouseMotionListner
  90.  * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/mouselistener.html">Tutorial: Writing a Mouse Listener</a>
  91.  * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/mousemotionlistener.html">Tutorial: Writing a Mouse Motion Listener</a>
  92.  * @see <a href="http://www.awl.com/cp/javaseries/jcl1_2.html">Reference: The Java Class Libraries (update file)</a>
  93.  *
  94.  * @version 1.16 03/18/98
  95.  * @author Carl Quinn
  96.  */
  97. public class MouseEvent extends InputEvent {
  98.  
  99.     /**
  100.      * The first number in the range of ids used for mouse events.
  101.      */
  102.     public static final int MOUSE_FIRST     = 500;
  103.  
  104.     /**
  105.      * The last number in the range of ids used for mouse events.
  106.      */
  107.     public static final int MOUSE_LAST          = 506;
  108.  
  109.     /**
  110.      * The "mouse clicked" event. This MouseEvent occurs when a mouse
  111.      * button is pressed and released.
  112.      */
  113.     public static final int MOUSE_CLICKED = MOUSE_FIRST;
  114.  
  115.     /**
  116.      * The "mouse pressed" event. This MouseEvent occurs when a mouse
  117.      * button is pushed down.
  118.      */
  119.     public static final int MOUSE_PRESSED = 1 + MOUSE_FIRST; //Event.MOUSE_DOWN
  120.  
  121.     /**
  122.      * The "mouse released" event. This MouseEvent occurs when a mouse
  123.      * button is let up.
  124.      */
  125.     public static final int MOUSE_RELEASED = 2 + MOUSE_FIRST; //Event.MOUSE_UP
  126.  
  127.     /**
  128.      * The "mouse moved" event. This MouseMotionEvent occurs when the mouse
  129.      * position changes.
  130.      */
  131.     public static final int MOUSE_MOVED = 3 + MOUSE_FIRST; //Event.MOUSE_MOVE
  132.  
  133.     /**
  134.      * The "mouse entered" event. This MouseEvent occurs when the mouse
  135.      * cursor enters a component's area.
  136.      */
  137.     public static final int MOUSE_ENTERED = 4 + MOUSE_FIRST; //Event.MOUSE_ENTER
  138.  
  139.     /**
  140.      * The "mouse exited" event. This MouseEvent occurs when the mouse
  141.      * cursor leaves a component's area.
  142.      */
  143.     public static final int MOUSE_EXITED = 5 + MOUSE_FIRST; //Event.MOUSE_EXIT
  144.  
  145.     /**
  146.      * The "mouse dragged" event. This MouseMotionEvent occurs when the mouse
  147.      * position changes while the "drag" modifier is active (for example, the
  148.      * shift key).
  149.      */
  150.     public static final int MOUSE_DRAGGED = 6 + MOUSE_FIRST; //Event.MOUSE_DRAG
  151.  
  152.     int x;
  153.     int y;
  154.     int clickCount;
  155.     boolean popupTrigger = false;
  156.  
  157.     /*
  158.      * JDK 1.1 serialVersionUID 
  159.      */
  160.     private static final long serialVersionUID = -991214153494842848L;
  161.  
  162.     /**
  163.      * Constructs a MouseEvent object with the specified source component,
  164.      * type, modifiers, coordinates, and click count.
  165.      *
  166.      * @param source       the Component that originated the event
  167.      * @param id           the integer that identifies the event
  168.      * @param when         a long int that gives the time the event occurred
  169.      * @param modifiers    the modifier keys down during event
  170.      *                     (shift, ctrl, alt, meta)
  171.      * @param x            the horizontal x coordinate for the mouse location
  172.      * @param y            the vertical y coordinate for the mouse location
  173.      * @param clickCount   the number of mouse clicks associated with event
  174.      * @param popupTrigger a boolean, true if this event is a trigger for a
  175.      *                     popup-menu 
  176.      */
  177.     public MouseEvent(Component source, int id, long when, int modifiers,
  178.                       int x, int y, int clickCount, boolean popupTrigger) {
  179.         super(source, id, when, modifiers);
  180.         this.x = x;
  181.         this.y = y;
  182.         this.clickCount = clickCount;
  183.         this.popupTrigger = popupTrigger;
  184.     }
  185.  
  186.     /**
  187.      * Returns the horizontal x position of the event relative to the 
  188.      * source component.
  189.      *
  190.      * @return x  an integer indicating horizontal position relative to
  191.      *            the component
  192.      */
  193.     public int getX() {
  194.         return x;
  195.     }
  196.  
  197.     /**
  198.      * Returns the vertical y position of the event relative to the
  199.      * source component.
  200.      *
  201.      * @return y  an integer indicating vertical position relative to
  202.      *            the component
  203.      */
  204.     public int getY() {
  205.         return y;
  206.     }
  207.  
  208.     /**
  209.      * Returns the x,y position of the event relative to the source component.
  210.      *
  211.      * @return a Point object containing the x and y coordinates 
  212.      *         relative to the source component 
  213.      *
  214.      */
  215.     public Point getPoint() {
  216.     int x;
  217.     int y;
  218.     synchronized (this) {
  219.         x = this.x;
  220.         y = this.y;
  221.     }
  222.         return new Point(x, y);
  223.     }
  224.  
  225.     /**
  226.      * Translates the event's coordinates to a new position
  227.      * by adding specified x (horizontal) and y (veritcal) offsets.
  228.      *
  229.      * @param x the horizontal x value to add to the current x coordinate position
  230.      * @param y the vertical y value to add to the current y coordinate position
  231.      */
  232.     public synchronized void translatePoint(int x, int y) {
  233.         this.x += x;
  234.         this.y += y;
  235.     }
  236.  
  237.     /**
  238.      * Return the number of mouse clicks associated with this event.
  239.      *
  240.      * @return integer value for the number of clicks
  241.      */
  242.     public int getClickCount() {
  243.         return clickCount;
  244.     }
  245.  
  246.     /**
  247.      * Returns whether or not this mouse event is the popup-menu
  248.      * trigger event for the platform.
  249.      *
  250.      * @return boolean, true if this event is the popup-menu trigger
  251.      *         for this platform
  252.      */
  253.     public boolean isPopupTrigger() {
  254.         return popupTrigger;
  255.     }
  256.  
  257.     /**
  258.      * Returns a parameter string identifying this event.
  259.      * This method is useful for event-logging and for debugging.
  260.      *
  261.      * @return a string identifying the event and its attributes
  262.      */
  263.     public String paramString() {
  264.         String typeStr;
  265.         switch(id) {
  266.           case MOUSE_PRESSED:
  267.               typeStr = "MOUSE_PRESSED";
  268.               break;
  269.           case MOUSE_RELEASED:
  270.               typeStr = "MOUSE_RELEASED";
  271.               break;
  272.           case MOUSE_CLICKED:
  273.               typeStr = "MOUSE_CLICKED";
  274.               break;
  275.           case MOUSE_ENTERED:
  276.               typeStr = "MOUSE_ENTERED";
  277.               break;
  278.           case MOUSE_EXITED:
  279.               typeStr = "MOUSE_EXITED";
  280.               break;
  281.           case MOUSE_MOVED:
  282.               typeStr = "MOUSE_MOVED";
  283.               break;
  284.           case MOUSE_DRAGGED:
  285.               typeStr = "MOUSE_DRAGGED";
  286.               break;
  287.           default:
  288.               typeStr = "unknown type";
  289.         }
  290.         return typeStr + ",("+x+","+y+")"+ ",mods="+getModifiers()+ 
  291.                ",clickCount="+clickCount;
  292.     }
  293.  
  294. }
  295.