[PATCH] protocol: Add a request and event to identify the visible area for a surface

[Kristian Høgsberg]

On Mon, Jan 28, 2013 at 05:18:34PM +0000, Rob Bradford wrote:
> 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.

This looks good.  The separate result object makes it pretty simple
and allows for sending off a bunch of queries and get a bunch of
replies using only one ruondtrip.

I think we should document the self-destructing nature of the results
object though.  I know that wl_callback (only other object with this
behavior) isn't documented like that, but we should do that for new
interfaces.

Kristian

> ---
>  protocol/wayland.xml | 36 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 36 insertions(+)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 0ce68ef..a12cbbc 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -729,6 +729,42 @@
>  	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.
> +      </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.0.2
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel