Added javadoc and getButtonName() debug method

svn changeset:11811/svn branch:6.3

diff --git a/src/com/vaadin/event/MouseEvents.java b/src/com/vaadin/event/MouseEvents.java
index 09fcc85b592d38040dd10b033ea7c630684381b7..a7daf70714796fce22dd1c899c4caecb5f42e40e 100644 (file)
--- a/src/com/vaadin/event/MouseEvents.java
+++ b/src/com/vaadin/event/MouseEvents.java
@@ -10,15 +10,29 @@ import com.vaadin.terminal.gwt.client.MouseEventDetails;
 import com.vaadin.tools.ReflectTools;
 import com.vaadin.ui.Component;
 
+/**
+ * Interface that serves as a wrapper for mouse related events.
+ * 
+ * @author IT Mill Ltd.
+ * @see ClickListener
+ * @version
+ * @VERSION@
+ * @since 6.2
+ */
 public interface MouseEvents {
 
     /**
-     * <code>ClickEvent</code> class for holding additional event information.
-     * Fired when the user clicks on a <code>Component</code>.
+     * Class for holding information about a mouse click event. A
+     * {@link ClickEvent} is fired when the user clicks on a
+     * <code>Component</code>.
      * 
-     * ClickEvents are rather terminal dependent events. Correct values in event
-     * details cannot be guaranteed.
+     * The information available for click events are terminal dependent.
+     * Correct values for all event details cannot be guaranteed.
      * 
+     * @author IT Mill Ltd.
+     * @see ClickListener
+     * @version
+     * @VERSION@
      * @since 6.2
      */
     public class ClickEvent extends Component.Event {
@@ -28,52 +42,113 @@ public interface MouseEvents {
 
         private MouseEventDetails details;
 
-        private static final long serialVersionUID = -7644184999481404162L;
-
         public ClickEvent(Component source, MouseEventDetails mouseEventDetails) {
             super(source);
-            this.details = mouseEventDetails;
+            details = mouseEventDetails;
         }
 
+        /**
+         * Returns an identifier describing which mouse button the user pushed.
+         * Compare with {@link #BUTTON_LEFT},{@link #BUTTON_MIDDLE},
+         * {@link #BUTTON_RIGHT} to find out which butten it is.
+         * 
+         * @return one of {@link #BUTTON_LEFT}, {@link #BUTTON_MIDDLE},
+         *         {@link #BUTTON_RIGHT}.
+         */
         public int getButton() {
             return details.getButton();
         }
 
+        /**
+         * Returns the mouse position (x coordinate) when the click took place.
+         * The position is relative to the browser client area.
+         * 
+         * @return The mouse cursor x position
+         */
         public int getClientX() {
             return details.getClientX();
         }
 
+        /**
+         * Returns the mouse position (y coordinate) when the click took place.
+         * The position is relative to the browser client area.
+         * 
+         * @return The mouse cursor y position
+         */
         public int getClientY() {
             return details.getClientY();
         }
 
+        /**
+         * Checks if the event is a double click event.
+         * 
+         * @return true if the event is a double click event, false otherwise
+         */
         public boolean isDoubleClick() {
             return details.isDoubleClick();
         }
 
+        /**
+         * Checks if the Alt key was down when the mouse event took place.
+         * 
+         * @return true if Alt was down when the event occured, false otherwise
+         */
         public boolean isAltKey() {
             return details.isAltKey();
         }
 
+        /**
+         * Checks if the Ctrl key was down when the mouse event took place.
+         * 
+         * @return true if Ctrl was pressed when the event occured, false
+         *         otherwise
+         */
         public boolean isCtrlKey() {
             return details.isCtrlKey();
         }
 
+        /**
+         * Checks if the Meta key was down when the mouse event took place.
+         * 
+         * @return true if Meta was pressed when the event occured, false
+         *         otherwise
+         */
         public boolean isMetaKey() {
             return details.isMetaKey();
         }
 
+        /**
+         * Checks if the Shift key was down when the mouse event took place.
+         * 
+         * @return true if Shift was pressed when the event occured, false
+         *         otherwise
+         */
         public boolean isShiftKey() {
             return details.isShiftKey();
         }
 
+        /**
+         * Returns a human readable string representing which button has been
+         * pushed. This is meant for debug purposes only and the string returned
+         * could change. Use {@link #getButton()} to check which button was
+         * pressed.
+         * 
+         * @since 6.3
+         * @return A string representation of which button was pushed.
+         */
+        public String getButtonName() {
+            return details.getButtonName();
+        }
     }
 
     /**
-     * <code>ClickListener</code> interface for listening for
-     * <code>ClickEvent</code> fired by a <code>Component</code>.
+     * Interface for listening for a {@link ClickEvent} fired by a
+     * {@link Component}.
      * 
      * @see ClickEvent
+     * @author IT Mill Ltd.
+     * @version
+     * @VERSION@
      * @since 6.2
      */
     public interface ClickListener extends ComponentEventListener {
@@ -82,35 +157,40 @@ public interface MouseEvents {
                 ClickListener.class, "click", ClickEvent.class);
 
         /**
-         * Component has been clicked
+         * Called when a {@link Component} has been clicked. A reference to the
+         * component is given by {@link ClickEvent#getComponent()}.
          * 
          * @param event
-         *            Component click event.
+         *            An event containing information about the click.
          */
         public void click(ClickEvent event);
     }
 
     /**
-     * <code>DoubleClickEvent</code> class for holding additional event
-     * information. Fired when the user double-clicks on a
-     * <code>Component</code>.
+     * Class for holding additional event information for DoubleClick events.
+     * Fired when the user double-clicks on a <code>Component</code>.
      * 
+     * @see ClickEvent
+     * @author IT Mill Ltd.
+     * @version
+     * @VERSION@
      * @since 6.2
      */
     public class DoubleClickEvent extends Component.Event {
 
-        private static final long serialVersionUID = -7644184999481404162L;
-
         public DoubleClickEvent(Component source) {
             super(source);
         }
     }
 
     /**
-     * <code>DoubleClickListener</code> interface for listening for
-     * <code>DoubleClickEvent</code> fired by a <code>Component</code>.
+     * Interface for listening for a {@link DoubleClickEvent} fired by a
+     * {@link Component}.
      * 
      * @see DoubleClickEvent
+     * @author IT Mill Ltd.
+     * @version
+     * @VERSION@
      * @since 6.2
      */
     public interface DoubleClickListener extends ComponentEventListener {
@@ -120,10 +200,11 @@ public interface MouseEvents {
                 DoubleClickEvent.class);
 
         /**
-         * Component value was changed
+         * Called when a {@link Component} has been double clicked. A reference
+         * to the component is given by {@link DoubleClickEvent#getComponent()}.
          * 
          * @param event
-         *            Component change event.
+         *            An event containing information about the double click.
          */
         public void doubleClick(DoubleClickEvent event);
     }