[PATCH weston 5/6] xdg-shell: Rewrite documentation

[Bill Spitzak]

On 11/22/2014 12:28 PM, Jasper St. Pierre wrote:

>     <interface name="xdg_shell" version="1">

> +      xdg_shell allows clients to turn a wl_surface into a "real window"
> +      which can be dragged, resized, stacked, and moved around by the
> +      user. Everything about this interface is suited towards traditional
> +      desktop environments.

I think this information should be moved to xdg_surface, which is much 
more the object the user is going to be thinking about. xdg_shell is 
just the factory used to create xdg_surface objects.

> +      Destroying a bound xdg_shell object while there are surfaces
> +      still alive with roles from this interface is illegal and will
> +      result in a protocol error. Make sure to destroy all surfaces
> +      before destroying this object.

There does not appear to be a way to destroy a xdg_shell, actually.

> +      <description summary="set the parent of this surface">
> +	Set the "parent" of this surface. This window should be stacked
> +	above a parent. The parent surface must be mapped as long as this
> +	surface is mapped.
> +
> +	Parent windows should be set on dialogs, toolboxes, or other
> +	"auxilliary" surfaces, so that the parent is raised when the dialog
> +	is raised.

I think (or I hope) you mean "the child will be raised when the parent 
is raised"). You certainly should be able to raise the dialog without 
raising the parent, otherwise you have something identical to a subsurface.