| 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 it's 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 it's 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 it's 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> |