Skip to content

Commit 0b76622

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

File tree

1 file changed

+394
-0
lines changed

1 file changed

+394
-0
lines changed

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

Lines changed: 394 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,394 @@
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+
Destroy the object.
66+
</description>
67+
</request>
68+
</interface>
69+
70+
<interface name="shell_workspace_target_creation_manager_v1" version="1">
71+
<description summary="creates workspace targets">
72+
Allows the creation of workspace targets.
73+
</description>
74+
75+
<request name="destroy" type="destructor">
76+
<description summary="destroy the manager">
77+
Destroy the manager. Destroying the manager does not destroy objects
78+
created by the manager.
79+
</description>
80+
</request>
81+
82+
<request name="get_target">
83+
<description summary="create a new workspace target">
84+
This request creates a new workspace target from a given workspace
85+
target descriptor.
86+
87+
The descriptor may be destroyed following this request.
88+
89+
Because the target descriptor cannot be versioned, this request
90+
is used to create a versionable target from the descriptor.
91+
</description>
92+
93+
<arg name="target" type="new_id" interface="shell_workspace_creation_target_v1"/>
94+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
95+
</request>
96+
97+
<request name="get_info">
98+
<description summary="get information about available capabilities">
99+
This request creates an info object, which exposes information
100+
about expected capabilities of workspace targets created in a group
101+
for a given workspace manager.
102+
</description>
103+
104+
<arg name="info" type="new_id" interface="shell_workspace_target_creation_info_v1"/>
105+
<arg name="workspace_manager" type="object" interface="ext_workspace_manager_v1"/>
106+
</request>
107+
</interface>
108+
109+
<interface name="shell_workspace_target_creation_info_v1" version="1">
110+
<description summary="workspace target creation info">
111+
This object exposes information about the expected capabilities of
112+
workspace targets created on each workspace group.
113+
</description>
114+
115+
<request name="destroy" type="destructor">
116+
<description summary="destroy the manager">
117+
Destroy the object.
118+
</description>
119+
</request>
120+
121+
<event name="group_capabilities">
122+
<description summary="update the capabilities of a workspace group">
123+
This event updates the expected capabilities for workspaces on a given
124+
workspace group.
125+
126+
Capabilities exposed by this event can be used by clients to determine
127+
available actions presented to a user. As such, the presented capabilities
128+
should usually be a superset of actions available to any target that might
129+
be created in the group.
130+
131+
A group capabilities event must be sent for each workspace group, even if
132+
it has no capabilities to expose. Following all group capability updates,
133+
'ext_workspace_manaver_v1.done' must be sent.
134+
</description>
135+
136+
<arg name="group" type="object" interface="ext_workspace_group_handle_v1"/>
137+
<arg name="capabilities" type="uint" enum="shell_workspace_creation_target_v1.capabilities"/>
138+
</event>
139+
</interface>
140+
141+
<interface name="shell_workspace_arbitrary_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_arbitrary_target">
150+
<description summary="create a workspace target relative to another workspace">
151+
This requests creates a workspace target that targets an arbitrary,
152+
compositor chosen location for the workspace within the given workspace
153+
group, or any group if the no group was given.
154+
</description>
155+
156+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
157+
<arg name="group" type="object" interface="ext_workspace_group_handle_v1" allow-null="true"/>
158+
</request>
159+
</interface>
160+
161+
<interface name="shell_workspace_coordinate_creation_manager_v1" version="1">
162+
<request name="destroy" type="destructor">
163+
<description summary="destroy the manager">
164+
Destroy the manager. Destroying the manager does not destroy objects
165+
created by the manager.
166+
</description>
167+
</request>
168+
169+
<request name="get_coordinate_target">
170+
<description summary="create a workspace target at the given coordinates">
171+
This request creates a workspace target at the given coordinates in
172+
the workspace group's coordinate space. This coordinate space
173+
should match the one used in 'ext_workspace_handle_v1.coordinates'.
174+
175+
A given set of coordinates may be unrepresentable or otherwise disallowed
176+
by the compositor, in which case the workspace target will be invalid.
177+
178+
If a workspace already exists at the given coordinates, the resuling
179+
target should be valid and refer to the existing workspace.
180+
</description>
181+
182+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
183+
<arg name="group" type="object" interface="ext_workspace_group_handle_v1"/>
184+
<arg name="coordinates" type="array"/>
185+
</request>
186+
</interface>
187+
188+
<interface name="shell_workspace_relative_creation_manager_v1" version="1">
189+
<request name="destroy" type="destructor">
190+
<description summary="destroy the manager">
191+
Destroy the manager. Destroying the manager does not destroy objects
192+
created by the manager.
193+
</description>
194+
</request>
195+
196+
<request name="get_relative_target">
197+
<description summary="create a workspace target relative to another workspace">
198+
This request creates a workspace target adjacent to the given workspace
199+
in the workspace group's coordinate space. The workspace coordinate space
200+
should match the one used in 'ext_workspace_handle_v1.coordinates'.
201+
202+
The provided offset must be one of [-1, 0, 1] for each axis supported by
203+
the compositor to be valid, however other offsets may be unrepresentable
204+
or otherwise disallowed by the compositor, in which case the workspace
205+
target will be invalid.
206+
</description>
207+
208+
<arg name="descriptor" type="new_id" interface="shell_workspace_creation_target_descriptor_v1"/>
209+
<arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
210+
<arg name="offset" type="array" summary="coordinate offset from the given workspace"/>
211+
</request>
212+
</interface>
213+
214+
<interface name="shell_workspace_creation_target_v1" version="1">
215+
<request name="destroy" type="destructor">
216+
<description summary="destroy the manager">
217+
Destroy the manager. Destroying the manager does not destroy objects
218+
created by the manager.
219+
</description>
220+
</request>
221+
222+
<description summary="a target for actions that may create or activate a target workspace">
223+
A workspace creation target is a target for actions that may create a new workspace
224+
if performed. It may refer to either an existing workspace, or act as a marker
225+
of where and how a new workspace should be created.
226+
</description>
227+
228+
<request name="destroy" type="destructor">
229+
<description summary="destroy the target">
230+
Destroy the workspace target. Destroying the target does not
231+
cancel committed requests.
232+
</description>
233+
</request>
234+
235+
<enum name="capabilities">
236+
<entry name="create_request"
237+
summary="the targeted workspace can be created with no other requirements"
238+
value="1"/>
239+
<entry name="create_external"
240+
summary="the targeted workspace can be created through an extension protocol"
241+
value="2"/>
242+
<entry name="create_by_name"
243+
summary="the targeted workspace can be created by assigning a name"
244+
value="4"/>
245+
<entry name="nameable"
246+
summary="the targeted workspace can be named during creation"
247+
value="8"/>
248+
<entry name="create_by_activate"
249+
summary="the targeted workspace can be created by activating it"
250+
value="16"/>
251+
<entry name="create_by_toplevel"
252+
summary="the workspace toplevels can be created by adding a toplevel to it"
253+
value="32"/>
254+
<entry name="move_target"
255+
summary="an existing workspace can be moved to the position specified by the target"
256+
value="64"/>
257+
</enum>
258+
259+
<event name="capabilities">
260+
<description summary="update the capabilities of the workspace target">
261+
This event updates the capabilities of the workspace target.
262+
It must be sent upon creation of the target, and may be
263+
sent again at any point thereafter.
264+
265+
A workspace target without any capabilities is considered to be
266+
invalid. An invalid target may be provided by the compositor
267+
if an unrepresentable, disallowed, or otherwise invalid workspace
268+
target is requested by the client.
269+
270+
Clients are not required to check the capabilities of the target
271+
before attempting to use them, but such uses must result in failure.
272+
</description>
273+
274+
<arg name="capabilities" type="uint" enum="capabilities"/>
275+
</event>
276+
277+
<event name="success">
278+
<description summary="an action was successful">
279+
This event reports that a requested action was successful.
280+
281+
Reported 'success' and 'failed' events correspond to actions
282+
in the order they were requested.
283+
</description>
284+
</event>
285+
286+
<event name="failed">
287+
<description summary="an action was successful">
288+
This event reports that a requested action was not successful.
289+
This may be due to a missing capability or any other compositor
290+
determined reason.
291+
292+
Reported 'success' and 'failed' events correspond to actions
293+
in the order they were requested.
294+
</description>
295+
</event>
296+
297+
<request name="commit">
298+
<description summary="submit a sequence of actions">
299+
This request submits a sequence of creation actions to be
300+
performed atomically.
301+
302+
Additional creation actions may be specified using
303+
a compositor-specific extension protocol.
304+
305+
Following this request, the client will receive a series of 'success'
306+
or 'failed' events corresponding to the requested actions.
307+
308+
The client may destroy the target object following this request if it
309+
does not care about the results of the actions or wishes to determine
310+
them in another way.
311+
</description>
312+
</request>
313+
314+
<request name="create">
315+
<description summary="create the workspace">
316+
Asks the compositor to create the workspace target.
317+
This request is redundant if any other action is requested.
318+
319+
This request must not take effect until committed.
320+
321+
A 'success' or 'failed' event must be sent in response to this
322+
following a commit. The request should be considered successful
323+
if the workspace exists following the request, regardless
324+
of if its creation was a result of this request.
325+
</description>
326+
</request>
327+
328+
<request name="set_name">
329+
<description summary="set the name of the targeted workspace">
330+
Asks the compositor to give a name to the targeted workspace.
331+
332+
If the 'by_name' capability is present, assigning a name to the
333+
workspace is enough to ensure its creation. The workspace may
334+
still accept a name if the 'nameable' capability is present.
335+
336+
This request must not take effect until committed.
337+
338+
A 'success' or 'failed' event must be sent in response to this
339+
following a commit. The request should be considered successful
340+
if the workspace is active following the request, regardless
341+
of if its activation was a result of this request.
342+
</description>
343+
344+
<arg name="name" type="string"/>
345+
</request>
346+
347+
<request name="activate">
348+
<description summary="activate the target workspace">
349+
Asks the compositor to activate the workspace target.
350+
351+
This request must not take effect until committed.
352+
353+
A 'success' or 'failed' event must be sent in response to this request,
354+
following a commit. The request should be considered successful
355+
if the workspace is active following the request, regardless
356+
of if its activation was a result of this request.
357+
</description>
358+
</request>
359+
360+
<request name="add_toplevel">
361+
<description summary="add a toplevel to the target workspace">
362+
Asks the compositor to move the given toplevel to the workspace
363+
target. This request should not activate the target workspace
364+
without an additional 'activate' request.
365+
366+
This request must not take effect until committed.
367+
368+
A 'success' or 'failed' event must be sent in response to this request,
369+
following a commit. The request should be considered successful
370+
if the toplevel is present on the workspace following the request,
371+
regardless of if its presence was a result of this request.
372+
</description>
373+
374+
<arg name="toplevel" type="object" interface="ext_foreign_toplevel_handle_v1"/>
375+
</request>
376+
377+
<request name="move_workspace">
378+
<description summary="move a workspace to the workspace target">
379+
Asks the compositor to move an existing workspace to the
380+
location specified by this workspace target. This request should
381+
not activate the workspace without an additional 'activate' request.
382+
383+
This request must not take effect until committed.
384+
385+
A 'success' or 'failed' event must be sent in response to this request,
386+
following a commit. The request should be considered successful if
387+
the given workspace is in the targeted location following the request,
388+
regardless of if its presence was a result of this request.
389+
</description>
390+
391+
<arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
392+
</request>
393+
</interface>
394+
</protocol>

0 commit comments

Comments
 (0)