Rename cancelable events to interruptable events

diff --git a/wcfsetup/install/files/lib/system/event/ICancelableEvent.class.php b/wcfsetup/install/files/lib/system/event/ICancelableEvent.class.php
deleted file mode 100644 (file)
index b01acae..0000000
--- a/wcfsetup/install/files/lib/system/event/ICancelableEvent.class.php
+++ /dev/null
@@ -1,25 +0,0 @@
-<?php
-
-namespace wcf\system\event;
-
-/**
- * Indicates that the event may be cancelled, stopping the action from happening.
- *
- * @author  Tim Duesterhus
- * @copyright   2001-2021 WoltLab GmbH
- * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
- * @package WoltLabSuite\Core\System\Event
- * @since   5.5
- */
-interface ICancelableEvent extends IEvent
-{
-    /**
-     * Cancels the event.
-     */
-    public function cancel(): void;
-
-    /**
-     * Returns whether the event is cancelled.
-     */
-    public function isCancelled(): bool;
-}

diff --git a/wcfsetup/install/files/lib/system/event/IInterruptableEvent.class.php b/wcfsetup/install/files/lib/system/event/IInterruptableEvent.class.php
new file mode 100644 (file)
index 0000000..8057249
--- /dev/null
+++ b/wcfsetup/install/files/lib/system/event/IInterruptableEvent.class.php
@@ -0,0 +1,34 @@
+<?php
+
+namespace wcf\system\event;
+
+/**
+ * Event listeners handling interruptable events may indicate that the code path
+ * of the action that fired the event should not proceed.
+ *
+ * As an example, this may be used to prevent a successful login if an interruptable
+ * event is being fired when a user logs in.
+ *
+ * @author  Tim Duesterhus
+ * @copyright   2001-2021 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @package WoltLabSuite\Core\System\Event
+ * @since   5.5
+ */
+interface IInterruptableEvent extends IEvent
+{
+    /**
+     * Indicates that the code path that fired this event should not proceed after
+     * this event was handled. The caller is responsible to check the status with
+     * `defaultPrevented()`.
+     *
+     * All event listeners will be invoked, even if an event listener in the middle
+     * of the stack calls `preventDefault()`.
+     */
+    public function preventDefault(): void;
+
+    /**
+     * Returns whether preventDefault() was called.
+     */
+    public function defaultPrevented(): bool;
+}

diff --git a/wcfsetup/install/files/lib/system/event/TCancelableEvent.class.php b/wcfsetup/install/files/lib/system/event/TCancelableEvent.class.php
deleted file mode 100644 (file)
index 9497d56..0000000
--- a/wcfsetup/install/files/lib/system/event/TCancelableEvent.class.php
+++ /dev/null
@@ -1,36 +0,0 @@
-<?php
-
-namespace wcf\system\event;
-
-/**
- * Default implementation for cancelable events.
- *
- * @author  Tim Duesterhus
- * @copyright   2001-2021 WoltLab GmbH
- * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
- * @package WoltLabSuite\Core\System\Event
- * @since   5.5
- */
-trait TCancelableEvent
-{
-    /**
-     * @var bool
-     */
-    private $isCancelled = false;
-
-    /**
-     * @see ICancelableEvent::cancel()
-     */
-    public function cancel(): void
-    {
-        $this->isCancelled = true;
-    }
-
-    /**
-     * @see ICancelableEvent::isCancelled()
-     */
-    public function isCancelled(): bool
-    {
-        return $this->isCancelled;
-    }
-}

diff --git a/wcfsetup/install/files/lib/system/event/TInterruptableEvent.class.php b/wcfsetup/install/files/lib/system/event/TInterruptableEvent.class.php
new file mode 100644 (file)
index 0000000..e41b583
--- /dev/null
+++ b/wcfsetup/install/files/lib/system/event/TInterruptableEvent.class.php
@@ -0,0 +1,36 @@
+<?php
+
+namespace wcf\system\event;
+
+/**
+ * Default implementation for interruptable events.
+ *
+ * @author  Tim Duesterhus
+ * @copyright   2001-2021 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @package WoltLabSuite\Core\System\Event
+ * @since   5.5
+ */
+trait TInterruptableEvent
+{
+    /**
+     * @var bool
+     */
+    private $defaultPrevented = false;
+
+    /**
+     * @see IInterruptableEvent::preventDefault()
+     */
+    public function preventDefault(): void
+    {
+        $this->defaultPrevented = true;
+    }
+
+    /**
+     * @see IInterruptableEvent::defaultPrevented()
+     */
+    public function defaultPrevented(): bool
+    {
+        return $this->defaultPrevented;
+    }
+}