From 29ddfdd0dfc6028082a944cc17f41cfc9537aa9b Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sat, 30 Mar 2013 01:11:47 -0400
Subject: [PATCH] docs: Add details about grabs

Mention implicit grabs, (lack of) explicit grabs, and popup
windows.
---
 doc/Wayland/en_US/Protocol.xml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
index a645409..61dc637 100644
--- a/doc/Wayland/en_US/Protocol.xml
+++ b/doc/Wayland/en_US/Protocol.xml
@@ -232,6 +232,14 @@
       focus. Seats are global objects. Pointer events are delivered
       in surface local coordinates.
     </para>
+    <para>
+      The compositor maintains an implicit grab when a button is
+      pressed, to ensure that the corresponding button release
+      event gets delivered to the same surface. But there is no way
+      for clients to take an explicit grab. Instead, surfaces can
+      be mapped as 'popup', which combines transient window semantics
+      with a pointer grab.
+    </para>
     <para>
       See <xref linkend="protocol-spec-interface-wl_seat"/> for the
       protocol description.