Skip to content
This repository has been archived by the owner on Nov 1, 2021. It is now read-only.

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

Open
wants to merge 9 commits into
base: master
Choose a base branch
from
Open

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

Changes from 3 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
0d270a1
Added wlr-workspace-unstable-v1.xml
Feb 25, 2019
96b2747
Improvements in light of reviews
Feb 26, 2019
f2f73ed
make description more explicit
Feb 26, 2019
097273d
Fixes in response to reviews
Feb 27, 2019
b7e6880
Add done request, to provide atomicity for other requests.
Feb 27, 2019
5b959e8
Rename done request to 'commit', clarify coordinates description.
Feb 27, 2019
65c0183
Correct copyright year, wrap everyhing to 80 chars
Feb 27, 2019
0a5f807
Re-introduce concept of workspace groups
Feb 28, 2019
4738eae
Rename to output_enter and output_leave
Feb 28, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 192 additions & 0 deletions unstable/wlr-workspace-unstable-v1.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,192 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="wlr_workspace_unstable_v1">
<copyright>
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.
</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. 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
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.
</description>

<event name="workspace">
<description summary="a workspace has been created">
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
zwlr_workspace_handle_v1.
</description>
<arg name="workspace" type="new_id" interface="zwlr_workspace_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 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.
</description>
</request>
</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.
</description>

<event name="output">
<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="output_remove">
<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 created
and whenever the name of the workspace changes.
</description>
<arg name="number" type="int"/>
</event>

<event name="coordinates">
<description summary="workspace coordinates changed">
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].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's unconventional, is there a reason to do this?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Row before column is the convention for image pixel coordinates and matrix indexing as far as I'm aware. I might change the text to say [row, column] instead though, since x and y are more often used for continuous variables where the convention is opposite.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer x, y, z, … because that way pos[0] is always x, pos[1] is always y and so on.

I'm still not sure it's a good idea to have this in the protocol.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can just leave it out, just there's a risk that different compositors will choose different conventions, and then clients won't be able to represent them graphically. Happy to go with [column, row] too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if someone wants to make 3D workspaces, or even 4D? I'd suggest adding an event which has dimension and extent.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The name field works for tagging, no?

Coordinates seem common enough that if we leave it free-form, I imagine an ad-hoc standard for making strings of coordinates will present itself (and that gnome would end up sending 2D coordinates within the strings to tell clients that its workspaces are vertical). So by making it a string we're just deferring that standard to be a de-facto one instead of in the protocol. The benefit is allowing information about non-grid-like layouts.

But if it's an opaque string, what's it called? 'layout?' 'geometry'?

My preferred outcome is coordinates with strictly defined interpretation as x, y, z, etc, with compositors without such a concept just not using this part of the protocol. We can add extra events for other paradigms, including a catch-all opaque string for compositor-specific info.

Copy link
Member

@ammen99 ammen99 Feb 27, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if we make this event optional, I'm ok

Copy link
Author

@chrisjbillington chrisjbillington Feb 27, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plus, in Wayfire I can't really make workspaces arranged in a grid in multimonitor configuration, they aren't in the same coordinate system.

The coordinates are only meaningful among workspaces that share a set of outputs. So you can have a workspace at (0,0) on output 1, and a workspace on (0,0) on output 2. Or you can have a workspace at (0,0) that is attached to both outputs 1 and 2. But you cannot have two workspaces with coords (0,0) on output 1. This all may have been more clear with the original concept of 'workspace groups' - that the coordinates are only meaningful (and only have to be unique) within a workspace group that share a common set of outputs.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

an ad-hoc standard for making strings of coordinates will present itself

This sounds fucking awful.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sounds fucking awful.

👍

</description>
<arg name="coordinates" type="array"/>
</event>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not define the dimensionality, be it 1D, 2D, etc. We need a second argument for that.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I considered the length of the array to be the dimensionality. Is that insufficient? (or non-obvious enough that I should mention it explicitly)?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be fine, xdg-shell already does the same.


<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"/>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about add urgent state as it was mentioned in issue. For purpose not search urgent toplevels and not bound pure workspace module with taskbar.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, active state means "available" and "visible" workspace, doesn't it?
In this case I think we need something like current state and only for one workspace in group.

</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 on the same outputs.
</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>
</interface>
</protocol>