8306021: Add event handler management to EventTarget

Reviewed-by: jhendrikx, nlisker, angorya, mhanl, kcr

Author: Michael Strauß

modules/javafx.base/src/main/java/javafx/event/EventTarget.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -54,4 +54,76 @@ public interface EventTarget {
      * @return the resulting event dispatch chain for this target
      */
     EventDispatchChain buildEventDispatchChain(EventDispatchChain tail);
+
+    /**
+     * 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>
+     * Since it is possible to register a single {@link EventHandler} instance for different event types,
+     * 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 target 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>
+     * Since it is possible to register a single {@link EventHandler} instance for different event types,
+     * 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();
+    }
 }

modules/javafx.controls/src/main/java/javafx/scene/control/Dialog.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -40,6 +40,7 @@
 import javafx.event.EventDispatchChain;
 import javafx.event.EventHandler;
 import javafx.event.EventTarget;
+import javafx.event.EventType;
 import javafx.scene.Node;
 import javafx.scene.control.ButtonBar.ButtonData;
 import javafx.stage.Modality;
@@ -894,11 +895,31 @@ public final ReadOnlyDoubleProperty yProperty() {
 
     private final EventHandlerManager eventHandlerManager = new EventHandlerManager(this);
 
-    /** {@inheritDoc} */
-    @Override public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
+    @Override
+    public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
         return tail.prepend(eventHandlerManager);
     }
 
+    @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);
+    }
+
     /**
      * Called just prior to the Dialog being shown.
      */

modules/javafx.controls/src/main/java/javafx/scene/control/Menu.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -30,6 +30,7 @@
 import javafx.collections.ListChangeListener.Change;
 import javafx.collections.ObservableList;
 import javafx.event.Event;
+import javafx.event.EventDispatchChain;
 import javafx.event.EventHandler;
 import javafx.event.EventType;
 import javafx.scene.Node;
@@ -39,7 +40,6 @@
 import javafx.beans.DefaultProperty;
 import javafx.beans.property.ReadOnlyBooleanProperty;
 import javafx.beans.property.ReadOnlyBooleanWrapper;
-import javafx.event.EventDispatchChain;
 
 /**
  * <p>
@@ -429,18 +429,8 @@ public void hide() {
         setShowing(false);
     }
 
-    /** {@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);
-    }
-
-     /** {@inheritDoc} */
-    @Override public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
+    @Override
+    public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
         return tail.prepend(eventHandlerManager);
     }
 

modules/javafx.controls/src/main/java/javafx/scene/control/MenuItem.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -459,37 +459,8 @@ public void fire() {
         Event.fireEvent(this, new ActionEvent(this, this));
     }
 
-    /**
-     * 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) {
-        eventHandlerManager.addEventHandler(eventType, 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) {
-        eventHandlerManager.removeEventHandler(eventType, eventHandler);
-    }
-
-    /** {@inheritDoc} */
-    @Override public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
+    @Override
+    public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
         // FIXME review that these are configure properly
         if (getParentPopup() != null) {
             getParentPopup().buildEventDispatchChain(tail);
@@ -502,6 +473,26 @@ public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHa
         return tail.prepend(eventHandlerManager);
     }
 
+    @Override
+    public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
+        eventHandlerManager.addEventHandler(eventType, eventHandler);
+    }
+
+    @Override
+    public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) {
+        eventHandlerManager.removeEventHandler(eventType, 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);
+    }
+
     /**
      * Returns the {@code Object} that was set by {@link #setUserData(Object)}, or {@code null} if no object has been
      * set.

modules/javafx.controls/src/main/java/javafx/scene/control/Tab.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -820,12 +820,31 @@ public ObservableList<String> getStyleClass() {
     private final EventHandlerManager eventHandlerManager =
             new EventHandlerManager(this);
 
-     /** {@inheritDoc} */
     @Override
     public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
         return tail.prepend(eventHandlerManager);
     }
 
+    @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);
+    }
+
     <E extends Event> void setEventHandler(EventType<E> eventType, EventHandler<E> eventHandler) {
         eventHandlerManager.setEventHandler(eventType, eventHandler);
     }

modules/javafx.controls/src/main/java/javafx/scene/control/TableColumnBase.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -726,42 +726,30 @@ public final T getCellData(final S item) {
      */
     public abstract ObservableValue<T> getCellObservableValue(S item);
 
-    /** {@inheritDoc} */
-    @Override public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
+    @Override
+    public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) {
         return tail.prepend(eventHandlerManager);
     }
 
-    /**
-     * 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) {
         eventHandlerManager.addEventHandler(eventType, 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) {
         eventHandlerManager.removeEventHandler(eventType, 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);
+    }
 
     /* *************************************************************************
      *                                                                         *