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;
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.
+ *
+ * <p>
+ * 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
+ * <i>parent</i> of the contained components.
+ * </p>
+ *
+ * <p>
+ * 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.
+ * </p>
+ *
+ * <p>
+ * A component becomes <i>attached</i> 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.
+ * </p>
*
* @author IT Mill Ltd.
* @version
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.
+ *
+ * <p>
+ * 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.
+ * </p>
*
- * @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.
+ *
+ * <pre>
+ * Label label = new Label("This text has a lot of style");
+ * label.setStyleName("myonestyle myotherstyle");
+ * </pre>
+ *
+ * <p>
+ * 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:
+ * </p>
+ *
+ * <pre>
+ * .myonestyle {background: blue;}
+ * </pre>
+ *
+ * <p>
+ * or
+ * </p>
+ *
+ * <pre>
+ * .v-button-myonestyle {background: blue;}
+ * </pre>
+ *
+ * <p>
+ * 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.
+ * </p>
+ *
+ * <p>
+ * This method will trigger a
+ * {@link com.vaadin.terminal.Paintable.RepaintRequestEvent
* RepaintRequestEvent}.
+ * </p>
*
* @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.
+ *
+ * <pre>
+ * Label label = new Label("This text has style");
+ * label.addStyleName("mystyle");
+ * </pre>
+ *
+ * <p>
+ * 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:
+ * </p>
+ *
+ * <pre>
+ * .mystyle {font-style: italic;}
+ * </pre>
*
+ * <p>
+ * or
+ * </p>
+ *
+ * <pre>
+ * .v-button-mystyle {font-style: italic;}
+ * </pre>
+ *
+ * <p>
* This method will trigger a
* {@link com.vaadin.terminal.Paintable.RepaintRequestEvent
* RepaintRequestEvent}.
+ * </p>
*
* @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.
+ *
+ * <p>
+ * 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.
+ * </p>
*
* @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);
/**
- * <p>
- * 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.
- * </p>
- *
- * <p>
- * <b>Note</b> The component is considered disabled if it's parent is
- * disabled.
- * </p>
+ * 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.
*
* <p>
- * Components should be enabled by default.
+ * As a security feature, all variable change events for disabled components
+ * are blocked on the server-side.
* </p>
*
- * @return <code>true</code> if the component, and it's parent, is enabled
+ * @return <code>true</code> if the component and its parent are enabled,
* <code>false</code> 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}.
- *
- * <p>
- * <b>Note</b> that after enabling a component, {@link #isEnabled()} might
- * still return false if the parent is disabled.
- * </p>
+ * 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.
+ *
+ * <pre>
+ * Button enabled = new Button("Enabled");
+ * enabled.setEnabled(true); // The default
+ * layout.addComponent(enabled);
+ *
+ * Button disabled = new Button("Disabled");
+ * disabled.setEnabled(false);
+ * layout.addComponent(disabled);
+ * </pre>
*
* <p>
- * <b>Also note</b> 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.
* </p>
*
* @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 <code>true</code>.
+ * Tests the <i>visibility</i> property of the component.
*
* <p>
- * <b>Note</b> 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.
+ * </p>
*
* <p>
- * <b>Also note</b> 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 <code>null</code>.
+ * 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.
+ * </p>
*
- * @return <code>true</code> if the component is visible in the UI,
- * <code>false</code> if not
+ * <p>
+ * 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}.
+ * </p>
+ *
+ * @return <code>true</code> if the component is visible in the user
+ * interface, <code>false</code> 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.
+ *
* <p>
- * <b>Note</b> 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.
+ * </p>
+ *
+ * <pre>
+ * TextField readonly = new TextField("Read-Only");
+ * readonly.setValue("You can't see this!");
+ * readonly.setVisible(false);
+ * layout.addComponent(readonly);
+ * </pre>
+ *
+ * <p>
+ * 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.
+ * </p>
*
* @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.
+ * <p>
+ * 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.
+ * </p>
+ *
+ * @return the parent component
+ * @see #setParent(Component)
*/
public Component getParent();
/**
- * Sets the component's parent component.
+ * Sets the parent component of the component.
+ *
+ * <p>
+ * 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.
+ * </p>
*
* <p>
- * This method calls automatically {@link #attach()} if the parent is
- * attached to a window (or is itself a window}, and {@link #detach()} if
- * <code>parent</code> is set <code>null</code>, 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.
* </p>
*
* <p>
- * 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}.
+ * </p>
*
* @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 <code>true</code> if the component is in read-only mode,
- * <code>false</code> if not.
+ * <p>
+ * Notice that the read-only mode only affects whether the user can change
+ * the <i>value</i> of the component; it is possible to, for example, scroll
+ * a read-only table.
+ * </p>
+ *
+ * <p>
+ * The read-only status affects only the user; the value can still be
+ * changed programmatically, for example, with
+ * {@link Property#setValue(Object)}.
+ * </p>
+ *
+ * <p>
+ * The method will return {@code true} if the component or any of its
+ * parents is in the read-only mode.
+ * </p>
+ *
+ * @return <code>true</code> if the component or any of its parents is in
+ * read-only mode, <code>false</code> 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.
+ *
+ * <p>
+ * 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.
+ * </p>
+ *
+ * <p>
+ * Notice that the read-only mode only affects whether the user can change
+ * the <i>value</i> of the component; it is possible to, for example, scroll
+ * a read-only table.
+ * </p>
+ *
+ * <p>
+ * The read-only status affects only the user; the value can still be
+ * changed programmatically, for example, with
+ * {@link Property#setValue(Object)}.
+ * </p>
+ *
+ * <p>
+ * This method will trigger a
* {@link com.vaadin.terminal.Paintable.RepaintRequestEvent
* RepaintRequestEvent}.
+ * </p>
*
* @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 <code>String</code>.
+ * @return the caption of the component or {@code null} if the caption is
+ * not set.
*/
public String getCaption();
/**
- * Sets the component's caption <code>String</code>. Caption is the visible
- * name of the component. This method will trigger a
+ * Sets the caption of the component.
+ *
+ * <p>
+ * A <i>caption</i> is an explanatory textual label accompanying a user
+ * interface component, usually shown above, left of, or inside the
+ * component. <i>Icon</i> (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.
+ * </p>
+ *
+ * <p>
+ * The caption can usually also be given as the first parameter to a
+ * constructor, though some components do not support it.
+ * </p>
+ *
+ * <pre>
+ * 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>");
+ * </pre>
+ *
+ * <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.
+ * </p>
+ *
+ * <p>
+ * 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.
+ * </p>
+ *
+ * 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 <code>String</code> 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 <code>null</code> 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.
+ *
+ * <p>
+ * 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.
+ * </p>
+ *
+ * <p>
+ * The image is loaded by the browser from a resource, typically a
+ * {@link com.vaadin.terminal.ThemeResource}.
+ * </p>
+ *
+ * <pre>
+ * // 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);
+ * </pre>
+ *
+ * <p>
+ * 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.
+ * </p>
+ *
+ * <p>
+ * 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}
+ * .
+ * </p>
+ *
+ * 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 <code>null</code> is returned.
+ * Gets the parent window of the component.
+ *
+ * <p>
+ * If the component is not attached to a window through a component
+ * containment hierarchy, <code>null</code> is returned.
+ * </p>
+ *
+ * <p>
+ * 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).
+ * </p>
*
- * @return the parent window of the component or <code>null</code>.
+ * @return the parent window of the component or <code>null</code> 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 <code>null</code> is returned.
+ * Gets the application object to which the component is attached.
+ *
+ * <p>
+ * The method will return {@code null} if the component has not yet been
+ * attached to an application.
+ * </p>
*
* @return the parent application of the component or <code>null</code>.
+ * @see #attach()
*/
public Application getApplication();
/**
+ * Notifies the component that it is connected to an application.
+ *
* <p>
- * 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 <code>getApplication</code> and
- * <code>getWindow</code> methods might return <code>null</code> 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.
* </p>
*
* <p>
- * 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:
+ * </p>
+ *
+ * <pre>
+ * 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);
+ * }
+ * }
+ * </pre>
+ *
+ * <p>
+ * 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)}.
+ * </p>
+ *
+ * <pre>
+ * 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);
+ * }
+ * }
+ * </pre>
+ *
+ * <p>
+ * The attachment logic is implemented in {@link AbstractComponent}.
* </p>
*/
public void attach();
/**
* Notifies the component that it is detached from the application.
+ *
* <p>
* The {@link #getApplication()} and {@link #getWindow()} methods might
* return <code>null</code> after this method is called.
* collection.
*/
public void childRequestedRepaint(
- Collection<RepaintRequestListener> alreadyNotified);
+ Collection<RepaintRequestListener> alreadyNotified);
/* Component event framework */
projects / vaadin-framework.git / commitdiff