From e5caa74cc45cdd63a0edae9989010699dfaea1be Mon Sep 17 00:00:00 2001 From: Artur Signell Date: Mon, 23 Nov 2009 14:15:17 +0000 Subject: [PATCH] Patch #4 from #3234 "JavaDoc and ClientEventList Update" svn changeset:9959/svn branch:event-framework-3234 --- src/com/vaadin/event/ClientEventList.java | 40 ++++++++++++--- src/com/vaadin/event/FieldEvents.java | 49 +++++++++++++++---- src/com/vaadin/event/MouseEvents.java | 35 +++++++++++-- .../gwt/client/ComponentEventHandler.java | 35 +++++++++++++ src/com/vaadin/ui/AbstractComponent.java | 19 +++++-- 5 files changed, 152 insertions(+), 26 deletions(-) diff --git a/src/com/vaadin/event/ClientEventList.java b/src/com/vaadin/event/ClientEventList.java index 633026ca8b..e2008085c4 100644 --- a/src/com/vaadin/event/ClientEventList.java +++ b/src/com/vaadin/event/ClientEventList.java @@ -9,11 +9,13 @@ import java.util.Map; /** * - * this class is used to store the registered events so a list of the required - * client event identifiers (that the client-side should listen for and send to - * the server-side) can be sent to the client-side via a variable. + * ClientEventList class used to store the registered events so a + * list of the required client event identifiers (that the client-side should + * listen for and send to the server-side) can be sent to the client-side via a + * variable. * * @author davengo GmbH (Germany/Berlin, www.davengo.com) + * @since 6.2 * */ public class ClientEventList { @@ -21,11 +23,15 @@ public class ClientEventList { /** * the list containing the registered client events (as strings for * client-side transfer) + * + * @since 6.2 */ private Map clientEvents = null; /** * initializes the list if necessary + * + * @since 6.2 */ private void checkList() { if (clientEvents == null) { @@ -40,14 +46,23 @@ public class ClientEventList { * * @param eventIdentifier * the identifier of the event to listen for + * + * @return true, if the event is newly added to the list
+ * false, if the list already contained the event (the internal + * counter was incremented) + * + * @since 6.2 */ - public void listenEvent(String eventIdentifier) { + public boolean listenEvent(String eventIdentifier) { checkList(); - if (!clientEvents.keySet().contains(eventIdentifier)) + if (!clientEvents.keySet().contains(eventIdentifier)) { clientEvents.put(eventIdentifier, 1); - else + return true; + } else { clientEvents.put(eventIdentifier, clientEvents.get(eventIdentifier) + 1); + return false; + } } /** @@ -58,19 +73,28 @@ public class ClientEventList { * * @param eventIdentifier * the identifier of the event to stop listening for + * @return true, if the event was removed from the list
+ * false, if the event is hold in list (the internal counter was + * greater than zero) */ - public void unlistenEvent(String eventIdentifier) { + public boolean unlistenEvent(String eventIdentifier) { checkList(); if (clientEvents.keySet().contains(eventIdentifier)) { clientEvents.put(eventIdentifier, clientEvents.get(eventIdentifier) - 1); - if (clientEvents.get(eventIdentifier) <= 0) + if (clientEvents.get(eventIdentifier) <= 0) { clientEvents.remove(eventIdentifier); + return true; + } + return false; } + return false; } /** * @return a string array containing all registered events + * + * @since 6.2 */ public String[] getEvents() { if (clientEvents == null) { diff --git a/src/com/vaadin/event/FieldEvents.java b/src/com/vaadin/event/FieldEvents.java index ab81ac85c0..3becb58aef 100644 --- a/src/com/vaadin/event/FieldEvents.java +++ b/src/com/vaadin/event/FieldEvents.java @@ -1,3 +1,7 @@ +/* +@ITMillApache2LicenseForJavaFiles@ + */ + package com.vaadin.event; import java.lang.reflect.Method; @@ -7,10 +11,12 @@ import com.vaadin.ui.Component; public interface FieldEvents { - /* - * component focus event and listener + /** + * FocusEvent class for holding additional event information. + * Fired when a Field receives keyboard focus. + * + * @since 6.2 */ - public class FocusEvent extends Component.Event { private static final long serialVersionUID = -7644184999481404162L; @@ -20,6 +26,13 @@ public interface FieldEvents { } } + /** + * FocusListener interface for listening for + * FocusEvent fired by a Field. + * + * @see FocusEvent + * @since 6.2 + */ public interface FocusListener extends ComponentEventListener { public static final Method focusMethod = ReflectTools.findMethod( @@ -34,10 +47,12 @@ public interface FieldEvents { public void focus(FocusEvent event); } - /* - * component blur event and listener + /** + * BlurEvent class for holding additional event information. + * Fired when a Field loses keyboard focus. + * + * @since 6.2 */ - public class BlurEvent extends Component.Event { private static final long serialVersionUID = -7644184999481404162L; @@ -47,6 +62,13 @@ public interface FieldEvents { } } + /** + * BlurListener interface for listening for + * BlurEvent fired by a Field. + * + * @see BlurEvent + * @since 6.2 + */ public interface BlurListener extends ComponentEventListener { public static final Method blurMethod = ReflectTools.findMethod( @@ -61,10 +83,12 @@ public interface FieldEvents { public void blur(BlurEvent event); } - /* - * component value change event + /** + * ValueChangeEvent class for holding additional event + * information. Fired when the value of a Field changes. + * + * @since 6.2 */ - public class ValueChangeEvent extends Component.Event { private static final long serialVersionUID = -7644184999481404162L; @@ -74,6 +98,13 @@ public interface FieldEvents { } } + /** + * ValueChangeListener interface for listening for + * ValueChangeEvent fired by a Field. + * + * @see ValueChangeEvent + * @since 6.2 + */ public interface ValueChangeListener extends ComponentEventListener { public static final Method valueChangeMethod = ReflectTools.findMethod( diff --git a/src/com/vaadin/event/MouseEvents.java b/src/com/vaadin/event/MouseEvents.java index 19fdff8cc4..bf417c1ebf 100644 --- a/src/com/vaadin/event/MouseEvents.java +++ b/src/com/vaadin/event/MouseEvents.java @@ -1,3 +1,7 @@ +/* +@ITMillApache2LicenseForJavaFiles@ + */ + package com.vaadin.event; import java.lang.reflect.Method; @@ -8,12 +12,18 @@ import com.vaadin.ui.Component; public interface MouseEvents { /** - * defines the clicked mouse button for a ComponentClickEvents + * defines the clicked mouse button for ClickEvents */ public enum MouseButton { LEFT, RIGHT, MIDDLE } + /** + * ClickEvent class for holding additional event information. + * Fired when the user clicks on a Component. + * + * @since 6.2 + */ public class ClickEvent extends Component.Event { private MouseButton mouseButton; @@ -37,6 +47,13 @@ public interface MouseEvents { } + /** + * ClickListener interface for listening for + * ClickEvent fired by a Component. + * + * @see ClickEvent + * @since 6.2 + */ public interface ClickListener extends ComponentEventListener { public static final Method clickMethod = ReflectTools.findMethod( @@ -51,10 +68,13 @@ public interface MouseEvents { public void click(ClickEvent event); } - /* - * component double click event + /** + * DoubleClickEvent class for holding additional event + * information. Fired when the user double-clicks on a + * Component. + * + * @since 6.2 */ - public class DoubleClickEvent extends Component.Event { private static final long serialVersionUID = -7644184999481404162L; @@ -64,6 +84,13 @@ public interface MouseEvents { } } + /** + * DoubleClickListener interface for listening for + * DoubleClickEvent fired by a Component. + * + * @see DoubleClickEvent + * @since 6.2 + */ public interface DoubleClickListener extends ComponentEventListener { public static final Method doubleClickMethod = ReflectTools.findMethod( diff --git a/src/com/vaadin/terminal/gwt/client/ComponentEventHandler.java b/src/com/vaadin/terminal/gwt/client/ComponentEventHandler.java index f309f79979..2df8f9bf11 100644 --- a/src/com/vaadin/terminal/gwt/client/ComponentEventHandler.java +++ b/src/com/vaadin/terminal/gwt/client/ComponentEventHandler.java @@ -12,6 +12,7 @@ import java.util.List; * class for event handlers used by ComponentEventHandler * * @author davengo GmbH (Germany/Berlin, www.davengo.com) + * @since 6.2 * */ public class ComponentEventHandler { @@ -23,6 +24,20 @@ public class ComponentEventHandler { private ComponentDetail detail; private ApplicationConnection client; + /** + * creates a new ComponentEventHandler instance for the given + * ComponentDetail and ApplicationConntection + * instance. + * + * @param detail + * the attached ComponentDetail + * @param client + * the ApplicationConnection for sending events + * + * @see ApplicationConnection + * @see ComponentDetail + * @since 6.2 + */ public ComponentEventHandler(ComponentDetail detail, ApplicationConnection client) { this.detail = detail; @@ -39,6 +54,7 @@ public class ComponentEventHandler { * the unique identifier for the event * @param parameters * the parameters for the event (can be null) + * @since 6.2 */ public void fireEvent(String eventIdentifier, String... parameters) { fireEvent(eventIdentifier, false, parameters); @@ -54,11 +70,24 @@ public class ComponentEventHandler { * the unique identifier for the event * @param parameters * the parameters for the event (can be null) + * @since 6.2 */ public void fireComponentEvent(String eventIdentifier, String... parameters) { fireEvent(eventIdentifier, true, parameters); } + /** + * Transmit the event to the Server (Fires a event which is transmitted to + * the server and passed on the the components handleEvent method) + * + * @param eventIdentifier + * the unique identifier for the event + * @param forceTransmission + * enforce the transmission to the server + * @param parameters + * the parameters for the event (can be null) + * @since 6.2 + */ private void fireEvent(String eventIdentifier, boolean forceTransmission, String... parameters) { @@ -86,6 +115,12 @@ public class ComponentEventHandler { } } + /** + * Registers the Events listened on the server-side from the UIDL + * + * @param componentUIDL + * @since 6.2 + */ void registerEventsFromUIDL(UIDL componentUIDL) { // read out the request event handlers diff --git a/src/com/vaadin/ui/AbstractComponent.java b/src/com/vaadin/ui/AbstractComponent.java index c624cf3224..ee07a560e4 100644 --- a/src/com/vaadin/ui/AbstractComponent.java +++ b/src/com/vaadin/ui/AbstractComponent.java @@ -688,7 +688,6 @@ public abstract class AbstractComponent implements Component, MethodEventSource target.addAttribute("description", getDescription()); } - // davengo GmbH: add client event variables String[] trigger = new String[] {}; String[] events = new String[] {}; if (clientEvents != null) { @@ -866,13 +865,15 @@ public abstract class AbstractComponent implements Component, MethodEventSource * event-api mechanism for listening on events. * * @param eventIdentifier + * @since 6.2 */ private void listenEvent(String eventIdentifier) { if (clientEvents == null) { clientEvents = new ClientEventList(); } - clientEvents.listenEvent(eventIdentifier); - requestRepaint(); + final boolean repaint = clientEvents.listenEvent(eventIdentifier); + if (repaint) + requestRepaint(); } /** @@ -886,11 +887,13 @@ public abstract class AbstractComponent implements Component, MethodEventSource * event-api mechanism for listening on events. * * @param eventIdentifier + * @since 6.2 */ private void unlistenEvent(String eventIdentifier) { if (clientEvents != null) { - clientEvents.unlistenEvent(eventIdentifier); - requestRepaint(); + final boolean repaint = clientEvents.unlistenEvent(eventIdentifier); + if (repaint) + requestRepaint(); } } @@ -957,6 +960,8 @@ public abstract class AbstractComponent implements Component, MethodEventSource * the object instance who owns the activation method. * @param method * the activation method. + * + * @since 6.2 */ protected void addEventListener(String eventIdentifier, Class eventType, Object object, Method method) { @@ -992,6 +997,8 @@ public abstract class AbstractComponent implements Component, MethodEventSource * @param target * the target object that has registered to listen to events of * type eventType with one or more methods. + * + * @since 6.2 */ protected void removeEventListener(String eventIdentifier, Class eventType, Object target) { @@ -1027,6 +1034,8 @@ public abstract class AbstractComponent implements Component, MethodEventSource * @param method * the method owned by target that's registered to * listen to events of type eventType. + * + * @since 6.2 */ protected void removeEventListener(String eventIdentifier, Class eventType, Object target, Method method) { -- 2.39.5