1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="ext_workspace_v1">
3 <copyright>
4 Copyright © 2019 Christopher Billington
5 Copyright © 2020 Ilia Bozhinov
6 Copyright © 2022 Victoria Brekenfeld
7
8 Permission to use, copy, modify, distribute, and sell this
9 software and its documentation for any purpose is hereby granted
10 without fee, provided that the above copyright notice appear in
11 all copies and that both that copyright notice and this permission
12 notice appear in supporting documentation, and that the name of
13 the copyright holders not be used in advertising or publicity
14 pertaining to distribution of the software without specific,
15 written prior permission. The copyright holders make no
16 representations about the suitability of this software for any
17 purpose. It is provided "as is" without express or implied
18 warranty.
19
20 THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
21 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
22 FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
23 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
24 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
25 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
26 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
27 THIS SOFTWARE.
28 </copyright>
29
30 <interface name="ext_workspace_manager_v1" version="1">
31 <description summary="list and control workspaces">
32 Workspaces, also called virtual desktops, are groups of surfaces. A
33 compositor with a concept of workspaces may only show some such groups of
34 surfaces (those of 'active' workspaces) at a time. 'Activating' a
35 workspace is a request for the compositor to display that workspace's
36 surfaces as normal, whereas the compositor may hide or otherwise
37 de-emphasise surfaces that are associated only with 'inactive' workspaces.
38 Workspaces are grouped by which sets of outputs they correspond to, and
39 may contain surfaces only from those outputs. In this way, it is possible
40 for each output to have its own set of workspaces, or for all outputs (or
41 any other arbitrary grouping) to share workspaces. Compositors may
42 optionally conceptually arrange each group of workspaces in an
43 N-dimensional grid.
44
45 The purpose of this protocol is to enable the creation of taskbars and
46 docks by providing them with a list of workspaces and their properties,
47 and allowing them to activate and deactivate workspaces.
48
49 After a client binds the ext_workspace_manager_v1, each workspace will be
50 sent via the workspace event.
51 </description>
52
53 <event name="workspace_group">
54 <description summary="a workspace group has been created">
55 This event is emitted whenever a new workspace group has been created.
56
57 All initial details of the workspace group (outputs) will be
58 sent immediately after this event via the corresponding events in
59 ext_workspace_group_handle_v1 and ext_workspace_handle_v1.
60 </description>
61 <arg name="workspace_group" type="new_id" interface="ext_workspace_group_handle_v1"/>
62 </event>
63
64 <event name="workspace">
65 <description summary="workspace has been created">
66 This event is emitted whenever a new workspace has been created.
67
68 All initial details of the workspace (name, coordinates, state) will
69 be sent immediately after this event via the corresponding events in
70 ext_workspace_handle_v1.
71
72 Workspaces start off unassigned to any workspace group.
73 </description>
74 <arg name="workspace" type="new_id" interface="ext_workspace_handle_v1"/>
75 </event>
76
77 <request name="commit">
78 <description summary="all requests about the workspaces have been sent">
79 The client must send this request after it has finished sending other
80 requests. The compositor must process a series of requests preceding a
81 commit request atomically.
82
83 This allows changes to the workspace properties to be seen as atomic,
84 even if they happen via multiple events, and even if they involve
85 multiple ext_workspace_handle_v1 objects, for example, deactivating one
86 workspace and activating another.
87 </description>
88 </request>
89
90 <event name="done">
91 <description summary="all information about the workspaces and workspace groups has been sent">
92 This event is sent after all changes in all workspaces and workspace groups have been
93 sent.
94
95 This allows changes to one or more ext_workspace_group_handle_v1
96 properties and ext_workspace_handle_v1 properties
97 to be seen as atomic, even if they happen via multiple events.
98 In particular, an output moving from one workspace group to
99 another sends an output_enter event and an output_leave event to the two
100 ext_workspace_group_handle_v1 objects in question. The compositor sends
101 the done event only after updating the output information in both
102 workspace groups.
103 </description>
104 </event>
105
106 <event name="finished" type="destructor">
107 <description summary="the compositor has finished with the workspace_manager">
108 This event indicates that the compositor is done sending events to the
109 ext_workspace_manager_v1. The server will destroy the object
110 immediately after sending this request.
111 </description>
112 </event>
113
114 <request name="stop">
115 <description summary="stop sending events">
116 Indicates the client no longer wishes to receive events for new
117 workspace groups. However the compositor may emit further workspace
118 events, until the finished event is emitted. The compositor is expected
119 to send the finished event eventually once the stop request has been processed.
120
121 The client must not send any requests after this one, doing so will raise a wl_display
122 invalid_object error.
123 </description>
124 </request>
125
126 </interface>
127
128 <interface name="ext_workspace_group_handle_v1" version="1">
129 <description summary="a workspace group assigned to a set of outputs">
130 A ext_workspace_group_handle_v1 object represents a workspace group
131 that is assigned a set of outputs and contains a number of workspaces.
132
133 The set of outputs assigned to the workspace group is conveyed to the client via
134 output_enter and output_leave events, and its workspaces are conveyed with
135 workspace events.
136
137 For example, a compositor which has a set of workspaces for each output may
138 advertise a workspace group (and its workspaces) per output, whereas a compositor
139 where a workspace spans all outputs may advertise a single workspace group for all
140 outputs.
141 </description>
142
143 <enum name="group_capabilities" bitfield="true">
144 <entry name="create_workspace" value="1" summary="create_workspace request is available"/>
145 </enum>
146
147 <event name="capabilities">
148 <description summary="compositor capabilities">
149 This event advertises the capabilities supported by the compositor. If
150 a capability isn't supported, clients should hide or disable the UI
151 elements that expose this functionality. For instance, if the
152 compositor doesn't advertise support for creating workspaces, a button
153 triggering the create_workspace request should not be displayed.
154
155 The compositor will ignore requests it doesn't support. For instance,
156 a compositor which doesn't advertise support for creating workspaces will ignore
157 create_workspace requests.
158
159 Compositors must send this event once after creation of an
160 ext_workspace_group_handle_v1. When the capabilities change, compositors
161 must send this event again.
162 </description>
163 <arg name="capabilities" type="uint" summary="capabilities" enum="group_capabilities"/>
164 </event>
165
166 <event name="output_enter">
167 <description summary="output assigned to workspace group">
168 This event is emitted whenever an output is assigned to the workspace
169 group or a new `wl_output` object is bound by the client, which was already
170 assigned to this workspace_group.
171 </description>
172 <arg name="output" type="object" interface="wl_output"/>
173 </event>
174
175 <event name="output_leave">
176 <description summary="output removed from workspace group">
177 This event is emitted whenever an output is removed from the workspace
178 group.
179 </description>
180 <arg name="output" type="object" interface="wl_output"/>
181 </event>
182
183 <event name="workspace_enter">
184 <description summary="workspace added to workspace group">
185 This event is emitted whenever a workspace is assigned to this group.
186 A workspace may only ever be assigned to a single group at a single point
187 in time, but can be re-assigned during its lifetime.
188 </description>
189 <arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
190 </event>
191
192 <event name="workspace_leave">
193 <description summary="workspace removed from workspace group">
194 This event is emitted whenever a workspace is removed from this group.
195 </description>
196 <arg name="workspace" type="object" interface="ext_workspace_handle_v1"/>
197 </event>
198
199 <event name="removed">
200 <description summary="this workspace group has been removed">
201 This event is send when the group associated with the ext_workspace_group_handle_v1
202 has been removed. After sending this request the compositor will immediately consider
203 the object inert. Any requests will be ignored except the destroy request.
204 It is guaranteed there won't be any more events referencing this
205 ext_workspace_group_handle_v1.
206
207 The compositor must remove all workspaces belonging to a workspace group
208 via a workspace_leave event before removing the workspace group.
209 </description>
210 </event>
211
212 <request name="create_workspace">
213 <description summary="create a new workspace">
214 Request that the compositor create a new workspace with the given name
215 and assign it to this group.
216
217 There is no guarantee that the compositor will create a new workspace,
218 or that the created workspace will have the provided name.
219 </description>
220 <arg name="workspace" type="string"/>
221 </request>
222
223 <request name="destroy" type="destructor">
224 <description summary="destroy the ext_workspace_group_handle_v1 object">
225 Destroys the ext_workspace_group_handle_v1 object.
226
227 This request should be send either when the client does not want to
228 use the workspace group object any more or after the removed event to finalize
229 the destruction of the object.
230 </description>
231 </request>
232 </interface>
233
234 <interface name="ext_workspace_handle_v1" version="1">
235 <description summary="a workspace handing a group of surfaces">
236 A ext_workspace_handle_v1 object represents a workspace that handles a
237 group of surfaces.
238
239 Each workspace has:
240 - a name, conveyed to the client with the name event
241 - potentially an id conveyed with the id event
242 - a list of states, conveyed to the client with the state event
243 - and optionally a set of coordinates, conveyed to the client with the
244 coordinates event
245
246 The client may request that the compositor activate or deactivate the workspace.
247
248 Each workspace can belong to only a single workspace group.
249 Depending on the compositor policy, there might be workspaces with
250 the same name in different workspace groups, but these workspaces are still
251 separate (e.g. one of them might be active while the other is not).
252 </description>
253
254 <event name="id">
255 <description summary="workspace id">
256 If this event is emitted, it will be send immediately after the
257 ext_workspace_handle_v1 is created or when an id is assigned to
258 a workspace (at most once during its lifetime).
259
260 An id will never change during the lifetime of the `ext_workspace_handle_v1`
261 and is guaranteed to be unique during its lifetime.
262
263 Ids are not human-readable and shouldn't be displayed, use `name` for that purpose.
264
265 Compositors are expected to only send ids for workspaces likely stable across multiple
266 sessions and can be used by clients to store preferences for workspaces. Workspaces without
267 ids should be considered temporary and any data associated with them should be deleted once
268 the respective object is lost.
269 </description>
270 <arg name="id" type="string"/>
271 </event>
272
273 <event name="name">
274 <description summary="workspace name changed">
275 This event is emitted immediately after the ext_workspace_handle_v1 is
276 created and whenever the name of the workspace changes.
277
278 A name is meant to be human-readable and can be displayed to a user.
279 Unlike the id it is neither stable nor unique.
280 </description>
281 <arg name="name" type="string"/>
282 </event>
283
284 <event name="coordinates">
285 <description summary="workspace coordinates changed">
286 This event is used to organize workspaces into an N-dimensional grid
287 within a workspace group, and if supported, is emitted immediately after
288 the ext_workspace_handle_v1 is created and whenever the coordinates of
289 the workspace change. Compositors may not send this event if they do not
290 conceptually arrange workspaces in this way. If compositors simply
291 number workspaces, without any geometric interpretation, they may send
292 1D coordinates, which clients should not interpret as implying any
293 geometry. Sending an empty array means that the compositor no longer
294 orders the workspace geometrically.
295
296 Coordinates have an arbitrary number of dimensions N with an uint32
297 position along each dimension. By convention if N > 1, the first
298 dimension is X, the second Y, the third Z, and so on. The compositor may
299 chose to utilize these events for a more novel workspace layout
300 convention, however. No guarantee is made about the grid being filled or
301 bounded; there may be a workspace at coordinate 1 and another at
302 coordinate 1000 and none in between. Within a workspace group, however,
303 workspaces must have unique coordinates of equal dimensionality.
304 </description>
305 <arg name="coordinates" type="array"/>
306 </event>
307
308 <enum name="state" bitfield="true">
309 <description summary="types of states on the workspace">
310 The different states that a workspace can have.
311 </description>
312
313 <entry name="active" value="1" summary="the workspace is active"/>
314 <entry name="urgent" value="2" summary="the workspace requests attention"/>
315 <entry name="hidden" value="4">
316 <description summary="the workspace is not visible">
317 The workspace is not visible in its workspace group, and clients
318 attempting to visualize the compositor workspace state should not
319 display such workspaces.
320 </description>
321 </entry>
322 </enum>
323
324 <event name="state">
325 <description summary="the state of the workspace changed">
326 This event is emitted immediately after the ext_workspace_handle_v1 is
327 created and each time the workspace state changes, either because of a
328 compositor action or because of a request in this protocol.
329
330 Missing states convey the opposite meaning, e.g. an unset active bit
331 means the workspace is currently inactive.
332 </description>
333 <arg name="state" type="uint" enum="state"/>
334 </event>
335
336 <enum name="workspace_capabilities" bitfield="true">
337 <entry name="activate" value="1" summary="activate request is available"/>
338 <entry name="deactivate" value="2" summary="deactivate request is available"/>
339 <entry name="remove" value="4" summary="remove request is available"/>
340 <entry name="assign" value="8" summary="assign request is available"/>
341 </enum>
342
343 <event name="capabilities">
344 <description summary="compositor capabilities">
345 This event advertises the capabilities supported by the compositor. If
346 a capability isn't supported, clients should hide or disable the UI
347 elements that expose this functionality. For instance, if the
348 compositor doesn't advertise support for removing workspaces, a button
349 triggering the remove request should not be displayed.
350
351 The compositor will ignore requests it doesn't support. For instance,
352 a compositor which doesn't advertise support for remove will ignore
353 remove requests.
354
355 Compositors must send this event once after creation of an
356 ext_workspace_handle_v1 . When the capabilities change, compositors
357 must send this event again.
358 </description>
359 <arg name="capabilities" type="uint" summary="capabilities" enum="workspace_capabilities"/>
360 </event>
361
362 <event name="removed">
363 <description summary="this workspace has been removed">
364 This event is send when the workspace associated with the ext_workspace_handle_v1
365 has been removed. After sending this request, the compositor will immediately consider
366 the object inert. Any requests will be ignored except the destroy request.
367
368 It is guaranteed there won't be any more events referencing this
369 ext_workspace_handle_v1.
370
371 The compositor must only remove a workspaces not currently belonging to any
372 workspace_group.
373 </description>
374 </event>
375
376 <request name="destroy" type="destructor">
377 <description summary="destroy the ext_workspace_handle_v1 object">
378 Destroys the ext_workspace_handle_v1 object.
379
380 This request should be made either when the client does not want to
381 use the workspace object any more or after the remove event to finalize
382 the destruction of the object.
383 </description>
384 </request>
385
386 <request name="activate">
387 <description summary="activate the workspace">
388 Request that this workspace be activated.
389
390 There is no guarantee the workspace will be actually activated, and
391 behaviour may be compositor-dependent. For example, activating a
392 workspace may or may not deactivate all other workspaces in the same
393 group.
394 </description>
395 </request>
396
397 <request name="deactivate">
398 <description summary="deactivate the workspace">
399 Request that this workspace be deactivated.
400
401 There is no guarantee the workspace will be actually deactivated.
402 </description>
403 </request>
404
405 <request name="assign">
406 <description summary="assign workspace to group">
407 Requests that this workspace is assigned to the given workspace group.
408
409 There is no guarantee the workspace will be assigned.
410 </description>
411 <arg name="workspace_group" type="object" interface="ext_workspace_group_handle_v1"/>
412 </request>
413
414 <request name="remove">
415 <description summary="remove the workspace">
416 Request that this workspace be removed.
417
418 There is no guarantee the workspace will be actually removed.
419 </description>
420 </request>
421 </interface>
422</protocol>