Summary
Promote methods to register and unregister event handlers to the EventTarget
interface.
Problem
The EventTarget
interface doesn't contain the methods used to register and unregister event handlers and event filters, and as a consequence of that, code that uses EventTarget
ends up requiring lots of brittle instanceof tests to call these methods on all the different implementations of EventTarget
.
Solution
Add the following methods to javafx.event.EventTarget
:
<E extends Event> addEventHandler(EventType<E>, EventHandler<? super E>)
<E extends Event> removeEventHandler(EventType<E>, EventHandler<? super E>)
<E extends Event> addEventFilter(EventType<E>, EventHandler<? super E>)
<E extends Event> removeEventFilter(EventType<E>, EventHandler<? super E>)
Menu
, MenuItem
, TableColumnBase
and TreeItem
declare methods with the same name and a similar signature as the methods above, but instead of accepting a parameter of type EventHandler<? super E>
, they accept a parameter of type EventHandler<E>
. Since methods with a different generic signature cannot override the proposed methods of the EventTarget
interface, the conflicting method declarations must be changed to conform to the proposed interface methods.
Specification
1. EventTarget
Add the following methods to javafx.event.EventTarget
:
/**
* Registers an event handler for this target.
* <p>
* The handler is called when the target receives an {@link Event} of the specified
* type during the bubbling phase of event delivery.
*
* @param <E> the event class of the handler
* @param eventType the type of the events received by the handler
* @param eventHandler the event handler
* @throws NullPointerException if {@code eventType} or {@code eventHandler} is {@code null}
* @throws UnsupportedOperationException if this target does not support event handlers
* @implSpec The default implementation of this method throws {@code UnsupportedOperationException}.
* @since 21
*/
default <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
throw new UnsupportedOperationException();
}
/**
* Unregisters a previously registered event handler from this target.
* <p>
* It is possible to register a single {@link EventHandler} instance for different event types,
* so the caller needs to specify the event type from which the handler should be unregistered.
*
* @param <E> the event class of the handler
* @param eventType the event type from which to unregister
* @param eventHandler the event handler
* @throws NullPointerException if {@code eventType} or {@code eventHandler} is {@code null}
* @throws UnsupportedOperationException if this target does not support event handlers
* @implSpec The default implementation of this method throws {@code UnsupportedOperationException}.
* @since 21
*/
default <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
throw new UnsupportedOperationException();
}
/**
* Registers an event filter for this target.
* <p>
* The filter is called when the node receives an {@link Event} of the specified
* type during the capturing phase of event delivery.
*
* @param <E> the event class of the filter
* @param eventType the type of the events received by the filter
* @param eventFilter the event filter
* @throws NullPointerException if {@code eventType} or {@code eventFilter} is {@code null}
* @throws UnsupportedOperationException if this target does not support event filters
* @implSpec The default implementation of this method throws {@code UnsupportedOperationException}.
* @since 21
*/
default <E extends Event> void addEventFilter(EventType<E> eventType, EventHandler<? super E> eventFilter) {
throw new UnsupportedOperationException();
}
/**
* Unregisters a previously registered event filter from this target.
* <p>
* It is possible to register a single {@link EventHandler} instance for different event types,
* so the caller needs to specify the event type from which the filter should be unregistered.
*
* @param <E> the event class of the filter
* @param eventType the event type from which to unregister
* @param eventFilter the event filter
* @throws NullPointerException if {@code eventType} or {@code eventFilter} is {@code null}
* @throws UnsupportedOperationException if this target does not support event filters
* @implSpec The default implementation of this method throws {@code UnsupportedOperationException}.
* @since 21
*/
default <E extends Event> void removeEventFilter(EventType<E> eventType, EventHandler<? super E> eventFilter) {
throw new UnsupportedOperationException();
}
2. Dialog, Tab
Add the following methods to Dialog
and Tab
:
@Override
public final <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
eventHandlerManager.addEventHandler(eventType, eventHandler);
}
@Override
public final <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
eventHandlerManager.removeEventHandler(eventType, eventHandler);
}
@Override
public final <E extends Event> void addEventFilter(EventType<E> eventType, EventHandler<? super E> eventFilter) {
eventHandlerManager.addEventFilter(eventType, eventFilter);
}
@Override
public final <E extends Event> void removeEventFilter(EventType<E> eventType, EventHandler<? super E> eventFilter) {
eventHandlerManager.removeEventFilter(eventType, eventFilter);
}
3. Menu, MenuItem
Remove the following methods from Menu
(they are already declared in MenuItem
):
/** {@inheritDoc} */
@Override public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) {
eventHandlerManager.addEventHandler(eventType, eventHandler);
}
/** {@inheritDoc} */
@Override public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) {
eventHandlerManager.removeEventHandler(eventType, eventHandler);
}
Change MenuItem
as follows:
- /**
- * Registers an event handler to this MenuItem. The handler is called when the
- * menu item receives an {@code Event} of the specified type during the bubbling
- * phase of event delivery.
- *
- * @param <E> the specific event class of the handler
- * @param eventType the type of the events to receive by the handler
- * @param eventHandler the handler to register
- * @throws NullPointerException if the event type or handler is null
- */
- public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) {
+ @Override
+ public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
- /**
- * Unregisters a previously registered event handler from this MenuItem. One
- * handler might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the handler.
- *
- * @param <E> the specific event class of the handler
- * @param eventType the event type from which to unregister
- * @param eventHandler the handler to unregister
- * @throws NullPointerException if the event type or handler is null
- */
- public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) {
+ @Override
+ public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
+ @Override
+ public <E extends Event> void addEventFilter(EventType<E> eventType, EventHandler<? super E> eventFilter) {
+ eventHandlerManager.addEventFilter(eventType, eventFilter);
+ }
+ @Override
+ public <E extends Event> void removeEventFilter(EventType<E> eventType, EventHandler<? super E> eventFilter) {
+ eventHandlerManager.removeEventFilter(eventType, eventFilter);
+ }
4. TableColumnBase
Change TableColumnBase
as follows:
- /**
- * Registers an event handler to this table column. The TableColumnBase class allows
- * registration of listeners which will be notified when editing occurs.
- * Note however that TableColumnBase is <b>not</b> a Node, and therefore no visual
- * events will be fired on it.
- *
- * @param <E> The type of event
- * @param eventType the type of the events to receive by the handler
- * @param eventHandler the handler to register
- * @throws NullPointerException if the event type or handler is null
- public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) {
+ @Override
+ public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
- /**
- * Unregisters a previously registered event handler from this table column. One
- * handler might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the handler.
- *
- * @param <E> The type of event
- * @param eventType the event type from which to unregister
- * @param eventHandler the handler to unregister
- * @throws NullPointerException if the event type or handler is null
- */
- public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) {
+ @Override
+ public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
+ @Override
+ public <E extends Event> void addEventFilter(EventType<E> eventType, EventHandler<? super E> eventHandler) {
+ eventHandlerManager.addEventFilter(eventType, eventHandler);
+ }
+ @Override
+ public <E extends Event> void removeEventFilter(EventType<E> eventType, EventHandler<? super E> eventHandler) {
+ eventHandlerManager.removeEventFilter(eventType, eventHandler);
+ }
5. TreeItem
Change TreeItem
as follows:
- /**
- * Registers an event handler to this TreeItem. The TreeItem class allows
- * registration of listeners which will be notified as the
- * number of items changes, their position or if the values themselves change.
- * Note however that a TreeItem is <b>not</b> a Node, and therefore no visual
- * events will be fired on the TreeItem. To get these events, it is necessary to
- * add relevant observers to the TreeCell instances (via a custom cell factory -
- * see the {@link Cell} class documentation for more details).
- *
- * @param <E> The event
- * @param eventType the type of the events to receive by the handler
- * @param eventHandler the handler to register
- * @throws NullPointerException if the event type or handler is null
- public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) {
+ /**
+ * {@inheritDoc}
+ * <p>
+ * The {@code TreeItem} class allows registration of listeners which will be notified as the number of items
+ * changes, their position, or if the values themselves change. Note that {@code TreeItem} is <b>not</b> a
+ * {@link Node}, and therefore no visual events will be fired on it. To get these events, it is necessary to
+ * add relevant observers to the {@code TreeCell} instances via a custom cell factory (see the {@link Cell}
+ * class documentation for more details).
+ */
+ @Override
+ public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
- /**
- * Unregisters a previously registered event handler from this TreeItem. One
- * handler might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the handler.
- *
- * @param <E> The event
- * @param eventType the event type from which to unregister
- * @param eventHandler the handler to unregister
- * @throws NullPointerException if the event type or handler is null
- */
- public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) {
+ @Override
+ public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
+ /**
+ * {@inheritDoc}
+ * <p>
+ * The {@code TreeItem} class allows registration of listeners which will be notified as the number of items
+ * changes, their position, or if the values themselves change. Note that {@code TreeItem} is <b>not</b> a
+ * {@link Node}, and therefore no visual events will be fired on it. To get these events, it is necessary to
+ * add relevant observers to the {@code TreeCell} instances via a custom cell factory (see the {@link Cell}
+ * class documentation for more details).
+ */
+ @Override
+ public <E extends Event> void addEventFilter(EventType<E> eventType, EventHandler<? super E> eventHandler) {
+ eventHandlerManager.addEventFilter(eventType, eventHandler);
+ }
+ @Override
+ public <E extends Event> void removeEventFilter(EventType<E> eventType, EventHandler<? super E> eventHandler) {
+ eventHandlerManager.removeEventFilter(eventType, eventHandler);
+ }
6. Service, Task
Change Service
and Task
as follows (both classes contain the same code):
- /**
- * Registers an event handler to this task. Any event filters are first
- * processed, then the specified onFoo event handlers, and finally any
- * event handlers registered by this method. As with other events
- * in the scene graph, if an event is consumed, it will not continue
- * dispatching.
- *
- * @param <T> the specific event class of the handler
- * @param eventType the type of the events to receive by the handler
- * @param eventHandler the handler to register
- * @throws NullPointerException if the event type or handler is null
- * @since JavaFX 2.1
- */
+ /**
+ * {@inheritDoc}
+ * @since JavaFX 2.1
+ */
+ @Override
public final <T extends Event> void addEventHandler(
- /**
- * Unregisters a previously registered event handler from this task. One
- * handler might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the handler.
- *
- * @param <T> the specific event class of the handler
- * @param eventType the event type from which to unregister
- * @param eventHandler the handler to unregister
- * @throws NullPointerException if the event type or handler is null
- * @since JavaFX 2.1
- */
+ /**
+ * {@inheritDoc}
+ * @since JavaFX 2.1
+ */
+ @Override
public final <T extends Event> void removeEventHandler(
- /**
- * Registers an event filter to this task. Registered event filters get
- * an event before any associated event handlers.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the type of the events to receive by the filter
- * @param eventFilter the filter to register
- * @throws NullPointerException if the event type or filter is null
- * @since JavaFX 2.1
- */
+ /**
+ * {@inheritDoc}
+ * @since JavaFX 2.1
+ */
+ @Override
public final <T extends Event> void addEventFilter(
- /**
- * Unregisters a previously registered event filter from this task. One
- * filter might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the filter.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the event type from which to unregister
- * @param eventFilter the filter to unregister
- * @throws NullPointerException if the event type or filter is null
- * @since JavaFX 2.1
- */
+ /**
+ * {@inheritDoc}
+ * @since JavaFX 2.1
+ */
+ @Override
public final <T extends Event> void removeEventFilter(
7. Node
Change Node
as follows:
- // PENDING_DOC_REVIEW
- /**
- * Registers an event handler to this node. The handler is called when the
- * node receives an {@code Event} of the specified type during the bubbling
- * phase of event delivery.
- *
- * @param <T> the specific event class of the handler
- * @param eventType the type of the events to receive by the handler
- * @param eventHandler the handler to register
- * @throws NullPointerException if the event type or handler is null
- */
+ @Override
public final <T extends Event> void addEventHandler(
- // PENDING_DOC_REVIEW
- /**
- * Unregisters a previously registered event handler from this node. One
- * handler might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the handler.
- *
- * @param <T> the specific event class of the handler
- * @param eventType the event type from which to unregister
- * @param eventHandler the handler to unregister
- * @throws NullPointerException if the event type or handler is null
- */
+ @Override
public final <T extends Event> void removeEventHandler(
- // PENDING_DOC_REVIEW
- /**
- * Registers an event filter to this node. The filter is called when the
- * node receives an {@code Event} of the specified type during the capturing
- * phase of event delivery.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the type of the events to receive by the filter
- * @param eventFilter the filter to register
- * @throws NullPointerException if the event type or filter is null
- */
+ @Override
public final <T extends Event> void addEventFilter(
- // PENDING_DOC_REVIEW
- /**
- * Unregisters a previously registered event filter from this node. One
- * filter might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the filter.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the event type from which to unregister
- * @param eventFilter the filter to unregister
- * @throws NullPointerException if the event type or filter is null
- */
+ @Override
public final <T extends Event> void removeEventFilter(
- // PENDING_DOC_REVIEW
- /**
- * Construct an event dispatch chain for this node. The event dispatch chain
- * contains all event dispatchers from the stage to this node.
- *
- * @param tail the initial chain to build from
- * @return the resulting event dispatch chain for this node
- */
+ @Override
public EventDispatchChain buildEventDispatchChain(
8. Scene
Change Scene
as follows:
- // PENDING_DOC_REVIEW
- /**
- * Registers an event handler to this scene. The handler is called when the
- * scene receives an {@code Event} of the specified type during the bubbling
- * phase of event delivery.
- *
- * @param <T> the specific event class of the handler
- * @param eventType the type of the events to receive by the handler
- * @param eventHandler the handler to register
- * @throws NullPointerException if the event type or handler is null
- */
+ @Override
public final <T extends Event> void addEventHandler(
- // PENDING_DOC_REVIEW
- /**
- * Unregisters a previously registered event handler from this scene. One
- * handler might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the handler.
- *
- * @param <T> the specific event class of the handler
- * @param eventType the event type from which to unregister
- * @param eventHandler the handler to unregister
- * @throws NullPointerException if the event type or handler is null
- */
+ @Override
public final <T extends Event> void removeEventHandler(
- // PENDING_DOC_REVIEW
- /**
- * Registers an event filter to this scene. The filter is called when the
- * scene receives an {@code Event} of the specified type during the
- * capturing phase of event delivery.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the type of the events to receive by the filter
- * @param eventFilter the filter to register
- * @throws NullPointerException if the event type or filter is null
- */
+ @Override
public final <T extends Event> void addEventFilter(
- // PENDING_DOC_REVIEW
- /**
- * Unregisters a previously registered event filter from this scene. One
- * filter might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the filter.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the event type from which to unregister
- * @param eventFilter the filter to unregister
- * @throws NullPointerException if the event type or filter is null
- */
+ @Override
public final <T extends Event> void removeEventFilter(
- // PENDING_DOC_REVIEW
- /**
- * Construct an event dispatch chain for this scene. The event dispatch
- * chain contains all event dispatchers from the stage to this scene.
- *
- * @param tail the initial chain to build from
- * @return the resulting event dispatch chain for this scene
- */
+ @Override
public EventDispatchChain buildEventDispatchChain(
9. Transform
Change Transform
as follows:
- /**
- * Registers an event handler to this transform. Any event filters are first
- * processed, then the specified onFoo event handlers, and finally any
- * event handlers registered by this method.
- * </p><p>
- * Currently the only event delivered to a {@code Transform} is the
- * {@code TransformChangedEvent} with it's single type
- * {@code TRANSFORM_CHANGED}.
- * </p>
- *
- * @param <T> the specific event class of the handler
- * @param eventType the type of the events to receive by the handler
- * @param eventHandler the handler to register
- * @throws NullPointerException if the event type or handler is null
- * @since JavaFX 8.0
- */
+ /**
+ * {@inheritDoc}
+ * <p>
+ * Currently the only event delivered to a {@code Transform} is the {@code TransformChangedEvent}
+ * with its single type {@code TRANSFORM_CHANGED}.
+ *
+ * @since JavaFX 8.0
+ */
+ @Override
public final <T extends Event> void addEventHandler(
- /**
- * Unregisters a previously registered event handler from this transform.
- * One handler might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the handler.
- *
- * @param <T> the specific event class of the handler
- * @param eventType the event type from which to unregister
- * @param eventHandler the handler to unregister
- * @throws NullPointerException if the event type or handler is null
- * @since JavaFX 8.0
- */
+ /**
+ * {@inheritDoc}
+ * @since JavaFX 8.0
+ */
+ @Override
public final <T extends Event> void removeEventHandler(
- /**
- * {@inheritDoc}
- * <p>
- * Registers an event filter to this transform. Registered event filters get
- * an event before any associated event handlers.
- * </p><p>
- * Currently the only event delivered to a {@code Transform} is the
- * {@code TransformChangedEvent} with it's single type
- * {@code TRANSFORM_CHANGED}.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the type of the events to receive by the filter
- * @param eventFilter the filter to register
- * @throws NullPointerException if the event type or filter is null
- * @since JavaFX 8.0
- */
+ /**
+ * {@inheritDoc}
+ * <p>
+ * Currently the only event delivered to a {@code Transform} is the {@code TransformChangedEvent}
+ * with its single type {@code TRANSFORM_CHANGED}.
+ *
+ * @since JavaFX 8.0
+ */
+ @Override
public final <T extends Event> void addEventFilter(
- /**
- * Unregisters a previously registered event filter from this transform. One
- * filter might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the filter.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the event type from which to unregister
- * @param eventFilter the filter to unregister
- * @throws NullPointerException if the event type or filter is null
- * @since JavaFX 8.0
- */
+ /**
+ * {@inheritDoc}
+ * @since JavaFX 8.0
+ */
+ @Override
public final <T extends Event> void removeEventFilter(
10. Window
Change Window
as follows:
- // PENDING_DOC_REVIEW
- /**
- * Registers an event handler to this node. The handler is called when the
- * node receives an {@code Event} of the specified type during the bubbling
- * phase of event delivery.
- *
- * @param <T> the specific event class of the handler
- * @param eventType the type of the events to receive by the handler
- * @param eventHandler the handler to register
- * @throws NullPointerException if the event type or handler is null
- */
+ @Override
public final <T extends Event> void addEventHandler(
- // PENDING_DOC_REVIEW
- /**
- * Unregisters a previously registered event handler from this node. One
- * handler might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the handler.
- *
- * @param <T> the specific event class of the handler
- * @param eventType the event type from which to unregister
- * @param eventHandler the handler to unregister
- * @throws NullPointerException if the event type or handler is null
- */
+ @Override
public final <T extends Event> void removeEventHandler(
- // PENDING_DOC_REVIEW
- /**
- * Registers an event filter to this node. The filter is called when the
- * node receives an {@code Event} of the specified type during the capturing
- * phase of event delivery.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the type of the events to receive by the filter
- * @param eventFilter the filter to register
- * @throws NullPointerException if the event type or filter is null
- */
+ @Override
public final <T extends Event> void addEventFilter(
- // PENDING_DOC_REVIEW
- /**
- * Unregisters a previously registered event filter from this node. One
- * filter might have been registered for different event types, so the
- * caller needs to specify the particular event type from which to
- * unregister the filter.
- *
- * @param <T> the specific event class of the filter
- * @param eventType the event type from which to unregister
- * @param eventFilter the filter to unregister
- * @throws NullPointerException if the event type or filter is null
- */
+ @Override
public final <T extends Event> void removeEventFilter(
- // PENDING_DOC_REVIEW
- /**
- * Construct an event dispatch chain for this window.
- *
- * @param tail the initial chain to build from
- * @return the resulting event dispatch chain for this window
- */
+ @Override
public EventDispatchChain buildEventDispatchChain(
- csr of
-
JDK-8306021 Add event handler management to EventTarget
- Resolved