com.vaadin.ui
Interface Component

All Superinterfaces:
ClientConnector, Connector, java.io.Serializable, Sizeable
All Known Subinterfaces:
Component.Focusable, ComponentContainer, DragSource, DropTarget, Field<T>, HasComponents, Layout, LegacyComponent, SelectiveRenderer, SingleComponentContainer
All Known Implementing Classes:
AbsoluteLayout, AbstractColorPicker, AbstractComponent, AbstractComponentContainer, AbstractEmbedded, AbstractField, AbstractJavaScriptComponent, AbstractLayout, AbstractMedia, AbstractOrderedLayout, AbstractSelect, AbstractSingleComponentContainer, AbstractSplitPanel, AbstractTextField, Accordion, Audio, BrowserFrame, Button, Calendar, CheckBox, ColorPicker, ColorPickerArea, ColorPickerGradient, ColorPickerGrid, ColorPickerHistory, ColorPickerPopup, ColorPickerPreview, ColorPickerSelect, ComboBox, CssLayout, CustomComponent, CustomField, CustomLayout, DateField, DragAndDropWrapper, Embedded, Flash, Form, FormLayout, GridLayout, HorizontalLayout, HorizontalSplitPanel, Image, InlineDateField, Label, LegacyWindow, Link, ListSelect, LoginForm, MenuBar, NativeButton, NativeSelect, Navigator.EmptyView, OptionGroup, Panel, PasswordField, PopupDateField, PopupView, ProgressBar, ProgressIndicator, RichTextArea, Select, Slider, Table, TabSheet, TextArea, TextField, Tree, TreeTable, TwinColSelect, UI, Upload, VerticalLayout, VerticalSplitPanel, Video, Window

public interface Component
extends ClientConnector, Sizeable, java.io.Serializable

Component is the top-level interface that is and must be implemented by all Vaadin components. Component is paired with 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 ComponentContainer interface. Such a container is the parent of the contained components.

The getParent() method allows retrieving the parent component of a component. While there is a setParent(), you rarely need it as you normally add components with the addComponent() method of the layout or other ComponentContainer, which automatically sets the parent.

A component becomes attached to an application (and the attach() is called) when it or one of its parents is attached to the main window of the application through its containment hierarchy.

Since:
3.0
Author:
Vaadin Ltd.

Nested Class Summary
static class Component.ErrorEvent
          Class of all component originated error events.
static class Component.Event
          Superclass of all component originated events.
static interface Component.Focusable
          A sub-interface implemented by components that can obtain input focus.
static interface Component.Listener
          Listener interface for receiving Component.Events.
 
Nested classes/interfaces inherited from interface com.vaadin.server.ClientConnector
ClientConnector.AttachEvent, ClientConnector.AttachListener, ClientConnector.ConnectorErrorEvent, ClientConnector.DetachEvent, ClientConnector.DetachListener
 
Nested classes/interfaces inherited from interface com.vaadin.server.Sizeable
Sizeable.Unit
 
Field Summary
 
Fields inherited from interface com.vaadin.server.Sizeable
SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS
 
Method Summary
 void addListener(Component.Listener listener)
          Registers a new (generic) component event listener for the component.
 void addStyleName(java.lang.String style)
          Adds one or more style names to this component.
 void attach()
          Notifies the connector that it is connected to a VaadinSession (and therefore also to a UI).
 java.lang.String getCaption()
          Gets the caption of the component.
 java.lang.String getDescription()
           Gets the component's description, used in tooltips and can be displayed directly in certain other components such as forms.
 Resource getIcon()
          Gets the icon resource of the component.
 java.lang.String getId()
          Get's currently set debug identifier
 java.util.Locale getLocale()
          Gets the locale of the component.
 HasComponents getParent()
          Gets the parent component of the component.
 java.lang.String getPrimaryStyleName()
          Gets the primary style name of the component.
 java.lang.String getStyleName()
          Gets all user-defined CSS style names of a component.
 UI getUI()
          Gets the UI the component is attached to.
 boolean isEnabled()
          Tests whether the component is enabled or not.
 boolean isReadOnly()
          Tests whether the component is in the read-only mode.
 boolean isVisible()
          Tests the visibility property of the component.
 void removeListener(Component.Listener listener)
          Removes a previously registered component event listener from this component.
 void removeStyleName(java.lang.String style)
          Removes one or more style names from component.
 void setCaption(java.lang.String caption)
          Sets the caption of the component.
 void setEnabled(boolean enabled)
          Enables or disables the component.
 void setIcon(Resource icon)
          Sets the icon of the component.
 void setId(java.lang.String id)
          Adds an unique id for component that get's transferred to terminal for testing purposes.
 void setParent(HasComponents parent)
          Sets the parent connector of the component.
 void setPrimaryStyleName(java.lang.String style)
          Changes the primary style name of the component.
 void setReadOnly(boolean readOnly)
          Sets the read-only mode of the component to the specified mode.
 void setStyleName(java.lang.String style)
          Sets one or more user-defined style names of the component, replacing any previous user-defined styles.
 void setVisible(boolean visible)
          Sets the visibility of the component.
 
Methods inherited from interface com.vaadin.server.ClientConnector
addAttachListener, addDetachListener, beforeClientResponse, detach, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, isConnectorEnabled, markAsDirty, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler
 
Methods inherited from interface com.vaadin.shared.Connector
getConnectorId
 
Methods inherited from interface com.vaadin.server.Sizeable
getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setSizeFull, setSizeUndefined, setWidth, setWidth
 

Method Detail

getStyleName

java.lang.String getStyleName()
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.

Returns:
the style name or a space-separated list of user-defined style names of the component
See Also:
setStyleName(String), addStyleName(String), removeStyleName(String)

setStyleName

void setStyleName(java.lang.String style)
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 Button component and give it "mystyle" style, the component will have both "mystyle" and "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 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 RepaintRequestEvent.

Parameters:
style - the new style or styles of the component as a space-separated list
See Also:
getStyleName(), addStyleName(String), removeStyleName(String)

addStyleName

void addStyleName(java.lang.String style)
Adds one or more style names to this component. Multiple styles can be specified as a space-separated list of style names. 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 Button component and give it "mystyle" style, the component will have both "mystyle" and "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 RepaintRequestEvent.

Parameters:
style - the new style to be added to the component
See Also:
getStyleName(), setStyleName(String), removeStyleName(String)

removeStyleName

void removeStyleName(java.lang.String style)
Removes one or more style names from component. Multiple styles can be specified as a space-separated list of style names.

The parameter must be a valid CSS style name. Only user-defined style names added with addStyleName() or setStyleName() can be removed; built-in style names defined in Vaadin or GWT can not be removed.

* This method will trigger a RepaintRequestEvent.

Parameters:
style - the style name or style names to be removed
See Also:
getStyleName(), setStyleName(String), addStyleName(String)

getPrimaryStyleName

java.lang.String getPrimaryStyleName()
Gets the primary style name of the component. See setPrimaryStyleName(String) for a better description of the primary stylename.


setPrimaryStyleName

void setPrimaryStyleName(java.lang.String style)
Changes the primary style name of the component.

The primary style name identifies the component when applying the CSS theme to the Component. By changing the style name all CSS rules targeted for that style name will no longer apply, and might result in the component not working as intended.

To preserve the original style of the component when changing to a new primary style you should make your new primary style inherit the old primary style using the SASS @include directive. See more in the SASS tutorials.

Parameters:
style - The new primary style name

isEnabled

boolean isEnabled()
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.

As a security feature, all updates for disabled components are blocked on the server-side.

Note that this method only returns the status of the component and does not take parents into account. Even though this method returns true the component can be disabled to the user if a parent is disabled.

Returns:
true if the component and its parent are enabled, false otherwise.
See Also:
VariableOwner.isEnabled()

setEnabled

void setEnabled(boolean enabled)
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.
 Button enabled = new Button("Enabled");
 enabled.setEnabled(true); // The default
 layout.addComponent(enabled);
 
 Button disabled = new Button("Disabled");
 disabled.setEnabled(false);
 layout.addComponent(disabled);
 

This method will trigger a RepaintRequestEvent for the component and, if it is a ComponentContainer, for all its children recursively.

Parameters:
enabled - a boolean value specifying if the component should be enabled or not

isVisible

boolean isVisible()
Tests the visibility property of the component.

Visible components are drawn in the user interface, while invisible ones are not. The effect is not merely a cosmetic CSS change - no information about an invisible component will be sent to the client. The effect is thus the same as removing the component from its parent. Making a component invisible through this property can alter the positioning of other components.

A component is visible only if all its parents are also visible. This is not checked by this method though, so even if this method returns true, the component can be hidden from the user because a parent is set to invisible.

Returns:
true if the component has been set to be visible in the user interface, false if not
See Also:
setVisible(boolean), attach()

setVisible

void setVisible(boolean visible)
Sets the visibility of the component.

Visible components are drawn in the user interface, while invisible ones are not. The effect is not merely a cosmetic CSS change - no information about an invisible component will be sent to the client. The effect is thus the same as removing the component from its parent.

 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.

Parameters:
visible - the boolean value specifying if the component should be visible after the call or not.
See Also:
isVisible()

setParent

void setParent(HasComponents parent)
Sets the parent connector of the component.

This method automatically calls attach() if the component becomes attached to the session, regardless of whether it was attached previously. Conversely, if the component currently is attached to the session, ClientConnector.detach() is called for the connector before attaching it to a new parent.

This method is rarely called directly. ComponentContainer.addComponent(Component) or a HasComponents specific method is normally used for adding components to a parent and the used method will call this method implicitly.

Parameters:
parent - the parent connector
Throws:
java.lang.IllegalStateException - if a parent is given even though the connector already has a parent

getParent

HasComponents getParent()
Gets the parent component of the 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 ComponentContainer interface.

Specified by:
getParent in interface ClientConnector
Specified by:
getParent in interface Connector
Returns:
the parent component

isReadOnly

boolean isReadOnly()
Tests whether the component is in the read-only mode. The user can not change the value of a read-only component. As only 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 method will return true if the component or any of its parents is in the read-only mode.

Returns:
true if the component or any of its parents is in read-only mode, false if not.
See Also:
setReadOnly(boolean)

setReadOnly

void setReadOnly(boolean readOnly)
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 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.

This method will trigger a RepaintRequestEvent.

Parameters:
readOnly - a boolean value specifying whether the component is put read-only mode or not

getCaption

java.lang.String getCaption()
Gets the caption of the component.

See setCaption(String) for a detailed description of the caption.

Returns:
the caption of the component or null if the caption is not set.
See Also:
setCaption(String)

setCaption

void setCaption(java.lang.String caption)
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 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 HTML 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 VerticalLayout component shows the captions left-aligned above the contained components, while the 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 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 Button and Panel, manage the caption themselves and display it inside the component.

This method will trigger a RepaintRequestEvent. A reimplementation should call the superclass implementation.

Parameters:
caption - the new caption for the component. If the caption is null, no caption is shown and it does not normally take any space

getIcon

Resource getIcon()
Gets the icon resource of the component.

See setIcon(Resource) for a detailed description of the icon.

Returns:
the icon resource of the component or null if the component has no icon
See Also:
setIcon(Resource)

setIcon

void setIcon(Resource icon)
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 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 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 VerticalLayout component shows the icons left-aligned above the contained components, while the 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 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 v-icon CSS style class. The containing layout may enclose an icon and a caption inside elements related to the caption, such as v-caption .

This method will trigger a RepaintRequestEvent.

Parameters:
icon - the icon of the component. If null, no icon is shown and it does not normally take any space.
See Also:
getIcon(), setCaption(String)

getUI

UI getUI()
Gets the UI the component is attached to.

If the component is not attached to a UI through a component containment hierarchy, null is returned.

Specified by:
getUI in interface ClientConnector
Returns:
the UI of the component or null if it is not attached to a UI

attach

void attach()
Notifies the connector that it is connected to a VaadinSession (and therefore also to a UI).

The caller of this method is #setParent(ClientConnector) if the parent is itself already attached to the session. If not, the parent will call the ClientConnector.attach() for all its children when it is attached to the session. This method is always called before the connector's data is sent to the client-side for the first time.

The attachment logic is implemented in AbstractClientConnector.

Reimplementing the attach() method is useful for tasks that need to get a reference to the parent, window, or application object with the getParent(), getUI(), and #getSession() methods. A component does not yet know these objects in the constructor, so in such case, the methods will return 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 attach() method for the component. Correspondingly, removing a component from a container triggers calling the ClientConnector.detach() method. If the parent of an added component is already connected to the application, the attach() is called immediately from #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);
     }
 }
 

Specified by:
attach in interface ClientConnector

getLocale

java.util.Locale getLocale()
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.

Returns:
Locale of this component or null if the component and none of its parents has a locale set and the component is not yet attached to an application.

setId

void setId(java.lang.String id)
Adds an unique id for component that get's transferred to terminal for testing purposes. Keeping identifiers unique is the responsibility of the programmer.

Parameters:
id - An alphanumeric id

getId

java.lang.String getId()
Get's currently set debug identifier

Returns:
current id, null if not set

getDescription

java.lang.String getDescription()

Gets the component's description, used in tooltips and can be displayed directly in certain other components such as forms. The description can be used to briefly describe the state of the component to the user. The description string may contain certain XML tags:

Tag Description Example
<b> bold bold text
<i> italic italic text
<u> underlined underlined text
<br> linebreak N/A
<ul>
<li>item1
<li>item1
</ul>
item list
  • item1
  • item2

These tags may be nested.

Returns:
component's description String

addListener

void addListener(Component.Listener listener)
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);
 

Parameters:
listener - the new Listener to be registered.
See Also:
Component.Event, removeListener(Listener)

removeListener

void removeListener(Component.Listener listener)
Removes a previously registered component event listener from this component.

Parameters:
listener - the listener to be removed.
See Also:
addListener(Listener)


Copyright © 2000-2011 Vaadin Ltd. All Rights Reserved.