Class Component
- All Implemented Interfaces:
AttachNotifier
,DetachNotifier
,HasElement
,HasStyle
,Serializable
- Direct Known Subclasses:
AbstractField
,AbstractLogin
,Accordion
,AppLayout
,Avatar
,AvatarGroup
,Board
,Button
,Chart
,Composite
,ConfirmDialog
,ContextMenuBase
,CookieConsent
,Crud
,Details
,Dialog
,FlexLayout
,FormLayout
,FormLayout.FormItem
,Grid
,Grid.Column
,GridSelectionColumn
,HorizontalLayout
,Html
,HtmlComponent
,Icon
,InternalServerError
,LitTemplate
,MapBase
,MenuBar
,MenuItemBase
,MessageInput
,MessageList
,Notification
,ProgressBar
,RouteNotFoundError
,RouterLink
,Row
,Scroller
,SplitLayout
,Svg
,Tab
,Tabs
,TabSheet
,Text
,UI
,UI.ClientViewPlaceholder
,Upload
,VerticalLayout
,VirtualList
,WebComponentWrapper
Element
or a
hierarchy of Element
s.
A component must have exactly one root element which is created based on the
Tag
annotation of the sub class (or in special cases set using the
constructor Component(Element)
or using
setElement(Component, Element)
before the element is attached to a
parent). The root element cannot be changed once it has been set.
- Since:
- 1.0
- Author:
- Vaadin Ltd
- See Also:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprotected <T extends ComponentEvent<?>>
RegistrationaddListener
(Class<T> eventType, ComponentEventListener<T> listener) Adds a listener for an event of the given type.<T> T
findAncestor
(Class<T> componentType) Traverses the component tree up and returns the first ancestor component that matches the given type.protected void
fireEvent
(ComponentEvent<?> componentEvent) Dispatches the event to all listeners registered for the event type.static <T extends Component>
TCreates a new component instance using the given element.protected <T> T
get
(PropertyDescriptor<?, T> descriptor) Gets the value of the given component property.Gets the child components of this component.Gets the low level root element of this component.protected ComponentEventBus
Gets the event bus for this component.getId()
Gets the id of the root element of this component.protected Collection<?>
getListeners
(Class<? extends ComponentEvent> eventType) Returns all listeners that match or extend the given event type.protected Locale
Gets the locale for this component.Gets the parent component of this component.getTranslation
(Object key, Object... params) Get the translation for the component locale.getTranslation
(Object key, Locale locale, Object... params) Deprecated.getTranslation
(String key, Object... params) Get the translation for the component locale.getTranslation
(String key, Locale locale, Object... params) Deprecated.UsegetTranslation(Locale, String, Object...)
insteadgetTranslation
(Locale locale, Object key, Object... params) Get the translation for key with given locale.getTranslation
(Locale locale, String key, Object... params) Get the translation for key with given locale.getUI()
Gets the UI this component is attached to.protected boolean
hasListener
(Class<? extends ComponentEvent> eventType) Checks if there is at least one listener registered for the given event type for this component.boolean
Checks whether this component is currently attached to a UI.protected boolean
Gets whether this component was attached as part of a template (by being mapped by anId
annotation), or if it was created directly.boolean
Gets the component visibility value.protected void
onAttach
(AttachEvent attachEvent) Called when the component is attached to a UI.protected void
onDetach
(DetachEvent detachEvent) Called when the component is detached from a UI.void
onEnabledStateChanged
(boolean enabled) Handle component enable state when the enabled state changes.void
Removes the component from its parent.void
Scrolls the current component into the visible area of the browser window.void
scrollIntoView
(ScrollOptions scrollOptions) Scrolls the current component into the visible area of the browser window.protected <T> void
set
(PropertyDescriptor<T, ?> descriptor, T value) Sets the value of the given component property.protected static void
setElement
(Component component, Element element) Initializes the root element of a component.void
Sets the id of the root element of this component.void
setVisible
(boolean visible) Sets the component visibility value.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface com.vaadin.flow.component.AttachNotifier
addAttachListener
Methods inherited from interface com.vaadin.flow.component.DetachNotifier
addDetachListener
Methods inherited from interface com.vaadin.flow.component.HasStyle
addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName
-
Constructor Details
-
Component
protected Component()Creates a component instance with an element created based on theTag
annotation of the sub class.If this is invoked through
from(Element, Class)
orElement.as(Class)
, uses the element defined in those methods instead of creating a new element. -
Component
Creates a component instance based on the given element.For nearly all cases you want to pass an element reference but it is possible to pass
null
to this method. If you passnull
you must ensure that the element is initialized usingsetElement(Component, Element)
beforegetElement()
is used.- Parameters:
element
- the root element for the component
-
-
Method Details
-
getElement
Gets the low level root element of this component.Note! Element API is designed for building components at a lower abstraction level than normal Vaadin UI development. If you see a direct call to this method in your applications UI code, you should consider that as a sign that you are probably doing something wrong and you should instead use other methods from your component, e.g. when getting children, parent or ancestor component or adding listeners. This method is breaking the Component's abstraction layer and its implementations provided. You should only call this method and use the Element API when creating or extending components (e.g. setting the attributes and properties, adding DOM listeners, execute JavaScript code), or when you otherwise need to break through the abstraction layer. If it is a hack or a workaround, it is also better to hide that into an extension, helper class, separate add-on module or at least into a private method documenting the usage.
Each component must have exactly one root element. When the component is attached to a parent component, this element is attached to the parent component's element hierarchy.
- Specified by:
getElement
in interfaceHasElement
- Returns:
- the root element of this component
-
setElement
Initializes the root element of a component.Each component must have a root element and it must be set before the component is attached to a parent. The root element of a component cannot be changed once it has been set.
Typically you do not want to call this method but define the element through
Component(Element)
instead.- Parameters:
component
- the component to set the root element toelement
- the root element of the component
-
getParent
Gets the parent component of this component.A component can only have one parent.
- Returns:
- an optional parent component, or an empty optional if the component is not attached to a parent
-
getChildren
Gets the child components of this component.The default implementation finds child components by traversing each child
Element
tree.If the component is injected to a PolymerTemplate using the
@Id
annotation the getChildren method will only return children added from the server side and will not return any children declared in the template file.- Returns:
- the child components of this component
- See Also:
-
getEventBus
Gets the event bus for this component.This method will create the event bus if it has not yet been created.
- Returns:
- the event bus for this component
-
addListener
protected <T extends ComponentEvent<?>> Registration addListener(Class<T> eventType, ComponentEventListener<T> listener) Adds a listener for an event of the given type.- Type Parameters:
T
- the component event type- Parameters:
eventType
- the component event type, notnull
listener
- the listener to add, notnull
- Returns:
- a handle that can be used for removing the listener
-
hasListener
Checks if there is at least one listener registered for the given event type for this component.- Parameters:
eventType
- the component event type- Returns:
true
if at least one listener is registered,false
otherwise
-
getListeners
Returns all listeners that match or extend the given event type.- Parameters:
eventType
- the component event type- Returns:
- A collection with all registered listeners for a given event type. Empty if no listeners are found.
-
fireEvent
Dispatches the event to all listeners registered for the event type.- Parameters:
componentEvent
- the event to fire- See Also:
-
getUI
Gets the UI this component is attached to.- Returns:
- an optional UI component, or an empty optional if this component is not attached to a UI
-
setId
Sets the id of the root element of this component. The id is used with various APIs to identify the element, and it should be unique on the page.- Parameters:
id
- the id to set, or""
to remove any previously set id
-
getId
Gets the id of the root element of this component.- Returns:
- the id, or and empty optional if no id has been set
- See Also:
-
onAttach
Called when the component is attached to a UI.The default implementation does nothing.
This method is invoked before the
AttachEvent
is fired for the component.- Parameters:
attachEvent
- the attach event
-
onDetach
Called when the component is detached from a UI.The default implementation does nothing.
This method is invoked before the
DetachEvent
is fired for the component.- Parameters:
detachEvent
- the detach event
-
isAttached
public boolean isAttached()Checks whether this component is currently attached to a UI.When
UI.close()
is called, the UI and the components are not detached immediately; the UI cleanup is performed at the end of the current request which also detaches the UI and its components.- Returns:
- true if the component is attached to an active UI.
-
set
Sets the value of the given component property.- Type Parameters:
T
- type of the value to set- Parameters:
descriptor
- the descriptor for the property to set, notnull
value
- the new property value to set- See Also:
-
get
Gets the value of the given component property.- Type Parameters:
T
- type of the value to get- Parameters:
descriptor
- the descriptor for the property to set, notnull
- Returns:
- the property value
- See Also:
-
from
Creates a new component instance using the given element.You can use this method when you have an element instance and want to use it through the API of a
Component
class.This method attaches the component instance to the element so that
Element.getComponent()
returns the component instance. This means thatgetParent()
,getChildren()
and other methods which rely onElement
->Component
mappings will work correctly.Note that only one
Component
can be mapped to any givenElement
.- Type Parameters:
T
- the component type to create- Parameters:
element
- the element to wrapcomponentType
- the component type- Returns:
- the component instance connected to the given element
- See Also:
-
setVisible
public void setVisible(boolean visible) Sets the component visibility value.When a component is set as invisible, all the updates of the component from the server to the client are blocked until the component is set as visible again.
Invisible components don't receive any updates from the client-side. Unlike the server-side updates, client-side updates, if any, are discarded while the component is invisible, and are not transmitted to the server when the component is made visible.
- Parameters:
visible
- the component visibility value
-
isVisible
public boolean isVisible()Gets the component visibility value.- Returns:
true
if the component is visible,false
otherwise
-
onEnabledStateChanged
public void onEnabledStateChanged(boolean enabled) Handle component enable state when the enabled state changes.By default this sets or removes the 'disabled' attribute from the element. This can be overridden to have custom handling.
- Parameters:
enabled
- the new enabled state of the component
-
isTemplateMapped
protected boolean isTemplateMapped()Gets whether this component was attached as part of a template (by being mapped by anId
annotation), or if it was created directly.- Returns:
true
when it was mapped inside a template,false
otherwise
-
getTranslation
Get the translation for the component locale.The method never returns a null. If there is no
I18NProvider
available or no translation for thekey
it returns an exception string e.g. '!{key}!'.- Parameters:
key
- translation keyparams
- parameters used in translation string- Returns:
- translation for key if found (implementation should not return null)
- See Also:
-
getTranslation
Get the translation for the component locale.The method never returns a null. If there is no
I18NProvider
available or no translation for thekey
it returns an exception string e.g. '!{key}!'.- Parameters:
key
- translation keyparams
- parameters used in translation string- Returns:
- translation for key if found (implementation should not return null)
- See Also:
-
getTranslation
Deprecated.UsegetTranslation(Locale, String, Object...)
insteadGet the translation for key with given locale.The method never returns a null. If there is no
I18NProvider
available or no translation for thekey
it returns an exception string e.g. '!{key}!'.- Parameters:
key
- translation keylocale
- locale to useparams
- parameters used in translation string- Returns:
- translation for key if found
-
getTranslation
Deprecated.UsegetTranslation(Locale, String, Object...)
insteadGet the translation for key with given locale.The method never returns a null. If there is no
I18NProvider
available or no translation for thekey
it returns an exception string e.g. '!{key}!'.- Parameters:
key
- translation keylocale
- locale to useparams
- parameters used in translation string- Returns:
- translation for key if found
-
getTranslation
Get the translation for key with given locale.The method never returns a null. If there is no
I18NProvider
available or no translation for thekey
it returns an exception string e.g. '!{key}!'.- Parameters:
locale
- locale to usekey
- translation keyparams
- parameters used in translation string- Returns:
- translation for key if found
-
getTranslation
Get the translation for key with given locale.The method never returns a null. If there is no
I18NProvider
available or no translation for thekey
it returns an exception string e.g. '!{key}!'.- Parameters:
locale
- locale to usekey
- translation keyparams
- parameters used in translation string- Returns:
- translation for key if found
-
getLocale
Gets the locale for this component.It returns the
UI
locale if it has been set. If there is noUI
locale available then it tries to use the first locale provided by theI18NProvider
. If there is no any provided locale then the default locale is used.- Returns:
- the component locale
-
scrollIntoView
public void scrollIntoView()Scrolls the current component into the visible area of the browser window. -
scrollIntoView
Scrolls the current component into the visible area of the browser window.- Parameters:
scrollOptions
- options to define the scrolling behavior
-
findAncestor
Traverses the component tree up and returns the first ancestor component that matches the given type.- Type Parameters:
T
- the type of the ancestor component to return- Parameters:
componentType
- the class of the ancestor component to search for- Returns:
- The first ancestor that can be assigned to the given class. Null if no ancestor with the correct type could be found.
-
removeFromParent
public void removeFromParent()Removes the component from its parent.
-
getTranslation(Locale, String, Object...)
instead