From: Marko Grönroos Date: Tue, 9 Mar 2010 17:23:03 +0000 (+0000) Subject: Revised JavaDoc documentation for Component (#4244). X-Git-Tag: 6.7.0.beta1~1959 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=01c553a622ed2e7b81f7382cb914eb092c89147e;p=vaadin-framework.git Revised JavaDoc documentation for Component (#4244). svn changeset:11734/svn branch:6.3 --- diff --git a/src/com/vaadin/ui/Component.java b/src/com/vaadin/ui/Component.java index 61df5164df..9549738aee 100644 --- a/src/com/vaadin/ui/Component.java +++ b/src/com/vaadin/ui/Component.java @@ -11,6 +11,7 @@ import java.util.EventObject; import java.util.Locale; import com.vaadin.Application; +import com.vaadin.data.Property; import com.vaadin.terminal.ErrorMessage; import com.vaadin.terminal.Paintable; import com.vaadin.terminal.Resource; @@ -18,8 +19,32 @@ import com.vaadin.terminal.Sizeable; import com.vaadin.terminal.VariableOwner; /** - * The top-level component interface which must be implemented by all UI - * components that use Vaadin. + * {@code Component} is the top-level interface that is and must be implemented + * by all Vaadin components. {@code Component} is paired with + * {@link AbstractComponent}, which provides a default implementation for all + * the methods defined in this interface. + * + *

+ * Components are laid out in the user interface hierarchically. The layout is + * managed by layout components, or more generally by components that implement + * the {@link ComponentContainer} interface. Such a container is the + * parent of the contained components. + *

+ * + *

+ * 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 + * {@link ComponentContainer#addComponent(Component) addComponent()} method of + * the {@code ComponentContainer} interface, which automatically sets the + * parent. + *

+ * + *

+ * A component becomes attached to an application (and the + * {@link #attach()} is called) when it or one of its parents is attached to the + * main window of the application through its containment hierarchy. + *

* * @author IT Mill Ltd. * @version @@ -30,243 +55,588 @@ public interface Component extends Paintable, VariableOwner, Sizeable, Serializable { /** - * Gets style for component. Multiple styles are joined with spaces. + * Gets all user-defined CSS style names of a component. If the component + * has multiple style names defined, the return string is a space-separated + * list of style names. Built-in style names defined in Vaadin or GWT are + * not returned. + * + *

+ * The style names are returned only in the basic form in which they were + * added; each user-defined style name shows as two CSS style class names in + * the rendered HTML: one as it was given and one prefixed with the + * component-specific style name. Only the former is returned. + *

* - * @return the component's styleValue of property style. + * @return the style name or a space-separated list of user-defined style + * names of the component + * @see #setStyleName(String) + * @see #addStyleName(String) + * @see #removeStyleName(String) */ public String getStyleName(); /** - * Sets and replaces all previous style names of the component. This method - * will trigger a {@link com.vaadin.terminal.Paintable.RepaintRequestEvent + * Sets one or more user-defined style names of the component, replacing any + * previous user-defined styles. Multiple styles can be specified as a + * space-separated list of style names. The style names must be valid CSS + * class names and should not conflict with any built-in style names in + * Vaadin or GWT. + * + * 
+     * Label label = new Label("This text has a lot of style");
+     * label.setStyleName("myonestyle myotherstyle");
+     *
+ * + *

+ * Each style name will occur in two versions: one as specified and one that + * is prefixed with the style name of the component. For example, if you + * have a {@code Button} component and give it "{@code mystyle}" style, the + * component will have both "{@code mystyle}" and "{@code v-button-mystyle}" + * styles. You could then style the component either with: + *

+ * + * 
+     * .myonestyle {background: blue;}
+     *
+ * + *

+ * or + *

+ * + * 
+     * .v-button-myonestyle {background: blue;}
+     *
+ * + *

+ * It is normally a good practice to use {@link #addStyleName(String) + * addStyleName()} rather than this setter, as different software + * abstraction layers can then add their own styles without accidentally + * removing those defined in other layers. + *

+ * + *

+ * This method will trigger a + * {@link com.vaadin.terminal.Paintable.RepaintRequestEvent * RepaintRequestEvent}. + *

* * @param style - * the new style of the component. + * the new style or styles of the component as a space-separated + * list + * @see #getStyleName() + * @see #addStyleName(String) + * @see #removeStyleName(String) */ public void setStyleName(String style); /** - * Adds style name to component. Handling additional style names is terminal - * specific, but in web browser environment they will most likely become CSS - * classes as given on server side. + * Adds a style name to component. The style name will be rendered as a HTML + * class name, which can be used in a CSS definition. + * + * 
+     * Label label = new Label("This text has style");
+     * label.addStyleName("mystyle");
+     *
+ * + *

+ * Each style name will occur in two versions: one as specified and one that + * is prefixed wil the style name of the component. For example, if you have + * a {@code Button} component and give it "{@code mystyle}" style, the + * component will have both "{@code mystyle}" and "{@code v-button-mystyle}" + * styles. You could then style the component either with: + *

+ * + * 
+     * .mystyle {font-style: italic;}
+     *
* + *

+ * or + *

+ * + * 
+     * .v-button-mystyle {font-style: italic;}
+     *
+ * + *

* This method will trigger a * {@link com.vaadin.terminal.Paintable.RepaintRequestEvent * RepaintRequestEvent}. + *

* * @param style * the new style to be added to the component + * @see #getStyleName() + * @see #setStyleName(String) + * @see #removeStyleName(String) */ public void addStyleName(String style); /** - * Removes given style name from component. + * Removes the given style name from component. + * + *

+ * The parameter must be a valid CSS style name. Only user-defined style + * names added with {@link #addStyleName(String) addStyleName()} or + * {@link #setStyleName(String) setStyleName()} can be removed; built-in + * style names defined in Vaadin or GWT can not be removed. + *

* * @param style - * the style to be removed + * the style name to be removed + * @see #getStyleName() + * @see #setStyleName(String) + * @see #addStyleName(String) */ public void removeStyleName(String style); /** - *

- * Tests if the component is enabled or not. All the variable change events - * are blocked from disabled components. Also the component should visually - * indicate that it is disabled (by shading the component for example). All - * hidden (isVisible() == false) components must return false. - *

- * - *

- * Note The component is considered disabled if it's parent is - * disabled. - *

+ * Tests whether the component is enabled or not. A user can not interact + * with disabled components. Disabled components are rendered in a style + * that indicates the status, usually in gray color. Children of a disabled + * component are also disabled. Components are enabled by default. * *

- * Components should be enabled by default. + * As a security feature, all variable change events for disabled components + * are blocked on the server-side. *

* - * @return true if the component, and it's parent, is enabled + * @return true if the component and its parent are enabled, * false otherwise. * @see VariableOwner#isEnabled() */ public boolean isEnabled(); /** - * Enables or disables the component. Being enabled means that the component - * can be edited. This method will trigger a - * {@link com.vaadin.terminal.Paintable.RepaintRequestEvent - * RepaintRequestEvent}. - * - *

- * Note that after enabling a component, {@link #isEnabled()} might - * still return false if the parent is disabled. - *

+ * Enables or disables the component. The user can not interact disabled + * components, which are shown with a style that indicates the status, + * usually shaded in light gray color. Components are enabled by default. + * Children of a disabled component are automatically disabled; if a child + * component is explicitly set as disabled, changes in the disabled status + * of its parents do not change its status. + * + * 
+     * Button enabled = new Button("Enabled");
+     * enabled.setEnabled(true); // The default
+     * layout.addComponent(enabled);
+     * 
+     * Button disabled = new Button("Disabled");
+     * disabled.setEnabled(false);
+     * layout.addComponent(disabled);
+     *
* *

- * Also note that if the component contains child-components, it - * should recursively call requestRepaint() for all descendant components. + * This method will trigger a + * {@link com.vaadin.terminal.Paintable.RepaintRequestEvent + * RepaintRequestEvent} for the component and, if it is a + * {@link ComponentContainer}, for all its children recursively. *

* * @param enabled - * the boolean value specifying if the component should be - * enabled after the call or not + * a boolean value specifying if the component should be enabled + * or not */ public void setEnabled(boolean enabled); /** - * Tests the components visibility. Visibility defines if the component is - * drawn when updating UI. Default is true. + * Tests the visibility property of the component. * *

- * Note that to return true, this component and all its parents must - * be visible. + * Visible components are drawn in the user interface, while invisible ones + * are not. The effect is not merely a cosmetic CSS change, but the entire + * HTML element will be empty. Making a component invisible through this + * property can alter the positioning of other components. + *

* *

- * Also note that this method does not check if component is attached - * and shown to user. Component and all its parents may be visible, but not - * necessary attached to application. To test if component will be drawn, - * check its visibility and that {@link Component#getApplication()} does not - * return null. + * A component is visible only if all its parents are also visible. Notice + * that if a child component is explicitly set as invisible, changes in the + * visibility status of its parents do not change its status. + *

* - * @return true if the component is visible in the UI, - * false if not + *

+ * This method does not check whether the component is attached (see + * {@link #attach()}). The component and all its parents may be considered + * "visible", but not necessarily attached to application. To test if + * component will actually be drawn, check both its visibility and that + * {@link #getApplication()} does not return {@code null}. + *

+ * + * @return true if the component is visible in the user + * interface, false if not + * @see #setVisible(boolean) + * @see #attach() */ public boolean isVisible(); /** - * Sets this components visibility status. Visibility defines if the - * component is shown in the UI or not. + * Sets the visibility of the component. + * *

- * Note that to be shown in UI this component and all its parents - * must be visible. + * Visible components are drawn in the user interface, while invisible ones + * are not. The effect is not merely a cosmetic CSS change, but the entire + * HTML element will be empty. + *

+ * + * 
+     * TextField readonly = new TextField("Read-Only");
+     * readonly.setValue("You can't see this!");
+     * readonly.setVisible(false);
+     * layout.addComponent(readonly);
+     *
+ * + *

+ * A component is visible only if all of its parents are also visible. If a + * component is explicitly set to be invisible, changes in the visibility of + * its parents will not change the visibility of the component. + *

* * @param visible * the boolean value specifying if the component should be * visible after the call or not. + * @see #isVisible() */ public void setVisible(boolean visible); /** - * Gets the visual parent of the component. The components can be nested but - * one component can have only one parent. + * Gets the parent component of the component. * - * @return the parent component. + *

+ * Components can be nested but a component can have only one parent. A + * component that contains other components, that is, can be a parent, + * should usually inherit the {@link ComponentContainer} interface. + *

+ * + * @return the parent component + * @see #setParent(Component) */ public Component getParent(); /** - * Sets the component's parent component. + * Sets the parent component of the component. + * + *

+ * This method automatically calls {@link #attach()} if the parent becomes + * attached to the application, regardless of whether it was attached + * previously. Conversely, if the parent is {@code null} and the component + * is attached to the application, {@link #detach()} is called for the + * component. + *

* *

- * This method calls automatically {@link #attach()} if the parent is - * attached to a window (or is itself a window}, and {@link #detach()} if - * parent is set null, but the component was in - * the application. + * This method is rarely called directly. The + * {@link ComponentContainer#addComponent(Component)} method is normally + * used for adding components to a container and it will call this method + * implicitly. *

* *

- * This method is rarely called directly. Instead the - * {@link ComponentContainer#addComponent(Component)} method is used to add - * components to container, which call this method implicitly. + * It is not possible to change the parent without first setting the parent + * to {@code null}. + *

* * @param parent - * the new parent component. + * the parent component + * @throws IllegalStateException + * if a parent is given even though the component already has a + * parent */ public void setParent(Component parent); /** - * Tests if the component is in read-only mode. + * Tests whether the component is in the read-only mode. The user can not + * change the value of a read-only component. As only {@link Field} + * components normally have a value that can be input or changed by the + * user, this is mostly relevant only to field components, though not + * restricted to them. * - * @return true if the component is in read-only mode, - * false if not. + *

+ * Notice that the read-only mode only affects whether the user can change + * the value of the component; it is possible to, for example, scroll + * a read-only table. + *

+ * + *

+ * The read-only status affects only the user; the value can still be + * changed programmatically, for example, with + * {@link Property#setValue(Object)}. + *

+ * + *

+ * The method will return {@code true} if the component or any of its + * parents is in the read-only mode. + *

+ * + * @return true if the component or any of its parents is in + * read-only mode, false if not. + * @see #setReadOnly(boolean) */ public boolean isReadOnly(); /** - * Sets the component's to read-only mode to the specified state. This - * method will trigger a + * Sets the read-only mode of the component to the specified mode. The user + * can not change the value of a read-only component. + * + *

+ * As only {@link Field} components normally have a value that can be input + * or changed by the user, this is mostly relevant only to field components, + * though not restricted to them. + *

+ * + *

+ * Notice that the read-only mode only affects whether the user can change + * the value of the component; it is possible to, for example, scroll + * a read-only table. + *

+ * + *

+ * The read-only status affects only the user; the value can still be + * changed programmatically, for example, with + * {@link Property#setValue(Object)}. + *

+ * + *

+ * This method will trigger a * {@link com.vaadin.terminal.Paintable.RepaintRequestEvent * RepaintRequestEvent}. + *

* * @param readOnly - * the boolean value specifying if the component should be in - * read-only mode after the call or not. + * a boolean value specifying whether the component is put + * read-only mode or not */ public void setReadOnly(boolean readOnly); /** - * Gets the caption of the component. Caption is the visible name of the - * component. + * Gets the caption of the component. See {@link #setCaption(String)} for a + * detailed description of the caption. * - * @return the component's caption String. + * @return the caption of the component or {@code null} if the caption is + * not set. */ public String getCaption(); /** - * Sets the component's caption String. Caption is the visible - * name of the component. This method will trigger a + * Sets the caption of the component. + * + *

+ * A caption is an explanatory textual label accompanying a user + * interface component, usually shown above, left of, or inside the + * component. Icon (see {@link #setIcon(Resource) setIcon()} is + * closely related to caption and is usually displayed horizontally before + * or after it, depending on the component and the containing layout. + *

+ * + *

+ * The caption can usually also be given as the first parameter to a + * constructor, though some components do not support it. + *

+ * + * 
+     * RichTextArea area = new RichTextArea();
+     * area.setCaption("You can edit stuff here");
+     * area.setValue("<h1>Helpful Heading</h1>" + "<p>All this is for you to edit.</p>");
+     *
+ * + *

+ * The contents of a caption are automatically quoted, so no raw XHTML can + * be rendered in a caption. The validity of the used character encoding, + * usually UTF-8, is not checked. + *

+ * + *

+ * The caption of a component is, by default, managed and displayed by the + * layout component or component container in which the component is placed. + * For example, the {@link VerticalLayout} component shows the captions + * left-aligned above the contained components, while the {@link FormLayout} + * component shows the captions on the left side of the vertically laid + * components, with the captions and their associated components + * left-aligned in their own columns. The {@link CustomComponent} does not + * manage the caption of its composition root, so if the root component has + * a caption, it will not be rendered. Some components, such as + * {@link Button} and {@link Panel}, manage the caption themselves and + * display it inside the component. + *

+ * + * This method will trigger a * {@link com.vaadin.terminal.Paintable.RepaintRequestEvent - * RepaintRequestEvent}. + * RepaintRequestEvent}. A reimplementation should call the superclass + * implementation. * * @param caption - * the new caption String for the component. + * the new caption for the component. If the caption is {@code + * null}, no caption is shown and it does not normally take any + * space */ public void setCaption(String caption); /** - * Gets the component's icon. A component may have a graphical icon - * associated with it, this method retrieves it if it is defined. + * Gets the icon of the component. See {@link #setIcon(Resource)} for a + * detailed description of the icon. * - * @return the component's icon or null if it not defined. + * @return the icon resource of the component or {@code null} if the + * component has no icon + * @see #setIcon(Resource) */ public Resource getIcon(); /** - * Sets the component's icon. This method will trigger a + * Sets the icon of the component. + * + *

+ * An icon is an explanatory graphical label accompanying a user interface + * component, usually shown above, left of, or inside the component. Icon is + * closely related to caption (see {@link #setCaption(String) setCaption()}) + * and is usually displayed horizontally before or after it, depending on + * the component and the containing layout. + *

+ * + *

+ * The image is loaded by the browser from a resource, typically a + * {@link com.vaadin.terminal.ThemeResource}. + *

+ * + * 
+     * // Component with an icon from a custom theme
+     * TextField name = new TextField("Name");
+     * name.setIcon(new ThemeResource("icons/user.png"));
+     * layout.addComponent(name);
+     * 
+     * // Component with an icon from another theme ('runo')
+     * Button ok = new Button("OK");
+     * ok.setIcon(new ThemeResource("../runo/icons/16/ok.png"));
+     * layout.addComponent(ok);
+     *
+ * + *

+ * The icon of a component is, by default, managed and displayed by the + * layout component or component container in which the component is placed. + * For example, the {@link VerticalLayout} component shows the icons + * left-aligned above the contained components, while the {@link FormLayout} + * component shows the icons on the left side of the vertically laid + * components, with the icons and their associated components left-aligned + * in their own columns. The {@link CustomComponent} does not manage the + * icon of its composition root, so if the root component has an icon, it + * will not be rendered. + *

+ * + *

+ * An icon will be rendered inside an HTML element that has the {@code + * v-icon} CSS style class. The containing layout may enclose an icon and a + * caption inside elements related to the caption, such as {@code v-caption} + * . + *

+ * + * This method will trigger a * {@link com.vaadin.terminal.Paintable.RepaintRequestEvent * RepaintRequestEvent}. * * @param icon - * the icon to be shown with the component's caption. + * the icon of the component. If null, no icon is shown and it + * does not normally take any space. + * @see #getIcon() + * @see #setCaption(String) */ public void setIcon(Resource icon); /** - * Gets the component's parent window. If the component does not yet belong - * to a window null is returned. + * Gets the parent window of the component. + * + *

+ * If the component is not attached to a window through a component + * containment hierarchy, null is returned. + *

+ * + *

+ * The window can be either an application-level window or a sub-window. If + * the component is itself a window, it returns a reference to itself, not + * to its containing window (of a sub-window). + *

* - * @return the parent window of the component or null. + * @return the parent window of the component or null if it is + * not attached to a window or is itself a window */ public Window getWindow(); /** - * Gets the component's parent application. If the component does not yet - * belong to a application null is returned. + * Gets the application object to which the component is attached. + * + *

+ * The method will return {@code null} if the component has not yet been + * attached to an application. + *

* * @return the parent application of the component or null. + * @see #attach() */ public Application getApplication(); /** + * Notifies the component that it is connected to an application. + * *

- * Notifies the component that it is connected to an application. This - * method is always called before the component is first time painted and is - * suitable to be extended. The getApplication and - * getWindow methods might return null before this - * method is called. + * The caller of this method is {@link #setParent(Component)} if the parent + * is itself already attached to the application. If not, the parent will + * call the {@link #attach()} for all its children when it is attached to + * the application. This method is always called before the component is + * painted for the first time. *

* *

- * The caller of this method is {@link #setParent(Component)} if the parent - * is already in the application. If the parent is not in the application, - * it must call the {@link #attach()} for all its children when it will be - * added to the application. + * Reimplementing the {@code attach()} method is useful for tasks that need + * to get a reference to the parent, window, or application object with the + * {@link #getParent()}, {@link #getWindow()}, and {@link #getApplication()} + * methods. A component does not yet know these objects in the constructor, + * so in such case, the methods will return {@code null}. For example, the + * following is invalid: + *

+ * + * 
+     * public class AttachExample extends CustomComponent {
+     *     public AttachExample() {
+     *         // ERROR: We can't access the application object yet.
+     *         ClassResource r = new ClassResource("smiley.jpg", getApplication());
+     *         Embedded image = new Embedded("Image:", r);
+     *         setCompositionRoot(image);
+     *     }
+     * }
+     *
+ * + *

+ * Adding a component to an application triggers calling the + * {@link #attach()} method for the component. Correspondingly, removing a + * component from a container triggers calling the {@link #detach()} method. + * If the parent of an added component is already connected to the + * application, the {@code attach()} is called immediately from + * {@link #setParent(Component)}. + *

+ * + * 
+     * public class AttachExample extends CustomComponent {
+     *     public AttachExample() {
+     *     }
+     * 
+     *     @Override
+     *     public void attach() {
+     *         super.attach(); // Must call.
+     * 
+     *         // Now we know who ultimately owns us.
+     *         ClassResource r = new ClassResource("smiley.jpg", getApplication());
+     *         Embedded image = new Embedded("Image:", r);
+     *         setCompositionRoot(image);
+     *     }
+     * }
+     *
+ * + *

+ * The attachment logic is implemented in {@link AbstractComponent}. *

*/ public void attach(); /** * Notifies the component that it is detached from the application. + * *

* The {@link #getApplication()} and {@link #getWindow()} methods might * return null after this method is called. @@ -309,7 +679,7 @@ public interface Component extends Paintable, VariableOwner, Sizeable, * collection. */ public void childRequestedRepaint( - Collection alreadyNotified); + Collection alreadyNotified); /* Component event framework */ diff --git a/src/com/vaadin/ui/package.html b/src/com/vaadin/ui/package.html index 6629060a49..6b19a28fe7 100644 --- a/src/com/vaadin/ui/package.html +++ b/src/com/vaadin/ui/package.html @@ -16,52 +16,56 @@

The general interface hierarchy looks like this:

-

- -

Note that the above picture includes only the main interfaces. This -package includes several other lesser subinterfaces which are not -significant in this scope. The interfaces not appearing here are documented -with the classes that define them.

- -

The {@link com.vaadin.ui.Component) interface is the top-level -interface which must be implemented by all UI components. It defines the -common properties of the components and how the framework will handle -them. Most simple components (like {@link com.vaadin.ui.Button} for -example} won't need to implement the lower level interfaces described -below. Note that the classes and interfaces required by the component event -framework are defined in {@link com.vaadin.ui.Component}.

- -

The next level in the component hierarchy are the classes implementing -the {@link com.vaadin.ui.ComponentContainer} interface. It adds the -capacity to contain other components to -{@link com.vaadin.ui.Component} with a simple API.

+

+ +

Note that the above picture includes only the main +interfaces. This package includes several other lesser sub-interfaces +which are not significant in this scope. The interfaces not appearing +here are documented with the classes that define them.

+ +

The {@link com.vaadin.ui.Component} interface is the top-level +interface which must be implemented by all user interface components in +Vaadin. It defines the common properties of the components and how the +framework will handle them. Most simple components, such as {@link +com.vaadin.ui.Button}, for example, do not need to implement the +lower-level interfaces described below. Notice that also the classes and +interfaces required by the component event framework are defined in +{@link com.vaadin.ui.Component}.

+ +

The next level in the component hierarchy are the classes +implementing the {@link com.vaadin.ui.ComponentContainer} interface. It +adds the capacity to contain other components to {@link +com.vaadin.ui.Component} with a simple API.

The third and last level is the {@link com.vaadin.ui.Layout}, which adds the concept of location to the components contained in a {@link com.vaadin.ui.ComponentContainer}. It can be used to create -containers whose contents can be positioned arbitrarily.

+containers which contents can be positioned.

Component class hierarchy

The actual component classes form a hierarchy like this:

-

+
+
Underlined classes are abstract.
-

At the top level is {@link com.vaadin.ui.AbstractComponent} -which implements the {@link com.vaadin.ui.Component} interface. As -the name suggests it is abstract, but it does include a default -implementation for all methods defined in Component so that -a component is free to override only those functionalities it needs.

- -

As seen in the picture, AbstractComponent serves as the -superclass for several "real" components, but it also has a some abstract -extensions. {@link com.vaadin.ui.AbstractComponentContainer} serves -as the root class for all components (for example, panels and windows) who -can contain other components. {@link com.vaadin.ui.AbstractField}, -on the other hand, implements several interfaces to provide a base class for -components that are used for data display and manipulation.

+

At the top level is {@link com.vaadin.ui.AbstractComponent} which +implements the {@link com.vaadin.ui.Component} interface. As the name +suggests it is abstract, but it does include a default implementation +for all methods defined in Component so that a component is +free to override only those functionalities it needs.

+ +

As seen in the picture, AbstractComponent serves as +the superclass for several "real" components, but it also has a some +abstract extensions. {@link com.vaadin.ui.AbstractComponentContainer} +serves as the root class for all components (for example, panels and +windows) who can contain other components. {@link +com.vaadin.ui.AbstractField}, on the other hand, implements several +interfaces to provide a base class for components that are used for data +display and manipulation.