Implement foreign-toplevel-info-v1

protocol/foreign-toplevel-info-unstable-v1.xml

@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="foreign_toplevel_info_unstable_v1">
+  <copyright>
+    Copyright © 2018 Ilia Bozhinov
+    Copyright © 2020 Isaac Freund
+
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation for any purpose is hereby granted
+    without fee, provided that the above copyright notice appear in
+    all copies and that both that copyright notice and this permission
+    notice appear in supporting documentation, and that the name of
+    the copyright holders not be used in advertising or publicity
+    pertaining to distribution of the software without specific,
+    written prior permission.  The copyright holders make no
+    representations about the suitability of this software for any
+    purpose.  It is provided "as is" without express or implied
+    warranty.
+
+    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+    THIS SOFTWARE.
+  </copyright>
+
+  <interface name="zext_foreign_toplevel_info_v1" version="1">
+    <description summary="list toplevels and properties thereof">
+      The purpose of this protocol is to enable clients such as taskbars
+      or docks to access a list of opened applications and basic properties
+      thereof.
+
+      The secondary purpose of this protocol is to provide protocol object
+      handles for toplevels which may be used to address said toplevels in
+      other protocols (e.g. to target a toplevel for screencopy).
+
+      After a client binds the zext_foreign_toplevel_info_v1, each opened
+      toplevel window will be sent via the toplevel event
+    </description>
+
+    <event name="toplevel">
+      <description summary="a toplevel has been created">
+        This event is emitted whenever a new toplevel window is created. It is
+        emitted for all toplevels, regardless of the app that has created them.
+
+        All initial properties of the toplevel (title, app_id, states, etc.)
+        will be sent immediately after this event via the corresponding
+        events in zext_foreign_toplevel_handle_v1.
+      </description>
+      <arg name="toplevel" type="new_id" interface="zext_foreign_toplevel_handle_v1"/>
+    </event>
+
+    <request name="stop">
+      <description summary="stop sending events">
+        This request indicates that the client no longer wishes to receive
+        events for new toplevels.  However, the compositor may emit further
+        toplevel_created events until the finished event is emitted.
+
+        The client must not send any more requests after this one.
+      </description>
+    </request>
+
+    <event name="finished">
+      <description summary="the compositor has finished with the toplevel manager">
+        This event indicates that the compositor is done sending events
+        to the zext_foreign_toplevel_info_v1. The server will destroy the
+        object immediately after sending this request, so it will become
+        invalid and the client should free any resources associated with it.
+      </description>
+    </event>
+  </interface>
+
+  <interface name="zext_foreign_toplevel_handle_v1" version="1">
+    <description summary="an open toplevel">
+      A zext_foreign_toplevel_handle_v1 object represents an open toplevel
+      window.  A single app may have multiple open toplevels.
+
+      Each toplevel has a list of outputs it is visible on, exposed to the
+      client via the output_enter and output_leave events.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the zext_foreign_toplevel_handle_v1 object">
+        This request should be called either when the client will no longer
+        use the zext_foreign_toplevel_handle_v1 or after the closed event
+        has been received to allow destruction of the object.
+      </description>
+    </request>
+
+    <event name="closed">
+      <description summary="the toplevel has been closed">
+        The server will emit no further events on the
+        zext_foreign_toplevel_handle_v1 after this event. Any requests received
+        aside from the destroy request will be ignored. Upon receiving this
+        event, the client should make the destroy request to allow freeing
+        of resources.
+      </description>
+    </event>
+
+    <event name="done">
+      <description summary="all information about the toplevel has been sent">
+        This event is sent after all changes in the toplevel state have
+        been sent.
+
+        This allows changes to the zext_foreign_toplevel_handle_v1 properties
+        to be seen as atomic, even if they happen via multiple events.
+
+        Note: this is is not sent after the closed event.
+      </description>
+    </event>
+
+    <event name="title">
+      <description summary="title change">
+        This event is emitted whenever the title of the toplevel changes.
+      </description>
+      <arg name="title" type="string"/>
+    </event>
+
+    <event name="app_id">
+      <description summary="app_id change">
+        This event is emitted whenever the app_id of the toplevel changes.
+      </description>
+      <arg name="app_id" type="string"/>
+    </event>
+
+    <event name="output_enter">
+      <description summary="toplevel entered an output">
+        This event is emitted whenever the toplevel becomes visible on the
+        given output. A toplevel may be visible on multiple outputs.
+      </description>
+      <arg name="output" type="object" interface="wl_output"/>
+    </event>
+
+    <event name="output_leave">
+      <description summary="toplevel left an output">
+        This event is emitted whenever the toplevel is no longer visible
+        on a given output. It is guaranteed that an output_enter event with
+        the same output has been emitted before this event.
+      </description>
+      <arg name="output" type="object" interface="wl_output"/>
+    </event>
+
+    <enum name="state">
+      <description summary="types of states on the toplevel">
+        The different states that a toplevel may have. These have the same
+        meaning as the states with the same names defined in xdg-toplevel
+      </description>
+      <entry name="maximized"  value="0" summary="the toplevel is maximized"/>
+      <entry name="minimized"  value="1" summary="the toplevel is minimized"/>
+      <entry name="activated"  value="2" summary="the toplevel is active"/>
+      <entry name="fullscreen" value="3" summary="the toplevel is fullscreen"/>
+    </enum>
+
+    <event name="state">
+      <description summary="the toplevel state changed">
+        This event is emitted once on creation of the
+        zext_foreign_toplevel_handle_v1 and again whenever the state of the
+        toplevel changes.
+      </description>
+      <arg name="state" type="array"/>
+    </event>
+
+    <event name="parent">
+      <description summary="parent change">
+        This event is emitted whenever the parent of the toplevel changes.
+
+        No event is emitted when the parent handle is destroyed by the client.
+      </description>
+      <arg name="parent" type="object" interface="zext_foreign_toplevel_handle_v1" allow-null="true"/>
+    </event>
+  </interface>
+</protocol>

protocol/meson.build

@@ -44,6 +44,7 @@ protocols = {
 	'wlr-output-power-management-unstable-v1': 'wlr-output-power-management-unstable-v1.xml',
 	'wlr-screencopy-unstable-v1': 'wlr-screencopy-unstable-v1.xml',
 	'wlr-virtual-pointer-unstable-v1': 'wlr-virtual-pointer-unstable-v1.xml',
+	'foreign-toplevel-info-unstable-v1': 'foreign-toplevel-info-unstable-v1.xml',
 }
 
 protocols_code = {}