307 lines
14 KiB
XML
307 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<protocol name="ext_workspace_unstable_v1">
|
||
<copyright>
|
||
Copyright © 2019 Christopher Billington
|
||
Copyright © 2020 Ilia Bozhinov
|
||
|
||
Permission to use, copy, modify, distribute, and sell this
|
||
software and its documentation for any purpose is hereby granted
|
||
without fee, provided that the above copyright notice appear in
|
||
all copies and that both that copyright notice and this permission
|
||
notice appear in supporting documentation, and that the name of
|
||
the copyright holders not be used in advertising or publicity
|
||
pertaining to distribution of the software without specific,
|
||
written prior permission. The copyright holders make no
|
||
representations about the suitability of this software for any
|
||
purpose. It is provided "as is" without express or implied
|
||
warranty.
|
||
|
||
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
|
||
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
||
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
|
||
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
|
||
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
|
||
THIS SOFTWARE.
|
||
</copyright>
|
||
|
||
<interface name="zext_workspace_manager_v1" version="1">
|
||
<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. '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,
|
||
and allowing them to activate and deactivate workspaces.
|
||
|
||
After a client binds the zext_workspace_manager_v1, each workspace will be
|
||
sent via the workspace event.
|
||
</description>
|
||
|
||
<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 group (workspaces, outputs) will be
|
||
sent immediately after this event via the corresponding events in
|
||
zext_workspace_group_handle_v1.
|
||
</description>
|
||
<arg name="workspace_group" type="new_id" interface="zext_workspace_group_handle_v1"/>
|
||
</event>
|
||
|
||
<request name="commit">
|
||
<description summary="all requests about the workspaces have been sent">
|
||
The client must send this request after it has finished sending other
|
||
requests. The compositor must process a series of requests preceding a
|
||
commit request 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 zext_workspace_handle_v1 objects, for example, deactivating one
|
||
workspace and activating another.
|
||
</description>
|
||
</request>
|
||
|
||
<event name="done">
|
||
<description summary="all information about the workspace groups has been sent">
|
||
This event is sent after all changes in all workspace groups have been
|
||
sent.
|
||
|
||
This allows changes to one or more zext_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 output_enter event and an output_leave event to the two
|
||
zext_workspace_group_handle_v1 objects in question. The compositor sends
|
||
the done event only after updating the output information in both
|
||
workspace groups.
|
||
</description>
|
||
</event>
|
||
|
||
<event name="finished">
|
||
<description summary="the compositor has finished with the workspace_manager">
|
||
This event indicates that the compositor is done sending events to the
|
||
zext_workspace_manager_v1. The server will destroy the object
|
||
immediately after sending this request, so it will become invalid and
|
||
the client should free any resources associated with it.
|
||
</description>
|
||
</event>
|
||
|
||
<request name="stop">
|
||
<description summary="stop sending events">
|
||
Indicates the client no longer wishes to receive events for new
|
||
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="zext_workspace_group_handle_v1" version="1">
|
||
<description summary="a workspace group assigned to a set of outputs">
|
||
A zext_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
|
||
output_enter and output_leave events, and its workspaces are conveyed with
|
||
workspace events.
|
||
|
||
For example, a compositor which has a set of workspaces for each output may
|
||
advertise a workspace group (and its workspaces) per output, whereas a compositor
|
||
where a workspace spans all outputs may advertise a single workspace group for all
|
||
outputs.
|
||
</description>
|
||
|
||
<event name="output_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="output_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
|
||
zext_workspace_handle_v1.
|
||
</description>
|
||
<arg name="workspace" type="new_id" interface="zext_workspace_handle_v1"/>
|
||
</event>
|
||
|
||
<event name="remove">
|
||
<description summary="this workspace group has been destroyed">
|
||
This event means the zext_workspace_group_handle_v1 has been destroyed.
|
||
It is guaranteed there won't be any more events for this
|
||
zext_workspace_group_handle_v1. The zext_workspace_group_handle_v1 becomes
|
||
inert so any requests will be ignored except the destroy request.
|
||
|
||
The compositor must remove all workspaces belonging to a workspace group
|
||
before removing the workspace group.
|
||
</description>
|
||
</event>
|
||
|
||
<request name="create_workspace">
|
||
<description summary="create a new workspace">
|
||
Request that the compositor create a new workspace with the given name.
|
||
|
||
There is no guarantee that the compositor will create a new workspace,
|
||
or that the created workspace will have the provided name.
|
||
</description>
|
||
<arg name="workspace" type="string"/>
|
||
</request>
|
||
|
||
<request name="destroy" type="destructor">
|
||
<description summary="destroy the zext_workspace_handle_v1 object">
|
||
Destroys the zext_workspace_handle_v1 object.
|
||
|
||
This request should be called either when the client does not want to
|
||
use the workspace object any more or after the remove event to finalize
|
||
the destruction of the object.
|
||
</description>
|
||
</request>
|
||
</interface>
|
||
|
||
<interface name="zext_workspace_handle_v1" version="1">
|
||
<description summary="a workspace handing a group of surfaces">
|
||
A zext_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; 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.
|
||
|
||
Each workspace can belong to only a single workspace group.
|
||
Depepending on the compositor policy, there might be workspaces with
|
||
the same name in different workspace groups, but these workspaces are still
|
||
separate (e.g. one of them might be active while the other is not).
|
||
</description>
|
||
|
||
<event name="name">
|
||
<description summary="workspace name changed">
|
||
This event is emitted immediately after the zext_workspace_handle_v1 is
|
||
created and whenever the name of the workspace changes.
|
||
</description>
|
||
<arg name="name" type="string"/>
|
||
</event>
|
||
|
||
<event name="coordinates">
|
||
<description summary="workspace coordinates changed">
|
||
This event is used to organize workspaces into an N-dimensional grid
|
||
within a workspace group, and if supported, is emitted immediately after
|
||
the zext_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. Sending an empty array means that the compositor no longer
|
||
orders the workspace geometrically.
|
||
|
||
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>
|
||
|
||
<event name="state">
|
||
<description summary="the state of the workspace changed">
|
||
This event is emitted immediately after the zext_workspace_handle_v1 is
|
||
created and each time the workspace state changes, either because of a
|
||
compositor action or because of a request in this protocol.
|
||
</description>
|
||
<arg name="state" type="array"/>
|
||
</event>
|
||
|
||
<enum name="state">
|
||
<description summary="types of states on the workspace">
|
||
The different states that a workspace can have.
|
||
</description>
|
||
|
||
<entry name="active" value="0" summary="the workspace is active"/>
|
||
<entry name="urgent" value="1" summary="the workspace requests attention"/>
|
||
<entry name="hidden" value="2">
|
||
<description summary="the workspace is not visible">
|
||
The workspace is not visible in its workspace group, and clients
|
||
attempting to visualize the compositor workspace state should not
|
||
display such workspaces.
|
||
</description>
|
||
</entry>
|
||
</enum>
|
||
|
||
<event name="remove">
|
||
<description summary="this workspace has been destroyed">
|
||
This event means the zext_workspace_handle_v1 has been destroyed. It is
|
||
guaranteed there won't be any more events for this
|
||
zext_workspace_handle_v1. The zext_workspace_handle_v1 becomes inert so
|
||
any requests will be ignored except the destroy request.
|
||
</description>
|
||
</event>
|
||
|
||
<request name="destroy" type="destructor">
|
||
<description summary="destroy the zext_workspace_handle_v1 object">
|
||
Destroys the zext_workspace_handle_v1 object.
|
||
|
||
This request should be called either when the client does not want to
|
||
use the workspace object any more or after the remove event to finalize
|
||
the destruction of the object.
|
||
</description>
|
||
</request>
|
||
|
||
<request name="activate">
|
||
<description summary="activate the workspace">
|
||
Request that this workspace be activated.
|
||
|
||
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 in the same
|
||
group.
|
||
</description>
|
||
</request>
|
||
|
||
<request name="deactivate">
|
||
<description summary="activate the workspace">
|
||
Request that this workspace be deactivated.
|
||
|
||
There is no guarantee the workspace will be actually deactivated.
|
||
</description>
|
||
</request>
|
||
|
||
<request name="remove">
|
||
<description summary="remove the workspace">
|
||
Request that this workspace be removed.
|
||
|
||
There is no guarantee the workspace will be actually removed.
|
||
</description>
|
||
</request>
|
||
</interface>
|
||
</protocol>
|