Updated fix to Issue 895.
Added more documentation to Delegating listeners.
Review by:jgw
git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@811 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/user/src/com/google/gwt/user/client/ui/DelegatingChangeListenerCollection.java b/user/src/com/google/gwt/user/client/ui/DelegatingChangeListenerCollection.java
index 445d805..b8c3a1c 100644
--- a/user/src/com/google/gwt/user/client/ui/DelegatingChangeListenerCollection.java
+++ b/user/src/com/google/gwt/user/client/ui/DelegatingChangeListenerCollection.java
@@ -17,13 +17,32 @@
package com.google.gwt.user.client.ui;
/**
- * {@link ClickListenerCollection} used to correctly hook up listeners which
+ * {@link ChangeListenerCollection} used to correctly hook up listeners which
* need to listen to events from another source.
+ * <p>
+ * For example, {@link Composite} widgets often need to listen to events
+ * generated on their wrapped widget. Upon the firing of a wrapped widget's
+ * event, the composite widget must fire its own listeners with itself as the
+ * source of the event. To use a {@link DelegatingChangeListenerCollection},
+ * simply use the {@link DelegatingChangeListenerCollection} instead of a
+ * {@link ChangeListenerCollection}. For example, in {@link SuggestBox}, the
+ * following code is used to listen to change events on the {@link SuggestBox}'s
+ * underlying widget.
+ * </p>
+ *
+ * <pre>
+ * public void addChangeListener(ChangeListener listener) {
+ * if (changeListeners == null) {
+ * changeListeners = new DelegatingChangeListenerCollection(this, box);
+ * }
+ * changeListeners.add(listener);
+ * }
+ *</pre>
*/
public class DelegatingChangeListenerCollection extends
ChangeListenerCollection implements ChangeListener {
- private Widget owner;
+ private final Widget owner;
/**
* Constructor for {@link DelegatingChangeListenerCollection}.
diff --git a/user/src/com/google/gwt/user/client/ui/DelegatingClickListenerCollection.java b/user/src/com/google/gwt/user/client/ui/DelegatingClickListenerCollection.java
index f10ca75..04ff9e7 100644
--- a/user/src/com/google/gwt/user/client/ui/DelegatingClickListenerCollection.java
+++ b/user/src/com/google/gwt/user/client/ui/DelegatingClickListenerCollection.java
@@ -19,12 +19,30 @@
/**
* {@link ClickListenerCollection} used to correctly hook up listeners which
* need to listen to events from another source.
+ * <p>
+ * For example, {@link Composite} widgets often need to listen to events
+ * generated on their wrapped widget. Upon the firing of a wrapped widget's
+ * event, the composite widget must fire its own listeners with itself as the
+ * source of the event. To use a {@link DelegatingClickListenerCollection},
+ * simply use the {@link DelegatingClickListenerCollection} instead of a
+ * {@link ClickListenerCollection}. For example, in {@link SuggestBox}, the
+ * following code is used to listen to click events on the {@link SuggestBox}'s
+ * underlying widget.
+ * </p>
*
+ * <pre>
+ * public void addClickListener(ClickListener listener) {
+ * if (clickListeners == null) {
+ * clickListeners = new DelegatingClickListenerCollection(this, box);
+ * }
+ * clickListeners.add(listener);
+ * }
+ *</pre>
*/
public class DelegatingClickListenerCollection extends ClickListenerCollection
implements ClickListener {
- private Widget owner;
+ private final Widget owner;
/**
* Constructor for {@link DelegatingClickListenerCollection}.
diff --git a/user/src/com/google/gwt/user/client/ui/DelegatingFocusListenerCollection.java b/user/src/com/google/gwt/user/client/ui/DelegatingFocusListenerCollection.java
index dda3e39..e10d687 100644
--- a/user/src/com/google/gwt/user/client/ui/DelegatingFocusListenerCollection.java
+++ b/user/src/com/google/gwt/user/client/ui/DelegatingFocusListenerCollection.java
@@ -19,12 +19,30 @@
/**
* {@link FocusListenerCollection} used to correctly hook up listeners which
* need to listen to events from another source.
+ * <p>
+ * For example, {@link Composite} widgets often need to listen to events
+ * generated on their wrapped widget. Upon the firing of a wrapped widget's
+ * event, the composite widget must fire its own listeners with itself as the
+ * source of the event. To use a {@link DelegatingFocusListenerCollection},
+ * simply use the {@link DelegatingFocusListenerCollection} instead of a
+ * {@link FocusListenerCollection}. For example, in {@link SuggestBox}, the
+ * following code is used to listen to focus events on the {@link SuggestBox}'s
+ * underlying widget.
+ * </p>
*
+ * <pre>
+ * public void addFocusListener(FocusListener listener) {
+ * if (focusListeners == null) {
+ * focusListeners = new DelegatingFocusListenerCollection(this, box);
+ * }
+ * focusListeners.add(listener);
+ * }
+ *</pre>
*/
public class DelegatingFocusListenerCollection extends FocusListenerCollection
implements FocusListener {
- private Widget owner;
+ private final Widget owner;
/**
* Constructor for {@link DelegatingFocusListenerCollection}. *
diff --git a/user/src/com/google/gwt/user/client/ui/DelegatingKeyboardListenerCollection.java b/user/src/com/google/gwt/user/client/ui/DelegatingKeyboardListenerCollection.java
index 3e362dd..bf0c803 100644
--- a/user/src/com/google/gwt/user/client/ui/DelegatingKeyboardListenerCollection.java
+++ b/user/src/com/google/gwt/user/client/ui/DelegatingKeyboardListenerCollection.java
@@ -20,11 +20,30 @@
* {@link KeyboardListenerCollection} used to correctly hook up event listeners
* to the composite's wrapped widget.
*
+ * <p>
+ * For example, {@link Composite} widgets often need to listen to events
+ * generated on their wrapped widget. Upon the firing of a wrapped widget's
+ * event, the composite widget must fire its own listeners with itself as the
+ * source of the event. To use a {@link DelegatingKeyboardListenerCollection},
+ * simply use the {@link DelegatingKeyboardListenerCollection} instead of a
+ * {@link KeyboardListenerCollection}. For example, in {@link SuggestBox}, the
+ * following code is used to listen to keyboard events on the {@link SuggestBox}'s
+ * underlying widget.
+ * </p>
+ *
+ * <pre>
+ * public void addKeyboardListener(KeyboardListener listener) {
+ * if (keyboardListeners == null) {
+ * keyboardListeners = new DelegatingKeyboardListenerCollection(this, box);
+ * }
+ * keyboardListeners.add(listener);
+ * }
+ *</pre>
*/
-public class DelegatingKeyboardListenerCollection extends KeyboardListenerCollection
- implements KeyboardListener {
+public class DelegatingKeyboardListenerCollection extends
+ KeyboardListenerCollection implements KeyboardListener {
- private Widget owner;
+ private final Widget owner;
/**
* Constructor for {@link DelegatingKeyboardListenerCollection}.
