fdo-mirrors/wlr-protocols
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wlroots/wlr-protocols.git synced 2026-05-05 11:07:59 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Re-introduce concept of workspace groups

Browse source
This commit is contained in:
Chris Billington 2019-02-27 19:13:58 -05:00
parent 65c01838cc
commit 0a5f807c88
1 changed files with 92 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

149
unstable/wlr-workspace-unstable-v1.xml
View file

@ -29,15 +29,16 @@
<description summary="list and control workspaces">
Workspaces, also called virtual desktops, are groups of surfaces. A
compositor with a concept of workspaces may only show some such groups of
surfaces (those of 'active' workspaces) at a time. Workspaces may contain
surfaces from one or more outputs, and 'activating' a workspace is a
request that the compositor display those surfaces on those outputs as
normal, whereas the compositor may hide or otherwise de-emphasise surfaces
that are associated only with 'inactive' workspaces. By associating a set
of outputs with each workspace, each output may have its own unique set of
workspaces, or all outputs (or any other arbitrary grouping) may share
workspaces. Compositors may optionally conceptually arrange workspaces
with a common set of outputs in an N-dimensional grid.
surfaces (those of 'active' workspaces) at a time. 'Activating' a
workspace is a request for the compositor to display that workspace's
surfaces as normal, whereas the compositor may hide or otherwise
de-emphasise surfaces that are associated only with 'inactive' workspaces.
Workspaces are grouped by which sets of outputs they correspond to, and
may contain surfaces only from those outputs. In this way, it is possible
for each output to have its own set of workspaces, or for all outputs (or
any other arbitrary grouping) to share workspaces. Compositors may
optionally conceptually arrange each group of workspaces in an
N-dimensional grid.
The purpose of this protocol is to enable the creation of taskbars and
docks by providing them with a list of workspaces and their properties,
@ -47,15 +48,15 @@
sent via the workspace event.
</description>
<event name="workspace">
<description summary="a workspace has been created">
This event is emitted whenever a new workspace has been created.
<event name="workspace_group">
<description summary="a workspace group has been created">
This event is emitted whenever a new workspace group has been created.
All initial details of the workspace (outputs, name, coordinates) will
be sent immediately after this event via the corresponding events in
zwlr_workspace_handle_v1.
All initial details of the workspace group (workspaces, outputs) will be
sent immediately after this event via the corresponding events in
zwlr_workspace_group_handle_v1.
</description>
<arg name="workspace" type="new_id" interface="zwlr_workspace_handle_v1"/>
<arg name="workspace_group" type="new_id" interface="zwlr_workspace_group_handle_v1"/>
</event>
<event name="finished">
@ -70,40 +71,78 @@
<request name="stop">
<description summary="stop sending events">
Indicates the client no longer wishes to receive events for new
workspaces. However the compositor may emit further workspace events,
until the finished event is emitted.
workspace groups. However the compositor may emit further workspace
events, until the finished event is emitted.
The client must not send any more requests after this one.
</description>
</request>
</interface>
<interface name="zwlr_workspace_group_handle_v1" version="1">
<description summary="a workspace group assigned to a set of outputs">
A zwlr_workspace_group_handle_v1 object represents a a workspace group
that is assigned a set of outputs and contains a number of workspaces.
The set of outputs assigned to the workspace group is conveyed to the
client via enter and leave events, and ita workspaces are conveyed with
the workspace event.
</description>
<event name="enter">
<description summary="output assigned to workspace group">
This event is emitted whenever an output is assigned to the workspace
group.
</description>
<arg name="output" type="object" interface="wl_output"/>
</event>
<event name="leave">
<description summary="output removed from workspace group">
This event is emitted whenever an output is removed from the workspace
group.
</description>
<arg name="output" type="object" interface="wl_output"/>
</event>
<event name="workspace">
<description summary="workspace added to workspace group">
This event is emitted whenever a new workspace has been created.
All initial details of the workspace (name, coordinates, state) will
be sent immediately after this event via the corresponding events in
zwlr_workspace_handle_v1.
</description>
<arg name="workspace" type="new_id" interface="zwlr_workspace_handle_v1"/>
</event>
<event name="done">
<description summary="all information about the workspace group has been sent">
This event is sent after all changes in the workspace group state have
been sent.
This allows changes to one or more zwlr_workspace_group_handle_v1
properties to be seen as atomic, even if they happen via multiple
events. In particular, an output moving from one workspace group to
another sends an enter event and a leave event to the two
zwlr_workspace_group_handle_v1 objects in question. The compositor sends
both done events only after both other events.
</description>
</event>
</interface>
<interface name="zwlr_workspace_handle_v1" version="1">
<description summary="a workspace handing a group of surfaces">
A zwlr_workspace_handle_v1 object represents a a workspace that handles a
group of surfaces.
Each workspace has a name, conveyed to the client with the name event; a
list of states, conveyed to the client with the state event; a list of
outputs, conveyed via one or more output events; and optionally a set of
coordinates, conveyed to the client with the coordinates event. The client
may request that the compositor activate or deactivate the workspace.
list of states, conveyed to the client with the state event; and
optionally a set of coordinates, conveyed to the client with the
coordinates event. The client may request that the compositor activate or
deactivate the workspace.
</description>
<event name="enter">
<description summary="output added to workspace">
This event is emitted whenever an output is added to the workspace.
</description>
<arg name="output" type="object" interface="wl_output"/>
</event>
<event name="leave">
<description summary="output removed from workspace">
This event is emitted whenever an output is removed from the workspace.
</description>
<arg name="output" type="object" interface="wl_output"/>
</event>
<event name="name">
<description summary="workspace name changed">
This event is emitted immediately after the zwlr_workspace_handle_v1 is
@ -114,27 +153,23 @@
<event name="coordinates">
<description summary="workspace coordinates changed">
This event is used to organize workspaces spatially into an
N-dimensional grid, and if supported, is emitted immediately after the
zwlr_workspace_handle_v1 is created and whenever the coordinates of the
workspace change. Compositors may not send this event if they do not
This event is used to organize workspaces into an N-dimensional grid
within a workspace group, and if supported, is emitted immediately after
the zwlr_workspace_handle_v1 is created and whenever the coordinates of
the workspace change. Compositors may not send this event if they do not
conceptually arrange workspaces in this way. If compositors simply
number workspaces, without any geometric interpretation, they may send
1D coordinates, which clients should not interpret as implying any
geometry.
Coordinates have an arbitrary number of dimensions with an uint32
position along each dimension. By convention if N>1, the first dimension
is X, the second Y, the third Z, and so on. The compositor may chose to
utilize these events for a more novel workspace layout convention,
however. No guarantee is made about the grid being filled or bounded;
there may be a workspace at coordinate 1 and another at coordinate 1000
and none in between.
Among a set of workspaces that have identical sets of outputs,
workspaces must have unique coordinates of the same dimensionality.
Coordinates otherwise need not be unique: in this way independent grids
can exist for each set of outputs that share workspaces.
Coordinates have an arbitrary number of dimensions N with an uint32
position along each dimension. By convention if N > 1, the first
dimension is X, the second Y, the third Z, and so on. The compositor may
chose to utilize these events for a more novel workspace layout
convention, however. No guarantee is made about the grid being filled or
bounded; there may be a workspace at coordinate 1 and another at
coordinate 1000 and none in between. Within a workspace group, however,
workspaces must have unique coordinates of equal dimensionality.
</description>
<arg name="coordinates" type="array"/>
</event>
@ -195,8 +230,8 @@
There is no guarantee the workspace will be actually activated, and
behaviour may be compositor-dependent. For example, activating a
workspace may or may not deactivate all other workspaces on the same
outputs.
workspace may or may not deactivate all other workspaces in the same
group.
</description>
</request>
@ -217,12 +252,12 @@
multiple zwlr_workspace_handle_v1 objects, the compositor must wait
until a commit request has been sent for every one of those
zwlr_workspace_handle_v1 objects, and process all of the preceding
requests atomically. This is important so that say, deactivating one
workspace and activating another can be treated atomically.
requests atomically.
This allows changes to the workspace properties to be seen as atomic,
even if they happen via multiple events, and even if they involve
multiple zwlr_workspace_handle_v1 objects.
multiple zwlr_workspace_handle_v1 objects, for example, deactivating one
workspace and activating another.
</description>
</request>