[PATCH v2 wayland 1/2] protocol: Add a request and event to identify the visible area for a surface

[Rob Bradford]

From: Rob Bradford <rob at linux.intel.com>

Add a probe_area request to the wl_shell_surface interface along with a
visible_area event to communicate the result of the probe.

The intention of this request and event is to allow the client to try and
refine the placement of popup windows that would otherwise be unusable.
---
 protocol/wayland.xml | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 0ce68ef..c4673e5 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -729,6 +729,46 @@
 	to the client owning the popup surface.
       </description>
     </event>
+
+    <request name="probe_area">
+      <description summary="query the compositor for visible area for a transient surface">
+        Asks the compositor what the visible area for a surface would be if it
+        was positioned with the proposed rectangle relative to the provided
+        surface. The visible_area event will be fired with the area that the
+        compositor would show. The client can then use this information to
+        reposition the surface as appropriate for its needs. The intention is
+        for this request to be used by clients looking to find the ideal
+        location for a popup window whilst still respecting the borders of the
+        output.
+
+        The object returned by this request will be destroyed by the
+        compositor after the area is returned and as such the client must not
+        attempt to use it after that point.
+      </description>
+      <arg name="x" type="int"/>
+      <arg name="y" type="int"/>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+      <arg name="result" type="new_id" interface="wl_probe_result"/>
+    </request>
+  </interface>
+
+  <interface name="wl_probe_result" version="1">
+    <event name="visible_area">
+      <description summary="the area that would be visible for a proposed transient surface">
+        This event is fired in response to the probe_area request on the
+        object returned for that request. It returns the visible area that
+        the surface would occupy when taking into consideration the
+        output's edges. If the width or height is zero this indicates that the
+        window would not be visible at all in that dimension. In that case the
+        x and y values represent the distance to the edge of the viewable
+        area.
+      </description>
+      <arg name="x" type="int"/>
+      <arg name="y" type="int"/>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+    </event>
   </interface>
 
   <interface name="wl_surface" version="2">
-- 
1.8.1