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

[Pekka Paalanen]

Hi Rob,

nice to get back to this. :-)

On Thu, 18 Apr 2013 13:17:47 +0100
Rob Bradford <robert.bradford at intel.com> 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.
> ---
>  protocol/wayland.xml | 40 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 40 insertions(+)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index edb8a03..023067a 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -874,6 +874,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.

I think this paragraph belongs to the wl_probe_result, since
autodestruct is a property of wl_probe_result class, not this request.

> +      </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"/>

To which surface are these values relative to, the parent, or the
hypothetical popup?

"Distance to the edge" is a bit vague, I'm not sure how to use that
based on this description alone. Can you write a formula on what
coordinates to try next to make the area maximally visible?

If width and/or height is zero, is it always both x and y, or just the
corresponding x and/or y that is the distance?

Is there really a case where it makes sense to have either width or
height zero, but not both? This might be hard to define for rotated
surfaces, that is, what should the compositor return.

Maybe just remove "in that dimension" from the description, since it
confuses at least me?

> +    </event>
>    </interface>
>  
>    <interface name="wl_surface" version="2">

Thanks,
pq