From: Marko Grönroos
* The {@link #getParent()} method allows retrieving the parent component of a
* component. While there is a {@link #setParent(Component) setParent()}, you
- * rarely need it as you usually add components with the
+ * rarely need it as you normally add components with the
* {@link ComponentContainer#addComponent(Component) addComponent()} method of
- * the {@code ComponentContainer} interface, which automatically sets the
+ * the layout or other {@code ComponentContainer}, which automatically sets the
* parent.
*
+ * See {@link #setCaption(String)} for a detailed description of the
+ * caption.
+ *
+ * // Component for which the locale is meaningful
+ * InlineDateField date = new InlineDateField("Datum");
+ *
+ * // German language specified with ISO 639-1 language
+ * // code and ISO 3166-1 alpha-2 country code.
+ * date.setLocale(new Locale("de", "DE"));
+ *
+ * date.setResolution(DateField.RESOLUTION_DAY);
+ * layout.addComponent(date);
+ *
+
*
* @param locale
* the locale to become this component's locale.
diff --git a/src/com/vaadin/ui/Component.java b/src/com/vaadin/ui/Component.java
index 9549738aee..251a415e83 100644
--- a/src/com/vaadin/ui/Component.java
+++ b/src/com/vaadin/ui/Component.java
@@ -12,6 +12,7 @@ import java.util.Locale;
import com.vaadin.Application;
import com.vaadin.data.Property;
+import com.vaadin.event.FieldEvents;
import com.vaadin.terminal.ErrorMessage;
import com.vaadin.terminal.Paintable;
import com.vaadin.terminal.Resource;
@@ -34,9 +35,9 @@ import com.vaadin.terminal.VariableOwner;
*
* This method will trigger a * {@link com.vaadin.terminal.Paintable.RepaintRequestEvent * RepaintRequestEvent}. A reimplementation should call the superclass * implementation. + *
* * @param caption * the new caption for the component. If the caption is {@code @@ -471,8 +479,11 @@ public interface Component extends Paintable, VariableOwner, Sizeable, public void setCaption(String caption); /** - * Gets the icon of the component. See {@link #setIcon(Resource)} for a - * detailed description of the icon. + * Gets the icon resource of the component. + * + *+ * See {@link #setIcon(Resource)} for a detailed description of the icon. + *
* * @return the icon resource of the component or {@code null} if the * component has no icon @@ -563,7 +574,11 @@ public interface Component extends Paintable, VariableOwner, Sizeable, * ** The method will return {@code null} if the component has not yet been - * attached to an application. + * attached to an application. This is often a problem in constructors of + * regular components and in the initializers of custom composite + * components. A standard workaround is to move the problematic + * initialization to {@link #attach()}, as described in the documentation of + * the method. *
* * @return the parent application of the component ornull
.
@@ -631,6 +646,8 @@ public interface Component extends Paintable, VariableOwner, Sizeable,
* * The attachment logic is implemented in {@link AbstractComponent}. *
+ * + * @see #getApplication() */ public void attach(); @@ -652,31 +669,51 @@ public interface Component extends Paintable, VariableOwner, Sizeable, public void detach(); /** - * Gets the locale of this component. - * - * @return This component's locale. If this component does not have a - * locale, the locale of its parent is returned. Eventually locale - * of application is returned. If application does not have its own - * locale the locale is determined by - *Locale.getDefautlt
. Returns null if the component
- * does not have its own locale and has not yet been added to a
- * containment hierarchy such that the locale can be determined from
- * the containing parent.
+ * Gets the locale of the component.
+ *
+ *
+ * If a component does not have a locale set, the locale of its parent is
+ * returned, and so on. Eventually, if no parent has locale set, the locale
+ * of the application is returned. If the application does not have a locale
+ * set, it is determined by Locale.getDefault()
.
+ *
+ * As the component must be attached before its locale can be acquired, + * using this method in the internationalization of component captions, etc. + * is generally not feasible. For such use case, we recommend using an + * otherwise acquired reference to the application locale. + *
+ * + * @return Locale of this component or {@code null} if the component and + * none of its parents has a locale set and the component is not yet + * attached to an application. */ public Locale getLocale(); /** - * The children must call this method when they need repainting. The call - * must be made event in the case the children sent the repaint request - * themselves. + * The child components of the component must call this method when they + * need repainting. The call must be made even in the case in which the + * children sent the repaint request themselves. + * + *+ * A repaint request is ignored if the component is invisible. + *
+ * + *+ * This method is called automatically by {@link AbstractComponent}, which + * also provides a default implementation of it. As this is a somewhat + * internal feature, it is rarely necessary to reimplement this or call it + * explicitly. + *
* * @param alreadyNotified * the collection of repaint request listeners that have been * already notified by the child. This component should not - * renotify the listed listeners again. The container given as + * re-notify the listed listeners again. The container given as * parameter must be modifiable as the component might modify it - * and pass it forwards. Null parameter is interpreted as empty - * collection. + * and pass it forward. A {@code null} parameter is interpreted + * as an empty collection. */ public void childRequestedRepaint( CollectionEvent
s.
+ * Superclass of all component originated events.
+ *
+ * + * Events are the basis of all user interaction handling in Vaadin. To + * handle events, you provide a listener object that receives the events of + * the particular event type. + *
+ * + *+ * Button button = new Button("Click Me!"); + * button.addListener(new Button.ClickListener() { + * public void buttonClick(ClickEvent event) { + * getWindow().showNotification("Thank You!"); + * } + * }); + * layout.addComponent(button); + *+ * + *
+ * Notice that while each of the event types have their corresponding + * listener types; the listener interfaces are not required to inherit the + * {@code Component.Listener} interface. + *
+ * + * @see Component.Listener */ @SuppressWarnings("serial") public class Event extends EventObject { /** - * Constructs a new event with a specified source component. + * Constructs a new event with the specified source component. * * @param source - * the source component of the event. + * the source component of the event */ public Event(Component source) { super(source); } /** - * Gets the Component where the event occurred. + * Gets the component where the event occurred. * - * @return the Source of the event. + * @return the source component of the event */ public Component getComponent() { return (Component) getSource(); @@ -711,12 +772,89 @@ public interface Component extends Paintable, VariableOwner, Sizeable, /** * Listener interface for receivingComponent.Event
s.
+ *
+ * + * Listener interfaces are the basis of all user interaction handling in + * Vaadin. You have or create a listener object that receives the events. + * All event types have their corresponding listener types; they are not, + * however, required to inherit the {@code Component.Listener} interface, + * and they rarely do so. + *
+ * + *+ * This generic listener interface is useful typically when you wish to + * handle events from different component types in a single listener method + * ({@code componentEvent()}. If you handle component events in an anonymous + * listener class, you normally use the component specific listener class, + * such as {@link com.vaadin.ui.Button.ClickEvent}. + *
+ * + *+ * class Listening extends CustomComponent implements Listener { + * Button ok; // Stored for determining the source of an event + * + * Label status; // For displaying info about the event + * + * public Listening() { + * VerticalLayout layout = new VerticalLayout(); + * + * // Some miscellaneous component + * TextField name = new TextField("Say it all here"); + * name.addListener(this); + * name.setImmediate(true); + * layout.addComponent(name); + * + * // Handle button clicks as generic events instead + * // of Button.ClickEvent events + * ok = new Button("OK"); + * ok.addListener(this); + * layout.addComponent(ok); + * + * // For displaying information about an event + * status = new Label(""); + * layout.addComponent(status); + * + * setCompositionRoot(layout); + * } + * + * public void componentEvent(Event event) { + * // Act according to the source of the event + * if (event.getSource() == ok && event.getClass() == Button.ClickEvent.class) + * getWindow().showNotification("Click!"); + * + * // Display source component and event class names + * status.setValue("Event from " + event.getSource().getClass().getName() + ": " + event.getClass().getName()); + * } + * } + * + * Listening listening = new Listening(); + * layout.addComponent(listening); + *+ * + * @see Component#addListener(Listener) */ public interface Listener extends EventListener, Serializable { /** * Notifies the listener of a component event. * + *
+ * As the event can typically come from one of many source components, + * you may need to differentiate between the event source by component + * reference, class, etc. + *
+ * + *+ * public void componentEvent(Event event) { + * // Act according to the source of the event + * if (event.getSource() == ok && event.getClass() == Button.ClickEvent.class) + * getWindow().showNotification("Click!"); + * + * // Display source component and event class names + * status.setValue("Event from " + event.getSource().getClass().getName() + ": " + event.getClass().getName()); + * } + *+ * * @param event * the event that has occured. */ @@ -724,10 +862,54 @@ public interface Component extends Paintable, VariableOwner, Sizeable, } /** - * Registers a new component event listener for this component. + * Registers a new (generic) component event listener for the component. + * + *
+ * class Listening extends CustomComponent implements Listener { + * // Stored for determining the source of an event + * Button ok; + * + * Label status; // For displaying info about the event + * + * public Listening() { + * VerticalLayout layout = new VerticalLayout(); + * + * // Some miscellaneous component + * TextField name = new TextField("Say it all here"); + * name.addListener(this); + * name.setImmediate(true); + * layout.addComponent(name); + * + * // Handle button clicks as generic events instead + * // of Button.ClickEvent events + * ok = new Button("OK"); + * ok.addListener(this); + * layout.addComponent(ok); + * + * // For displaying information about an event + * status = new Label(""); + * layout.addComponent(status); + * + * setCompositionRoot(layout); + * } + * + * public void componentEvent(Event event) { + * // Act according to the source of the event + * if (event.getSource() == ok) + * getWindow().showNotification("Click!"); + * + * status.setValue("Event from " + event.getSource().getClass().getName() + ": " + event.getClass().getName()); + * } + * } + * + * Listening listening = new Listening(); + * layout.addComponent(listening); + ** * @param listener * the new Listener to be registered. + * @see Component.Event + * @see #removeListener(Listener) */ public void addListener(Component.Listener listener); @@ -737,11 +919,19 @@ public interface Component extends Paintable, VariableOwner, Sizeable, * * @param listener * the listener to be removed. + * @see #addListener(Listener) */ public void removeListener(Component.Listener listener); /** - * Class of all component originated
ErrorEvent
s.
+ * Class of all component originated error events.
+ *
+ * + * The component error event is normally fired by + * {@link AbstractComponent#setComponentError(ErrorMessage)}. The component + * errors are set by the framework in some situations and can be set by user + * code. They are indicated in a component with an error indicator. + *
*/ @SuppressWarnings("serial") public class ErrorEvent extends Event { @@ -786,30 +976,128 @@ public interface Component extends Paintable, VariableOwner, Sizeable, } /** - * Interface implemented by components which can obtain input focus. + * A sub-interface implemented by components that can obtain input focus. + * This includes all {@link Field} components as well as some other + * components, such as {@link Upload}. + * + *+ * Focus can be set with {@link #focus()}. This interface does not provide + * an accessor that would allow finding out the currently focused component; + * focus information can be acquired for some (but not all) {@link Field} + * components through the {@link com.vaadin.event.FieldEvents.FocusListener} + * and {@link com.vaadin.event.FieldEvents.BlurListener} interfaces. + *
+ * + * @see FieldEvents */ public interface Focusable extends Component { /** * Sets the focus to this component. + * + *+ * Form loginBox = new Form(); + * loginBox.setCaption("Login"); + * layout.addComponent(loginBox); + * + * // Create the first field which will be focused + * TextField username = new TextField("User name"); + * loginBox.addField("username", username); + * + * // Set focus to the user name + * username.focus(); + * + * TextField password = new TextField("Password"); + * loginBox.addField("password", password); + * + * Button login = new Button("Login"); + * loginBox.getFooter().addComponent(login); + *+ * + *
+ * Notice that this interface does not provide an accessor that would + * allow finding out the currently focused component. Focus information + * can be acquired for some (but not all) {@link Field} components + * through the {@link com.vaadin.event.FieldEvents.FocusListener} and + * {@link com.vaadin.event.FieldEvents.BlurListener} interfaces. + *
+ * + * @see com.vaadin.event.FieldEvents + * @see com.vaadin.event.FieldEvents.FocusEvent + * @see com.vaadin.event.FieldEvents.FocusListener + * @see com.vaadin.event.FieldEvents.BlurEvent + * @see com.vaadin.event.FieldEvents.BlurListener */ public void focus(); /** - * Gets the Tabulator index of this Focusable component. + * Gets the tabulator index of the {@code Focusable} component. * - * @return tab index set for this Focusable component + * @return tab index set for the {@code Focusable} component + * @see #setTabIndex(int) */ public int getTabIndex(); /** - * Sets the tab index of this field. The tab index property is used to - * specify the natural tab order of fields. + * Sets the tabulator index of the {@code Focusable} component. + * The tab index property is used to specify the order in which the + * fields are focused when the user presses the Tab key. Components with + * a defined tab index are focused sequentially first, and then the + * components with no tab index. + * + *+ * Form loginBox = new Form(); + * loginBox.setCaption("Login"); + * layout.addComponent(loginBox); + * + * // Create the first field which will be focused + * TextField username = new TextField("User name"); + * loginBox.addField("username", username); + * + * // Set focus to the user name + * username.focus(); + * + * TextField password = new TextField("Password"); + * loginBox.addField("password", password); + * + * Button login = new Button("Login"); + * loginBox.getFooter().addComponent(login); + * + * // An additional component which natural focus order would + * // be after the button. + * CheckBox remember = new CheckBox("Remember me"); + * loginBox.getFooter().addComponent(remember); + * + * username.setTabIndex(1); + * password.setTabIndex(2); + * remember.setTabIndex(3); // Different than natural place + * login.setTabIndex(4); + *+ * + *
+ * After all focusable user interface components are done, the browser + * can begin again from the component with the smallest tab index, or it + * can take the focus out of the page, for example, to the location bar. + *
+ * + *+ * If the tab index is not set (is set to zero), the default tab order + * is used. The order is somewhat browser-dependent, but generally + * follows the HTML structure of the page. + *
+ * + *+ * A negative value means that the component is completely removed from + * the tabulation order and can not be reached by pressing the Tab key + * at all. + *
* * @param tabIndex * the tab order of this component. Indexes usually start - * from 1. Negative value means that field is not wanted to - * tabbing sequence. + * from 1. Zero means that default tab order should be used. + * A negative value means that the field should not be + * included in the tabbing sequence. + * @see #getTabIndex() */ public void setTabIndex(int tabIndex);