Class Component

Constructor Detail

• 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 Detail

• getElement

  public Element getElement()

  Gets the root element of this component.

  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:

  Id

• 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

• 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:

  ComponentUtil.fireEvent(Component, ComponentEvent)

• 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:

  setId(String)

• 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:

  PropertyDescriptor

• 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:

  PropertyDescriptor

• 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:

  Element.as(Class)

• 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:

  getLocale()

• getTranslation

  public String getTranslation(String key,
                               Locale locale,
                               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:

  key - translation key

  locale - locale to use

  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