Skip to content

Commit 0706bb1

Browse files
committed
workspace-create: add workspace creation protocol
1 parent 486cd18 commit 0706bb1

File tree

1 file changed

+347
-0
lines changed

1 file changed

+347
-0
lines changed
Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<protocol name="shell_workspace_creation_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 the creation of workspaces">
29+
Many compositors make use of workspaces that are created dynamically
30+
based on content or focus. This protocol aims to allow creation of
31+
workspaces in such environments by combining the intent to create
32+
a workspace with actions suitable to create one.
33+
34+
This protocol additionally aims to make any logical workspace location
35+
or workspace type available to the client, through globals defined
36+
in this protocol or compositor-specific companion protocols.
37+
38+
A client may attempt to discover potential creation methods by
39+
creating new workspace targets, checking their capabilities and
40+
destroying them without use.
41+
42+
The key words "must", "must not", "required", "shall", "shall not",
43+
"should", "should not", "recommended", "may", and "optional" in this
44+
document are to be interpreted as described in IETF RFC 2119.
45+
46+
Warning! The protocol described in this file is intended as a stopgap
47+
and is expected to be superseded by a solution in wayland-protocols.
48+
Clients should not assume this protocol will continue to exist in the
49+
future.
50+
</description>
51+
52+
<interface name="shell_workspace_creation_target_descriptor_v1" version="1">
53+
<description summary="opaque workspace creation target descriptor">
54+
The workspace creation target descriptor is an opaque object
55+
that describes where and how a workspace will be created.
56+
57+
Because shell_workspace_creation_target_descriptor_v1 objects
58+
are created from multiple independent factory interfaces,
59+
the shell_workspace_creation_target_descriptor_v1 interface
60+
is frozen at version 1.
61+
</description>
62+
63+
<request name="destroy" type="destructor">
64+
<description summary="destroy the descriptor">
65+
Destroys the object.
66+
</description>
67+
</request>
68+
</interface>
69+
70+
<interface name="shell_workspace_target_creation_manager_v1" version="1">
71+
<request name="destroy" type="destructor">
72+
<description summary="destroy the manager">
73+
Destroy the manager. Destroying the manager does not destroy objects
74+
created by the manager.
75+
</description>
76+
</request>
77+
78+
<request name="get_target">
79+
<description>
80+
This request creates a new workspace target from a given workspace
81+
target descriptor.
82+
83+
The descriptor may be destroyed following this request.
84+
85+
Because the target descriptor cannot be versioned, this request
86+
is used to create a versionable target from the descriptor.
87+
</description>
88+
89+
<arg name="target" type="new_id" interface="shell_workspace_creation_target_v1"/>
90+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
91+
</request>
92+
</interface>
93+
94+
<interface name="shell_workspace_arbitrary_creation_manager_v1" version="1">
95+
<request name="destroy" type="destructor">
96+
<description summary="destroy the manager">
97+
Destroy the manager. Destroying the manager does not destroy objects
98+
created by the manager.
99+
</description>
100+
</request>
101+
102+
<request name="get_arbitrary_target">
103+
<description summary="create a workspace target relative to another workspace">
104+
This requests creates a workspace target that targets an arbitrary,
105+
compositor chosen location for the workspace within the given workspace
106+
group, or any group if the no group was given.
107+
</description>
108+
109+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
110+
<arg name="group" type="object" interface="ext_workspace_group_handle_v1" allow-null="true"/>
111+
</request>
112+
</interface>
113+
114+
<interface name="shell_workspace_coordinate_creation_manager_v1" version="1">
115+
<request name="destroy" type="destructor">
116+
<description summary="destroy the manager">
117+
Destroy the manager. Destroying the manager does not destroy objects
118+
created by the manager.
119+
</description>
120+
</request>
121+
122+
<request name="get_coordinate_target">
123+
<description summary="create a workspace target at the given coordinates">
124+
This request creates a workspace target at the given coordinates in
125+
the workspace group's coordinate space. This coordinate space
126+
should match the one used in 'ext_workspace_handle_v1.coordinates'.
127+
128+
A given set of coordinates may be unrepresentable or otherwise disallowed
129+
by the compositor, in which case the workspace target will be invalid.
130+
131+
If a workspace already exists at the given coordinates, the resuling
132+
target should be valid and refer to the existing workspace.
133+
</description>
134+
135+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
136+
<arg name="group" type="object" interface="ext_workspace_group_handle_v1"/>
137+
<arg name="coordinates" type="array"/>
138+
</request>
139+
</interface>
140+
141+
<interface name="shell_workspace_relative_creation_manager_v1" version="1">
142+
<request name="destroy" type="destructor">
143+
<description summary="destroy the manager">
144+
Destroy the manager. Destroying the manager does not destroy objects
145+
created by the manager.
146+
</description>
147+
</request>
148+
149+
<request name="get_relative_target">
150+
<description summary="create a workspace target relative to another workspace">
151+
This request creates a workspace target adjacent to the given workspace
152+
in the workspace group's coordinate space. The workspace coordinate space
153+
should match the one used in 'ext_workspace_handle_v1.coordinates'.
154+
155+
The provided offset must be one of [-1, 0, 1] for each axis supported by
156+
the compositor to be valid, however other offsets may be unrepresentable
157+
or otherwise disallowed by the compositor, in which case the workspace
158+
target will be invalid.
159+
</description>
160+
161+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
162+
<arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
163+
<arg name="offset" type="array" summary="coordinate offset from the given workspace"/>
164+
</request>
165+
</interface>
166+
167+
<interface name="shell_workspace_creation_target_v1" version="1">
168+
<request name="destroy" type="destructor">
169+
<description summary="destroy the manager">
170+
Destroy the manager. Destroying the manager does not destroy objects
171+
created by the manager.
172+
</description>
173+
</request>
174+
175+
<description summary="a target for actions that may create or activate a target workspace">
176+
A workspace creation target is a target for actions that may create a new workspace
177+
if performed. It may refer to either an existing workspace, or act as a marker
178+
of where and how a new workspace should be created.
179+
</description>
180+
181+
<request name="destroy" type="destructor">
182+
<description summary="destroy the target">
183+
Destroy the workspace target. Destroying the target does not
184+
cancel committed requests.
185+
</description>
186+
</request>
187+
188+
<enum name="capabilities">
189+
<entry name="create_request"
190+
summary="the targeted workspace can be created with no other requirements"
191+
value="1"/>
192+
<entry name="create_external"
193+
summary="the targeted workspace can be created through an extension protocol"
194+
value="2"/>
195+
<entry name="create_by_name"
196+
summary="the targeted workspace can be created by assigning a name"
197+
value="4"/>
198+
<entry name="nameable"
199+
summary="the targeted workspace can be named during creation"
200+
value="8"/>
201+
<entry name="create_by_activate"
202+
summary="the targeted workspace can be created by activating it"
203+
value="16"/>
204+
<entry name="create_by_toplevel"
205+
summary="the workspace toplevels can be created by adding a toplevel to it"
206+
value="32"/>
207+
<entry name="move_target"
208+
summary="an existing workspace can be moved to the position specified by the target"
209+
value="64"/>
210+
</enum>
211+
212+
<event name="capabilities">
213+
<description summary="update the capabilities of the workspace target">
214+
This event updates the capabilities of the workspace target.
215+
It must be sent upon creation of the target, and may be
216+
sent again at any point thereafter.
217+
218+
A workspace target without any capabilities is considered to be
219+
invalid. An invalid target may be provided by the compositor
220+
if an unrepresentable, disallowed, or otherwise invalid workspace
221+
target is requested by the client.
222+
223+
Clients are not required to check the capabilities of the target
224+
before attempting to use them, but such uses must result in failure.
225+
</description>
226+
227+
<arg name="capabilities" type="uint" enum="capabilities"/>
228+
</event>
229+
230+
<event name="success">
231+
<description summary="an action was successful">
232+
This event reports that a requested action was successful.
233+
234+
Reported 'success' and 'failed' events correspond to actions
235+
in the order they were requested.
236+
</description>
237+
</event>
238+
239+
<event name="failed">
240+
<description summary="an action was successful">
241+
This event reports that a requested action was not successful.
242+
This may be due to a missing capability or any other compositor
243+
determined reason.
244+
245+
Reported 'success' and 'failed' events correspond to actions
246+
in the order they were requested.
247+
</description>
248+
</event>
249+
250+
<request name="commit">
251+
<description summary="submit a sequence of actions">
252+
This request submits a sequence of creation actions to be
253+
performed atomically.
254+
255+
Additional creation actions may be specified using
256+
a compositor-specific extension protocol.
257+
258+
Following this request, the client will receive a series of 'success'
259+
or 'failed' events corresponding to the requested actions.
260+
261+
The client may destroy the target object following this request if it
262+
does not care about the results of the actions or wishes to determine
263+
them in another way.
264+
</description>
265+
</request>
266+
267+
<request name="create">
268+
<description summary="create the workspace">
269+
Asks the compositor to create the workspace target.
270+
This request is redundant if any other action is requested.
271+
272+
This request must not take effect until committed.
273+
274+
A 'success' or 'failed' event must be sent in response to this
275+
following a commit. The request should be considered successful
276+
if the workspace exists following the request, regardless
277+
of if its creation was a result of this request.
278+
</description>
279+
</request>
280+
281+
<request name="set_name">
282+
<description summary="set the name of the targeted workspace">
283+
Asks the compositor to give a name to the targeted workspace.
284+
285+
If the 'by_name' capability is present, assigning a name to the
286+
workspace is enough to ensure its creation. The workspace may
287+
still accept a name if the 'nameable' capability is present.
288+
289+
This request must not take effect until committed.
290+
291+
A 'success' or 'failed' event must be sent in response to this
292+
following a commit. The request should be considered successful
293+
if the workspace is active following the request, regardless
294+
of if its activation was a result of this request.
295+
</description>
296+
297+
<arg name="name" type="string"/>
298+
</request>
299+
300+
<request name="activate">
301+
<description summary="activate the target workspace">
302+
Asks the compositor to activate the workspace target.
303+
304+
This request must not take effect until committed.
305+
306+
A 'success' or 'failed' event must be sent in response to this request,
307+
following a commit. The request should be considered successful
308+
if the workspace is active following the request, regardless
309+
of if its activation was a result of this request.
310+
</description>
311+
</request>
312+
313+
<request name="add_toplevel">
314+
<description summary="add a toplevel to the target workspace">
315+
Asks the compositor to move the given toplevel to the workspace
316+
target. This request should not activate the target workspace
317+
without an additional 'activate' request.
318+
319+
This request must not take effect until committed.
320+
321+
A 'success' or 'failed' event must be sent in response to this request,
322+
following a commit. The request should be considered successful
323+
if the toplevel is present on the workspace following the request,
324+
regardless of if its presence was a result of this request.
325+
</description>
326+
327+
<arg name="toplevel" type="object" interface="ext_foreign_toplevel_handle_v1"/>
328+
</request>
329+
330+
<request name="move_workspace">
331+
<description summary="move a workspace to the workspace target">
332+
Asks the compositor to move an existing workspace to the
333+
location specified by this workspace target. This request should
334+
not activate the workspace without an additional 'activate' request.
335+
336+
This request must not take effect until committed.
337+
338+
A 'success' or 'failed' event must be sent in response to this request,
339+
following a commit. The request should be considered successful if
340+
the given workspace is in the targeted location following the request,
341+
regardless of if its presence was a result of this request.
342+
</description>
343+
344+
<arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
345+
</request>
346+
</interface>
347+
</protocol>

0 commit comments

Comments
 (0)