Merge pull request #31 from SirCmpwn/layer-shell

Port to wlroots layer shell

8 files changed, 1266 insertions, 502 deletions

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..30ab761
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+
+[*.{c,h,cmake,txt}]
+indent_style = space
+indent_size = 4
diff --git a/lib/renderers/wayland/CMakeLists.txt b/lib/renderers/wayland/CMakeLists.txt
index 23fb350..3aa66ac 100644
--- a/lib/renderers/wayland/CMakeLists.txt
+++ b/lib/renderers/wayland/CMakeLists.txt
@@ -5,9 +5,10 @@ FIND_PACKAGE(XKBCommon)
 
 if (WAYLAND_FOUND AND CAIRO_FOUND AND PANGO_FOUND AND XKBCOMMON_FOUND)
     INCLUDE(Wayland)
+    WAYLAND_ADD_PROTOCOL_CLIENT(proto-layer-shell "wlr-layer-shell-unstable-v1.xml" layer-shell)
     WAYLAND_ADD_PROTOCOL_CLIENT(proto-xdg-shell "xdg-shell.xml" xdg-shell)
     INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR} ${WAYLAND_CLIENT_INCLUDE_DIR} ${XKBCOMMON_INCLUDE_DIR} ${CAIRO_INCLUDE_DIRS} ${PANGO_INCLUDE_DIRS})
-    ADD_LIBRARY(bemenu-renderer-wayland SHARED wayland.c registry.c window.c ${proto-xdg-shell})
+    ADD_LIBRARY(bemenu-renderer-wayland SHARED wayland.c registry.c window.c ${proto-layer-shell} ${proto-xdg-shell})
     SET_TARGET_PROPERTIES(bemenu-renderer-wayland PROPERTIES PREFIX "")
     TARGET_LINK_LIBRARIES(bemenu-renderer-wayland ${BEMENU_LIBRARIES} ${WAYLAND_CLIENT_LIBRARIES} ${XKBCOMMON_LIBRARIES} ${CAIRO_LIBRARIES} ${PANGO_LIBRARIES} m)
     INSTALL(TARGETS bemenu-renderer-wayland DESTINATION "${CMAKE_INSTALL_LIBDIR}/bemenu")
diff --git a/lib/renderers/wayland/registry.c b/lib/renderers/wayland/registry.c
index 5ade7a4..726ed94 100644
--- a/lib/renderers/wayland/registry.c
+++ b/lib/renderers/wayland/registry.c
@@ -27,17 +27,6 @@ const enum mod_bit BM_XKB_MODS[MASK_LAST] = {
 };
 
 static void
-xdg_shell_ping(void *data, struct xdg_shell *shell, uint32_t serial)
-{
-    (void)data;
-    xdg_shell_pong(shell, serial);
-}
-
-static const struct xdg_shell_listener xdg_shell_listener = {
-    .ping = xdg_shell_ping,
-};
-
-static void
 shm_format(void *data, struct wl_shm *wl_shm, uint32_t format)
 {
     (void)wl_shm;
@@ -260,12 +249,11 @@ display_handle_scale(void *data, struct wl_output *wl_output, int32_t scale)
 static void
 display_handle_mode(void *data, struct wl_output *wl_output, uint32_t flags, int width, int height, int refresh)
 {
-    (void)wl_output, (void)refresh, (void)height;
-    struct wayland *wayland = data;
+    (void)wl_output, (void)refresh, (void)height, (void)width;
+    struct output *output = data;
 
     if (flags & WL_OUTPUT_MODE_CURRENT) {
-        wayland->window.width = width;
-        wayland->window.max_height = height;
+        output->height = height;
     }
 }
 
@@ -284,12 +272,8 @@ registry_handle_global(void *data, struct wl_registry *registry, uint32_t id, co
 
     if (strcmp(interface, "wl_compositor") == 0) {
         wayland->compositor = wl_registry_bind(registry, id, &wl_compositor_interface, 1);
-    } else if (strcmp(interface, "xdg_shell") == 0) {
-        wayland->xdg_shell = wl_registry_bind(registry, id, &xdg_shell_interface, 1);
-        xdg_shell_use_unstable_version(wayland->xdg_shell, XDG_SHELL_VERSION_CURRENT);
-        xdg_shell_add_listener(wayland->xdg_shell, &xdg_shell_listener, data);
-    } else if (strcmp(interface, "wl_shell") == 0) {
-        wayland->shell = wl_registry_bind(registry, id, &wl_shell_interface, 1);
+    } else if (strcmp(interface, zwlr_layer_shell_v1_interface.name) == 0) {
+        wayland->layer_shell = wl_registry_bind(registry, id, &zwlr_layer_shell_v1_interface, 1);
     } else if (strcmp(interface, "wl_seat") == 0) {
         wayland->seat = wl_registry_bind(registry, id, &wl_seat_interface, 1);
         wl_seat_add_listener(wayland->seat, &seat_listener, &wayland->input);
@@ -297,8 +281,11 @@ registry_handle_global(void *data, struct wl_registry *registry, uint32_t id, co
         wayland->shm = wl_registry_bind(registry, id, &wl_shm_interface, 1);
         wl_shm_add_listener(wayland->shm, &shm_listener, data);
     } else if (strcmp(interface, "wl_output") == 0) {
-        wayland->output = wl_registry_bind(registry, id, &wl_output_interface, 2);
-        wl_output_add_listener(wayland->output, &output_listener, wayland);
+        struct wl_output *wl_output = wl_registry_bind(registry, id, &wl_output_interface, 2);
+        struct output *output = calloc(1, sizeof(struct output));
+        output->output = wl_output;
+        wl_list_insert(&wayland->outputs, &output->link);
+        wl_output_add_listener(wl_output, &output_listener, output);
     }
 }
 
@@ -334,11 +321,8 @@ bm_wl_registry_destroy(struct wayland *wayland)
     if (wayland->shm)
         wl_shm_destroy(wayland->shm);
 
-    if (wayland->shell)
-        wl_shell_destroy(wayland->shell);
-
-    if (wayland->xdg_shell)
-        xdg_shell_destroy(wayland->xdg_shell);
+    if (wayland->layer_shell)
+        zwlr_layer_shell_v1_destroy(wayland->layer_shell);
 
     if (wayland->compositor)
         wl_compositor_destroy(wayland->compositor);
@@ -358,9 +342,11 @@ bm_wl_registry_register(struct wayland *wayland)
     if (!(wayland->registry = wl_display_get_registry(wayland->display)))
         return false;
 
+    wl_list_init(&wayland->outputs);
+    wl_list_init(&wayland->windows);
     wl_registry_add_listener(wayland->registry, &registry_listener, wayland);
     wl_display_roundtrip(wayland->display); // trip 1, registry globals
-    if (!wayland->compositor || !wayland->seat || !wayland->shm || !(wayland->shell || wayland->xdg_shell))
+    if (!wayland->compositor || !wayland->seat || !wayland->shm || !wayland->layer_shell)
         return false;
 
     wl_display_roundtrip(wayland->display); // trip 2, global listeners
diff --git a/lib/renderers/wayland/wayland.c b/lib/renderers/wayland/wayland.c
index 6f6f322..ab32a3e 100644
--- a/lib/renderers/wayland/wayland.c
+++ b/lib/renderers/wayland/wayland.c
@@ -38,7 +38,10 @@ render(const struct bm_menu *menu)
     }
 
     if (wayland->input.code != wayland->input.last_code) {
-        bm_wl_window_render(&wayland->window, menu);
+        struct window *window;
+            wl_list_for_each(window, &wayland->windows, link) {
+            bm_wl_window_render(window, menu);
+        }
         wayland->input.last_code = wayland->input.code;
     }
 }
@@ -165,7 +168,13 @@ get_displayed_count(const struct bm_menu *menu)
 {
     struct wayland *wayland = menu->renderer->internal;
     assert(wayland);
-    return wayland->window.displayed;
+    uint32_t max = 0;
+    struct window *window;
+    wl_list_for_each(window, &wayland->windows, link) {
+        if (window->displayed > max)
+            max = window->displayed;
+    }
+    return max;
 }
 
 static void
@@ -176,7 +185,10 @@ destructor(struct bm_menu *menu)
     if (!wayland)
         return;
 
-    bm_wl_window_destroy(&wayland->window);
+    struct window *window;
+    wl_list_for_each(window, &wayland->windows, link) {
+        bm_wl_window_destroy(window);
+    }
     bm_wl_registry_destroy(wayland);
 
     xkb_context_unref(wayland->input.xkb.context);
@@ -203,9 +215,6 @@ constructor(struct bm_menu *menu)
     if (!(menu->renderer->internal = wayland = calloc(1, sizeof(struct wayland))))
         goto fail;
 
-    wayland->window.width = 800;
-    wayland->window.height = 1;
-
     if (!(wayland->display = wl_display_connect(NULL)))
         goto fail;
 
@@ -215,19 +224,26 @@ constructor(struct bm_menu *menu)
     if (!bm_wl_registry_register(wayland))
         goto fail;
 
-    struct wl_surface *surface;
-    if (!(surface = wl_compositor_create_surface(wayland->compositor)))
-        goto fail;
+    wayland->fds.display = wl_display_get_fd(wayland->display);
+    wayland->fds.repeat = timerfd_create(CLOCK_MONOTONIC, TFD_CLOEXEC | TFD_NONBLOCK);
+    wayland->input.repeat_fd = &wayland->fds.repeat;
 
-    if (!bm_wl_window_create(&wayland->window, wayland->shm, wayland->shell, wayland->xdg_shell, surface))
-        goto fail;
+    struct output *output;
+    wl_list_for_each(output, &wayland->outputs, link) {
+	struct wl_surface *surface;
+	if (!(surface = wl_compositor_create_surface(wayland->compositor)))
+	    goto fail;
+	struct window *window = calloc(1, sizeof(struct window));
+	if (!bm_wl_window_create(window, wayland->display, wayland->shm, output->output, wayland->layer_shell, surface))
+	    goto fail;
+	window->notify.render = bm_cairo_paint;
+	window->max_height = output->height;
+	wl_list_insert(&wayland->windows, &window->link);
+    }
 
     if (!efd && (efd = epoll_create(EPOLL_CLOEXEC)) < 0)
         goto fail;
 
-    wayland->fds.display = wl_display_get_fd(wayland->display);
-    wayland->fds.repeat = timerfd_create(CLOCK_MONOTONIC, TFD_CLOEXEC | TFD_NONBLOCK);
-
     struct epoll_event ep;
     ep.events = EPOLLIN | EPOLLERR | EPOLLHUP;
     ep.data.ptr = &wayland->fds.display;
@@ -237,9 +253,6 @@ constructor(struct bm_menu *menu)
     ep2.events = EPOLLIN;
     ep2.data.ptr = &wayland->fds.repeat;
     epoll_ctl(efd, EPOLL_CTL_ADD, wayland->fds.repeat, &ep2);
-
-    wayland->window.notify.render = bm_cairo_paint;
-    wayland->input.repeat_fd = &wayland->fds.repeat;
     return true;
 
 fail:
diff --git a/lib/renderers/wayland/wayland.h b/lib/renderers/wayland/wayland.h
index dff6aba..a4ba5f3 100644
--- a/lib/renderers/wayland/wayland.h
+++ b/lib/renderers/wayland/wayland.h
@@ -4,7 +4,7 @@
 #include <wayland-client.h>
 #include <xkbcommon/xkbcommon.h>
 
-#include "wayland-xdg-shell-client-protocol.h"
+#include "wayland-layer-shell-client-protocol.h"
 
 #include "renderers/cairo.h"
 
@@ -76,19 +76,25 @@ struct buffer {
 
 struct window {
     struct wl_surface *surface;
-    struct wl_shell_surface *shell_surface;
     struct wl_callback *frame_cb;
-    struct xdg_surface *xdg_surface;
+    struct zwlr_layer_surface_v1 *layer_surface;
     struct wl_shm *shm;
     struct buffer buffers[2];
     uint32_t width, height, max_height;
     uint32_t displayed;
+    struct wl_list link;
 
     struct {
         void (*render)(struct cairo *cairo, uint32_t width, uint32_t height, uint32_t max_height, const struct bm_menu *menu, struct cairo_paint_result *result);
     } notify;
 };
 
+struct output {
+    struct wl_output *output;
+    struct wl_list link;
+    int height;
+};
+
 struct wayland {
     struct {
         int32_t display;
@@ -98,13 +104,12 @@ struct wayland {
     struct wl_display *display;
     struct wl_registry *registry;
     struct wl_compositor *compositor;
-    struct wl_output *output;
+    struct wl_list outputs;
     struct wl_seat *seat;
-    struct xdg_shell *xdg_shell;
-    struct wl_shell *shell;
+    struct zwlr_layer_shell_v1 *layer_shell;
     struct wl_shm *shm;
     struct input input;
-    struct window window;
+    struct wl_list windows;
     uint32_t formats;
 };
 
@@ -112,7 +117,7 @@ void bm_wl_repeat(struct wayland *wayland);
 bool bm_wl_registry_register(struct wayland *wayland);
 void bm_wl_registry_destroy(struct wayland *wayland);
 void bm_wl_window_render(struct window *window, const struct bm_menu *menu);
-bool bm_wl_window_create(struct window *window, struct wl_shm *shm, struct wl_shell *shell, struct xdg_shell *xdg_shell, struct wl_surface *surface);
+bool bm_wl_window_create(struct window *window, struct wl_display *display, struct wl_shm *shm, struct wl_output *output, struct zwlr_layer_shell_v1 *layer_shell, struct wl_surface *surface);
 void bm_wl_window_destroy(struct window *window);
 
 #endif /* _BM_WAYLAND_H_ */
diff --git a/lib/renderers/wayland/window.c b/lib/renderers/wayland/window.c
index af9325f..5807bfa 100644
--- a/lib/renderers/wayland/window.c
+++ b/lib/renderers/wayland/window.c
@@ -7,8 +7,6 @@
 #include <stdlib.h>
 #include <sys/mman.h>
 
-#define USE_XDG_SHELL false
-
 static int
 set_cloexec_or_close(int fd)
 {
@@ -193,49 +191,6 @@ next_buffer(struct window *window)
 }
 
 static void
-shell_surface_ping(void *data, struct wl_shell_surface *surface, uint32_t serial)
-{
-   (void)data;
-   wl_shell_surface_pong(surface, serial);
-}
-
-static void
-shell_surface_configure(void *data, struct wl_shell_surface *surface, uint32_t edges, int32_t width, int32_t height)
-{
-    (void)data, (void)surface, (void)edges, (void)width, (void)height;
-}
-
-static void
-shell_surface_popup_done(void *data, struct wl_shell_surface *surface)
-{
-    (void)data, (void)surface;
-}
-
-static const struct wl_shell_surface_listener shell_surface_listener = {
-    .ping = shell_surface_ping,
-    .configure = shell_surface_configure,
-    .popup_done = shell_surface_popup_done,
-};
-
-static void
-xdg_surface_configure(void *data, struct xdg_surface *surface, int32_t width, int32_t height, struct wl_array *states, uint32_t serial)
-{
-    (void)data, (void)states, (void)width, (void)height, (void)states, (void)serial;
-    xdg_surface_ack_configure(surface, serial);
-}
-
-static void
-xdg_surface_close(void *data, struct xdg_surface *surface)
-{
-    (void)data, (void)surface;
-}
-
-static const struct xdg_surface_listener xdg_surface_listener = {
-    .configure = xdg_surface_configure,
-    .close = xdg_surface_close,
-};
-
-static void
 frame_callback(void *data, struct wl_callback *callback, uint32_t time)
 {
     (void)time;
@@ -294,29 +249,48 @@ bm_wl_window_destroy(struct window *window)
     for (int32_t i = 0; i < 2; ++i)
         destroy_buffer(&window->buffers[i]);
 
-    if (window->xdg_surface)
-        xdg_surface_destroy(window->xdg_surface);
-
-    if (window->shell_surface)
-        wl_shell_surface_destroy(window->shell_surface);
+    if (window->layer_surface)
+        zwlr_layer_surface_v1_destroy(window->layer_surface);
 
     if (window->surface)
         wl_surface_destroy(window->surface);
 }
 
+static void
+layer_surface_configure(void *data, struct zwlr_layer_surface_v1 *layer_surface, uint32_t serial, uint32_t width, uint32_t height)
+{
+    struct window *window = data;
+    window->width = width;
+    window->height = height;
+    zwlr_layer_surface_v1_ack_configure(layer_surface, serial);
+}
+
+static void
+layer_surface_closed(void *data, struct zwlr_layer_surface_v1 *layer_surface)
+{
+    struct window *window = data;
+    zwlr_layer_surface_v1_destroy(layer_surface);
+    wl_surface_destroy(window->surface);
+    exit(1);
+}
+
+static const struct zwlr_layer_surface_v1_listener layer_surface_listener = {
+    .configure = layer_surface_configure,
+    .closed = layer_surface_closed,
+};
+
 bool
-bm_wl_window_create(struct window *window, struct wl_shm *shm, struct wl_shell *shell, struct xdg_shell *xdg_shell, struct wl_surface *surface)
+bm_wl_window_create(struct window *window, struct wl_display *display, struct wl_shm *shm, struct wl_output *output, struct zwlr_layer_shell_v1 *layer_shell, struct wl_surface *surface)
 {
     assert(window);
 
-    if (USE_XDG_SHELL && xdg_shell && (window->xdg_surface = xdg_shell_get_xdg_surface(xdg_shell, surface))) {
-        xdg_surface_add_listener(window->xdg_surface, &xdg_surface_listener, window);
-        xdg_surface_set_title(window->xdg_surface, "bemenu");
-    } else if (shell && (window->shell_surface = wl_shell_get_shell_surface(shell, surface))) {
-        wl_shell_surface_add_listener(window->shell_surface, &shell_surface_listener, window);
-        wl_shell_surface_set_title(window->shell_surface, "bemenu");
-        wl_shell_surface_set_class(window->shell_surface, "bemenu");
-        wl_shell_surface_set_toplevel(window->shell_surface);
+    if (layer_shell && (window->layer_surface = zwlr_layer_shell_v1_get_layer_surface(layer_shell, surface, output, ZWLR_LAYER_SHELL_V1_LAYER_TOP, "menu"))) {
+        zwlr_layer_surface_v1_add_listener(window->layer_surface, &layer_surface_listener, window);
+        zwlr_layer_surface_v1_set_anchor(window->layer_surface, ZWLR_LAYER_SURFACE_V1_ANCHOR_TOP | ZWLR_LAYER_SURFACE_V1_ANCHOR_LEFT | ZWLR_LAYER_SURFACE_V1_ANCHOR_RIGHT);
+        zwlr_layer_surface_v1_set_size(window->layer_surface, 0, 32);
+        zwlr_layer_surface_v1_set_keyboard_interactivity(window->layer_surface, true);
+        wl_surface_commit(surface);
+        wl_display_roundtrip(display);
     } else {
         return false;
     }
diff --git a/lib/renderers/wayland/wlr-layer-shell-unstable-v1.xml b/lib/renderers/wayland/wlr-layer-shell-unstable-v1.xml
new file mode 100644
index 0000000..3181c0b
--- /dev/null
+++ b/lib/renderers/wayland/wlr-layer-shell-unstable-v1.xml
@@ -0,0 +1,281 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="wlr_layer_shell_unstable_v1">
+  <copyright>
+    Copyright © 2017 Drew DeVault
+
+    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_layer_shell_v1" version="1">
+    <description summary="create surfaces that are layers of the desktop">
+      Clients can use this interface to assign the surface_layer role to
+      wl_surfaces. Such surfaces are assigned to a "layer" of the output and
+      rendered with a defined z-depth respective to each other. They may also be
+      anchored to the edges and corners of a screen and specify input handling
+      semantics. This interface should be suitable for the implementation of
+      many desktop shell components, and a broad number of other applications
+      that interact with the desktop.
+    </description>
+
+    <request name="get_layer_surface">
+      <description summary="create a layer_surface from a surface">
+        Create a layer surface for an existing surface. This assigns the role of
+        layer_surface, or raises a protocol error if another role is already
+        assigned.
+
+        Creating a layer surface from a wl_surface which has a buffer attached
+        or committed is a client error, and any attempts by a client to attach
+        or manipulate a buffer prior to the first layer_surface.configure call
+        must also be treated as errors.
+
+        Clients can specify a namespace that defines the purpose of the layer
+        surface.
+      </description>
+      <arg name="id" type="new_id" interface="zwlr_layer_surface_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="output" type="object" interface="wl_output"/>
+      <arg name="layer" type="uint" enum="layer" summary="layer to add this surface to"/>
+      <arg name="namespace" type="string" summary="namespace for the layer surface"/>
+    </request>
+
+    <enum name="error">
+      <entry name="role" value="0" summary="wl_surface has another role"/>
+      <entry name="invalid_layer" value="1" summary="layer value is invalid"/>
+      <entry name="already_constructed" value="2" summary="wl_surface has a buffer attached or committed"/>
+    </enum>
+
+    <enum name="layer">
+      <description summary="available layers for surfaces">
+        These values indicate which layers a surface can be rendered in. They
+        are ordered by z depth, bottom-most first. Traditional shell surfaces
+        will typically be rendered between the bottom and top layers.
+        Fullscreen shell surfaces are typically rendered at the top layer.
+        Multiple surfaces can share a single layer, and ordering within a
+        single layer is undefined.
+      </description>
+
+      <entry name="background" value="0"/>
+      <entry name="bottom" value="1"/>
+      <entry name="top" value="2"/>
+      <entry name="overlay" value="3"/>
+    </enum>
+  </interface>
+
+  <interface name="zwlr_layer_surface_v1" version="1">
+    <description summary="layer metadata interface">
+      An interface that may be implemented by a wl_surface, for surfaces that
+      are designed to be rendered as a layer of a stacked desktop-like
+      environment.
+
+      Layer surface state (size, anchor, exclusive zone, margin, interactivity)
+      is double-buffered, and will be applied at the time wl_surface.commit of
+      the corresponding wl_surface is called.
+    </description>
+
+    <request name="set_size">
+      <description summary="sets the size of the surface">
+        Sets the size of the surface in surface-local coordinates. The
+        compositor will display the surface centered with respect to its
+        anchors.
+
+        If you pass 0 for either value, the compositor will assign it and
+        inform you of the assignment in the configure event. You must set your
+        anchor to opposite edges in the dimensions you omit; not doing so is a
+        protocol error. Both values are 0 by default.
+
+        Size is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="width" type="uint"/>
+      <arg name="height" type="uint"/>
+    </request>
+
+    <request name="set_anchor">
+      <description summary="configures the anchor point of the surface">
+        Requests that the compositor anchor the surface to the specified edges
+        and corners. If two orthoginal edges are specified (e.g. 'top' and
+        'left'), then the anchor point will be the intersection of the edges
+        (e.g. the top left corner of the output); otherwise the anchor point
+        will be centered on that edge, or in the center if none is specified.
+
+        Anchor is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="anchor" type="uint" enum="anchor"/>
+    </request>
+
+    <request name="set_exclusive_zone">
+      <description summary="configures the exclusive geometry of this surface">
+        Requests that the compositor avoids occluding an area of the surface
+        with other surfaces. The compositor's use of this information is
+        implementation-dependent - do not assume that this region will not
+        actually be occluded.
+
+        A positive value is only meaningful if the surface is anchored to an
+        edge, rather than a corner. The zone is the number of surface-local
+        coordinates from the edge that are considered exclusive.
+
+        Surfaces that do not wish to have an exclusive zone may instead specify
+        how they should interact with surfaces that do. If set to zero, the
+        surface indicates that it would like to be moved to avoid occluding
+        surfaces with a positive excluzive zone. If set to -1, the surface
+        indicates that it would not like to be moved to accomodate for other
+        surfaces, and the compositor should extend it all the way to the edges
+        it is anchored to.
+
+        For example, a panel might set its exclusive zone to 10, so that
+        maximized shell surfaces are not shown on top of it. A notification
+        might set its exclusive zone to 0, so that it is moved to avoid
+        occluding the panel, but shell surfaces are shown underneath it. A
+        wallpaper or lock screen might set their exclusive zone to -1, so that
+        they stretch below or over the panel.
+
+        The default value is 0.
+
+        Exclusive zone is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="zone" type="int"/>
+    </request>
+
+    <request name="set_margin">
+      <description summary="sets a margin from the anchor point">
+        Requests that the surface be placed some distance away from the anchor
+        point on the output, in surface-local coordinates. Setting this value
+        for edges you are not anchored to has no effect.
+
+        The exclusive zone includes the margin.
+
+        Margin is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="top" type="int"/>
+      <arg name="right" type="int"/>
+      <arg name="bottom" type="int"/>
+      <arg name="left" type="int"/>
+    </request>
+
+    <request name="set_keyboard_interactivity">
+      <description summary="requests keyboard events">
+        Set to 1 to request that the seat send keyboard events to this layer
+        surface. For layers below the shell surface layer, the seat will use
+        normal focus semantics. For layers above the shell surface layers, the
+        seat will always give exclusive keyboard focus to the top-most layer
+        which has keyboard interactivity set to true.
+
+        Layer surfaces receive pointer, touch, and tablet events normally. If
+        you do not want to receive them, set the input region on your surface
+        to an empty region.
+
+        Events is double-buffered, see wl_surface.commit.
+      </description>
+      <arg name="keyboard_interactivity" type="uint"/>
+    </request>
+
+    <request name="get_popup">
+      <description summary="assign this layer_surface as an xdg_popup parent">
+        This assigns an xdg_popup's parent to this layer_surface.  This popup
+        should have been created via xdg_surface::get_popup with the parent set
+        to NULL, and this request must be invoked before committing the popup's
+        initial state.
+
+        See the documentation of xdg_popup for more details about what an
+        xdg_popup is and how it is used.
+      </description>
+      <arg name="popup" type="object" interface="xdg_popup"/>
+    </request>
+
+    <request name="ack_configure">
+      <description summary="ack a configure event">
+        When a configure event is received, if a client commits the
+        surface in response to the configure event, then the client
+        must make an ack_configure request sometime before the commit
+        request, passing along the serial of the configure event.
+
+        If the client receives multiple configure events before it
+        can respond to one, it only has to ack the last configure event.
+
+        A client is not required to commit immediately after sending
+        an ack_configure request - it may even ack_configure several times
+        before its next surface commit.
+
+        A client may send multiple ack_configure requests before committing, but
+        only the last request sent before a commit indicates which configure
+        event the client really is responding to.
+      </description>
+      <arg name="serial" type="uint" summary="the serial from the configure event"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the layer_surface">
+        This request destroys the layer surface.
+      </description>
+    </request>
+
+    <event name="configure">
+      <description summary="suggest a surface change">
+        The configure event asks the client to resize its surface.
+
+        Clients should arrange their surface for the new states, and then send
+        an ack_configure request with the serial sent in this configure event at
+        some point before committing the new surface.
+
+        The client is free to dismiss all but the last configure event it
+        received.
+
+        The width and height arguments specify the size of the window in
+        surface-local coordinates.
+
+        The size is a hint, in the sense that the client is free to ignore it if
+        it doesn't resize, pick a smaller size (to satisfy aspect ratio or
+        resize in steps of NxM pixels). If the client picks a smaller size and
+        is anchored to two opposite anchors (e.g. 'top' and 'bottom'), the
+        surface will be centered on this axis.
+
+        If the width or height arguments are zero, it means the client should
+        decide its own window dimension.
+      </description>
+      <arg name="serial" type="uint"/>
+      <arg name="width" type="uint"/>
+      <arg name="height" type="uint"/>
+    </event>
+
+    <event name="closed">
+      <description summary="surface should be closed">
+        The closed event is sent by the compositor when the surface will no
+        longer be shown. The output may have been destroyed or the user may
+        have asked for it to be removed. Further changes to the surface will be
+        ignored. The client should destroy the resource after receiving this
+        event, and create a new surface if they so choose.
+      </description>
+    </event>
+
+    <enum name="error">
+      <entry name="invalid_surface_state" value="0" summary="provided surface state is invalid"/>
+      <entry name="invalid_size" value="1" summary="size is invalid"/>
+      <entry name="invalid_anchor" value="2" summary="anchor bitfield is invalid"/>
+    </enum>
+
+    <enum name="anchor" bitfield="true">
+      <entry name="top" value="1" summary="the top edge of the anchor rectangle"/>
+      <entry name="bottom" value="2" summary="the bottom edge of the anchor rectangle"/>
+      <entry name="left" value="4" summary="the left edge of the anchor rectangle"/>
+      <entry name="right" value="8" summary="the right edge of the anchor rectangle"/>
+    </enum>
+  </interface>
+</protocol>
diff --git a/lib/renderers/wayland/xdg-shell.xml b/lib/renderers/wayland/xdg-shell.xml
index 7321ba7..d524ea9 100644
--- a/lib/renderers/wayland/xdg-shell.xml
+++ b/lib/renderers/wayland/xdg-shell.xml
@@ -1,11 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<protocol name="xdg_shell_unstable_v5">
+<protocol name="xdg_shell">
 
   <copyright>
     Copyright © 2008-2013 Kristian Høgsberg
     Copyright © 2013      Rafael Antognolli
     Copyright © 2013      Jasper St. Pierre
     Copyright © 2010-2013 Intel Corporation
+    Copyright © 2015-2017 Samsung Electronics Co., Ltd
+    Copyright © 2015-2017 Red Hat Inc.
 
     Permission is hereby granted, free of charge, to any person obtaining a
     copy of this software and associated documentation files (the "Software"),
@@ -27,214 +29,604 @@
     DEALINGS IN THE SOFTWARE.
   </copyright>
 
-  <interface name="xdg_shell" version="1">
+  <interface name="xdg_wm_base" version="1">
     <description summary="create desktop-style surfaces">
-      xdg_shell allows clients to turn a wl_surface into a "real window"
-      which can be dragged, resized, stacked, and moved around by the
-      user. Everything about this interface is suited towards traditional
-      desktop environments.
+      The xdg_wm_base interface is exposed as a global object enabling clients
+      to turn their wl_surfaces into windows in a desktop environment. It
+      defines the basic functionality needed for clients and the compositor to
+      create windows that can be dragged, resized, maximized, etc, as well as
+      creating transient windows such as popup menus.
     </description>
 
-    <enum name="version">
-      <description summary="latest protocol version">
-    The 'current' member of this enum gives the version of the
-    protocol.  Implementations can compare this to the version
-    they implement using static_assert to ensure the protocol and
-    implementation versions match.
-      </description>
-      <entry name="current" value="5" summary="Always the latest version"/>
-    </enum>
-
     <enum name="error">
       <entry name="role" value="0" summary="given wl_surface has another role"/>
-      <entry name="defunct_surfaces" value="1" summary="xdg_shell was destroyed before children"/>
-      <entry name="not_the_topmost_popup" value="2" summary="the client tried to map or destroy a non-topmost popup"/>
-      <entry name="invalid_popup_parent" value="3" summary="the client specified an invalid popup parent surface"/>
+      <entry name="defunct_surfaces" value="1"
+	     summary="xdg_wm_base was destroyed before children"/>
+      <entry name="not_the_topmost_popup" value="2"
+	     summary="the client tried to map or destroy a non-topmost popup"/>
+      <entry name="invalid_popup_parent" value="3"
+	     summary="the client specified an invalid popup parent surface"/>
+      <entry name="invalid_surface_state" value="4"
+	     summary="the client provided an invalid surface state"/>
+      <entry name="invalid_positioner" value="5"
+	     summary="the client provided an invalid positioner"/>
     </enum>
 
     <request name="destroy" type="destructor">
-      <description summary="destroy xdg_shell">
-        Destroy this xdg_shell object.
+      <description summary="destroy xdg_wm_base">
+	Destroy this xdg_wm_base object.
 
-        Destroying a bound xdg_shell object while there are surfaces
-        still alive created by this xdg_shell object instance is illegal
-        and will result in a protocol error.
+	Destroying a bound xdg_wm_base object while there are surfaces
+	still alive created by this xdg_wm_base object instance is illegal
+	and will result in a protocol error.
       </description>
     </request>
 
-    <request name="use_unstable_version">
-      <description summary="enable use of this unstable version">
-    Negotiate the unstable version of the interface.  This
-    mechanism is in place to ensure client and server agree on the
-    unstable versions of the protocol that they speak or exit
-    cleanly if they don't agree.  This request will go away once
-    the xdg-shell protocol is stable.
+    <request name="create_positioner">
+      <description summary="create a positioner object">
+	Create a positioner object. A positioner object is used to position
+	surfaces relative to some parent surface. See the interface description
+	and xdg_surface.get_popup for details.
       </description>
-      <arg name="version" type="int"/>
+      <arg name="id" type="new_id" interface="xdg_positioner"/>
     </request>
 
     <request name="get_xdg_surface">
       <description summary="create a shell surface from a surface">
-    This creates an xdg_surface for the given surface and gives it the
-    xdg_surface role. A wl_surface can only be given an xdg_surface role
-    once. If get_xdg_surface is called with a wl_surface that already has
-    an active xdg_surface associated with it, or if it had any other role,
-    an error is raised.
+	This creates an xdg_surface for the given surface. While xdg_surface
+	itself is not a role, the corresponding surface may only be assigned
+	a role extending xdg_surface, such as xdg_toplevel or xdg_popup.
+
+	This creates an xdg_surface for the given surface. An xdg_surface is
+	used as basis to define a role to a given surface, such as xdg_toplevel
+	or xdg_popup. It also manages functionality shared between xdg_surface
+	based surface roles.
 
-    See the documentation of xdg_surface for more details about what an
-    xdg_surface is and how it is used.
+	See the documentation of xdg_surface for more details about what an
+	xdg_surface is and how it is used.
       </description>
       <arg name="id" type="new_id" interface="xdg_surface"/>
       <arg name="surface" type="object" interface="wl_surface"/>
     </request>
 
-    <request name="get_xdg_popup">
-      <description summary="create a popup for a surface">
-    This creates an xdg_popup for the given surface and gives it the
-    xdg_popup role. A wl_surface can only be given an xdg_popup role
-    once. If get_xdg_popup is called with a wl_surface that already has
-    an active xdg_popup associated with it, or if it had any other role,
-    an error is raised.
-
-    This request must be used in response to some sort of user action
-    like a button press, key press, or touch down event.
-
-    See the documentation of xdg_popup for more details about what an
-    xdg_popup is and how it is used.
+    <request name="pong">
+      <description summary="respond to a ping event">
+	A client must respond to a ping event with a pong request or
+	the client may be deemed unresponsive. See xdg_wm_base.ping.
       </description>
-      <arg name="id" type="new_id" interface="xdg_popup"/>
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="parent" type="object" interface="wl_surface"/>
-      <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
-      <arg name="serial" type="uint" summary="the serial of the user event"/>
-      <arg name="x" type="int"/>
-      <arg name="y" type="int"/>
+      <arg name="serial" type="uint" summary="serial of the ping event"/>
     </request>
 
     <event name="ping">
       <description summary="check if the client is alive">
-        The ping event asks the client if it's still alive. Pass the
-        serial specified in the event back to the compositor by sending
-        a "pong" request back with the specified serial.
+	The ping event asks the client if it's still alive. Pass the
+	serial specified in the event back to the compositor by sending
+	a "pong" request back with the specified serial. See xdg_wm_base.ping.
 
-        Compositors can use this to determine if the client is still
-        alive. It's unspecified what will happen if the client doesn't
-        respond to the ping request, or in what timeframe. Clients should
-        try to respond in a reasonable amount of time.
+	Compositors can use this to determine if the client is still
+	alive. It's unspecified what will happen if the client doesn't
+	respond to the ping request, or in what timeframe. Clients should
+	try to respond in a reasonable amount of time.
 
-        A compositor is free to ping in any way it wants, but a client must
-        always respond to any xdg_shell object it created.
+	A compositor is free to ping in any way it wants, but a client must
+	always respond to any xdg_wm_base object it created.
       </description>
       <arg name="serial" type="uint" summary="pass this to the pong request"/>
     </event>
+  </interface>
 
-    <request name="pong">
-      <description summary="respond to a ping event">
-    A client must respond to a ping event with a pong request or
-    the client may be deemed unresponsive.
+  <interface name="xdg_positioner" version="1">
+    <description summary="child surface positioner">
+      The xdg_positioner provides a collection of rules for the placement of a
+      child surface relative to a parent surface. Rules can be defined to ensure
+      the child surface remains within the visible area's borders, and to
+      specify how the child surface changes its position, such as sliding along
+      an axis, or flipping around a rectangle. These positioner-created rules are
+      constrained by the requirement that a child surface must intersect with or
+      be at least partially adjacent to its parent surface.
+
+      See the various requests for details about possible rules.
+
+      At the time of the request, the compositor makes a copy of the rules
+      specified by the xdg_positioner. Thus, after the request is complete the
+      xdg_positioner object can be destroyed or reused; further changes to the
+      object will have no effect on previous usages.
+
+      For an xdg_positioner object to be considered complete, it must have a
+      non-zero size set by set_size, and a non-zero anchor rectangle set by
+      set_anchor_rect. Passing an incomplete xdg_positioner object when
+      positioning a surface raises an error.
+    </description>
+
+    <enum name="error">
+      <entry name="invalid_input" value="0" summary="invalid input provided"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the xdg_positioner object">
+	Notify the compositor that the xdg_positioner will no longer be used.
       </description>
-      <arg name="serial" type="uint" summary="serial of the ping event"/>
+    </request>
+
+    <request name="set_size">
+      <description summary="set the size of the to-be positioned rectangle">
+	Set the size of the surface that is to be positioned with the positioner
+	object. The size is in surface-local coordinates and corresponds to the
+	window geometry. See xdg_surface.set_window_geometry.
+
+	If a zero or negative size is set the invalid_input error is raised.
+      </description>
+      <arg name="width" type="int" summary="width of positioned rectangle"/>
+      <arg name="height" type="int" summary="height of positioned rectangle"/>
+    </request>
+
+    <request name="set_anchor_rect">
+      <description summary="set the anchor rectangle within the parent surface">
+	Specify the anchor rectangle within the parent surface that the child
+	surface will be placed relative to. The rectangle is relative to the
+	window geometry as defined by xdg_surface.set_window_geometry of the
+	parent surface.
+
+	When the xdg_positioner object is used to position a child surface, the
+	anchor rectangle may not extend outside the window geometry of the
+	positioned child's parent surface.
+
+	If a negative size is set the invalid_input error is raised.
+      </description>
+      <arg name="x" type="int" summary="x position of anchor rectangle"/>
+      <arg name="y" type="int" summary="y position of anchor rectangle"/>
+      <arg name="width" type="int" summary="width of anchor rectangle"/>
+      <arg name="height" type="int" summary="height of anchor rectangle"/>
+    </request>
+
+    <enum name="anchor">
+      <entry name="none" value="0"/>
+      <entry name="top" value="1"/>
+      <entry name="bottom" value="2"/>
+      <entry name="left" value="3"/>
+      <entry name="right" value="4"/>
+      <entry name="top_left" value="5"/>
+      <entry name="bottom_left" value="6"/>
+      <entry name="top_right" value="7"/>
+      <entry name="bottom_right" value="8"/>
+    </enum>
+
+    <request name="set_anchor">
+      <description summary="set anchor rectangle anchor">
+	Defines the anchor point for the anchor rectangle. The specified anchor
+	is used derive an anchor point that the child surface will be
+	positioned relative to. If a corner anchor is set (e.g. 'top_left' or
+	'bottom_right'), the anchor point will be at the specified corner;
+	otherwise, the derived anchor point will be centered on the specified
+	edge, or in the center of the anchor rectangle if no edge is specified.
+      </description>
+      <arg name="anchor" type="uint" enum="anchor"
+	   summary="anchor"/>
+    </request>
+
+    <enum name="gravity">
+      <entry name="none" value="0"/>
+      <entry name="top" value="1"/>
+      <entry name="bottom" value="2"/>
+      <entry name="left" value="3"/>
+      <entry name="right" value="4"/>
+      <entry name="top_left" value="5"/>
+      <entry name="bottom_left" value="6"/>
+      <entry name="top_right" value="7"/>
+      <entry name="bottom_right" value="8"/>
+    </enum>
+
+    <request name="set_gravity">
+      <description summary="set child surface gravity">
+	Defines in what direction a surface should be positioned, relative to
+	the anchor point of the parent surface. If a corner gravity is
+	specified (e.g. 'bottom_right' or 'top_left'), then the child surface
+	will be placed towards the specified gravity; otherwise, the child
+	surface will be centered over the anchor point on any axis that had no
+	gravity specified.
+      </description>
+      <arg name="gravity" type="uint" enum="gravity"
+	   summary="gravity direction"/>
+    </request>
+
+    <enum name="constraint_adjustment" bitfield="true">
+      <description summary="constraint adjustments">
+	The constraint adjustment value define ways the compositor will adjust
+	the position of the surface, if the unadjusted position would result
+	in the surface being partly constrained.
+
+	Whether a surface is considered 'constrained' is left to the compositor
+	to determine. For example, the surface may be partly outside the
+	compositor's defined 'work area', thus necessitating the child surface's
+	position be adjusted until it is entirely inside the work area.
+
+	The adjustments can be combined, according to a defined precedence: 1)
+	Flip, 2) Slide, 3) Resize.
+      </description>
+      <entry name="none" value="0">
+	<description summary="don't move the child surface when constrained">
+	  Don't alter the surface position even if it is constrained on some
+	  axis, for example partially outside the edge of an output.
+	</description>
+      </entry>
+      <entry name="slide_x" value="1">
+	<description summary="move along the x axis until unconstrained">
+	  Slide the surface along the x axis until it is no longer constrained.
+
+	  First try to slide towards the direction of the gravity on the x axis
+	  until either the edge in the opposite direction of the gravity is
+	  unconstrained or the edge in the direction of the gravity is
+	  constrained.
+
+	  Then try to slide towards the opposite direction of the gravity on the
+	  x axis until either the edge in the direction of the gravity is
+	  unconstrained or the edge in the opposite direction of the gravity is
+	  constrained.
+	</description>
+      </entry>
+      <entry name="slide_y" value="2">
+	<description summary="move along the y axis until unconstrained">
+	  Slide the surface along the y axis until it is no longer constrained.
+
+	  First try to slide towards the direction of the gravity on the y axis
+	  until either the edge in the opposite direction of the gravity is
+	  unconstrained or the edge in the direction of the gravity is
+	  constrained.
+
+	  Then try to slide towards the opposite direction of the gravity on the
+	  y axis until either the edge in the direction of the gravity is
+	  unconstrained or the edge in the opposite direction of the gravity is
+	  constrained.
+	</description>
+      </entry>
+      <entry name="flip_x" value="4">
+	<description summary="invert the anchor and gravity on the x axis">
+	  Invert the anchor and gravity on the x axis if the surface is
+	  constrained on the x axis. For example, if the left edge of the
+	  surface is constrained, the gravity is 'left' and the anchor is
+	  'left', change the gravity to 'right' and the anchor to 'right'.
+
+	  If the adjusted position also ends up being constrained, the resulting
+	  position of the flip_x adjustment will be the one before the
+	  adjustment.
+	</description>
+      </entry>
+      <entry name="flip_y" value="8">
+	<description summary="invert the anchor and gravity on the y axis">
+	  Invert the anchor and gravity on the y axis if the surface is
+	  constrained on the y axis. For example, if the bottom edge of the
+	  surface is constrained, the gravity is 'bottom' and the anchor is
+	  'bottom', change the gravity to 'top' and the anchor to 'top'.
+
+	  The adjusted position is calculated given the original anchor
+	  rectangle and offset, but with the new flipped anchor and gravity
+	  values.
+
+	  If the adjusted position also ends up being constrained, the resulting
+	  position of the flip_y adjustment will be the one before the
+	  adjustment.
+	</description>
+      </entry>
+      <entry name="resize_x" value="16">
+	<description summary="horizontally resize the surface">
+	  Resize the surface horizontally so that it is completely
+	  unconstrained.
+	</description>
+      </entry>
+      <entry name="resize_y" value="32">
+	<description summary="vertically resize the surface">
+	  Resize the surface vertically so that it is completely unconstrained.
+	</description>
+      </entry>
+    </enum>
+
+    <request name="set_constraint_adjustment">
+      <description summary="set the adjustment to be done when constrained">
+	Specify how the window should be positioned if the originally intended
+	position caused the surface to be constrained, meaning at least
+	partially outside positioning boundaries set by the compositor. The
+	adjustment is set by constructing a bitmask describing the adjustment to
+	be made when the surface is constrained on that axis.
+
+	If no bit for one axis is set, the compositor will assume that the child
+	surface should not change its position on that axis when constrained.
+
+	If more than one bit for one axis is set, the order of how adjustments
+	are applied is specified in the corresponding adjustment descriptions.
+
+	The default adjustment is none.
+      </description>
+      <arg name="constraint_adjustment" type="uint"
+	   summary="bit mask of constraint adjustments"/>
+    </request>
+
+    <request name="set_offset">
+      <description summary="set surface position offset">
+	Specify the surface position offset relative to the position of the
+	anchor on the anchor rectangle and the anchor on the surface. For
+	example if the anchor of the anchor rectangle is at (x, y), the surface
+	has the gravity bottom|right, and the offset is (ox, oy), the calculated
+	surface position will be (x + ox, y + oy). The offset position of the
+	surface is the one used for constraint testing. See
+	set_constraint_adjustment.
+
+	An example use case is placing a popup menu on top of a user interface
+	element, while aligning the user interface element of the parent surface
+	with some user interface element placed somewhere in the popup surface.
+      </description>
+      <arg name="x" type="int" summary="surface position x offset"/>
+      <arg name="y" type="int" summary="surface position y offset"/>
     </request>
   </interface>
 
   <interface name="xdg_surface" version="1">
-    <description summary="A desktop window">
+    <description summary="desktop user interface surface base interface">
       An interface that may be implemented by a wl_surface, for
       implementations that provide a desktop-style user interface.
 
-      It provides requests to treat surfaces like windows, allowing to set
-      properties like maximized, fullscreen, minimized, and to move and resize
-      them, and associate metadata like title and app id.
+      It provides a base set of functionality required to construct user
+      interface elements requiring management by the compositor, such as
+      toplevel windows, menus, etc. The types of functionality are split into
+      xdg_surface roles.
+
+      Creating an xdg_surface does not set the role for a wl_surface. In order
+      to map an xdg_surface, the client must create a role-specific object
+      using, e.g., get_toplevel, get_popup. The wl_surface for any given
+      xdg_surface can have at most one role, and may not be assigned any role
+      not based on xdg_surface.
+
+      A role must be assigned before any other requests are made to the
+      xdg_surface object.
 
       The client must call wl_surface.commit on the corresponding wl_surface
-      for the xdg_surface state to take effect. Prior to committing the new
-      state, it can set up initial configuration, such as maximizing or setting
-      a window geometry.
+      for the xdg_surface state to take effect.
+
+      Creating an xdg_surface from a wl_surface which has a buffer attached or
+      committed is a client error, and any attempts by a client to attach or
+      manipulate a buffer prior to the first xdg_surface.configure call must
+      also be treated as errors.
+
+      Mapping an xdg_surface-based role surface is defined as making it
+      possible for the surface to be shown by the compositor. Note that
+      a mapped surface is not guaranteed to be visible once it is mapped.
+
+      For an xdg_surface to be mapped by the compositor, the following
+      conditions must be met:
+      (1) the client has assigned an xdg_surface-based role to the surface
+      (2) the client has set and committed the xdg_surface state and the
+	  role-dependent state to the surface
+      (3) the client has committed a buffer to the surface
+
+      A newly-unmapped surface is considered to have met condition (1) out
+      of the 3 required conditions for mapping a surface if its role surface
+      has not been destroyed.
+    </description>
+
+    <enum name="error">
+      <entry name="not_constructed" value="1"/>
+      <entry name="already_constructed" value="2"/>
+      <entry name="unconfigured_buffer" value="3"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the xdg_surface">
+	Destroy the xdg_surface object. An xdg_surface must only be destroyed
+	after its role object has been destroyed.
+      </description>
+    </request>
+
+    <request name="get_toplevel">
+      <description summary="assign the xdg_toplevel surface role">
+	This creates an xdg_toplevel object for the given xdg_surface and gives
+	the associated wl_surface the xdg_toplevel role.
+
+	See the documentation of xdg_toplevel for more details about what an
+	xdg_toplevel is and how it is used.
+      </description>
+      <arg name="id" type="new_id" interface="xdg_toplevel"/>
+    </request>
+
+    <request name="get_popup">
+      <description summary="assign the xdg_popup surface role">
+	This creates an xdg_popup object for the given xdg_surface and gives
+	the associated wl_surface the xdg_popup role.
+
+	If null is passed as a parent, a parent surface must be specified using
+	some other protocol, before committing the initial state.
+
+	See the documentation of xdg_popup for more details about what an
+	xdg_popup is and how it is used.
+      </description>
+      <arg name="id" type="new_id" interface="xdg_popup"/>
+      <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
+      <arg name="positioner" type="object" interface="xdg_positioner"/>
+    </request>
+
+    <request name="set_window_geometry">
+      <description summary="set the new window geometry">
+	The window geometry of a surface is its "visible bounds" from the
+	user's perspective. Client-side decorations often have invisible
+	portions like drop-shadows which should be ignored for the
+	purposes of aligning, placing and constraining windows.
+
+	The window geometry is double buffered, and will be applied at the
+	time wl_surface.commit of the corresponding wl_surface is called.
+
+	When maintaining a position, the compositor should treat the (x, y)
+	coordinate of the window geometry as the top left corner of the window.
+	A client changing the (x, y) window geometry coordinate should in
+	general not alter the position of the window.
+
+	Once the window geometry of the surface is set, it is not possible to
+	unset it, and it will remain the same until set_window_geometry is
+	called again, even if a new subsurface or buffer is attached.
+
+	If never set, the value is the full bounds of the surface,
+	including any subsurfaces. This updates dynamically on every
+	commit. This unset is meant for extremely simple clients.
+
+	The arguments are given in the surface-local coordinate space of
+	the wl_surface associated with this xdg_surface.
+
+	The width and height must be greater than zero. Setting an invalid size
+	will raise an error. When applied, the effective window geometry will be
+	the set window geometry clamped to the bounding rectangle of the
+	combined geometry of the surface of the xdg_surface and the associated
+	subsurfaces.
+      </description>
+      <arg name="x" type="int"/>
+      <arg name="y" type="int"/>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+    </request>
 
-      Even without attaching a buffer the compositor must respond to initial
-      committed configuration, for instance sending a configure event with
-      expected window geometry if the client maximized its surface during
-      initialization.
+    <request name="ack_configure">
+      <description summary="ack a configure event">
+	When a configure event is received, if a client commits the
+	surface in response to the configure event, then the client
+	must make an ack_configure request sometime before the commit
+	request, passing along the serial of the configure event.
+
+	For instance, for toplevel surfaces the compositor might use this
+	information to move a surface to the top left only when the client has
+	drawn itself for the maximized or fullscreen state.
+
+	If the client receives multiple configure events before it
+	can respond to one, it only has to ack the last configure event.
 
-      For a surface to be mapped by the compositor the client must have
-      committed both an xdg_surface state and a buffer.
+	A client is not required to commit immediately after sending
+	an ack_configure request - it may even ack_configure several times
+	before its next surface commit.
+
+	A client may send multiple ack_configure requests before committing, but
+	only the last request sent before a commit indicates which configure
+	event the client really is responding to.
+      </description>
+      <arg name="serial" type="uint" summary="the serial from the configure event"/>
+    </request>
+
+    <event name="configure">
+      <description summary="suggest a surface change">
+	The configure event marks the end of a configure sequence. A configure
+	sequence is a set of one or more events configuring the state of the
+	xdg_surface, including the final xdg_surface.configure event.
+
+	Where applicable, xdg_surface surface roles will during a configure
+	sequence extend this event as a latched state sent as events before the
+	xdg_surface.configure event. Such events should be considered to make up
+	a set of atomically applied configuration states, where the
+	xdg_surface.configure commits the accumulated state.
+
+	Clients should arrange their surface for the new states, and then send
+	an ack_configure request with the serial sent in this configure event at
+	some point before committing the new surface.
+
+	If the client receives multiple configure events before it can respond
+	to one, it is free to discard all but the last event it received.
+      </description>
+      <arg name="serial" type="uint" summary="serial of the configure event"/>
+    </event>
+  </interface>
+
+  <interface name="xdg_toplevel" version="1">
+    <description summary="toplevel surface">
+      This interface defines an xdg_surface role which allows a surface to,
+      among other things, set window-like properties such as maximize,
+      fullscreen, and minimize, set application-specific metadata like title and
+      id, and well as trigger user interactive operations such as interactive
+      resize and move.
+
+      Unmapping an xdg_toplevel means that the surface cannot be shown
+      by the compositor until it is explicitly mapped again.
+      All active operations (e.g., move, resize) are canceled and all
+      attributes (e.g. title, state, stacking, ...) are discarded for
+      an xdg_toplevel surface when it is unmapped.
+
+      Attaching a null buffer to a toplevel unmaps the surface.
     </description>
 
     <request name="destroy" type="destructor">
-      <description summary="Destroy the xdg_surface">
-    Unmap and destroy the window. The window will be effectively
-    hidden from the user's point of view, and all state like
-    maximization, fullscreen, and so on, will be lost.
+      <description summary="destroy the xdg_toplevel">
+	This request destroys the role surface and unmaps the surface;
+	see "Unmapping" behavior in interface section for details.
       </description>
     </request>
 
     <request name="set_parent">
       <description summary="set the parent of this surface">
-    Set the "parent" of this surface. This window should be stacked
-    above a parent. The parent surface must be mapped as long as this
-    surface is mapped.
-
-    Parent windows should be set on dialogs, toolboxes, or other
-    "auxiliary" surfaces, so that the parent is raised when the dialog
-    is raised.
+	Set the "parent" of this surface. This surface should be stacked
+	above the parent surface and all other ancestor surfaces.
+
+	Parent windows should be set on dialogs, toolboxes, or other
+	"auxiliary" surfaces, so that the parent is raised when the dialog
+	is raised.
+
+	Setting a null parent for a child window removes any parent-child
+	relationship for the child. Setting a null parent for a window which
+	currently has no parent is a no-op.
+
+	If the parent is unmapped then its children are managed as
+	though the parent of the now-unmapped parent has become the
+	parent of this surface. If no parent exists for the now-unmapped
+	parent then the children are managed as though they have no
+	parent surface.
       </description>
-      <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
+      <arg name="parent" type="object" interface="xdg_toplevel" allow-null="true"/>
     </request>
 
     <request name="set_title">
       <description summary="set surface title">
-    Set a short title for the surface.
+	Set a short title for the surface.
 
-    This string may be used to identify the surface in a task bar,
-    window list, or other user interface elements provided by the
-    compositor.
+	This string may be used to identify the surface in a task bar,
+	window list, or other user interface elements provided by the
+	compositor.
 
-    The string must be encoded in UTF-8.
+	The string must be encoded in UTF-8.
       </description>
       <arg name="title" type="string"/>
     </request>
 
     <request name="set_app_id">
       <description summary="set application ID">
-    Set an application identifier for the surface.
+	Set an application identifier for the surface.
 
-    The app ID identifies the general class of applications to which
-    the surface belongs. The compositor can use this to group multiple
-    surfaces together, or to determine how to launch a new application.
+	The app ID identifies the general class of applications to which
+	the surface belongs. The compositor can use this to group multiple
+	surfaces together, or to determine how to launch a new application.
 
-    For D-Bus activatable applications, the app ID is used as the D-Bus
-    service name.
+	For D-Bus activatable applications, the app ID is used as the D-Bus
+	service name.
 
-    The compositor shell will try to group application surfaces together
-    by their app ID.  As a best practice, it is suggested to select app
-    ID's that match the basename of the application's .desktop file.
-    For example, "org.freedesktop.FooViewer" where the .desktop file is
-    "org.freedesktop.FooViewer.desktop".
+	The compositor shell will try to group application surfaces together
+	by their app ID. As a best practice, it is suggested to select app
+	ID's that match the basename of the application's .desktop file.
+	For example, "org.freedesktop.FooViewer" where the .desktop file is
+	"org.freedesktop.FooViewer.desktop".
 
-    See the desktop-entry specification [0] for more details on
-    application identifiers and how they relate to well-known D-Bus
-    names and .desktop files.
+	See the desktop-entry specification [0] for more details on
+	application identifiers and how they relate to well-known D-Bus
+	names and .desktop files.
 
-    [0] http://standards.freedesktop.org/desktop-entry-spec/
+	[0] http://standards.freedesktop.org/desktop-entry-spec/
       </description>
       <arg name="app_id" type="string"/>
     </request>
 
     <request name="show_window_menu">
       <description summary="show the window menu">
-        Clients implementing client-side decorations might want to show
-        a context menu when right-clicking on the decorations, giving the
-        user a menu that they can use to maximize or minimize the window.
+	Clients implementing client-side decorations might want to show
+	a context menu when right-clicking on the decorations, giving the
+	user a menu that they can use to maximize or minimize the window.
 
-        This request asks the compositor to pop up such a window menu at
-        the given position, relative to the local surface coordinates of
-        the parent surface. There are no guarantees as to what menu items
-        the window menu contains.
+	This request asks the compositor to pop up such a window menu at
+	the given position, relative to the local surface coordinates of
+	the parent surface. There are no guarantees as to what menu items
+	the window menu contains.
 
-        This request must be used in response to some sort of user action
-        like a button press, key press, or touch down event.
+	This request must be used in response to some sort of user action
+	like a button press, key press, or touch down event.
       </description>
-
       <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
       <arg name="serial" type="uint" summary="the serial of the user event"/>
       <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
@@ -243,22 +635,22 @@
 
     <request name="move">
       <description summary="start an interactive move">
-    Start an interactive, user-driven move of the surface.
-
-    This request must be used in response to some sort of user action
-    like a button press, key press, or touch down event. The passed
-    serial is used to determine the type of interactive move (touch,
-    pointer, etc).
-
-    The server may ignore move requests depending on the state of
-    the surface (e.g. fullscreen or maximized), or if the passed serial
-    is no longer valid.
-
-    If triggered, the surface will lose the focus of the device
-    (wl_pointer, wl_touch, etc) used for the move. It is up to the
-    compositor to visually indicate that the move is taking place, such as
-    updating a pointer cursor, during the move. There is no guarantee
-    that the device focus will return when the move is completed.
+	Start an interactive, user-driven move of the surface.
+
+	This request must be used in response to some sort of user action
+	like a button press, key press, or touch down event. The passed
+	serial is used to determine the type of interactive move (touch,
+	pointer, etc).
+
+	The server may ignore move requests depending on the state of
+	the surface (e.g. fullscreen or maximized), or if the passed serial
+	is no longer valid.
+
+	If triggered, the surface will lose the focus of the device
+	(wl_pointer, wl_touch, etc) used for the move. It is up to the
+	compositor to visually indicate that the move is taking place, such as
+	updating a pointer cursor, during the move. There is no guarantee
+	that the device focus will return when the move is completed.
       </description>
       <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
       <arg name="serial" type="uint" summary="the serial of the user event"/>
@@ -266,8 +658,8 @@
 
     <enum name="resize_edge">
       <description summary="edge values for resizing">
-    These values are used to indicate which edge of a surface
-    is being dragged in a resize operation.
+	These values are used to indicate which edge of a surface
+	is being dragged in a resize operation.
       </description>
       <entry name="none" value="0"/>
       <entry name="top" value="1"/>
@@ -282,36 +674,36 @@
 
     <request name="resize">
       <description summary="start an interactive resize">
-    Start a user-driven, interactive resize of the surface.
-
-    This request must be used in response to some sort of user action
-    like a button press, key press, or touch down event. The passed
-    serial is used to determine the type of interactive resize (touch,
-    pointer, etc).
-
-    The server may ignore resize requests depending on the state of
-    the surface (e.g. fullscreen or maximized).
-
-    If triggered, the client will receive configure events with the
-    "resize" state enum value and the expected sizes. See the "resize"
-    enum value for more details about what is required. The client
-    must also acknowledge configure events using "ack_configure". After
-    the resize is completed, the client will receive another "configure"
-    event without the resize state.
-
-    If triggered, the surface also will lose the focus of the device
-    (wl_pointer, wl_touch, etc) used for the resize. It is up to the
-    compositor to visually indicate that the resize is taking place,
-    such as updating a pointer cursor, during the resize. There is no
-    guarantee that the device focus will return when the resize is
-    completed.
-
-    The edges parameter specifies how the surface should be resized,
-    and is one of the values of the resize_edge enum. The compositor
-    may use this information to update the surface position for
-    example when dragging the top left corner. The compositor may also
-    use this information to adapt its behavior, e.g. choose an
-    appropriate cursor image.
+	Start a user-driven, interactive resize of the surface.
+
+	This request must be used in response to some sort of user action
+	like a button press, key press, or touch down event. The passed
+	serial is used to determine the type of interactive resize (touch,
+	pointer, etc).
+
+	The server may ignore resize requests depending on the state of
+	the surface (e.g. fullscreen or maximized).
+
+	If triggered, the client will receive configure events with the
+	"resize" state enum value and the expected sizes. See the "resize"
+	enum value for more details about what is required. The client
+	must also acknowledge configure events using "ack_configure". After
+	the resize is completed, the client will receive another "configure"
+	event without the resize state.
+
+	If triggered, the surface also will lose the focus of the device
+	(wl_pointer, wl_touch, etc) used for the resize. It is up to the
+	compositor to visually indicate that the resize is taking place,
+	such as updating a pointer cursor, during the resize. There is no
+	guarantee that the device focus will return when the resize is
+	completed.
+
+	The edges parameter specifies how the surface should be resized,
+	and is one of the values of the resize_edge enum. The compositor
+	may use this information to update the surface position for
+	example when dragging the top left corner. The compositor may also
+	use this information to adapt its behavior, e.g. choose an
+	appropriate cursor image.
       </description>
       <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
       <arg name="serial" type="uint" summary="the serial of the user event"/>
@@ -320,304 +712,407 @@
 
     <enum name="state">
       <description summary="types of state on the surface">
-        The different state values used on the surface. This is designed for
-        state values like maximized, fullscreen. It is paired with the
-        configure event to ensure that both the client and the compositor
-        setting the state can be synchronized.
-
-        States set in this way are double-buffered. They will get applied on
-        the next commit.
-
-        Desktop environments may extend this enum by taking up a range of
-        values and documenting the range they chose in this description.
-        They are not required to document the values for the range that they
-        chose. Ideally, any good extensions from a desktop environment should
-        make its way into standardization into this enum.
+	The different state values used on the surface. This is designed for
+	state values like maximized, fullscreen. It is paired with the
+	configure event to ensure that both the client and the compositor
+	setting the state can be synchronized.
 
-        The current reserved ranges are:
-
-        0x0000 - 0x0FFF: xdg-shell core values, documented below.
-        0x1000 - 0x1FFF: GNOME
-        0x2000 - 0x2FFF: EFL
+	States set in this way are double-buffered. They will get applied on
+	the next commit.
       </description>
       <entry name="maximized" value="1" summary="the surface is maximized">
-    <description summary="the surface is maximized">
-      The surface is maximized. The window geometry specified in the configure
-      event must be obeyed by the client.
-    </description>
+	<description summary="the surface is maximized">
+	  The surface is maximized. The window geometry specified in the configure
+	  event must be obeyed by the client.
+	</description>
       </entry>
       <entry name="fullscreen" value="2" summary="the surface is fullscreen">
-    <description summary="the surface is fullscreen">
-      The surface is fullscreen. The window geometry specified in the configure
-      event must be obeyed by the client.
-    </description>
+	<description summary="the surface is fullscreen">
+	  The surface is fullscreen. The window geometry specified in the
+	  configure event is a maximum; the client cannot resize beyond it. For
+	  a surface to cover the whole fullscreened area, the geometry
+	  dimensions must be obeyed by the client. For more details, see
+	  xdg_toplevel.set_fullscreen.
+	</description>
       </entry>
       <entry name="resizing" value="3" summary="the surface is being resized">
-    <description summary="the surface is being resized">
-      The surface is being resized. The window geometry specified in the
-      configure event is a maximum; the client cannot resize beyond it.
-      Clients that have aspect ratio or cell sizing configuration can use
-      a smaller size, however.
-    </description>
+	<description summary="the surface is being resized">
+	  The surface is being resized. The window geometry specified in the
+	  configure event is a maximum; the client cannot resize beyond it.
+	  Clients that have aspect ratio or cell sizing configuration can use
+	  a smaller size, however.
+	</description>
       </entry>
       <entry name="activated" value="4" summary="the surface is now activated">
-    <description summary="the surface is now activated">
-      Client window decorations should be painted as if the window is
-      active. Do not assume this means that the window actually has
-      keyboard or pointer focus.
-    </description>
+	<description summary="the surface is now activated">
+	  Client window decorations should be painted as if the window is
+	  active. Do not assume this means that the window actually has
+	  keyboard or pointer focus.
+	</description>
       </entry>
     </enum>
 
-    <event name="configure">
-      <description summary="suggest a surface change">
-    The configure event asks the client to resize its surface or to
-    change its state.
+    <request name="set_max_size">
+      <description summary="set the maximum size">
+	Set a maximum size for the window.
 
-    The width and height arguments specify a hint to the window
-    about how its surface should be resized in window geometry
-    coordinates. See set_window_geometry.
+	The client can specify a maximum size so that the compositor does
+	not try to configure the window beyond this size.
 
-    If the width or height arguments are zero, it means the client
-    should decide its own window dimension. This may happen when the
-    compositor need to configure the state of the surface but doesn't
-    have any information about any previous or expected dimension.
+	The width and height arguments are in window geometry coordinates.
+	See xdg_surface.set_window_geometry.
 
-    The states listed in the event specify how the width/height
-    arguments should be interpreted, and possibly how it should be
-    drawn.
+	Values set in this way are double-buffered. They will get applied
+	on the next commit.
 
-    Clients should arrange their surface for the new size and
-    states, and then send a ack_configure request with the serial
-    sent in this configure event at some point before committing
-    the new surface.
+	The compositor can use this information to allow or disallow
+	different states like maximize or fullscreen and draw accurate
+	animations.
 
-    If the client receives multiple configure events before it
-        can respond to one, it is free to discard all but the last
-        event it received.
-      </description>
+	Similarly, a tiling window manager may use this information to
+	place and resize client windows in a more effective way.
 
-      <arg name="width" type="int"/>
-      <arg name="height" type="int"/>
-      <arg name="states" type="array"/>
-      <arg name="serial" type="uint"/>
-    </event>
-
-    <request name="ack_configure">
-      <description summary="ack a configure event">
-        When a configure event is received, if a client commits the
-        surface in response to the configure event, then the client
-        must make an ack_configure request sometime before the commit
-        request, passing along the serial of the configure event.
+	The client should not rely on the compositor to obey the maximum
+	size. The compositor may decide to ignore the values set by the
+	client and request a larger size.
 
-        For instance, the compositor might use this information to move
-        a surface to the top left only when the client has drawn itself
-        for the maximized or fullscreen state.
+	If never set, or a value of zero in the request, means that the
+	client has no expected maximum size in the given dimension.
+	As a result, a client wishing to reset the maximum size
+	to an unspecified state can use zero for width and height in the
+	request.
 
-        If the client receives multiple configure events before it
-        can respond to one, it only has to ack the last configure event.
+	Requesting a maximum size to be smaller than the minimum size of
+	a surface is illegal and will result in a protocol error.
 
-        A client is not required to commit immediately after sending
-        an ack_configure request - it may even ack_configure several times
-        before its next surface commit.
-
-        The compositor expects that the most recently received
-        ack_configure request at the time of a commit indicates which
-        configure event the client is responding to.
+	The width and height must be greater than or equal to zero. Using
+	strictly negative values for width and height will result in a
+	protocol error.
       </description>
-      <arg name="serial" type="uint" summary="the serial from the configure event"/>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
     </request>
 
-    <request name="set_window_geometry">
-      <description summary="set the new window geometry">
-        The window geometry of a window is its "visible bounds" from the
-        user's perspective. Client-side decorations often have invisible
-        portions like drop-shadows which should be ignored for the
-        purposes of aligning, placing and constraining windows.
+    <request name="set_min_size">
+      <description summary="set the minimum size">
+	Set a minimum size for the window.
 
-        The window geometry is double buffered, and will be applied at the
-        time wl_surface.commit of the corresponding wl_surface is called.
+	The client can specify a minimum size so that the compositor does
+	not try to configure the window below this size.
 
-        Once the window geometry of the surface is set once, it is not
-        possible to unset it, and it will remain the same until
-        set_window_geometry is called again, even if a new subsurface or
-        buffer is attached.
+	The width and height arguments are in window geometry coordinates.
+	See xdg_surface.set_window_geometry.
 
-        If never set, the value is the full bounds of the surface,
-        including any subsurfaces. This updates dynamically on every
-        commit. This unset mode is meant for extremely simple clients.
+	Values set in this way are double-buffered. They will get applied
+	on the next commit.
 
-        If responding to a configure event, the window geometry in here
-        must respect the sizing negotiations specified by the states in
-        the configure event.
+	The compositor can use this information to allow or disallow
+	different states like maximize or fullscreen and draw accurate
+	animations.
 
-        The arguments are given in the surface local coordinate space of
-        the wl_surface associated with this xdg_surface.
+	Similarly, a tiling window manager may use this information to
+	place and resize client windows in a more effective way.
 
-        The width and height must be greater than zero.
+	The client should not rely on the compositor to obey the minimum
+	size. The compositor may decide to ignore the values set by the
+	client and request a smaller size.
+
+	If never set, or a value of zero in the request, means that the
+	client has no expected minimum size in the given dimension.
+	As a result, a client wishing to reset the minimum size
+	to an unspecified state can use zero for width and height in the
+	request.
+
+	Requesting a minimum size to be larger than the maximum size of
+	a surface is illegal and will result in a protocol error.
+
+	The width and height must be greater than or equal to zero. Using
+	strictly negative values for width and height will result in a
+	protocol error.
       </description>
-      <arg name="x" type="int"/>
-      <arg name="y" type="int"/>
       <arg name="width" type="int"/>
       <arg name="height" type="int"/>
     </request>
 
     <request name="set_maximized">
       <description summary="maximize the window">
-        Maximize the surface.
-
-        After requesting that the surface should be maximized, the compositor
-        will respond by emitting a configure event with the "maximized" state
-        and the required window geometry. The client should then update its
-        content, drawing it in a maximized state, i.e. without shadow or other
-        decoration outside of the window geometry. The client must also
-        acknowledge the configure when committing the new content (see
-        ack_configure).
-
-        It is up to the compositor to decide how and where to maximize the
-        surface, for example which output and what region of the screen should
-        be used.
-
-        If the surface was already maximized, the compositor will still emit
-        a configure event with the "maximized" state.
+	Maximize the surface.
+
+	After requesting that the surface should be maximized, the compositor
+	will respond by emitting a configure event with the "maximized" state
+	and the required window geometry. The client should then update its
+	content, drawing it in a maximized state, i.e. without shadow or other
+	decoration outside of the window geometry. The client must also
+	acknowledge the configure when committing the new content (see
+	ack_configure).
+
+	It is up to the compositor to decide how and where to maximize the
+	surface, for example which output and what region of the screen should
+	be used.
+
+	If the surface was already maximized, the compositor will still emit
+	a configure event with the "maximized" state.
+
+	If the surface is in a fullscreen state, this request has no direct
+	effect. It will alter the state the surface is returned to when
+	unmaximized if not overridden by the compositor.
       </description>
     </request>
 
     <request name="unset_maximized">
       <description summary="unmaximize the window">
-        Unmaximize the surface.
-
-        After requesting that the surface should be unmaximized, the compositor
-        will respond by emitting a configure event without the "maximized"
-        state. If available, the compositor will include the window geometry
-        dimensions the window had prior to being maximized in the configure
-        request. The client must then update its content, drawing it in a
-        regular state, i.e. potentially with shadow, etc. The client must also
-        acknowledge the configure when committing the new content (see
-        ack_configure).
-
-        It is up to the compositor to position the surface after it was
-        unmaximized; usually the position the surface had before maximizing, if
-        applicable.
-
-        If the surface was already not maximized, the compositor will still
-        emit a configure event without the "maximized" state.
+	Unmaximize the surface.
+
+	After requesting that the surface should be unmaximized, the compositor
+	will respond by emitting a configure event without the "maximized"
+	state. If available, the compositor will include the window geometry
+	dimensions the window had prior to being maximized in the configure
+	event. The client must then update its content, drawing it in a
+	regular state, i.e. potentially with shadow, etc. The client must also
+	acknowledge the configure when committing the new content (see
+	ack_configure).
+
+	It is up to the compositor to position the surface after it was
+	unmaximized; usually the position the surface had before maximizing, if
+	applicable.
+
+	If the surface was already not maximized, the compositor will still
+	emit a configure event without the "maximized" state.
+
+	If the surface is in a fullscreen state, this request has no direct
+	effect. It will alter the state the surface is returned to when
+	unmaximized if not overridden by the compositor.
       </description>
     </request>
 
     <request name="set_fullscreen">
-      <description summary="set the window as fullscreen on a monitor">
-    Make the surface fullscreen.
+      <description summary="set the window as fullscreen on an output">
+	Make the surface fullscreen.
+
+	After requesting that the surface should be fullscreened, the
+	compositor will respond by emitting a configure event with the
+	"fullscreen" state and the fullscreen window geometry. The client must
+	also acknowledge the configure when committing the new content (see
+	ack_configure).
+
+	The output passed by the request indicates the client's preference as
+	to which display it should be set fullscreen on. If this value is NULL,
+	it's up to the compositor to choose which display will be used to map
+	this surface.
+
+	If the surface doesn't cover the whole output, the compositor will
+	position the surface in the center of the output and compensate with
+	with border fill covering the rest of the output. The content of the
+	border fill is undefined, but should be assumed to be in some way that
+	attempts to blend into the surrounding area (e.g. solid black).
+
+	If the fullscreened surface is not opaque, the compositor must make
+	sure that other screen content not part of the same surface tree (made
+	up of subsurfaces, popups or similarly coupled surfaces) are not
+	visible below the fullscreened surface.
+      </description>
+      <arg name="output" type="object" interface="wl_output" allow-null="true"/>
+    </request>
+
+    <request name="unset_fullscreen">
+      <description summary="unset the window as fullscreen">
+	Make the surface no longer fullscreen.
+
+	After requesting that the surface should be unfullscreened, the
+	compositor will respond by emitting a configure event without the
+	"fullscreen" state.
 
-        You can specify an output that you would prefer to be fullscreen.
-    If this value is NULL, it's up to the compositor to choose which
-        display will be used to map this surface.
+	Making a surface unfullscreen sets states for the surface based on the following:
+	* the state(s) it may have had before becoming fullscreen
+	* any state(s) decided by the compositor
+	* any state(s) requested by the client while the surface was fullscreen
 
-        If the surface doesn't cover the whole output, the compositor will
-        position the surface in the center of the output and compensate with
-        black borders filling the rest of the output.
+	The compositor may include the previous window geometry dimensions in
+	the configure event, if applicable.
+
+	The client must also acknowledge the configure when committing the new
+	content (see ack_configure).
       </description>
-      <arg name="output" type="object" interface="wl_output" allow-null="true"/>
     </request>
-    <request name="unset_fullscreen" />
 
     <request name="set_minimized">
       <description summary="set the window as minimized">
-    Request that the compositor minimize your surface. There is no
-    way to know if the surface is currently minimized, nor is there
-    any way to unset minimization on this surface.
-
-    If you are looking to throttle redrawing when minimized, please
-    instead use the wl_surface.frame event for this, as this will
-    also work with live previews on windows in Alt-Tab, Expose or
-    similar compositor features.
+	Request that the compositor minimize your surface. There is no
+	way to know if the surface is currently minimized, nor is there
+	any way to unset minimization on this surface.
+
+	If you are looking to throttle redrawing when minimized, please
+	instead use the wl_surface.frame event for this, as this will
+	also work with live previews on windows in Alt-Tab, Expose or
+	similar compositor features.
       </description>
     </request>
 
+    <event name="configure">
+      <description summary="suggest a surface change">
+	This configure event asks the client to resize its toplevel surface or
+	to change its state. The configured state should not be applied
+	immediately. See xdg_surface.configure for details.
+
+	The width and height arguments specify a hint to the window
+	about how its surface should be resized in window geometry
+	coordinates. See set_window_geometry.
+
+	If the width or height arguments are zero, it means the client
+	should decide its own window dimension. This may happen when the
+	compositor needs to configure the state of the surface but doesn't
+	have any information about any previous or expected dimension.
+
+	The states listed in the event specify how the width/height
+	arguments should be interpreted, and possibly how it should be
+	drawn.
+
+	Clients must send an ack_configure in response to this event. See
+	xdg_surface.configure and xdg_surface.ack_configure for details.
+      </description>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+      <arg name="states" type="array"/>
+    </event>
+
     <event name="close">
       <description summary="surface wants to be closed">
-        The close event is sent by the compositor when the user
-        wants the surface to be closed. This should be equivalent to
-        the user clicking the close button in client-side decorations,
-        if your application has any...
-
-        This is only a request that the user intends to close your
-        window. The client may choose to ignore this request, or show
-        a dialog to ask the user to save their data...
+	The close event is sent by the compositor when the user
+	wants the surface to be closed. This should be equivalent to
+	the user clicking the close button in client-side decorations,
+	if your application has any.
+
+	This is only a request that the user intends to close the
+	window. The client may choose to ignore this request, or show
+	a dialog to ask the user to save their data, etc.
       </description>
     </event>
   </interface>
 
   <interface name="xdg_popup" version="1">
     <description summary="short-lived, popup surfaces for menus">
-      A popup surface is a short-lived, temporary surface that can be
-      used to implement menus. It takes an explicit grab on the surface
-      that will be dismissed when the user dismisses the popup. This can
-      be done by the user clicking outside the surface, using the keyboard,
-      or even locking the screen through closing the lid or a timeout.
-
-      When the popup is dismissed, a popup_done event will be sent out,
-      and at the same time the surface will be unmapped. The xdg_popup
-      object is now inert and cannot be reactivated, so clients should
-      destroy it. Explicitly destroying the xdg_popup object will also
-      dismiss the popup and unmap the surface.
-
-      Clients will receive events for all their surfaces during this
-      grab (which is an "owner-events" grab in X11 parlance). This is
-      done so that users can navigate through submenus and other
-      "nested" popup windows without having to dismiss the topmost
-      popup.
-
-      Clients that want to dismiss the popup when another surface of
-      their own is clicked should dismiss the popup using the destroy
-      request.
+      A popup surface is a short-lived, temporary surface. It can be used to
+      implement for example menus, popovers, tooltips and other similar user
+      interface concepts.
 
-      The parent surface must have either an xdg_surface or xdg_popup
-      role.
+      A popup can be made to take an explicit grab. See xdg_popup.grab for
+      details.
 
-      Specifying an xdg_popup for the parent means that the popups are
-      nested, with this popup now being the topmost popup. Nested
-      popups must be destroyed in the reverse order they were created
-      in, e.g. the only popup you are allowed to destroy at all times
-      is the topmost one.
+      When the popup is dismissed, a popup_done event will be sent out, and at
+      the same time the surface will be unmapped. See the xdg_popup.popup_done
+      event for details.
 
-      If there is an existing popup when creating a new popup, the
-      parent must be the current topmost popup.
+      Explicitly destroying the xdg_popup object will also dismiss the popup and
+      unmap the surface. Clients that want to dismiss the popup when another
+      surface of their own is clicked should dismiss the popup using the destroy
+      request.
+
+      The parent surface must have either the xdg_toplevel or xdg_popup surface
+      role.
 
-      A parent surface must be mapped before the new popup is mapped.
+      A newly created xdg_popup will be stacked on top of all previously created
+      xdg_popup surfaces associated with the same xdg_toplevel.
 
-      When compositors choose to dismiss a popup, they will likely
-      dismiss every nested popup as well. When a compositor dismisses
-      popups, it will follow the same dismissing order as required
-      from the client.
+      The parent of an xdg_popup must be mapped (see the xdg_surface
+      description) before the xdg_popup itself.
 
       The x and y arguments passed when creating the popup object specify
       where the top left of the popup should be placed, relative to the
       local surface coordinates of the parent surface. See
-      xdg_shell.get_xdg_popup.
+      xdg_surface.get_popup. An xdg_popup must intersect with or be at least
+      partially adjacent to its parent surface.
 
       The client must call wl_surface.commit on the corresponding wl_surface
       for the xdg_popup state to take effect.
-
-      For a surface to be mapped by the compositor the client must have
-      committed both the xdg_popup state and a buffer.
     </description>
 
+    <enum name="error">
+      <entry name="invalid_grab" value="0"
+	     summary="tried to grab after being mapped"/>
+    </enum>
+
     <request name="destroy" type="destructor">
       <description summary="remove xdg_popup interface">
-    This destroys the popup. Explicitly destroying the xdg_popup
-    object will also dismiss the popup, and unmap the surface.
+	This destroys the popup. Explicitly destroying the xdg_popup
+	object will also dismiss the popup, and unmap the surface.
+
+	If this xdg_popup is not the "topmost" popup, a protocol error
+	will be sent.
+      </description>
+    </request>
 
-    If this xdg_popup is not the "topmost" popup, a protocol error
-    will be sent.
+    <request name="grab">
+      <description summary="make the popup take an explicit grab">
+	This request makes the created popup take an explicit grab. An explicit
+	grab will be dismissed when the user dismisses the popup, or when the
+	client destroys the xdg_popup. This can be done by the user clicking
+	outside the surface, using the keyboard, or even locking the screen
+	through closing the lid or a timeout.
+
+	If the compositor denies the grab, the popup will be immediately
+	dismissed.
+
+	This request must be used in response to some sort of user action like a
+	button press, key press, or touch down event. The serial number of the
+	event should be passed as 'serial'.
+
+	The parent of a grabbing popup must either be an xdg_toplevel surface or
+	another xdg_popup with an explicit grab. If the parent is another
+	xdg_popup it means that the popups are nested, with this popup now being
+	the topmost popup.
+
+	Nested popups must be destroyed in the reverse order they were created
+	in, e.g. the only popup you are allowed to destroy at all times is the
+	topmost one.
+
+	When compositors choose to dismiss a popup, they may dismiss every
+	nested grabbing popup as well. When a compositor dismisses popups, it
+	will follow the same dismissing order as required from the client.
+
+	The parent of a grabbing popup must either be another xdg_popup with an
+	active explicit grab, or an xdg_popup or xdg_toplevel, if there are no
+	explicit grabs already taken.
+
+	If the topmost grabbing popup is destroyed, the grab will be returned to
+	the parent of the popup, if that parent previously had an explicit grab.
+
+	If the parent is a grabbing popup which has already been dismissed, this
+	popup will be immediately dismissed. If the parent is a popup that did
+	not take an explicit grab, an error will be raised.
+
+	During a popup grab, the client owning the grab will receive pointer
+	and touch events for all their surfaces as normal (similar to an
+	"owner-events" grab in X11 parlance), while the top most grabbing popup
+	will always have keyboard focus.
       </description>
+      <arg name="seat" type="object" interface="wl_seat"
+	   summary="the wl_seat of the user event"/>
+      <arg name="serial" type="uint" summary="the serial of the user event"/>
     </request>
 
+    <event name="configure">
+      <description summary="configure the popup surface">
+	This event asks the popup surface to configure itself given the
+	configuration. The configured state should not be applied immediately.
+	See xdg_surface.configure for details.
+
+	The x and y arguments represent the position the popup was placed at
+	given the xdg_positioner rule, relative to the upper left corner of the
+	window geometry of the parent surface.
+      </description>
+      <arg name="x" type="int"
+	   summary="x position relative to parent surface window geometry"/>
+      <arg name="y" type="int"
+	   summary="y position relative to parent surface window geometry"/>
+      <arg name="width" type="int" summary="window geometry width"/>
+      <arg name="height" type="int" summary="window geometry height"/>
+    </event>
+
     <event name="popup_done">
       <description summary="popup interaction is done">
-    The popup_done event is sent out when a popup is dismissed by the
-    compositor. The client should destroy the xdg_popup object at this
-    point.
+	The popup_done event is sent out when a popup is dismissed by the
+	compositor. The client should destroy the xdg_popup object at this
+	point.
       </description>
     </event>