public abstract class Component extends Object implements HasElement, AttachNotifier, DetachNotifier
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.
Modifier | Constructor and Description |
---|---|
protected |
Component()
Creates a component instance with an element created based on the
Tag annotation of the sub class. |
protected |
Component(Element element)
Creates a component instance based on the given element.
|
Modifier and Type | Method and Description |
---|---|
protected <T extends ComponentEvent<?>> |
addListener(Class<T> eventType,
ComponentEventListener<T> listener)
Adds a listener for an event of the given type.
|
protected void |
fireEvent(ComponentEvent<?> componentEvent)
Dispatches the event to all listeners registered for the event type.
|
static <T extends Component> |
from(Element element,
Class<T> componentType)
Creates a new component instance using the given element.
|
protected <T> T |
get(PropertyDescriptor<?,T> descriptor)
Gets the value of the given component property.
|
Stream<Component> |
getChildren()
Gets the child components of this component.
|
Element |
getElement()
Gets the root element of this component.
|
protected ComponentEventBus |
getEventBus()
Gets the event bus for this component.
|
Optional<String> |
getId()
Gets the id of the root element of this component.
|
protected Locale |
getLocale()
Gets the locale for this component.
|
Optional<Component> |
getParent()
Gets the parent component of this component.
|
String |
getTranslation(Object key,
Locale locale,
Object... params)
Get the translation for key with given locale.
|
String |
getTranslation(Object key,
Object... params)
Get the translation for the component locale.
|
String |
getTranslation(String key,
Locale locale,
Object... params)
Get the translation for key with given locale.
|
String |
getTranslation(String key,
Object... params)
Get the translation for the component locale.
|
Optional<UI> |
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 |
isAttached()
Checks whether this component is currently attached to a UI.
|
protected boolean |
isTemplateMapped()
Gets whether this component was attached as part of a
PolymerTemplate (by being mapped by an Id annotation), or
if it was created directly. |
boolean |
isVisible()
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.
|
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 |
setId(String id)
Sets the id of the root element of this component.
|
void |
setVisible(boolean visible)
Sets the component visibility value.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
addAttachListener
addDetachListener
protected Component()
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.
protected Component(Element 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.
element
- the root element for the componentpublic Element getElement()
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.
getElement
in interface HasElement
protected static void setElement(Component component, Element element)
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.
component
- the component to set the root element toelement
- the root element of the componentpublic Optional<Component> getParent()
A component can only have one parent.
public Stream<Component> getChildren()
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.
Id
protected ComponentEventBus getEventBus()
This method will create the event bus if it has not yet been created.
protected <T extends ComponentEvent<?>> Registration addListener(Class<T> eventType, ComponentEventListener<T> listener)
T
- the component event typeeventType
- the component event type, not null
listener
- the listener to add, not null
protected boolean hasListener(Class<? extends ComponentEvent> eventType)
eventType
- the component event typetrue
if at least one listener is registered,
false
otherwiseprotected void fireEvent(ComponentEvent<?> componentEvent)
componentEvent
- the event to fireComponentUtil.fireEvent(Component, ComponentEvent)
public Optional<UI> getUI()
public void setId(String id)
id
- the id to set, or ""
to remove any previously set
idpublic Optional<String> getId()
setId(String)
protected void onAttach(AttachEvent attachEvent)
The default implementation does nothing.
This method is invoked before the AttachEvent
is fired for the
component.
attachEvent
- the attach eventprotected void onDetach(DetachEvent detachEvent)
The default implementation does nothing.
This method is invoked before the DetachEvent
is fired for the
component.
detachEvent
- the detach eventpublic boolean isAttached()
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.
protected <T> void set(PropertyDescriptor<T,?> descriptor, T value)
T
- type of the value to setdescriptor
- the descriptor for the property to set, not null
value
- the new property value to setPropertyDescriptor
protected <T> T get(PropertyDescriptor<?,T> descriptor)
T
- type of the value to getdescriptor
- the descriptor for the property to set, not null
PropertyDescriptor
public static <T extends Component> T from(Element element, Class<T> componentType)
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
.
T
- the component type to createelement
- the element to wrapcomponentType
- the component typeElement.as(Class)
public void setVisible(boolean visible)
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.
visible
- the component visibility valuepublic boolean isVisible()
true
if the component is visible, false
otherwisepublic void onEnabledStateChanged(boolean enabled)
By default this sets or removes the 'disabled' attribute from the element. This can be overridden to have custom handling.
enabled
- the new enabled state of the componentprotected boolean isTemplateMapped()
PolymerTemplate
(by being mapped by an Id
annotation), or
if it was created directly.true
when it was mapped inside a template,
false
otherwisepublic String getTranslation(String key, Object... params)
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}!'.
key
- translation keyparams
- parameters used in translation stringgetLocale()
public String getTranslation(Object key, Object... params)
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}!'.
key
- translation keyparams
- parameters used in translation stringgetLocale()
public String getTranslation(String key, Locale locale, Object... params)
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}!'.
key
- translation keylocale
- locale to useparams
- parameters used in translation stringpublic String getTranslation(Object key, Locale locale, Object... params)
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}!'.
key
- translation keylocale
- locale to useparams
- parameters used in translation stringprotected Locale getLocale()
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.
Copyright © 2023. All rights reserved.