From de15f2cd207f17ae94b74f7e35a287606d9aeb36 Mon Sep 17 00:00:00 2001
From: probonopd <probono@puredarwin.org>
Date: Sun, 30 Mar 2025 15:37:08 +0000
Subject: [PATCH] Add `not_placed` event

---
 .../ext-toplevel-placement-v1.xml               | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/staging/ext-toplevel-placement/ext-toplevel-placement-v1.xml b/staging/ext-toplevel-placement/ext-toplevel-placement-v1.xml
index 508b8a3..00adb1a 100644
--- a/staging/ext-toplevel-placement/ext-toplevel-placement-v1.xml
+++ b/staging/ext-toplevel-placement/ext-toplevel-placement-v1.xml
@@ -92,8 +92,9 @@
         Compositors are unlikely to substantially alter placement based on
         suggestions sent after the window is already mapped and positioned.
 
-        This request causes the compositor to send the placement state, including
-        the output and logical coordinates where the toplevel is currently placed.
+        This request causes the compositor to send `placement_state`, including
+        the output and logical coordinates where the toplevel is currently placed,
+        or `not_placed`.
       </description>
       <arg name="output" type="object" interface="xdg_output" summary="target output"/>
       <arg name="x" type="int" summary="suggested logical x coordinate relative to output"/>
@@ -127,6 +128,18 @@
        <arg name="y" type="int" summary="current logical y coordinate relative to output"/>
     </event>
 
+    <event name="not_placed">
+      <description summary="notify client that placement based on suggestion definitively failed">
+        This event is sent if the compositor *cannot* place the toplevel window
+        *as suggested*. This might be due to various reasons like no suitable output,
+        geometry conflicts, or unresolvable policy restrictions *after considering the suggestion*.
+        Receiving this event implies that the compositor will *not* honor the
+        placement suggestion and the toplevel might not be placed at all, or will be
+        placed using a fallback mechanism unrelated to the suggestion.
+      </description>
+      <arg name="reason_string" type="string" optional="true" summary="optional human-readable reason for placement failure"/>
+    </event>
+
   </interface>
 
 </protocol>
\ No newline at end of file