WIP: Added wlr-workspace-unstable-v1.xml

unstable/wlr-workspace-unstable-v1.xml

@@ -0,0 +1,265 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="wlr_workspace_unstable_v1">
+  <copyright>
+    Copyright © 2019 Christopher Billington
+
+    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="zwlr_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 zwlr_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
+        zwlr_workspace_group_handle_v1.
+      </description>
+      <arg name="workspace_group" type="new_id" interface="zwlr_workspace_group_handle_v1"/>
+    </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
+        zwlr_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="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
+      output_enter and output_leave events, and its workspaces are conveyed with
+      workspace events.
+    </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
+        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 output_enter event and an output_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; 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="name">
+      <description summary="workspace name changed">
+        This event is emitted immediately after the zwlr_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 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 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 zwlr_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"/>
+    </enum>
+
+    <event name="done">
+      <description summary="all information about the workspace has been sent">
+        This event is sent after all changes in the workspace state have been
+        sent.
+
+        This allows changes to one or more zwlr_workspace_handle_v1 properties
+        to be seen as atomic, even if they happen via multiple events. In
+        particular, if a workspace changes its coordinates, coordinates events
+        may be sent to multiple zwlr_workspace_handle_v1 objects as workspaces
+        are reordered. The compositor sends the done events only after all
+        coordinates events have been sent.
+      </description>
+    </event>
+
+    <event name="remove">
+      <description summary="this workspace has been destroyed">
+        This event means the zwlr_workspace_handle_v1 has been destroyed. It is
+        guaranteed there won't be any more events for this
+        zwlr_workspace_handle_v1. The zwlr_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 zwlr_workspace_handle_v1 object">
+        Destroys the zwlr_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="commit">
+      <description summary="all requests about the workspace 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 includes requests on other
+        zwlr_workspace_handle_v1 objects: if the client sends requests for
+        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 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, for example, deactivating one
+        workspace and activating another.
+      </description>
+    </request>
+
+  </interface>
+</protocol>