Skip to content

Commit c5f88f2

Browse files
outfoxxedoutfoxxed
committed
workspace-create: add workspace creation protocol
1 parent 486cd18 commit c5f88f2

File tree

1 file changed

+321
-0
lines changed

1 file changed

+321
-0
lines changed

‎protocols/shell-workspace-creation-v1.xml

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
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 name and location for the workspace.
106+
</description>
107+
108+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
109+
</request>
110+
</interface>
111+
112+
<interface name="shell_workspace_coordinate_creation_manager_v1" version="1">
113+
<request name="destroy" type="destructor">
114+
<description summary="destroy the manager">
115+
Destroy the manager. Destroying the manager does not destroy objects
116+
created by the manager.
117+
</description>
118+
</request>
119+
120+
<request name="get_coordinate_target">
121+
<description summary="create a workspace target at the given coordinates">
122+
This request creates a workspace target at the given coordinates in
123+
the compositor's workspace coordinate space. This coordinate space
124+
should match the one used in 'ext_workspace_handle_v1.coordinates'.
125+
126+
A given set of coordinates may be unrepresentable or otherwise disallowed
127+
by the compositor, in which case the workspace target will be invalid.
128+
129+
If a workspace already exists at the given coordinates, the resuling
130+
target should be valid and refer to the existing workspace.
131+
</description>
132+
133+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
134+
<arg name="coordinates" type="array"/>
135+
</request>
136+
</interface>
137+
138+
<interface name="shell_workspace_relative_creation_manager_v1" version="1">
139+
<request name="destroy" type="destructor">
140+
<description summary="destroy the manager">
141+
Destroy the manager. Destroying the manager does not destroy objects
142+
created by the manager.
143+
</description>
144+
</request>
145+
146+
<request name="get_relative_target">
147+
<description summary="create a workspace target relative to another workspace">
148+
This request creates a workspace target at the given coordinate offset
149+
from another workspace. The workspace coordinate space should match the
150+
one used in 'ext_workspace_handle_v1.coordinates'.
151+
152+
A given coordinate offset may be unrepresentable or otherwise disallowed
153+
by the compositor, in which case the workspace target will be invalid.
154+
155+
If a workspace already exists at the given offset, the resuling
156+
target should be valid and refer to the existing workspace.
157+
</description>
158+
159+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
160+
<arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
161+
<arg name="offset" type="array" summary="coordinate offset from the given workspace"/>
162+
</request>
163+
</interface>
164+
165+
<interface name="shell_workspace_creation_target_v1" version="1">
166+
<request name="destroy" type="destructor">
167+
<description summary="destroy the manager">
168+
Destroy the manager. Destroying the manager does not destroy objects
169+
created by the manager.
170+
</description>
171+
</request>
172+
173+
<description summary="a target for actions that may create or activate a target workspace">
174+
A workspace creation target is a target for actions that may create a new workspace
175+
if performed. It may refer to either an existing workspace, or act as a marker
176+
of where and how a new workspace should be created.
177+
</description>
178+
179+
<request name="destroy" type="destructor">
180+
<description summary="destroy the target">
181+
Destroy the workspace target. Destroying the target does not
182+
cancel committed requests.
183+
</description>
184+
</request>
185+
186+
<enum name="capabilities">
187+
<entry name="create"
188+
summary="the targeted workspace can be created with only a request"
189+
value="1"/>
190+
<entry name="external"
191+
summary="the targeted workspace can be created through an extension protocol"
192+
value="2"/>
193+
<entry name="by_name"
194+
summary="the targeted workspace can be created by assigning a name"
195+
value="4"/>
196+
<entry name="nameable"
197+
summary="the targeted workspace can be named during creation"
198+
value="8"/>
199+
<entry name="activate"
200+
summary="the targeted workspace can be created by activating it"
201+
value="16"/>
202+
<entry name="add_toplevel"
203+
summary="the workspace toplevels can be created by adding a toplevel to it"
204+
value="32"/>
205+
</enum>
206+
207+
<event name="capabilities">
208+
<description summary="update the capabilities of the workspace target">
209+
This event updates the capabilities of the workspace target.
210+
It must be sent upon creation of the target, and may be
211+
sent again at any point thereafter.
212+
213+
A workspace target without any capabilities is considered to be
214+
invalid. An invalid target may be provided by the compositor
215+
if an unrepresentable, disallowed, or otherwise invalid workspace
216+
target is requested by the client.
217+
218+
Clients are not required to check the capabilities of the target
219+
before attempting to use them, but such uses must result in failure.
220+
</description>
221+
222+
<arg name="capabilities" type="uint" enum="capabilities"/>
223+
</event>
224+
225+
<event name="success">
226+
<description summary="an action was successful">
227+
This event reports that a requested action was successful.
228+
229+
Reported 'success' and 'failed' events correspond to actions
230+
in the order they were requested.
231+
</description>
232+
</event>
233+
234+
<event name="failed">
235+
<description summary="an action was successful">
236+
This event reports that a requested action was not successful.
237+
This may be due to a missing capability or any other compositor
238+
determined reason.
239+
240+
Reported 'success' and 'failed' events correspond to actions
241+
in the order they were requested.
242+
</description>
243+
</event>
244+
245+
<request name="commit">
246+
<description summary="submit a sequence of actions">
247+
This request submits a sequence of creation actions to be
248+
performed atomically.
249+
250+
Additional creation actions may be specified using
251+
a compositor-specific extension protocol.
252+
253+
Following this request, the client will receive a series of 'success'
254+
or 'failed' events corresponding to the requested actions.
255+
256+
The client may destroy the target object following this request if it
257+
does not care about the results of the actions or wishes to determine
258+
them in another way.
259+
</description>
260+
</request>
261+
262+
<request name="create">
263+
<description summary="create the workspace">
264+
Asks the compositor to create the workspace target.
265+
This request is redundant if any other action is requested.
266+
267+
This request must not take effect until committed.
268+
269+
A 'success' or 'failed' event must be sent in response to this
270+
following a commit. The request should be considered successful
271+
if the workspace exists following the request, regardless
272+
of if its creation was a result of this request.
273+
</description>
274+
</request>
275+
276+
<request name="set_name">
277+
<description summary="set the name of the targeted workspace">
278+
Asks the compositor to give a name to the targeted workspace.
279+
280+
If the 'by_name' capability is present, assigning a name to the
281+
workspace is enough to ensure its creation. The workspace may
282+
still accept a name if the 'nameable' capability is present.
283+
284+
This request must not take effect until committed.
285+
286+
A 'success' or 'failed' event must be sent in response to this
287+
following a commit. The request should be considered successful
288+
if the workspace is active following the request, regardless
289+
of if its activation was a result of this request.
290+
</description>
291+
</request>
292+
293+
<request name="activate">
294+
<description summary="activate the target workspace">
295+
Asks the compositor to active the workspace target.
296+
297+
This request must not take effect until committed.
298+
299+
A 'success' or 'failed' event must be sent in response to this
300+
following a commit. The request should be considered successful
301+
if the workspace is active following the request, regardless
302+
of if its activation was a result of this request.
303+
</description>
304+
</request>
305+
306+
<request name="add_toplevel">
307+
<description summary="add a toplevel to the target workspace">
308+
Asks the compositor to move the given toplevel to the workspace
309+
target. This request should not activate the target workspace
310+
without an additional 'activate' request.
311+
312+
This request must not take effect until committed.
313+
314+
A 'success' or 'failed' event must be sent in response to this
315+
following a commit. The request should be considered successful
316+
if the toplevel is present on the workspace following the request,
317+
regardless of if its presence was a result of this request.
318+
</description>
319+
</request>
320+
</interface>
321+
</protocol>

0 commit comments

Comments
 (0)