Interface DomListenerRegistration
-
- All Superinterfaces:
Registration
,Serializable
public interface DomListenerRegistration extends Registration
A registration for configuring or removing a DOM event listener added to an element.- Since:
- 1.0
- Author:
- Vaadin Ltd
- See Also:
Element.addEventListener(String, DomEventListener)
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description DomListenerRegistration
addEventData(String eventData)
Add a JavaScript expression for extracting event data.default DomListenerRegistration
addEventDataElement(String eventData)
Add a JavaScript expression for extracting an element as event data.default DomListenerRegistration
debounce(int timeout)
Configures this listener to be notified only when at leasttimeout
milliseconds has passed since the last time the event was triggered.DomListenerRegistration
debounce(int timeout, DebouncePhase firstPhase, DebouncePhase... rest)
Configures the debouncing phases for which this listener should be triggered.default Set<DebouncePhase>
getDebouncePhases()
Gets the debouncing phases for which this listener should be triggered.default int
getDebounceTimeout()
Gets the debounce timeout that is configured by debounce or throttle.default String
getEventType()
Gets the event type that the listener is registered for.String
getFilter()
Gets the currently set filter expression.default DomListenerRegistration
mapEventTargetElement()
Marks that the DOM event should map theevent.target
to the closest correspondingElement
on the server side, to be returned byDomEvent.getEventTarget()
.default DomListenerRegistration
onUnregister(SerializableRunnable unregisterHandler)
Adds a handler that will be run when this registration is removed.DomListenerRegistration
setDisabledUpdateMode(DisabledUpdateMode disabledUpdateMode)
Configure whether this listener will be called even in cases when the element is disabled.DomListenerRegistration
setFilter(String filter)
Sets a JavaScript expression that is used for filtering events to this listener.default DomListenerRegistration
synchronizeProperty(String propertyName)
Marks that the DOM event of this registration should trigger synchronization for the given property.default DomListenerRegistration
throttle(int period)
Configures this listener to not be notified more often thanperiod
milliseconds.-
Methods inherited from interface com.vaadin.flow.shared.Registration
remove
-
-
-
-
Method Detail
-
addEventData
DomListenerRegistration addEventData(String eventData)
Add a JavaScript expression for extracting event data. When an event is fired in the browser, the expression is evaluated and its value is sent back to the server. The expression is evaluated in a context whereelement
refers to this element andevent
refers to the fired event. If multiple expressions are defined for the same event, their order of execution is undefined.The result of the evaluation is available in
DomEvent.getEventData()
with the expression as the key in the JSON object. An expression might be e.g.element.value
the get the value of an input element for a change event.event.button === 0
to get true for click events triggered by the primary mouse button.
- Parameters:
eventData
- definition for data that should be passed back to the server together with the event, notnull
- Returns:
- this registration, for chaining
- See Also:
for mapping an element
,to map the to an element
-
setFilter
DomListenerRegistration setFilter(String filter)
Sets a JavaScript expression that is used for filtering events to this listener. When an event is fired in the browser, the expression is evaluated and an event is sent to the server only if the expression value istrue
-ish according to JavaScript type coercion rules. The expression is evaluated in a context whereelement
refers to this element andevent
refers to the fired event.An expression might be e.g.
event.button === 0
to only forward events triggered by the primary mouse button.Any previous filter for this registration is discarded.
- Parameters:
filter
- the JavaScript filter expression, ornull
to clear the filter- Returns:
- this registration, for chaining
-
getFilter
String getFilter()
Gets the currently set filter expression.- Returns:
- the current filter expression, or
null
if no filter is in use - See Also:
setFilter(String)
-
setDisabledUpdateMode
DomListenerRegistration setDisabledUpdateMode(DisabledUpdateMode disabledUpdateMode)
Configure whether this listener will be called even in cases when the element is disabled.When used in combination with
synchronizeProperty(String)
, the most permissive update mode for the same property will be effective. This means that there might be unexpected property updates for a disabled component if multiple parties independently configure different aspects for the same component. This is based on the assumption that if a property is explicitly safe to update for disabled components in one context, then the nature of that property is probably such that it's also safe to update in other contexts.- Parameters:
disabledUpdateMode
- controls RPC communication from the client side to the server side when the element is disabled, notnull
- Returns:
- this registration, for chaining
-
debounce
DomListenerRegistration debounce(int timeout, DebouncePhase firstPhase, DebouncePhase... rest)
Configures the debouncing phases for which this listener should be triggered. Debouncing is disabled and the set phases are ignored iftimeout
is set to 0.This methods overrides the settings previously set through
debounce(int)
,throttle(int)
ordebounce(int, DebouncePhase, DebouncePhase...)
.- Parameters:
timeout
- the debounce timeout in milliseconds, or 0 to disable debouncingfirstPhase
- the first phase to userest
- any remaining phases to use- Returns:
- this registration, for chaining
- See Also:
DebouncePhase
-
debounce
default DomListenerRegistration debounce(int timeout)
Configures this listener to be notified only when at leasttimeout
milliseconds has passed since the last time the event was triggered. This is useful for cases such as text input where it's only relevant to know the result once the user stops typing.Debouncing is disabled if the
timeout
is set to 0.This methods overrides the settings previously set through
debounce(int)
,throttle(int)
ordebounce(int, DebouncePhase, DebouncePhase...)
.- Parameters:
timeout
- the debounce timeout in milliseconds, or 0 to disable debouncing- Returns:
- this registration, for chaining
-
throttle
default DomListenerRegistration throttle(int period)
Configures this listener to not be notified more often thanperiod
milliseconds.Throttling is disabled if the
period
is set to 0.This methods overrides the settings previously set through
debounce(int)
,throttle(int)
ordebounce(int, DebouncePhase, DebouncePhase...)
.- Parameters:
period
- the minimum period between listener invocations, or 0 to disable throttling- Returns:
- this registration, for chaining
-
getDebounceTimeout
default int getDebounceTimeout()
Gets the debounce timeout that is configured by debounce or throttle.- Returns:
- timeout in milliseconds, or
0
if debouncing is disabled - See Also:
debounce(int, DebouncePhase, DebouncePhase...)
,debounce(int)
,throttle(int)
-
getDebouncePhases
default Set<DebouncePhase> getDebouncePhases()
Gets the debouncing phases for which this listener should be triggered.- Returns:
- debounce phases
- See Also:
debounce(int, DebouncePhase, DebouncePhase...)
,debounce(int)
,throttle(int)
-
getEventType
default String getEventType()
Gets the event type that the listener is registered for.- Returns:
- DOM event type of the listener
-
onUnregister
default DomListenerRegistration onUnregister(SerializableRunnable unregisterHandler)
Adds a handler that will be run when this registration is removed.- Parameters:
unregisterHandler
- the handler to run when the registration is removed, notnull
- Returns:
- this registration, for chaining
- Since:
- 1.3
-
synchronizeProperty
default DomListenerRegistration synchronizeProperty(String propertyName)
Marks that the DOM event of this registration should trigger synchronization for the given property.- Parameters:
propertyName
- the name of the property to synchronize, notnull
or""
- Returns:
- this registration, for chaining
-
mapEventTargetElement
default DomListenerRegistration mapEventTargetElement()
Marks that the DOM event should map theevent.target
to the closest correspondingElement
on the server side, to be returned byDomEvent.getEventTarget()
.- Returns:
- this registration, for chaining
- Since:
- 9.0
-
addEventDataElement
default DomListenerRegistration addEventDataElement(String eventData)
Add a JavaScript expression for extracting an element as event data. When an event is fired in the browser, the expression is evaluated and if it returns an element from DOM, the server side element or closest parent element is sent to server side. The expression is evaluated in a context whereelement
refers to this element andevent
refers to the fired event. If multiple expressions are defined for the same event, their order of execution is undefined.The result of the evaluation is available in
DomEvent.getEventDataElement(String)
with the expression as the key in the JSON object.In case you want to get the
event.target
element to the server side, use themapEventTargetElement()
method to get it mapped and theDomEvent.getEventTarget()
to fetch the element.- Parameters:
eventData
- definition for element that should be passed back to the server together with the event, notnull
- Returns:
- this registration, for chaining
- Since:
- 9.0
- See Also:
to map the to an element
-
-