Skip to content

Commit a60d021

Browse files
dkondordkondor
committed
Add ext-workspace protocol draft
This is from the Wayfire PR: WayfireWM/wayfire#647
1 parent 47eeb64 commit a60d021

File tree

2 files changed

+310
-0
lines changed

2 files changed

+310
-0
lines changed

‎src/implementations/CMakeLists.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,10 @@ if(WaylandScanner_FOUND)
6565
impl_SRCS
6666
PROTOCOL "proto/plasma-virtual-desktop.xml"
6767
BASENAME "plasma-virtual-desktop")
68+
ecm_add_wayland_client_protocol(
69+
impl_SRCS
70+
PROTOCOL "proto/ext-workspace-unstable-v1.xml"
71+
BASENAME "ext-workspace")
6872
endif()
6973

7074
add_library(implementations STATIC ${impl_SRCS})

‎src/implementations/proto/ext-workspace-unstable-v1.xml

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<protocol name="ext_workspace_unstable_v1">
3+
<copyright>
4+
Copyright © 2019 Christopher Billington
5+
Copyright © 2020 Ilia Bozhinov
6+
7+
Permission to use, copy, modify, distribute, and sell this
8+
software and its documentation for any purpose is hereby granted
9+
without fee, provided that the above copyright notice appear in
10+
all copies and that both that copyright notice and this permission
11+
notice appear in supporting documentation, and that the name of
12+
the copyright holders not be used in advertising or publicity
13+
pertaining to distribution of the software without specific,
14+
written prior permission. The copyright holders make no
15+
representations about the suitability of this software for any
16+
purpose. It is provided "as is" without express or implied
17+
warranty.
18+
19+
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
20+
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
21+
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
22+
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
23+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
24+
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
25+
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
26+
THIS SOFTWARE.
27+
</copyright>
28+
29+
<interface name="zext_workspace_manager_v1" version="1">
30+
<description summary="list and control workspaces">
31+
Workspaces, also called virtual desktops, are groups of surfaces. A
32+
compositor with a concept of workspaces may only show some such groups of
33+
surfaces (those of 'active' workspaces) at a time. 'Activating' a
34+
workspace is a request for the compositor to display that workspace's
35+
surfaces as normal, whereas the compositor may hide or otherwise
36+
de-emphasise surfaces that are associated only with 'inactive' workspaces.
37+
Workspaces are grouped by which sets of outputs they correspond to, and
38+
may contain surfaces only from those outputs. In this way, it is possible
39+
for each output to have its own set of workspaces, or for all outputs (or
40+
any other arbitrary grouping) to share workspaces. Compositors may
41+
optionally conceptually arrange each group of workspaces in an
42+
N-dimensional grid.
43+
44+
The purpose of this protocol is to enable the creation of taskbars and
45+
docks by providing them with a list of workspaces and their properties,
46+
and allowing them to activate and deactivate workspaces.
47+
48+
After a client binds the zext_workspace_manager_v1, each workspace will be
49+
sent via the workspace event.
50+
</description>
51+
52+
<event name="workspace_group">
53+
<description summary="a workspace group has been created">
54+
This event is emitted whenever a new workspace group has been created.
55+
56+
All initial details of the workspace group (workspaces, outputs) will be
57+
sent immediately after this event via the corresponding events in
58+
zext_workspace_group_handle_v1.
59+
</description>
60+
<arg name="workspace_group" type="new_id" interface="zext_workspace_group_handle_v1"/>
61+
</event>
62+
63+
<request name="commit">
64+
<description summary="all requests about the workspaces have been sent">
65+
The client must send this request after it has finished sending other
66+
requests. The compositor must process a series of requests preceding a
67+
commit request atomically.
68+
69+
This allows changes to the workspace properties to be seen as atomic,
70+
even if they happen via multiple events, and even if they involve
71+
multiple zext_workspace_handle_v1 objects, for example, deactivating one
72+
workspace and activating another.
73+
</description>
74+
</request>
75+
76+
<event name="done">
77+
<description summary="all information about the workspace groups has been sent">
78+
This event is sent after all changes in all workspace groups have been
79+
sent.
80+
81+
This allows changes to one or more zext_workspace_group_handle_v1
82+
properties to be seen as atomic, even if they happen via multiple
83+
events. In particular, an output moving from one workspace group to
84+
another sends an output_enter event and an output_leave event to the two
85+
zext_workspace_group_handle_v1 objects in question. The compositor sends
86+
the done event only after updating the output information in both
87+
workspace groups.
88+
</description>
89+
</event>
90+
91+
<event name="finished">
92+
<description summary="the compositor has finished with the workspace_manager">
93+
This event indicates that the compositor is done sending events to the
94+
zext_workspace_manager_v1. The server will destroy the object
95+
immediately after sending this request, so it will become invalid and
96+
the client should free any resources associated with it.
97+
</description>
98+
</event>
99+
100+
<request name="stop">
101+
<description summary="stop sending events">
102+
Indicates the client no longer wishes to receive events for new
103+
workspace groups. However the compositor may emit further workspace
104+
events, until the finished event is emitted.
105+
106+
The client must not send any more requests after this one.
107+
</description>
108+
</request>
109+
</interface>
110+
111+
<interface name="zext_workspace_group_handle_v1" version="1">
112+
<description summary="a workspace group assigned to a set of outputs">
113+
A zext_workspace_group_handle_v1 object represents a a workspace group
114+
that is assigned a set of outputs and contains a number of workspaces.
115+
116+
The set of outputs assigned to the workspace group is conveyed to the client via
117+
output_enter and output_leave events, and its workspaces are conveyed with
118+
workspace events.
119+
120+
For example, a compositor which has a set of workspaces for each output may
121+
advertise a workspace group (and its workspaces) per output, whereas a compositor
122+
where a workspace spans all outputs may advertise a single workspace group for all
123+
outputs.
124+
</description>
125+
126+
<event name="output_enter">
127+
<description summary="output assigned to workspace group">
128+
This event is emitted whenever an output is assigned to the workspace
129+
group.
130+
</description>
131+
<arg name="output" type="object" interface="wl_output"/>
132+
</event>
133+
134+
<event name="output_leave">
135+
<description summary="output removed from workspace group">
136+
This event is emitted whenever an output is removed from the workspace
137+
group.
138+
</description>
139+
<arg name="output" type="object" interface="wl_output"/>
140+
</event>
141+
142+
<event name="workspace">
143+
<description summary="workspace added to workspace group">
144+
This event is emitted whenever a new workspace has been created.
145+
146+
All initial details of the workspace (name, coordinates, state) will
147+
be sent immediately after this event via the corresponding events in
148+
zext_workspace_handle_v1.
149+
</description>
150+
<arg name="workspace" type="new_id" interface="zext_workspace_handle_v1"/>
151+
</event>
152+
153+
<event name="remove">
154+
<description summary="this workspace group has been destroyed">
155+
This event means the zext_workspace_group_handle_v1 has been destroyed.
156+
It is guaranteed there won't be any more events for this
157+
zext_workspace_group_handle_v1. The zext_workspace_group_handle_v1 becomes
158+
inert so any requests will be ignored except the destroy request.
159+
160+
The compositor must remove all workspaces belonging to a workspace group
161+
before removing the workspace group.
162+
</description>
163+
</event>
164+
165+
<request name="create_workspace">
166+
<description summary="create a new workspace">
167+
Request that the compositor create a new workspace with the given name.
168+
169+
There is no guarantee that the compositor will create a new workspace,
170+
or that the created workspace will have the provided name.
171+
</description>
172+
<arg name="workspace" type="string"/>
173+
</request>
174+
175+
<request name="destroy" type="destructor">
176+
<description summary="destroy the zext_workspace_handle_v1 object">
177+
Destroys the zext_workspace_handle_v1 object.
178+
179+
This request should be called either when the client does not want to
180+
use the workspace object any more or after the remove event to finalize
181+
the destruction of the object.
182+
</description>
183+
</request>
184+
</interface>
185+
186+
<interface name="zext_workspace_handle_v1" version="1">
187+
<description summary="a workspace handing a group of surfaces">
188+
A zext_workspace_handle_v1 object represents a a workspace that handles a
189+
group of surfaces.
190+
191+
Each workspace has a name, conveyed to the client with the name event; a
192+
list of states, conveyed to the client with the state event; and
193+
optionally a set of coordinates, conveyed to the client with the
194+
coordinates event. The client may request that the compositor activate or
195+
deactivate the workspace.
196+
197+
Each workspace can belong to only a single workspace group.
198+
Depepending on the compositor policy, there might be workspaces with
199+
the same name in different workspace groups, but these workspaces are still
200+
separate (e.g. one of them might be active while the other is not).
201+
</description>
202+
203+
<event name="name">
204+
<description summary="workspace name changed">
205+
This event is emitted immediately after the zext_workspace_handle_v1 is
206+
created and whenever the name of the workspace changes.
207+
</description>
208+
<arg name="name" type="string"/>
209+
</event>
210+
211+
<event name="coordinates">
212+
<description summary="workspace coordinates changed">
213+
This event is used to organize workspaces into an N-dimensional grid
214+
within a workspace group, and if supported, is emitted immediately after
215+
the zext_workspace_handle_v1 is created and whenever the coordinates of
216+
the workspace change. Compositors may not send this event if they do not
217+
conceptually arrange workspaces in this way. If compositors simply
218+
number workspaces, without any geometric interpretation, they may send
219+
1D coordinates, which clients should not interpret as implying any
220+
geometry. Sending an empty array means that the compositor no longer
221+
orders the workspace geometrically.
222+
223+
Coordinates have an arbitrary number of dimensions N with an uint32
224+
position along each dimension. By convention if N > 1, the first
225+
dimension is X, the second Y, the third Z, and so on. The compositor may
226+
chose to utilize these events for a more novel workspace layout
227+
convention, however. No guarantee is made about the grid being filled or
228+
bounded; there may be a workspace at coordinate 1 and another at
229+
coordinate 1000 and none in between. Within a workspace group, however,
230+
workspaces must have unique coordinates of equal dimensionality.
231+
</description>
232+
<arg name="coordinates" type="array"/>
233+
</event>
234+
235+
<event name="state">
236+
<description summary="the state of the workspace changed">
237+
This event is emitted immediately after the zext_workspace_handle_v1 is
238+
created and each time the workspace state changes, either because of a
239+
compositor action or because of a request in this protocol.
240+
</description>
241+
<arg name="state" type="array"/>
242+
</event>
243+
244+
<enum name="state">
245+
<description summary="types of states on the workspace">
246+
The different states that a workspace can have.
247+
</description>
248+
249+
<entry name="active" value="0" summary="the workspace is active"/>
250+
<entry name="urgent" value="1" summary="the workspace requests attention"/>
251+
<entry name="hidden" value="2">
252+
<description summary="the workspace is not visible">
253+
The workspace is not visible in its workspace group, and clients
254+
attempting to visualize the compositor workspace state should not
255+
display such workspaces.
256+
</description>
257+
</entry>
258+
</enum>
259+
260+
<event name="remove">
261+
<description summary="this workspace has been destroyed">
262+
This event means the zext_workspace_handle_v1 has been destroyed. It is
263+
guaranteed there won't be any more events for this
264+
zext_workspace_handle_v1. The zext_workspace_handle_v1 becomes inert so
265+
any requests will be ignored except the destroy request.
266+
</description>
267+
</event>
268+
269+
<request name="destroy" type="destructor">
270+
<description summary="destroy the zext_workspace_handle_v1 object">
271+
Destroys the zext_workspace_handle_v1 object.
272+
273+
This request should be called either when the client does not want to
274+
use the workspace object any more or after the remove event to finalize
275+
the destruction of the object.
276+
</description>
277+
</request>
278+
279+
<request name="activate">
280+
<description summary="activate the workspace">
281+
Request that this workspace be activated.
282+
283+
There is no guarantee the workspace will be actually activated, and
284+
behaviour may be compositor-dependent. For example, activating a
285+
workspace may or may not deactivate all other workspaces in the same
286+
group.
287+
</description>
288+
</request>
289+
290+
<request name="deactivate">
291+
<description summary="activate the workspace">
292+
Request that this workspace be deactivated.
293+
294+
There is no guarantee the workspace will be actually deactivated.
295+
</description>
296+
</request>
297+
298+
<request name="remove">
299+
<description summary="remove the workspace">
300+
Request that this workspace be removed.
301+
302+
There is no guarantee the workspace will be actually removed.
303+
</description>
304+
</request>
305+
</interface>
306+
</protocol>

0 commit comments

Comments
 (0)