[PATCH wayland v3] protocol: define the concept of wl_surface role

[Jasper St. Pierre]

On Wed, Aug 20, 2014 at 7:09 AM, Pekka Paalanen <ppaalanen at gmail.com> wrote:

> From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
>
> Define what a role is, and what restrictions there are.
>
> A change to existing behaviour is that a role cannot be changed at all
> once set. However, this is unlikely to cause problems, as there is no
> reason to re-use wl_surfaces in clients.
>
> v2: give more concrete examples of roles, define losing a role, Jasper
> rewrote the paragraph on how a role is set.
>
> v3: make role permanent, there is no such thing as "losing a role".
> Re-issuing the same role again must be allowed for wl_pointer.set_cursor
> et al. to work.
>
> Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> ---
>  protocol/wayland.xml | 27 +++++++++++++++++++++++++--
>  1 file changed, 25 insertions(+), 2 deletions(-)
>
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 2d57f69..7b05338 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -973,8 +973,31 @@
>        local coordinates of the pixel content, in case a buffer_transform
>        or a buffer_scale is used.
>
> -      Surfaces are also used for some special purposes, e.g. as
> -      cursor images for pointers, drag icons, etc.
> +      A surface without a "role" is fairly useless, a compositor does
> +      not know where, when or how to present it. The role is the
> +      purpose of a wl_surface. Examples of roles are a cursor for a
> +      pointer (as set by wl_pointer.set_cursor), a drag icon
> +      (wl_data_device.start_drag), a sub-surface
> +      (wl_subcompositor.get_subsurface), and a window as defined by a
> +      shell protocol (e.g. wl_shell.get_shell_surface).
> +
> +      A surface can have only one role at a time. Initially a
> +      wl_surface does not have a role. Once a wl_surface is given a
> +      role, it is set permanently for the whole lifetime of the
> +      wl_surface object. Giving the current role again is allowed,
> +      unless explicitly forbidden by the relevant interface
> +      specification.
> +
> +      Surface roles are given by requests in other interfaces such as
> +      wl_pointer.set_cursor. The request should explicitly mention
> +      that this request gives a role to a wl_surface. Often, this
> +      request also creates a new protocol object that represents the
> +      role and adds additional functionality to wl_surface. When a
> +      client wants to destroy a wl_surface, they must destroy this 'role
> +      object' before the wl_surface.
> +
> +      Destroying the role object does not remove the role from the
> +      wl_surface, but it may stop the wl_surface from playing the role.
>

This is an odd expression to use. I'd put it in quotes, and give a few
examples.

Destroying the role object does not remove the role from the wl_surface,
but it may stop the wl_surface from "playing the role". For instance,
destroying the wl_subsurface object will hide the subsurface, but the
object will still have the subsurface role. To re-show the subsurface, a
new wl_subsurface object may be created on the same wl_surface.


>      </description>
>
>      <enum name="error">
> --
> 1.8.5.5
>
>


-- 
  Jasper
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20140820/0174eb65/attachment.html>