From: Tim Düsterhus <duesterhus@woltlab.com>
Date: Mon, 7 Jun 2021 08:19:19 +0000 (+0200)
Subject: Rename cancelable events to interruptable events
X-Git-Tag: 5.5.0_Alpha_1~687^2~4
X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=334ec699a8d738e2d8482c7fb3a1306a330c2e74;p=GitHub%2FWoltLab%2FWCF.git

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
index b01acae89c..0000000000
--- 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
index 0000000000..8057249edc
--- /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
index 9497d562c7..0000000000
--- 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
index 0000000000..e41b583b31
--- /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;
+    }
+}