Skip to content

Commit 4ace463

Browse files
outfoxxedoutfoxxed
committed
geom-tracker: add geometry tracker protocol
1 parent 486cd18 commit 4ace463

File tree

1 file changed

+267
-0
lines changed

1 file changed

+267
-0
lines changed

‎protocols/shell-foreign-toplevel-geometry-tracker-v1.xml

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<protocol name="shell_foreign_toplevel_geometry_tracker_v1">
3+
<copyright>
4+
Copyright © 2025 outfoxxed
5+
6+
Permission to use, copy, modify, distribute, and sell this
7+
software and its documentation for any purpose is hereby granted
8+
without fee, provided that the above copyright notice appear in
9+
all copies and that both that copyright notice and this permission
10+
notice appear in supporting documentation, and that the name of
11+
the copyright holders not be used in advertising or publicity
12+
pertaining to distribution of the software without specific,
13+
written prior permission. The copyright holders make no
14+
representations about the suitability of this software for any
15+
purpose. It is provided "as is" without express or implied
16+
warranty.
17+
18+
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
19+
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
20+
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
21+
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
22+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
23+
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
24+
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
25+
THIS SOFTWARE.
26+
</copyright>
27+
28+
<description summary="protocol allowing clients to track foreign toplevel geometry">
29+
This protocol allows clients to track the geometry of toplevels
30+
relative to outputs or workspaces, enabling workspace overviews
31+
and window picking.
32+
33+
This protocol is privileged and should be limited to trusted clients.
34+
35+
The key words "must", "must not", "required", "shall", "shall not",
36+
"should", "should not", "recommended", "may", and "optional" in this
37+
document are to be interpreted as described in IETF RFC 2119.
38+
39+
Warning! The protocol described in this file is intended as a stopgap
40+
and is expected to be superseded by a solution in wayland-protocols.
41+
Clients should not assume this protocol will continue to exist in the
42+
future.
43+
</description>
44+
45+
<interface name="shell_foreign_toplevel_geometry_tracker_manager_v1" version="1">
46+
<description summary="manager for geometry trackers">
47+
This global creates and synchronizes geometry trackers.
48+
</description>
49+
50+
<enum name="error">
51+
<entry name="live_trackers"
52+
summary="destroyed geometry tracker manager while trackers were live"
53+
value="1"/>
54+
</enum>
55+
56+
<request name="destroy" type="destructor">
57+
<description summary="destroy the manager">
58+
Destroy the manager. Destroying the manager prior to
59+
the destruction of all trackers created by it is a protocol
60+
error, as the manager is responsible for synchronization.
61+
</description>
62+
</request>
63+
64+
<event name="done">
65+
<description summary="all geometry tracker events have been sent">
66+
This event signals that all events related to created geometry
67+
trackers and their members have been sent.
68+
</description>
69+
</event>
70+
71+
<request name="get_output_tracker">
72+
<description summary="create a geometry tracker for a given output">
73+
Creates a geometry tracker which tracks toplevels on a given output.
74+
</description>
75+
76+
<arg name="tracker" type="new_id" interface="shell_foreign_toplevel_geometry_tracker_v1"/>
77+
<arg name="output" type="object" interface="wl_output"/>
78+
</request>
79+
80+
<request name="get_workspace_tracker">
81+
<description summary="create a geometry tracker for a given workspace">
82+
Creates a geometry tracker which tracks toplevels on a given workspace.
83+
</description>
84+
85+
<arg name="tracker" type="new_id" interface="shell_foreign_toplevel_geometry_tracker_v1"/>
86+
<arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
87+
</request>
88+
</interface>
89+
90+
<interface name="shell_foreign_toplevel_geometry_tracker_v1" version="1">
91+
<description summary="tracks relative geometry of intersecting objects">
92+
A geometry tracker tracks the relative geometry of toplevels
93+
intersecting with an output or workspace.
94+
95+
Upon creation, an 'area' event must be sent.
96+
</description>
97+
98+
<enum name="error">
99+
<entry name="reset_toplevel_list"
100+
summary="attempted to assign a toplevel list to the tracker multiple times"
101+
value="1"/>
102+
<entry name="destroyed_toplevel_list"
103+
summary="toplevel list used in a geometry tracker was destroyed"
104+
value="2"/>
105+
</enum>
106+
107+
<request name="destroy" type="destructor">
108+
<description summary="destroy the tracker">
109+
Destroy the tracker. All tracker members must receive a
110+
finished event following this request.
111+
</description>
112+
</request>
113+
114+
<event name="area">
115+
<description summary="reports the geometry of the tracked area">
116+
This event reports the geometry of the tracked area.
117+
118+
Reported width and height should match the dimensions of the
119+
tracked area in logical pixels.
120+
121+
This event must be sent upon creation of the tracker, and
122+
whenever the tracked area changes. This event is double-buffered
123+
and must be followed by a
124+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
125+
</description>
126+
127+
<arg name="width" type="int"/>
128+
<arg name="height" type="int"/>
129+
</event>
130+
131+
<event name="margins">
132+
<description summary="reports insets into the tracked area">
133+
This event reports margins into the tracked area where toplevels
134+
may not normally be placed, such as exclusive zones of layer
135+
surfaces. Clients may use this information to avoid showing
136+
gaps in visual representations of the tracked area.
137+
138+
Reported margins must be in the same coordinate space as
139+
those reported by 'area'.
140+
141+
This event may be sent upon creation of the tracker, and
142+
whenever insets change. This event is double-buffered
143+
and must be followed by a
144+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
145+
</description>
146+
147+
<arg name="left" type="int"/>
148+
<arg name="top" type="int"/>
149+
<arg name="right" type="int"/>
150+
<arg name="bottom" type="int"/>
151+
</event>
152+
153+
<event name="entered">
154+
<description name="an entity has entered the tracker area">
155+
This event reports that a toplevel has entered the tracking
156+
area. Untracked entities must not receive 'entered' events.
157+
</description>
158+
159+
<arg name="member" type="new_id" interface="shell_foreign_toplevel_geometry_tracker_member_v1"/>
160+
</evnt>
161+
162+
<request name="track_toplevels">
163+
<description summary="begins tracking toplevels">
164+
This request asks the compositor to track all toplevels created by the
165+
given toplevel list that enter the tracking area.
166+
167+
Upon request, all toplevels that qualify as members of the tracker
168+
must be provided via an 'enter' event.
169+
170+
Attempting to set the toplevel list more than once is an error, as
171+
is destroying the toplevel list prior to the destruction of
172+
this object.
173+
</description>
174+
175+
<arg name="list" type="object" interface="ext_foreign_toplevel_list_v1"/>
176+
</request>
177+
</interface>
178+
179+
<interface name="shell_foreign_toplevel_geometry_tracker_member_v1" version="1">
180+
<description summary="tracked entity visible on a geometry tracker">
181+
A toplevel tracked by a geometry tracker.
182+
183+
Upon creation, toplevel, geometry, and optionally stacking order
184+
events must be sent by the compositor.
185+
</description>
186+
187+
<request name="destroy" type="destructor">
188+
<description summary="destroy the member">
189+
Destroys the tracker member object.
190+
</description>
191+
</request>
192+
193+
<event name="left">
194+
<description summary="the toplevel has left the tracked area">
195+
The toplevel has left the tracked area. A toplevel must not be
196+
considered to have left until the toplevel's geometry has no
197+
intersection with the geometry tracker.
198+
199+
Following this event, the member object should be destroyed and no more
200+
events will be sent to it. If the toplevel later re-enters the tracked
201+
area it will do so as a new object.
202+
203+
This event is double-buffered and must be followed by a
204+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
205+
</description>
206+
</event>
207+
208+
<event name="geometry">
209+
<description summary="geometry of the toplevel has changed">
210+
New toplevel geometry information is available.
211+
This event is sent upon creation of the member object or changes
212+
to the toplevel's geometry.
213+
214+
Compositor policy dictates which window decorations are included
215+
in the toplevel's geometry, but excluding non-window extents
216+
such as shadows is recommended.
217+
218+
This event is double-buffered and must be followed by a
219+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
220+
</description>
221+
222+
<arg name="x" type="int"/>
223+
<arg name="y" type="int"/>
224+
<arg name="width" type="int"/>
225+
<arg name="height" type="int"/>
226+
</event>
227+
228+
<event name="above">
229+
<description summary="the toplevel is now above another">
230+
This event reports that the toplevel is now directly above the
231+
given sibling in Z-order.
232+
233+
This event is double-buffered and must be followed by a
234+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
235+
</description>
236+
237+
<arg name="sibling" type="object" interface="shell_foreign_toplevel_geometry_tracker_member_v1"/>
238+
</event>
239+
240+
<event name="below">
241+
<description summary="the toplevel is now below another">
242+
This event reports that the toplevel is now directly below the
243+
given sibling in Z-order.
244+
245+
This event is double-buffered and must be followed by a
246+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
247+
</description>
248+
249+
<arg name="sibling" type="object" interface="shell_foreign_toplevel_geometry_tracker_member_v1"/>
250+
</event>
251+
252+
<event name="toplevel">
253+
<description summary="this member has been marked as a toplevel">
254+
This event sets the toplevel the tracker member refers to. This
255+
event can only be sent once, prior to the first 'done' event
256+
following the creation of the member object.
257+
258+
A 'left' event must be sent upon closure of the toplevel.
259+
260+
This event is double-buffered and must be followed by a
261+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
262+
</description>
263+
264+
<arg name="toplevel" type="object" interface="ext_foreign_toplevel_handle_v1"/>
265+
</event>
266+
</interface>
267+
</protocol>

0 commit comments

Comments
 (0)