Skip to content

Commit ac6fea1

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

File tree

1 file changed

+260
-0
lines changed

1 file changed

+260
-0
lines changed

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

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
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+
<request name="destroy" type="destructor">
51+
<description summary="destroy the manager">
52+
Destroy the manager. Destroying the manager prior to
53+
the destruction of all trackers created by it is a protocol
54+
error, as the manager is responsible for synchronization.
55+
</description>
56+
</request>
57+
58+
<event name="done">
59+
<description summary="all geometry tracker events have been sent">
60+
This event signals that all events related to created geometry
61+
trackers and their members have been sent.
62+
</description>
63+
</event>
64+
65+
<request name="get_output_tracker">
66+
<description summary="create a geometry tracker for a given output">
67+
Creates a geometry tracker which tracks toplevels on a given output.
68+
</description>
69+
70+
<arg name="tracker" type="new_id" interface="shell_foreign_toplevel_geometry_tracker_v1"/>
71+
<arg name="output" type="object" interface="wl_output"/>
72+
</request>
73+
74+
<request name="get_workspace_tracker">
75+
<description summary="create a geometry tracker for a given workspace">
76+
Creates a geometry tracker which tracks toplevels on a given workspace.
77+
</description>
78+
79+
<arg name="tracker" type="new_id" interface="shell_foreign_toplevel_geometry_tracker_v1"/>
80+
<arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
81+
</request>
82+
</interface>
83+
84+
<interface name="shell_foreign_toplevel_geometry_tracker_v1" version="1">
85+
<description summary="tracks relative geometry of intersecting objects">
86+
A geometry tracker tracks the relative geometry of toplevels
87+
intersecting with an output or workspace.
88+
89+
Upon creation, an 'area' event must be sent.
90+
</description>
91+
92+
<enum name="error">
93+
<entry name="reset_toplevel_list"
94+
summary="attempted to assign a toplevel list to the tracker multiple times"
95+
value="1"/>
96+
<entry name="destroyed_toplevel_list"
97+
summary="toplevel list used in a geometry tracker was destroyed"
98+
value="2"/>
99+
</enum>
100+
101+
<request name="destroy" type="destructor">
102+
<description summary="destroy the tracker">
103+
Destroy the tracker. All tracker members must receive a
104+
finished event following this request.
105+
</description>
106+
</request>
107+
108+
<event name="area">
109+
<description summary="reports the geometry of the tracked area">
110+
This event reports the geometry of the tracked area.
111+
112+
Reported width and height should match the dimensions of the
113+
tracked area in logical pixels.
114+
115+
This event must be sent upon creation of the tracker, and
116+
whenever the tracked area changes. This event is double-buffered
117+
and must be followed by a
118+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
119+
</description>
120+
121+
<arg name="width" type="int"/>
122+
<arg name="height" type="int"/>
123+
</description>
124+
125+
<event name="margins">
126+
<description summary="reports insets into the tracked area">
127+
This event reports margins into the tracked area where toplevels
128+
will not normally be placed, such as exclusive zones of layer
129+
surfaces. Clients may use this information to avoid showing
130+
gaps in visual representations of the tracked area.
131+
132+
Reported margins must be in the same coordinate space as
133+
those reported by 'area'.
134+
135+
This event may be sent upon creation of the tracker, and
136+
whenever insets change. This event is double-buffered
137+
and must be followed by a
138+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
139+
</description>
140+
141+
<arg name="left" type="int"/>
142+
<arg name="top" type="int"/>
143+
<arg name="right" type="int"/>
144+
<arg name="bottom" type="int"/>
145+
</event>
146+
147+
<event name="entered">
148+
<description name="an entity has entered the tracker area">
149+
This event reports that a toplevel has entered the tracking
150+
area. Untracked entities must not receive 'entered' events.
151+
</description>
152+
153+
<arg name="member" type="new_id" interface="shell_foreign_toplevel_geometry_tracker_member_v1"/>
154+
</evnt>
155+
156+
<request name="track_toplevels">
157+
<description summary="begins tracking toplevels">
158+
This request asks the compositor to track all toplevels created by the
159+
given toplevel list that enter the tracking area.
160+
161+
Upon request, all toplevels that qualify as members of the tracker
162+
must be provided via an 'enter' event.
163+
164+
Attempting to set the toplevel list more than once is an error, as
165+
is destroying the toplevel list prior to the destruction of
166+
this object.
167+
</description>
168+
169+
<arg name="list" type="object" interface="ext_foreign_toplevel_list_v1"/>
170+
</request>
171+
</interface>
172+
173+
<interface name="shell_foreign_toplevel_geometry_tracker_member_v1" version="1">
174+
<description summary="tracked entity visible on a geometry tracker">
175+
A toplevel tracked by a geometry tracker.
176+
177+
Upon creation, toplevel, geometry, and optionally stacking order
178+
events must be sent by the compositor.
179+
</description>
180+
181+
<request name="destroy" type="destructor">
182+
<description summary="destroy the member">
183+
Destroys the tracker member object.
184+
</description>
185+
</request>
186+
187+
<event name="left">
188+
<description summary="the toplevel has left the tracked area">
189+
The toplevel has left the tracked area. A toplevel must not be
190+
considered to have left until the toplevel's geometry has no
191+
intersection with the geometry tracker.
192+
193+
Following this event, the member object should be destroyed and no more
194+
events will be sent to it. If the toplevel later re-enters the tracked
195+
area it will do so as a new object.
196+
197+
This event is double-buffered and must be followed by a
198+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
199+
</description>
200+
</event>
201+
202+
<event name="geometry">
203+
<description summary="geometry of the toplevel has changed">
204+
New toplevel geometry information is available.
205+
This event is sent upon creation of the member object or changes
206+
to the toplevel's geometry.
207+
208+
Reported geometry should include window decorations such as borders
209+
but not shadows.
210+
211+
This event is double-buffered and must be followed by a
212+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
213+
</description>
214+
215+
<arg name="x" type="int"/>
216+
<arg name="y" type="int"/>
217+
<arg name="width" type="int"/>
218+
<arg name="height" type="int"/>
219+
</event>
220+
221+
<event name="above">
222+
<description summary="the toplevel is now above another">
223+
This event reports that the toplevel is now directly above the
224+
given sibling in Z-order.
225+
226+
This event is double-buffered and must be followed by a
227+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
228+
</description>
229+
230+
<arg name="sibling" type="object" interface="shell_foreign_toplevel_geometry_tracker_member_v1"/>
231+
</event>
232+
233+
<event name="below">
234+
<description summary="the toplevel is now below another">
235+
This event reports that the toplevel is now directly below the
236+
given sibling in Z-order.
237+
238+
This event is double-buffered and must be followed by a
239+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
240+
</description>
241+
242+
<arg name="sibling" type="object" interface="shell_foreign_toplevel_geometry_tracker_member_v1"/>
243+
</event>
244+
245+
<event name="toplevel">
246+
<description summary="this member has been marked as a toplevel">
247+
This event sets the toplevel the tracker member refers to. This
248+
event can only be sent once, prior to the first 'done' event
249+
following the creation of the member object.
250+
251+
A 'left' event must be sent upon closure of the toplevel.
252+
253+
This event is double-buffered and must be followed by a
254+
'shell_foreign_toplevel_geometry_tracker_manager_v1.done' event.
255+
</description>
256+
257+
<arg name="toplevel" type="object" interface="ext_foreign_toplevel_handle_v1"/>
258+
</event>
259+
</interface>
260+
</protocol>

0 commit comments

Comments
 (0)