Skip to content

Commit fc7609f

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

File tree

1 file changed

+351
-0
lines changed

1 file changed

+351
-0
lines changed

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

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

0 commit comments

Comments
 (0)