From 0d270a1ef707a6fa3c6f46ff88c27bbaf65e6ae6 Mon Sep 17 00:00:00 2001 From: Chris Billington Date: Mon, 25 Feb 2019 15:05:53 -0500 Subject: [PATCH 1/9] Added wlr-workspace-unstable-v1.xml Addresses github issue #10 --- unstable/wlr-workspace-unstable-v1.xml | 226 +++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 unstable/wlr-workspace-unstable-v1.xml diff --git a/unstable/wlr-workspace-unstable-v1.xml b/unstable/wlr-workspace-unstable-v1.xml new file mode 100644 index 0000000..b979805 --- /dev/null +++ b/unstable/wlr-workspace-unstable-v1.xml @@ -0,0 +1,226 @@ + + + + Copyright © 2018 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. + + + + + + Workspaces, also called virtual desktops, are groups of surfaces. A compositor + with a concept of workspaces may only show one such group of windows (those of the + 'active' workspace) at a time. Outputs may be grouped together, such that all + outputs share workspaces, or a group of outputs (possibly a single output) may + have its own set of workspaces, separate from other outputs. The purpose of this + protocol is to enable the creation of taskbars and docks by providing them with a + list of workspaces for each group of outputs, and allowing them to set the active + workspace on each workspace group corresponding to a set of outputs. + + After a client binds the zwlr_workspace_manager_v1, each workspace group + will be sent via the output_group event + + + + + 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. + + + + + + + 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. + + + + + + Indicates the client no longer wishes to receive events for new workspace + groups. However the compositor may emit further workspace_group events, until + the finished event is emitted. + + The client must not send any more requests after this one. + + + + + + + A zwlr_workspace_group_handle_v1 object represents a set of workspaces shared + by a set of outputs. Each output may belong to only one workspace group. + + Each workspace group has a list of outputs, conveyed to the client with the + output and output_remove events; and a list of workspaces, conveyed to the client + with workspace and workspace_remove events. + + + + + This event is emitted whenever an output is added to the workspace group. + + + + + + + This event is emitted whenever an output is removed from the workspace group. + + + + + + + This event is emitted whenever a workspace is added to the workspace group. + + All initial details of the workspace (number, state) will be sent immediately + after this event via the corresponding events in zwlr_workspace_handle_v1. + + + + + + + This event is emitted whenever a workspace is removed from the workspace group + + + + + + + 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 event and an + output_remove event to the two zwlr_workspace_group_handle_v1 objects in + question. The compositor sends both done events only after both other events. + + + + + + This event means the zwlr_workspace_group_handle_v1 has been destroyed. It is + guaranteed there won't be any more events for this + zwlr_workspace_group_handle_v1. The zwlr_workspace_group_handle_v1 becomes inert + so any requests will be ignored except the destroy request. + + + + + + Destroys the zwlr_workspace_group_handle_v1 object. + + This request should be called either when the client does not want to use the + workspace_group anymore or after the closed event to finalize the destruction of + the object. + + + + + + + A zwlr_workspace_handle_v1 object represents a a workspace belonging to a + workspace group. + + Each workspace group has a number, conveyed to the client with the number event, + and a list of states, conveyed to the client with the state event. The client may + request the compositor to activate the workspace. + + + + + This event is emitted immediately after the zwlr_workspace_handle_v1 is created + and whenever the number of the workspace changed. Workspaces within a workspace + group are uniquely and contiguously numbered starting from zero. + + + + + + + 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. + + + + + + + The different states that a workspace can have. + + + + + + + + + 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, a + workspace changing its number sends number events to multiple + zwlr_workspace_handle_v1 objects in order to keep their numbers sequential. The + compositor sends both done events only after both number events have been sent. + + + + + + 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. + + + + + + Destroys the zwlr_workspace_handle_v1 object. + + This request should be called either when the client does not want to use the + workspace_group anymore or after the closed event to finalize the destruction of + the object. + + + + + + Request that this workspace be set as the active workspace for its workspace + group. + + There is no guarantee the workspace will be actually activated. + + + + From 96b274785213119a4c0f842a9b9f8e377809fd7a Mon Sep 17 00:00:00 2001 From: Chris Billington Date: Tue, 26 Feb 2019 13:31:11 -0500 Subject: [PATCH 2/9] Improvements in light of reviews * Remove the concept of a workspace group, instead associate outputs directly with workspaces. * Remove 'empty' state: clients will instead determine themselves if a workspace is empty once functionality is added either to this or the foreign toplevel manager protocol to determine which toplevels are on which workspaces. * Add name event * Replace number event with coordinates of arbitrary dimension * Add deactivate request, since activating one workspace need not imply that others are deactivated * Rename destroy event to remove. * Improve descriptions --- unstable/wlr-workspace-unstable-v1.xml | 181 ++++++++++--------------- 1 file changed, 73 insertions(+), 108 deletions(-) diff --git a/unstable/wlr-workspace-unstable-v1.xml b/unstable/wlr-workspace-unstable-v1.xml index b979805..4997812 100644 --- a/unstable/wlr-workspace-unstable-v1.xml +++ b/unstable/wlr-workspace-unstable-v1.xml @@ -29,27 +29,29 @@ Workspaces, also called virtual desktops, are groups of surfaces. A compositor - with a concept of workspaces may only show one such group of windows (those of the - 'active' workspace) at a time. Outputs may be grouped together, such that all - outputs share workspaces, or a group of outputs (possibly a single output) may - have its own set of workspaces, separate from other outputs. The purpose of this - protocol is to enable the creation of taskbars and docks by providing them with a - list of workspaces for each group of outputs, and allowing them to set the active - workspace on each workspace group corresponding to a set of outputs. - - After a client binds the zwlr_workspace_manager_v1, each workspace group - will be sent via the output_group event + 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, such that activating the workspace will cause the compositor to display + the workspace's surfaces on those outputs. In this way, each output may have its + own unique set of workspaces, or all outputs (or any other arbitrary grouping) may + share workspaces. Workspaces may be conceptually arranged in a grid of arbitrary + dimension. 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. - - - This event is emitted whenever a new workspace group has been created. + + + This event is emitted whenever a new workspace has been created. - All initial details of the workspace_group (workspaces, outputs) will be sent + All initial details of the workspace (outputs, name, coordinates) will be sent immediately after this event via the corresponding events in - zwlr_workspace_group_handle_v1. + zwlr_workspace_handle_v1. - + @@ -63,108 +65,63 @@ - Indicates the client no longer wishes to receive events for new workspace - groups. However the compositor may emit further workspace_group events, until - the finished event is emitted. + 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. The client must not send any more requests after this one. - - - A zwlr_workspace_group_handle_v1 object represents a set of workspaces shared - by a set of outputs. Each output may belong to only one workspace group. - - Each workspace group has a list of outputs, conveyed to the client with the - output and output_remove events; and a list of workspaces, conveyed to the client - with workspace and workspace_remove events. + + + 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. - - This event is emitted whenever an output is added to the workspace group. + + This event is emitted whenever an output is added to the workspace. - - This event is emitted whenever an output is removed from the workspace group. + + This event is emitted whenever an output is removed from the workspace. - - - This event is emitted whenever a workspace is added to the workspace group. - - All initial details of the workspace (number, state) will be sent immediately - after this event via the corresponding events in zwlr_workspace_handle_v1. - - - - - - - This event is emitted whenever a workspace is removed from the workspace group - - - - - - - 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 event and an - output_remove event to the two zwlr_workspace_group_handle_v1 objects in - question. The compositor sends both done events only after both other events. - - - - - - This event means the zwlr_workspace_group_handle_v1 has been destroyed. It is - guaranteed there won't be any more events for this - zwlr_workspace_group_handle_v1. The zwlr_workspace_group_handle_v1 becomes inert - so any requests will be ignored except the destroy request. - - - - - - Destroys the zwlr_workspace_group_handle_v1 object. - - This request should be called either when the client does not want to use the - workspace_group anymore or after the closed event to finalize the destruction of - the object. - - - - - - - A zwlr_workspace_handle_v1 object represents a a workspace belonging to a - workspace group. - - Each workspace group has a number, conveyed to the client with the number event, - and a list of states, conveyed to the client with the state event. The client may - request the compositor to activate the workspace. - - - - + + This event is emitted immediately after the zwlr_workspace_handle_v1 is created - and whenever the number of the workspace changed. Workspaces within a workspace - group are uniquely and contiguously numbered starting from zero. + and whenever the name of the workspace changes. + + + If the compositor assigns coordinates to workspaces, this event is emitted + immediately after the zwlr_workspace_handle_v1 is created and whenever the + coordinates of the workspace change. Coordinates have an arbitrary number of + dimensions with an unsigned integer position for each dimension. Among a set of + workspaces that have identical sets of outputs, workspaces must have unique + coordinates with the same number of dimensions, such that the workspaces form a + grid with at most one workspace in each position. By convention, 2D coordinates + represent [y_pos, x_pos]. + + + + This event is emitted immediately after the zwlr_workspace_handle_v1 is created @@ -180,7 +137,6 @@ - @@ -188,14 +144,14 @@ 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, a - workspace changing its number sends number events to multiple - zwlr_workspace_handle_v1 objects in order to keep their numbers sequential. The - compositor sends both done events only after both number events have been sent. + 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. - + 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 @@ -205,22 +161,31 @@ - + Destroys the zwlr_workspace_handle_v1 object. This request should be called either when the client does not want to use the - workspace_group anymore or after the closed event to finalize the destruction of - the object. + workspace object any more or after the remove event to finalize the destruction + of the object. - Request that this workspace be set as the active workspace for its workspace - group. + 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 on the same outputs. + + + + + + Request that this workspace be deactivated. - There is no guarantee the workspace will be actually activated. + There is no guarantee the workspace will be actually deactivated. - + \ No newline at end of file From f2f73ed1306fe8d41ae75c0df2511d427baeba5f Mon Sep 17 00:00:00 2001 From: Chris Billington Date: Tue, 26 Feb 2019 13:51:35 -0500 Subject: [PATCH 3/9] make description more explicit --- unstable/wlr-workspace-unstable-v1.xml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/unstable/wlr-workspace-unstable-v1.xml b/unstable/wlr-workspace-unstable-v1.xml index 4997812..a7c658d 100644 --- a/unstable/wlr-workspace-unstable-v1.xml +++ b/unstable/wlr-workspace-unstable-v1.xml @@ -27,17 +27,18 @@ - 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, such that activating the workspace will cause the compositor to display - the workspace's surfaces on those outputs. In this way, each output may have its - own unique set of workspaces, or all outputs (or any other arbitrary grouping) may - share workspaces. Workspaces may be conceptually arranged in a grid of arbitrary - dimension. 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. + outputs, such that activating the workspace will request that the compositor + display the workspace's surfaces on those outputs, 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. Workspaces may be conceptually arranged in a grid + of arbitrary dimension. 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. From 097273d13e2bf57dfbb969ed680d74a1c53d8908 Mon Sep 17 00:00:00 2001 From: Chris Billington Date: Wed, 27 Feb 2019 11:34:42 -0500 Subject: [PATCH 4/9] Fixes in response to reviews * Fix two minor bugs pointed out in reviews * clarify meaning and optional-ness of coordinates. --- unstable/wlr-workspace-unstable-v1.xml | 46 ++++++++++++++++---------- 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/unstable/wlr-workspace-unstable-v1.xml b/unstable/wlr-workspace-unstable-v1.xml index a7c658d..67fc093 100644 --- a/unstable/wlr-workspace-unstable-v1.xml +++ b/unstable/wlr-workspace-unstable-v1.xml @@ -30,15 +30,17 @@ 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, such that activating the workspace will request that the compositor - display the workspace's surfaces on those outputs, whereas the compositor may hide - or otherwise de-emphasise surfaces that are associated only with inactive + 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. Workspaces may be conceptually arranged in a grid - of arbitrary dimension. 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. + grouping) may share workspaces. Compositors may optionally conceptually arrange + workspaces with a common set of outputs 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. @@ -87,14 +89,14 @@ activate or deactivate the workspace. - + This event is emitted whenever an output is added to the workspace. - + This event is emitted whenever an output is removed from the workspace. @@ -106,19 +108,27 @@ This event is emitted immediately after the zwlr_workspace_handle_v1 is created and whenever the name of the workspace changes. - + - If the compositor assigns coordinates to workspaces, this event is emitted - immediately after the zwlr_workspace_handle_v1 is created and whenever the - coordinates of the workspace change. Coordinates have an arbitrary number of - dimensions with an unsigned integer position for each dimension. Among a set of - workspaces that have identical sets of outputs, workspaces must have unique - coordinates with the same number of dimensions, such that the workspaces form a - grid with at most one workspace in each position. By convention, 2D coordinates - represent [y_pos, x_pos]. + 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 conceptually arrange workspaces in this way. + + Coordinates have an arbitrary number of dimensions with an uint32 position along + each dimension. By convention, 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. From b7e68808bf175a7745cefe8dadb5ddb21fc322e5 Mon Sep 17 00:00:00 2001 From: Chris Billington Date: Wed, 27 Feb 2019 12:08:36 -0500 Subject: [PATCH 5/9] Add done request, to provide atomicity for other requests. --- unstable/wlr-workspace-unstable-v1.xml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/unstable/wlr-workspace-unstable-v1.xml b/unstable/wlr-workspace-unstable-v1.xml index 67fc093..d88f733 100644 --- a/unstable/wlr-workspace-unstable-v1.xml +++ b/unstable/wlr-workspace-unstable-v1.xml @@ -198,5 +198,23 @@ There is no guarantee the workspace will be actually deactivated. + + + + The client must send this request after it has finished sending other requests. + The compositor must process a series of requests preceding a done 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 done request has been sent for every + zwlr_workspace_handle_v1 involved, and process all of the preceding requests + atomically. This is important so that say, deactivating one workspace and + activating another can be treated 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. + + + \ No newline at end of file From 5b959e8ce3e4e8134bb6320aed1264c528a294f0 Mon Sep 17 00:00:00 2001 From: Chris Billington Date: Wed, 27 Feb 2019 15:32:09 -0500 Subject: [PATCH 6/9] Rename done request to 'commit', clarify coordinates description. --- unstable/wlr-workspace-unstable-v1.xml | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/unstable/wlr-workspace-unstable-v1.xml b/unstable/wlr-workspace-unstable-v1.xml index d88f733..6e8510d 100644 --- a/unstable/wlr-workspace-unstable-v1.xml +++ b/unstable/wlr-workspace-unstable-v1.xml @@ -117,13 +117,16 @@ 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, 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. + 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 @@ -199,14 +202,14 @@ - + The client must send this request after it has finished sending other requests. - The compositor must process a series of requests preceding a done request + 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 done request has been sent for every - zwlr_workspace_handle_v1 involved, and process all of the preceding requests + 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. From 65c01838cc11703a3bb7dfcb4a9119cbb613f1f9 Mon Sep 17 00:00:00 2001 From: Chris Billington Date: Wed, 27 Feb 2019 16:18:32 -0500 Subject: [PATCH 7/9] Correct copyright year, wrap everyhing to 80 chars --- unstable/wlr-workspace-unstable-v1.xml | 175 +++++++++++++------------ 1 file changed, 91 insertions(+), 84 deletions(-) diff --git a/unstable/wlr-workspace-unstable-v1.xml b/unstable/wlr-workspace-unstable-v1.xml index 6e8510d..36667d3 100644 --- a/unstable/wlr-workspace-unstable-v1.xml +++ b/unstable/wlr-workspace-unstable-v1.xml @@ -1,7 +1,7 @@ - Copyright © 2018 Christopher Billington + Copyright © 2019 Christopher Billington Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted @@ -27,31 +27,32 @@ - 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. - - 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. + 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. + + 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. This event is emitted whenever a new workspace has been created. - All initial details of the workspace (outputs, name, coordinates) will be sent - immediately after this event via the corresponding events in + 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. @@ -60,17 +61,17 @@ 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. + 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. - 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. + 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. The client must not send any more requests after this one. @@ -79,14 +80,14 @@ - 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. + 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. @@ -105,42 +106,44 @@ - This event is emitted immediately after the zwlr_workspace_handle_v1 is created - and whenever the name of the workspace changes. + This event is emitted immediately after the zwlr_workspace_handle_v1 is + created and whenever the name of the workspace changes. - 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 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 + 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 + 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 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. - 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. + 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. @@ -155,22 +158,24 @@ - 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. + 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. 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. + 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. @@ -178,9 +183,9 @@ 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. + 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. @@ -188,9 +193,10 @@ 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 on the same outputs. + 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. @@ -204,18 +210,19 @@ - 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 is important so that say, deactivating one workspace and - activating another can be treated 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. + 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 is important so that say, deactivating one + workspace and activating another can be treated 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. From 0a5f807c8877b11ee086ae483f56c0b6eebf66b7 Mon Sep 17 00:00:00 2001 From: Chris Billington Date: Wed, 27 Feb 2019 19:13:58 -0500 Subject: [PATCH 8/9] Re-introduce concept of workspace groups --- unstable/wlr-workspace-unstable-v1.xml | 139 ++++++++++++++++--------- 1 file changed, 87 insertions(+), 52 deletions(-) diff --git a/unstable/wlr-workspace-unstable-v1.xml b/unstable/wlr-workspace-unstable-v1.xml index 36667d3..7794e0b 100644 --- a/unstable/wlr-workspace-unstable-v1.xml +++ b/unstable/wlr-workspace-unstable-v1.xml @@ -29,15 +29,16 @@ 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. - - - This event is emitted whenever a new workspace 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. - + @@ -70,40 +71,78 @@ 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. - - - A zwlr_workspace_handle_v1 object represents a a workspace that handles a - group of surfaces. + + + 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. - 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. + 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. - - This event is emitted whenever an output is added to the workspace. + + This event is emitted whenever an output is assigned to the workspace + group. - - This event is emitted whenever an output is removed from the workspace. + + This event is emitted whenever an output is removed from the 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. + + + + + + + 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. + + + + + + + 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. + + This event is emitted immediately after the zwlr_workspace_handle_v1 is @@ -114,27 +153,23 @@ - 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. @@ -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. @@ -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. From 4738eae37b3135f25e0f52ffd6031637ce062f57 Mon Sep 17 00:00:00 2001 From: Chris Billington Date: Thu, 28 Feb 2019 11:45:35 -0500 Subject: [PATCH 9/9] Rename to output_enter and output_leave To match the foreign-toplevel-management protocol. --- unstable/wlr-workspace-unstable-v1.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/unstable/wlr-workspace-unstable-v1.xml b/unstable/wlr-workspace-unstable-v1.xml index 7794e0b..b054080 100644 --- a/unstable/wlr-workspace-unstable-v1.xml +++ b/unstable/wlr-workspace-unstable-v1.xml @@ -84,12 +84,12 @@ 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. + 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. - + This event is emitted whenever an output is assigned to the workspace group. @@ -97,7 +97,7 @@ - + This event is emitted whenever an output is removed from the workspace group. @@ -124,7 +124,7 @@ 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 + 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.