Interface Component

All Superinterfaces:

EventListener, Paintable, Serializable, Sizeable, VariableOwner

All Known Subinterfaces:

Component.Focusable, ComponentContainer, DragSource, DropTarget, Field, Layout

All Known Implementing Classes:

AbsoluteLayout, AbstractComponent, AbstractComponentContainer, AbstractField, AbstractLayout, AbstractMedia, AbstractOrderedLayout, AbstractSelect, AbstractSplitPanel, AbstractTextField, Accordion, Audio, Button, CheckBox, ComboBox, CssLayout, CustomComponent, CustomLayout, DateField, DragAndDropWrapper, Embedded, ExpandLayout, Form, FormLayout, GridLayout, HorizontalLayout, HorizontalSplitPanel, InlineDateField, Label, Link, ListSelect, LoginForm, MenuBar, NativeButton, NativeSelect, OptionGroup, OrderedLayout, Panel, PasswordField, PopupDateField, PopupView, ProgressIndicator, RichTextArea, Select, Slider, SplitPanel, Table, TabSheet, TextArea, TextField, Tree, TreeTable, TwinColSelect, Upload, UriFragmentUtility, VerticalLayout, VerticalSplitPanel, Video, Window

public interface Component
extends Paintable, VariableOwner, Sizeable, 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

Version:

6.8.18

Author:

Vaadin Ltd.

Nested Class Summary
static class	Component.ErrorEvent           Class of all component originated error events.
static interface	Component.ErrorListener           Listener interface for receiving Component.Errorss.
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.terminal.Paintable
Paintable.RepaintRequestEvent, Paintable.RepaintRequestListener

 

Field Summary

 

Fields inherited from interface com.vaadin.terminal.Sizeable
SIZE_UNDEFINED, UNIT_SYMBOLS, 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(String style)           Adds a style name to component.
void	attach()           Notifies the component that it is connected to an application.
void	childRequestedRepaint(Collection<Paintable.RepaintRequestListener> alreadyNotified)           The child components of the component must call this method when they need repainting.
void	detach()           Notifies the component that it is detached from the application.
Application	getApplication()           Gets the application object to which the component is attached.
String	getCaption()           Gets the caption of the component.
Resource	getIcon()           Gets the icon resource of the component.
Locale	getLocale()           Gets the locale of the component.
Component	getParent()           Gets the parent component of the component.
String	getStyleName()           Gets all user-defined CSS style names of a component.
Window	getWindow()           Gets the parent window of the component.
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(String style)           Removes one or more style names from component.
void	setCaption(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	setParent(Component parent)           Sets the parent component of the component.
void	setReadOnly(boolean readOnly)           Sets the read-only mode of the component to the specified mode.
void	setStyleName(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.terminal.Paintable
addListener, getDebugId, paint, removeListener, requestRepaint, requestRepaintRequests, setDebugId

 

Methods inherited from interface com.vaadin.terminal.VariableOwner
changeVariables, isImmediate

 

Methods inherited from interface com.vaadin.terminal.Sizeable
getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeight, setHeightUnits, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidth, setWidthUnits

 

Method Detail

getStyleName

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(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(String style)

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 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(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)

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 variable change events for disabled components are blocked on the server-side.

Specified by:

isEnabled in interface VariableOwner

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. 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);
 

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, but the entire HTML element will be empty. 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. Notice that if a child component is explicitly set as invisible, changes in the visibility status of its parents do not change its status.

This method does not check whether the component is attached (see 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 getApplication() does not return null.

Returns:

true if the component is 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, 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.

Parameters:

visible - the boolean value specifying if the component should be visible after the call or not.

See Also:

isVisible()

getParent

Component 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.

Returns:

the parent component

See Also:

setParent(Component)

setParent

void setParent(Component parent)

Sets the parent component of the component.

This method automatically calls attach() if the parent becomes attached to the application, regardless of whether it was attached previously. Conversely, if the parent is null and the component is attached to the application, detach() is called for the component.

This method is rarely called directly. The ComponentContainer.addComponent(Component) method is normally used for adding components to a container and it will call this method implicitly.

It is not possible to change the parent without first setting the parent to null.

Parameters:

parent - the parent component

Throws:

IllegalStateException - if a parent is given even though the component already has a parent

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

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(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 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 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)

getWindow

Window getWindow()

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).

Returns:

the parent window of the component or null if it is not attached to a window or is itself a window

getApplication

Application getApplication()

Gets the application object to which the component is attached.

The method will return null if the component is not currently 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 attach(), as described in the documentation of the method.

Returns:

the parent application of the component or null.

See Also:

attach()

attach

void attach()

Notifies the component that it is connected to an application.

The caller of this method is setParent(Component) if the parent is itself already attached to the application. If not, the parent will call the 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.

Reimplementing the attach() method is useful for tasks that need to get a reference to the parent, window, or application object with the getParent(), getWindow(), and getApplication() 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 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);
     }
 }
 

The attachment logic is implemented in AbstractComponent.

See Also:

getApplication()

detach

void detach()

Notifies the component that it is detached from the application.

The getApplication() and getWindow() methods might return null after this method is called.

The caller of this method is setParent(Component) if the parent is in the application. When the parent is detached from the application it is its response to call detach() for all the children and to detach itself from the terminal.

getLocale

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.

childRequestedRepaint

void childRequestedRepaint(Collection<Paintable.RepaintRequestListener> alreadyNotified)

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 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.

Parameters:

alreadyNotified - the collection of repaint request listeners that have been already notified by the child. This component should not re-notify the listed listeners again. The container given as parameter must be modifiable as the component might modify it and pass it forward. A null parameter is interpreted as an empty collection.

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)