public interface Component extends ClientConnector, Sizeable
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(HasComponents), 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.
| Modifier and Type | Interface and Description |
|---|---|
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. |
ClientConnector.AttachEvent, ClientConnector.AttachListener, ClientConnector.ConnectorErrorEvent, ClientConnector.DetachEvent, ClientConnector.DetachListenerSizeable.UnitSIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS| Modifier and Type | Method and Description |
|---|---|
Registration |
addListener(Component.Listener listener)
Registers a new (generic) component event listener for the component.
|
void |
addStyleName(String style)
Adds one or more style names to this component.
|
default void |
addStyleNames(String... styles)
Adds one or more style names to this component by using one or multiple
parameters.
|
void |
attach()
Notifies the connector that it is connected to a VaadinSession (and
therefore also to a UI).
|
String |
getCaption()
Gets the caption of the component.
|
String |
getDescription()
Gets the components 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.
|
String |
getId()
Gets currently set debug identifier.
|
Locale |
getLocale()
Gets the locale of the component.
|
HasComponents |
getParent()
Gets the parent component of the component.
|
String |
getPrimaryStyleName()
Gets the primary style name of the component.
|
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 |
isVisible()
Tests the visibility property of the component.
|
void |
readDesign(org.jsoup.nodes.Element design,
DesignContext designContext)
Reads the component state from the given design.
|
void |
removeListener(Component.Listener listener)
Deprecated.
As of 8.0, replaced by
Registration.remove() in the
registration object returned from
addListener(Component.Listener). |
void |
removeStyleName(String style)
Removes one or more style names from component.
|
default void |
removeStyleNames(String... styles)
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 |
setId(String id)
Adds an unique id for component that is used in the client-side for
testing purposes.
|
void |
setParent(HasComponents parent)
Sets the parent connector of the component.
|
void |
setPrimaryStyleName(String style)
Changes the primary style name of the component.
|
void |
setStyleName(String style)
Sets one or more user-defined style names of the component, replacing any
previous user-defined styles.
|
default void |
setStyleName(String style,
boolean add)
Adds or removes a style name.
|
void |
setVisible(boolean visible)
Sets the visibility of the component.
|
void |
writeDesign(org.jsoup.nodes.Element design,
DesignContext designContext)
Writes the component state to the given design.
|
addAttachListener, addDetachListener, beforeClientResponse, detach, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, isConnectorEnabled, markAsDirty, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandlergetConnectorIdgetHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeightFull, setHeightUndefined, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthFull, setWidthUndefinedString getStyleName()
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.
setStyleName(String),
addStyleName(String),
removeStyleName(String)void setStyleName(String style)
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.
style - the new style or styles of the component as a space-separated
listgetStyleName(),
addStyleName(String),
removeStyleName(String)default void setStyleName(String style, boolean add)
add parameter is true, the style name is added to the
component. If the add parameter is false, the style name is
removed from the component.
Functionally this is equivalent to using addStyleName(String) or
removeStyleName(String)
style - the style name to be added or removedadd - true to add the given style, false
to remove itaddStyleName(String),
removeStyleName(String)void addStyleName(String style)
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 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:
.mystyle {font-style: italic;}
or
.v-button-mystyle {font-style: italic;}
style - the new style to be added to the componentgetStyleName(),
setStyleName(String),
removeStyleName(String)default void addStyleNames(String... styles)
styles - the style name or style names to be added to the componentaddStyleName(String),
setStyleName(String),
removeStyleName(String)void removeStyleName(String style)
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.
style - the style name or style names to be removedgetStyleName(),
setStyleName(String),
addStyleName(String)default void removeStyleNames(String... styles)
styles - the style name or style names to be removedremoveStyleName(String),
setStyleName(String),
addStyleName(String)String getPrimaryStyleName()
setPrimaryStyleName(String) for a better description of
the primary stylename.void setPrimaryStyleName(String style)
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.
style - The new primary style nameboolean isEnabled()
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.
true if the component and its parent are enabled,
false otherwise.VariableOwner.isEnabled()void setEnabled(boolean enabled)
Button enabled = new Button("Enabled");
enabled.setEnabled(true); // The default
layout.addComponent(enabled);
Button disabled = new Button("Disabled");
disabled.setEnabled(false);
layout.addComponent(disabled);
enabled - a boolean value specifying if the component should be enabled
or notboolean isVisible()
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.
true if the component has been set to be visible in
the user interface, false if notsetVisible(boolean),
attach()void setVisible(boolean visible)
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.
visible - the boolean value specifying if the component should be
visible after the call or not.isVisible()void setParent(HasComponents parent)
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.
parent - the parent connectorIllegalStateException - if a parent is given even though the connector already has a
parentHasComponents getParent()
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.
getParent in interface ClientConnectorgetParent in interface ConnectorString getCaption()
See setCaption(String) for a detailed description of the
caption.
null if the caption is
not set.setCaption(String)void setCaption(String caption)
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.
caption - the new caption for the component. If the caption is
null, no caption is shown and it does not normally
take any spaceResource getIcon()
See setIcon(Resource) for a detailed description of the icon.
null if the
component has no iconsetIcon(Resource)void setIcon(Resource icon)
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 .
icon - the icon of the component. If null, no icon is shown and it
does not normally take any space.getIcon(),
setCaption(String)UI getUI()
If the component is not attached to a UI through a component containment
hierarchy, null is returned.
getUI in interface ClientConnectornull if it is not
attached to a UIvoid attach()
The caller of this method is Connector#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() and getUI() 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(HasComponents).
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);
}
}
attach in interface ClientConnectorLocale getLocale()
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.
null if the component and
none of its parents has a locale set and the component is not yet
attached to an application.void setId(String id)
id - An alphanumeric idString getId()
String getDescription()
Gets the components 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 |
|
These tags may be nested.
Stringvoid readDesign(org.jsoup.nodes.Element design,
DesignContext designContext)
The component is responsible not only for updating its own state but also for ensuring that its children update their state based on the design.
It is assumed that the component is in its default state when this method is called. Reading should only take into consideration attributes specified in the design and not reset any unspecified attributes to their defaults.
This method must not modify the design.
design - The element to obtain the state fromdesignContext - The DesignContext instance used for parsing the designvoid writeDesign(org.jsoup.nodes.Element design,
DesignContext designContext)
The component is responsible not only for writing its own state but also for ensuring that its children write their state to the design.
This method must not modify the component state.
design - The element to write the component state to. Any previous
attributes or child nodes are not cleared.designContext - The DesignContext instance used for writing the designRegistration addListener(Component.Listener listener)
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);
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);
listener - the new Listener to be registered.Component.Event,
Registration@Deprecated void removeListener(Component.Listener listener)
Registration.remove() in the
registration object returned from
addListener(Component.Listener).listener - the listener to be removed.addListener(Listener)Copyright © 2020 Vaadin Ltd. All rights reserved.