Package com.vaadin.flow.component

Class Component

java.lang.Object
com.vaadin.flow.component.Component
All Implemented Interfaces:
AttachNotifier, DetachNotifier, HasElement, HasStyle, Serializable
Direct Known Subclasses:
AbstractField, AbstractRouteNotFoundError, Composite, Html, HtmlComponent, InternalServerError, RouteAccessDeniedError, RouterLink, Svg, Text, UI, UI.ClientViewPlaceholder, WebComponentWrapper
public abstract class Component extends Object implements HasStyle, AttachNotifier, DetachNotifier
A Component is a higher level abstraction of an Element or a hierarchy of Elements.

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 Details

    • Component

      protected Component()
      Creates a component instance with an element created based on the Tag annotation of the sub class.

      If this is invoked through from(Element, Class) or Element.as(Class), uses the element defined in those methods instead of creating a new element.

    • Component

      protected Component(Element element)
      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 pass null you must ensure that the element is initialized using setElement(Component, Element) before getElement() is used.

      Parameters:
      element - the root element for the component

  • Method Details

    • getElement

      public Element 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 interface HasElement
      Returns:
      the root element of this component

    • setElement

      protected static void setElement(Component component, Element element)
      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 to
      element - the root element of the component

    • getParent

      public Optional<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

      public Stream<Component> 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

      protected ComponentEventBus 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, not null
      listener - the listener to add, not null
      Returns:
      a handle that can be used for removing the listener

    • hasListener

      protected boolean hasListener(Class<? extends ComponentEvent> eventType)
      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

      protected Collection<?> getListeners(Class<? extends ComponentEvent> eventType)
      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

      protected void fireEvent(ComponentEvent<?> componentEvent)
      Dispatches the event to all listeners registered for the event type.
      Parameters:
      componentEvent - the event to fire
      See Also:

    • getUI

      public Optional<UI> 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

      public void setId(String id)
      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

      public Optional<String> 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

      protected void onAttach(AttachEvent attachEvent)
      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

      protected void onDetach(DetachEvent detachEvent)
      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

      protected <T> void set(PropertyDescriptor<T,?> descriptor, T value)
      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, not null
      value - the new property value to set
      See Also:

    • get

      protected <T> T get(PropertyDescriptor<?,T> descriptor)
      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, not null
      Returns:
      the property value
      See Also:

    • from

      public static <T extends Component> T from(Element element, Class<T> componentType)
      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 that getParent(), getChildren() and other methods which rely on Element -> Component mappings will work correctly.

      Note that only one Component can be mapped to any given Element.

      Type Parameters:
      T - the component type to create
      Parameters:
      element - the element to wrap
      componentType - 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 an Id annotation), or if it was created directly.
      Returns:
      true when it was mapped inside a template, false otherwise

    • getTranslation

      public String getTranslation(String key, Object... params)
      Get the translation for the component locale.

      The method never returns a null. If there is no I18NProvider available or no translation for the key it returns an exception string e.g. '!{key}!'.

      Parameters:
      key - translation key
      params - parameters used in translation string
      Returns:
      translation for key if found (implementation should not return null)
      See Also:

    • getTranslation

      public String getTranslation(Object key, Object... params)
      Get the translation for the component locale.

      The method never returns a null. If there is no I18NProvider available or no translation for the key it returns an exception string e.g. '!{key}!'.

      Parameters:
      key - translation key
      params - parameters used in translation string
      Returns:
      translation for key if found (implementation should not return null)
      See Also:

    • getTranslation

      @Deprecated public String getTranslation(String key, Locale locale, Object... params)
      Deprecated.
      Use getTranslation(Locale, String, Object...) instead
      Get the translation for key with given locale.

      The method never returns a null. If there is no I18NProvider available or no translation for the key it returns an exception string e.g. '!{key}!'.

      Parameters:
      key - translation key
      locale - locale to use
      params - parameters used in translation string
      Returns:
      translation for key if found

    • getTranslation

      @Deprecated public String getTranslation(Object key, Locale locale, Object... params)
      Deprecated.
      Use getTranslation(Locale, String, Object...) instead
      Get the translation for key with given locale.

      The method never returns a null. If there is no I18NProvider available or no translation for the key it returns an exception string e.g. '!{key}!'.

      Parameters:
      key - translation key
      locale - locale to use
      params - parameters used in translation string
      Returns:
      translation for key if found

    • getTranslation

      public String getTranslation(Locale locale, String key, Object... params)
      Get the translation for key with given locale.

      The method never returns a null. If there is no I18NProvider available or no translation for the key it returns an exception string e.g. '!{key}!'.

      Parameters:
      locale - locale to use
      key - translation key
      params - parameters used in translation string
      Returns:
      translation for key if found

    • getTranslation

      public String getTranslation(Locale locale, Object key, Object... params)
      Get the translation for key with given locale.

      The method never returns a null. If there is no I18NProvider available or no translation for the key it returns an exception string e.g. '!{key}!'.

      Parameters:
      locale - locale to use
      key - translation key
      params - parameters used in translation string
      Returns:
      translation for key if found

    • getLocale

      protected Locale getLocale()
      Gets the locale for this component.

      It returns the UI locale if it has been set. If there is no UI locale available then it tries to use the first locale provided by the I18NProvider. 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

      public void scrollIntoView(ScrollOptions scrollOptions)
      Scrolls the current component into the visible area of the browser window.
      Parameters:
      scrollOptions - options to define the scrolling behavior

    • findAncestor

      public <T> T findAncestor(Class<T> componentType)
      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.