[PATCH wayland-protocols 00/11] Declaring xdg-shell stable

[Jonas Ådahl]

Hi,

I think it is time to take the next step regarding xdg_shell: declaring it
stable. The current unstable version (xdg_shell unstable v6) has been
implemented in multiple code bases, used by multiple desktop environments for
quite some time, and I think this proves it is time to take the next step.

While it has indeed been implemented and used, there has been various issues
raised regarding the protocol, but I believe all of these qualify as minor
enough not requiring a new unstable release.

I'll go through them here in this E-mail, but please do read the actual commits
for the actual change.

1) Renaming the main global interface

It is not possible to just strip the unstable protocol prefix/postfix of the
global interface name, so it had to be renamed. The reason for this is that up
until the unstable version 6, the global interface name of the protocol was
simply "xdg_shell". This means that without clever version hackery, we can not
make the it discoverable that this is indeed the new stable interface and not
an old unstable one.

The new name has been discussion previously on #wayland, and at one point Pekka
came up with "xdg_wm_base" as xdg_shell really is about the window management
basics. I chose this name for this patch series, but it is not set in stone.
Other suggestions include "wp_shell", "wp_desktop_shell", "xdg_desktop_shell".

2) The anchor rectangle of a xdg_positioner may now be empty

If one wants to position a menu against corner of a pixel and have it flip in
any direction, this was not possible due to the requirement that a anchor
rectangle of a xdg_positioner had to be non-empty. Allowing an empty anchor
rectangle fixes this without any down sides.

3) More forgiving managing of stacking relationships

The set_parent request of xdg_toplevel was specified to require unmapping the
parent before the child. This was poorly enforced in various implementations,
and making it an error will have serious consequences when the relationship
crosses client boundaries, as is possible using xdg_foreign (used by
xdg-desktop-portal, i.e. sandboxed clients using portals). Make things a bit
more forgiving, while at the same time more predictable. For example, unmapping
a parent that itself has a parent, will turn its children children of its own
parent.

4) Allowing external protocols to define popup parent relationships

To use xdg_popup for things such as a window menu implemented in westons
desktop shell client, we must allow passing null as a parent, relying on some
external protocol for setting up this relationship. Allowing this also makes it
possible to extend xdg_foreign with foreign popup menus in case this is ever
needed.

5) Define behaviour when attaching a null buffer to a surface

The behaviour of attaching a null buffer was previously undefined. Some
compositors just didn't render the surface, some assumed it was invalid
behaviour and sent an error. In short, the now defined behavior depends on the
role; it'll either permanently unmap the surface (xdg_popup), or unmap it and
reset all attributes as if the xdg_surface and role objects was just created
(xdg_toplevel). See corresponding patch (xdg-shell: clarify map/unmap wording)
for details.

6) Misc minor changes/clarification/rewording

Other changes are best read in the actual patches, but just to make things more
complete, they include some rewording of the documentation of the global
interface, clarification of maintaining window positions in relation to window
management changes and terminology corrections. The maintainers listed in the
README has also changed to be me and Mike Blumenkrantz.


So these are the changes that should provide us on a good base shell protocol.
If we can agree on making this, we can later start adding more extensions, both
externally (as separate protocols) or inside xdg_shell (as global interfaces,
or new requests/events). There are already plans and ideas of additions that
has been discussed at various places, but I believe we should not try to
introduce any new features to the base protocol before having something we can
rely on for backward compatibility.

So in other words, proposing to make xdg_shell stable does not mean it defines
everything that needs to be defined; it means that it defines the bare minimum
a compositor must implement to support clients that use xdg_shell in a way that
can be extended in the future. If there is something missing for implementing a
certain feature, that is expected; if there is something that makes extending
the protocol to implement a certain feature impossible, that should be fixed.


Jonas



Jonas Ådahl (10):
  Add xdg-shell to stable/
  xdg-shell: Rename interfaces
  xdg-shell: Update copyright notices
  xdg-shell: Reword the xdg_wm_base introduction
  xdg-shell/positioner: Allow empty anchor_rect
  xdg-shell: Replace 'monitor' with 'output'
  xdg-shell/surface: Add note about window position and geometry
  xdg-shell/toplevel: Clarify xdg_toplevel.set_parent(null)
  xdg-shell/toplevel: Chain multiple parent-child relationships
  xdg-shell/popup: Allow custom parent by passing null as parent

Mike Blumenkrantz (1):
  xdg-shell: clarify map/unmap wording

 stable/xdg-shell/README        |    5 +
 stable/xdg-shell/xdg-shell.xml | 1080 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 1085 insertions(+)
 create mode 100644 stable/xdg-shell/README
 create mode 100644 stable/xdg-shell/xdg-shell.xml

-- 
2.13.0