From a803c12e7e63cc521d1fdaaf5f6219e752a1a0dd Mon Sep 17 00:00:00 2001
From: YaoBing Xiao <xiaoyaobing@uniontech.com>
Date: Mon, 13 Oct 2025 11:34:48 +0800
Subject: [PATCH] ext-foreign-toplevel-list: add icon event for toplevel

Add an icon event to ext_foreign_toplevel_handle_v1 that provides the
icon name for foreign toplevels following the freedesktop.org icon
naming specification. This allows clients to load appropriate icons
from the current icon theme.

Additionally, add ext_foreign_toplevel_icon_image_capture_source_manager_v1
to ext-image-capture-source-v1 as a fallback mechanism for capturing
toplevel icons when the icon event is not available.

The design uses a two-tier approach:
1. Primary: Compositors send the icon event with a themed icon name
   when icon information is available
2. Fallback: Clients can use the icon capture source manager to capture
   the actual icon image when the icon event is not sent

This addresses the need for window managers, docks, and task switchers
to display appropriate icons for all applications while maintaining
theme consistency and providing a robust fallback mechanism.

Signed-off-by: YaoBing Xiao <xiaoyaobing@uniontech.com>
---
 .../ext-foreign-toplevel-list-v1.xml          | 24 ++++++++++-
 .../ext-image-capture-source-v1.xml           | 42 +++++++++++++++++++
 2 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml b/staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml
index 11b0113..17e8778 100644
--- a/staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml
+++ b/staging/ext-foreign-toplevel-list/ext-foreign-toplevel-list-v1.xml
@@ -120,7 +120,7 @@
     </request>
   </interface>
 
-  <interface name="ext_foreign_toplevel_handle_v1" version="1">
+  <interface name="ext_foreign_toplevel_handle_v1" version="2">
     <description summary="a mapped toplevel">
       A ext_foreign_toplevel_handle_v1 object represents a mapped toplevel
       window. A single app may have multiple mapped toplevels.
@@ -215,5 +215,27 @@
       </description>
       <arg name="identifier" type="string"/>
     </event>
+
+    <!-- Version 2 additions -->
+    <event name="icon" since="2">
+      <description summary="icon information">
+        This event provides the icon name for the toplevel. The icon name
+        follows the freedesktop.org icon naming specification, allowing
+        clients to load the appropriate icon from the current icon theme.
+
+        This event is only sent when the toplevel has set an icon name via
+        xdg_toplevel_icon_v1.set_name. If the toplevel has not set an icon
+        name through this mechanism, this event will not be sent. In such
+        cases, clients should use
+        ext_foreign_toplevel_icon_image_capture_source_manager_v1 from
+        the ext-image-capture-source-v1 protocol to capture the toplevel's
+        icon if it was set via xdg_toplevel_icon_v1.add_buffer.
+
+        The configured state must not be applied immediately. See
+        ext_foreign_toplevel_handle_v1.done for details.
+      </description>
+      <arg name="icon_name" type="string"
+           summary="icon name following freedesktop.org icon naming specification"/>
+    </event>
   </interface>
 </protocol>
diff --git a/staging/ext-image-capture-source/ext-image-capture-source-v1.xml b/staging/ext-image-capture-source/ext-image-capture-source-v1.xml
index b31a5da..d552c25 100644
--- a/staging/ext-image-capture-source/ext-image-capture-source-v1.xml
+++ b/staging/ext-image-capture-source/ext-image-capture-source-v1.xml
@@ -106,4 +106,46 @@
       </description>
     </request>
   </interface>
+
+  <interface name="ext_foreign_toplevel_icon_image_capture_source_manager_v1" version="1">
+    <description summary="image capture source manager for foreign toplevel icons">
+      A manager for creating image capture source objects for capturing the
+      icon of ext_foreign_toplevel_handle_v1 objects.
+
+      This is intended as a fallback mechanism when the compositor does not
+      provide icon information via the ext_foreign_toplevel_handle_v1.icon
+      event. Clients should prefer using the icon event when available, and
+      only use this capture mechanism when the icon event is not sent.
+    </description>
+
+    <request name="create_source">
+      <description summary="create source object for foreign toplevel icon">
+        Creates a source object for capturing a foreign toplevel's icon.
+        Images captured from this source will show the icon of the toplevel.
+
+        This capture source is valid in two cases:
+        1. The toplevel has not used xdg_toplevel_icon_v1 at all
+        2. The toplevel has set an icon using xdg_toplevel_icon_v1.add_buffer
+           (capturing the explicitly set icon buffer)
+
+        If the toplevel has only used xdg_toplevel_icon_v1.set_name without
+        add_buffer, the capture source may fail or produce empty/invalid
+        results, as there is no pixel data to capture.
+
+        Clients should check if the toplevel provides icon information via
+        the ext_foreign_toplevel_handle_v1.icon event before attempting to
+        use this capture mechanism.
+      </description>
+      <arg name="source" type="new_id" interface="ext_image_capture_source_v1"/>
+      <arg name="toplevel_handle" type="object" interface="ext_foreign_toplevel_handle_v1"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="delete this object">
+        Destroys the manager. This request may be sent at any time by the client
+        and objects created by the manager will remain valid after its
+        destruction.
+      </description>
+    </request>
+  </interface>
 </protocol>