Javadoc

svn changeset:10045/svn branch:event-framework-3234

6 files changed, 113 insertions, 14 deletions

diff --git a/src/TestListeners.java b/src/TestListeners.java
index 9650c2269a..87255b4eac 100644
--- a/src/TestListeners.java
+++ b/src/TestListeners.java
@@ -8,6 +8,7 @@ import com.vaadin.event.LayoutEvents.LayoutClickListener;
 import com.vaadin.event.MouseEvents.ClickEvent;
 import com.vaadin.event.MouseEvents.ClickListener;
 import com.vaadin.terminal.ExternalResource;
+import com.vaadin.terminal.gwt.client.MouseEventDetails;
 import com.vaadin.ui.AbsoluteLayout;
 import com.vaadin.ui.Component;
 import com.vaadin.ui.Embedded;
@@ -28,19 +29,6 @@ public class TestListeners extends Application implements LayoutClickListener,
         setMainWindow(w);
         HorizontalLayout hl = new HorizontalLayout();
         w.setContent(hl);
-        // Panel p = new Panel("My panel");
-        // p.addListener(new ClickListener() {
-        //
-        // public void click(ClickEvent event) {
-        // getMainWindow().showNotification("Clicked!");
-        //
-        // }
-        // });
-        // w.addComponent(p);
-        // if (true) {
-        // return;
-        // }
-        // VerticalLayout vl = new VerticalLayout();
 
         final AbsoluteLayout al = new AbsoluteLayout();
         al.setWidth("200px");
@@ -186,7 +174,17 @@ public class TestListeners extends Application implements LayoutClickListener,
     public void click(ClickEvent event) {
         getMainWindow().showNotification(
                 "Clicked on " + event.getComponent() + " using "
-                        + event.getButton());
+                        + getButton(event));
+    }
+
+    private String getButton(ClickEvent event) {
+        if (event.getButton() == MouseEventDetails.BUTTON_LEFT) {
+            return "left";
+        } else if (event.getButton() == MouseEventDetails.BUTTON_RIGHT) {
+            return "right";
+        } else {
+            return "middle";
+        }
     }
 
     public void focus(FocusEvent event) {
diff --git a/src/com/vaadin/ui/AbsoluteLayout.java b/src/com/vaadin/ui/AbsoluteLayout.java
index 849538b49a..d32ba913b1 100644
--- a/src/com/vaadin/ui/AbsoluteLayout.java
+++ b/src/com/vaadin/ui/AbsoluteLayout.java
@@ -375,11 +375,33 @@ public class AbsoluteLayout extends AbstractLayout {
         fireEvent(new LayoutClickEvent(this, mouseDetails, childComponent));
     }
 
+    /**
+     * Add a click listener to the layout. The listener is called whenever the
+     * user clicks inside the layout. Also when the click targets a component
+     * inside the Panel, provided the targeted component does not prevent the
+     * click event from propagating. A caption is not considered part of a
+     * component.
+     * 
+     * The child component that was clicked is included in the
+     * {@link LayoutClickEvent}.
+     * 
+     * Use {@link #removeListener(LayoutClickListener)} to remove the listener.
+     * 
+     * @param listener
+     *            The listener to add
+     */
     public void addListener(LayoutClickListener listener) {
         addListener(CLICK_EVENT, LayoutClickEvent.class, listener,
                 LayoutClickListener.clickMethod);
     }
 
+    /**
+     * Remove a click listener from the layout. The listener should earlier have
+     * been added using {@link #addListener(LayoutClickListener)}.
+     * 
+     * @param listener
+     *            The listener to remove
+     */
     public void removeListener(LayoutClickListener listener) {
         removeListener(CLICK_EVENT, LayoutClickEvent.class, listener);
     }
diff --git a/src/com/vaadin/ui/AbstractOrderedLayout.java b/src/com/vaadin/ui/AbstractOrderedLayout.java
index 2a6bd84771..dc722bbd12 100644
--- a/src/com/vaadin/ui/AbstractOrderedLayout.java
+++ b/src/com/vaadin/ui/AbstractOrderedLayout.java
@@ -330,11 +330,33 @@ public abstract class AbstractOrderedLayout extends AbstractLayout implements
         fireEvent(new LayoutClickEvent(this, mouseDetails, childComponent));
     }
 
+    /**
+     * Add a click listener to the layout. The listener is called whenever the
+     * user clicks inside the layout. Also when the click targets a component
+     * inside the Panel, provided the targeted component does not prevent the
+     * click event from propagating. A caption is not considered part of a
+     * component.
+     * 
+     * The child component that was clicked is included in the
+     * {@link LayoutClickEvent}.
+     * 
+     * Use {@link #removeListener(LayoutClickListener)} to remove the listener.
+     * 
+     * @param listener
+     *            The listener to add
+     */
     public void addListener(LayoutClickListener listener) {
         addListener(CLICK_EVENT, LayoutClickEvent.class, listener,
                 LayoutClickListener.clickMethod);
     }
 
+    /**
+     * Remove a click listener from the layout. The listener should earlier have
+     * been added using {@link #addListener(LayoutClickListener)}.
+     * 
+     * @param listener
+     *            The listener to remove
+     */
     public void removeListener(LayoutClickListener listener) {
         removeListener(CLICK_EVENT, LayoutClickEvent.class, listener);
     }
diff --git a/src/com/vaadin/ui/Embedded.java b/src/com/vaadin/ui/Embedded.java
index 7d5d7ff144..298953d1b1 100644
--- a/src/com/vaadin/ui/Embedded.java
+++ b/src/com/vaadin/ui/Embedded.java
@@ -420,11 +420,28 @@ public class Embedded extends AbstractComponent {
         }
     }
 
+    /**
+     * Add a click listener to the component. The listener is called whenever
+     * the user clicks inside the component. Depending on the content the event
+     * may be blocked and in that case no event is fired.
+     * 
+     * Use {@link #removeListener(ClickListener)} to remove the listener.
+     * 
+     * @param listener
+     *            The listener to add
+     */
     public void addListener(ClickListener listener) {
         addListener(CLICK_EVENT, ClickEvent.class, listener,
                 ClickListener.clickMethod);
     }
 
+    /**
+     * Remove a click listener from the component. The listener should earlier
+     * have been added using {@link #addListener(ClickListener)}.
+     * 
+     * @param listener
+     *            The listener to remove
+     */
     public void removeListener(ClickListener listener) {
         removeListener(CLICK_EVENT, ClickEvent.class, listener);
     }
diff --git a/src/com/vaadin/ui/GridLayout.java b/src/com/vaadin/ui/GridLayout.java
index 602703980e..856565194c 100644
--- a/src/com/vaadin/ui/GridLayout.java
+++ b/src/com/vaadin/ui/GridLayout.java
@@ -1322,11 +1322,33 @@ public class GridLayout extends AbstractLayout implements
         fireEvent(new LayoutClickEvent(this, mouseDetails, childComponent));
     }
 
+    /**
+     * Add a click listener to the layout. The listener is called whenever the
+     * user clicks inside the layout. Also when the click targets a component
+     * inside the Panel, provided the targeted component does not prevent the
+     * click event from propagating. A caption is not considered part of a
+     * component.
+     * 
+     * The child component that was clicked is included in the
+     * {@link LayoutClickEvent}.
+     * 
+     * Use {@link #removeListener(LayoutClickListener)} to remove the listener.
+     * 
+     * @param listener
+     *            The listener to add
+     */
     public void addListener(LayoutClickListener listener) {
         addListener(CLICK_EVENT, LayoutClickEvent.class, listener,
                 LayoutClickListener.clickMethod);
     }
 
+    /**
+     * Remove a click listener from the layout. The listener should earlier have
+     * been added using {@link #addListener(LayoutClickListener)}.
+     * 
+     * @param listener
+     *            The listener to remove
+     */
     public void removeListener(LayoutClickListener listener) {
         removeListener(CLICK_EVENT, LayoutClickEvent.class, listener);
     }
diff --git a/src/com/vaadin/ui/Panel.java b/src/com/vaadin/ui/Panel.java
index 789fca5fea..d21de3d313 100644
--- a/src/com/vaadin/ui/Panel.java
+++ b/src/com/vaadin/ui/Panel.java
@@ -553,11 +553,29 @@ public class Panel extends AbstractComponentContainer implements Scrollable,
         }
     }
 
+    /**
+     * Add a click listener to the Panel. The listener is called whenever the
+     * user clicks inside the Panel. Also when the click targets a component
+     * inside the Panel, provided the targeted component does not prevent the
+     * click event from propagating.
+     * 
+     * Use {@link #removeListener(ClickListener)} to remove the listener.
+     * 
+     * @param listener
+     *            The listener to add
+     */
     public void addListener(ClickListener listener) {
         addListener(CLICK_EVENT, ClickEvent.class, listener,
                 ClickListener.clickMethod);
     }
 
+    /**
+     * Remove a click listener from the Panel. The listener should earlier have
+     * been added using {@link #addListener(ClickListener)}.
+     * 
+     * @param listener
+     *            The listener to remove
+     */
     public void removeListener(ClickListener listener) {
         removeListener(CLICK_EVENT, ClickEvent.class, listener);
     }