public interface Component extends ClientConnector, 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.
| 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 |
|---|---|
void |
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.
|
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 |
isReadOnly()
Tests whether the component is in the read-only mode.
|
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)
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 |
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 |
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.
|
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, setHeightUndefined, setSizeFull, setSizeUndefined, setWidth, setWidth, 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.
This method will trigger a RepaintRequestEvent.
style - the new style or styles of the component as a space-separated
listgetStyleName(),
addStyleName(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;}
This method will trigger a RepaintRequestEvent.
style - the new style to be added to the componentgetStyleName(),
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.
RepaintRequestEvent.style - the style name or style names to be removedgetStyleName(),
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);
This method will trigger a RepaintRequestEvent for the component
and, if it is a ComponentContainer, for all its children
recursively.
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 Connectorboolean isReadOnly()
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.
true if the component or any of its parents is in
read-only mode, false if not.setReadOnly(boolean)void setReadOnly(boolean readOnly)
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.
readOnly - a boolean value specifying whether the component is put
read-only mode or notString 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.
This method will trigger a RepaintRequestEvent. A
reimplementation should call the superclass implementation.
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 .
RepaintRequestEvent.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 #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);
}
}
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 designvoid 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);
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);
listener - the new Listener to be registered.Component.Event,
removeListener(Listener)void removeListener(Component.Listener listener)
listener - the listener to be removed.addListener(Listener)Copyright © 2019 Vaadin Ltd. All rights reserved.