diff options
| -rw-r--r-- | shared/src/com/vaadin/shared/annotations/DelegateToWidget.java | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/shared/src/com/vaadin/shared/annotations/DelegateToWidget.java b/shared/src/com/vaadin/shared/annotations/DelegateToWidget.java index ba661e3f32..9109162a31 100644 --- a/shared/src/com/vaadin/shared/annotations/DelegateToWidget.java +++ b/shared/src/com/vaadin/shared/annotations/DelegateToWidget.java @@ -19,11 +19,70 @@ import java.io.Serializable; import java.lang.annotation.ElementType; import java.lang.annotation.Target; +/** + * Signals that the property value from a state class should be forwarded to the + * Widget of the corresponding connector instance. + * <p> + * When this annotation is present on a field or on a setter method, the + * framework will call the corresponding setter in the Connector's Widget + * instance with the current state property value whenever it has been changed. + * This is happens after firing + * {@link com.vaadin.client.ConnectorHierarchyChangeEvent}s but before firing + * any {@link com.vaadin.client.communication.StateChangeEvent}. + * <p> + * Take for example a state class looking like this: + * + * <pre> + * public class MyComponentState extends AbstractComponentState { + * @DelegateToWidget + * public String myProperty; + * } + * </pre> + * + * Whenever <code>myProperty</code> is changed, the framework will call code + * like this: + * + * <pre> + * connector.getWidget().setMyProperty(connector.getState().myProperty); + * </pre> + * + * <p> + * By default, the Widget method to call is derived from the property name, but + * {@link #value()} in the annotation can be used to provide a custom method + * name, e.g. {@code @DelegateToWidget("someSpecialName")}. + * + * @since 7.0.0 + * @author Vaadin Ltd + */ @Target({ ElementType.METHOD, ElementType.FIELD }) public @interface DelegateToWidget { + /** + * Defines the name of the Widget method to call when the annotated state + * property has changed. If no value is defined, the method name will be + * derived from the property name, so e.g. a field named + * <code>myProperty</code> will delegate to a method named + * <code>setMyProperty</code>. + * + * @return the name of the method to delegate to, or empty string to use the + * default name + */ public String value() default ""; + /** + * Internal helper for handling default values in a uniform way both at + * runtime and during widgetset compilation. + */ public static class Helper implements Serializable { + /** + * Gets the name of the method to delegate to for a given property name + * and annotation value. + * + * @param propertyName + * the name of the delegated property + * @param annotationValue + * the {@link DelegateToWidget#value()} of the annotation + * @return the name of the method to delegate to + */ public static String getDelegateTarget(String propertyName, String annotationValue) { String name = annotationValue; |