[RFC wayland-protocols v4] Add Primary Selection Protocol Version 1

[Bryce Harrington]

On Sat, Feb 20, 2016 at 01:31:59AM +0100, Carlos Garnacho wrote:
> From: Lyude <cpaul at redhat.com>
> 
> This primary selection is similar in spirit to the eponimous
> in X11, allowing a quick "select text + middle click" shortcut
> to copying and pasting.
> 
> It's otherwise very similar to it wayland counterpart, and
> explicitly made consistent with it.
> 
> Signed-off-by: Lyude <cpaul at redhat.com>
> Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
> ---
> After having talked with Lyude, I'll be trying to move this ahead.

I'm glad to see this work continuing and hope we'll see a v5 soon?

> Changes since v3:
> - Added a rather verbose protocol description, including a
>   high-level overview of the workings.
> - Made event emission 1:1 with wayland core protocol selections,
>   wp_primary_selection_offer.offer events are now expected to be
>   emitted between wp_primary_data_device.data_offer and 
>   wp_primary_data_device.selection
> - Improved wording here and there.
> - Added serial argument to wp_primary_data_offer.receive that can be
>   used to match against recent events.
> 
> 
>  Makefile.am                                        |   1 +
>  unstable/primary-selection/README                  |   4 +
>  .../primary-selection-unstable-v1.xml              | 229 +++++++++++++++++++++
>  3 files changed, 234 insertions(+)
>  create mode 100644 unstable/primary-selection/README
>  create mode 100644 unstable/primary-selection/primary-selection-unstable-v1.xml
>
> diff --git a/Makefile.am b/Makefile.am
> index 57d0023..eefa20f 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -7,6 +7,7 @@ unstable_protocols =								\
>  	unstable/xdg-shell/xdg-shell-unstable-v5.xml				\
>  	unstable/relative-pointer/relative-pointer-unstable-v1.xml		\
>  	unstable/pointer-constraints/pointer-constraints-unstable-v1.xml	\
> +	unstable/primary-selection/primary-selection-unstable-v1.xml		\
>  	$(NULL)
>  
>  stable_protocols =								\
> diff --git a/unstable/primary-selection/README b/unstable/primary-selection/README
> new file mode 100644
> index 0000000..6d8c0c6
> --- /dev/null
> +++ b/unstable/primary-selection/README
> @@ -0,0 +1,4 @@
> +Primary selection protocol
> +
> +Maintainers:
> +Lyude <cpaul at redhat.com>
> diff --git a/unstable/primary-selection/primary-selection-unstable-v1.xml b/unstable/primary-selection/primary-selection-unstable-v1.xml
> new file mode 100644
> index 0000000..a3618d5
> --- /dev/null
> +++ b/unstable/primary-selection/primary-selection-unstable-v1.xml
> @@ -0,0 +1,229 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="primary_selection_unstable_v1">
> +  <copyright>
> +    Copyright © 2015 Red Hat
> +
> +    Permission is hereby granted, free of charge, to any person obtaining a
> +    copy of this software and associated documentation files (the "Software"),
> +    to deal in the Software without restriction, including without limitation
> +    the rights to use, copy, modify, merge, publish, distribute, sublicense,
> +    and/or sell copies of the Software, and to permit persons to whom the
> +    Software is furnished to do so, subject to the following conditions:
> +
> +    The above copyright notice and this permission notice (including the next
> +    paragraph) shall be included in all copies or substantial portions of the
> +    Software.
> +
> +    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> +    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> +    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
> +    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> +    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
> +    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
> +    DEALINGS IN THE SOFTWARE.
> +  </copyright>


I want to give just a few general comments on the overall text, and a
couple more tangible suggestions below.

I'm glad to see this is being developed in a generalized fashion that
doesn't specify what input operations are used.  For example, on my
laptop there isn't a 'middle mouse button' and synthesizing it by L+R
clicks is cumbersome, so I configure primary selection paste to occur
with a keyboard combo.  It looks like nothing in this protocol would
prohibit that, and compositors make the input operations easily
customizable.

This protocol references the X protocol in a number of places.  Thinking
to the future, I wonder if perhaps our future readers will be a lot less
familiar with X (assuming we're successful here), so perhaps some of
these references could be minimalized.  E.g. imagine the reader is an
Android or iPhone developer unfamiliar with X intricacies.

That said, if you do want to reference the X protocol, it would be
useful to highlight where this protocol behaves differently than X.
(That is, if it does differ... I'm not familiar enough with X selection
internals to say.)

I think in many places where the word 'should' is used, these could be
tightened up with a 'must' to make the requirement more definitive.
In specifications 'should' can sometimes be interpreted as meaning "may
or may not", which I'm guessing is not correct in some of these cases.

I'd also like to see a clearer distinction between the parts of the
protocol dealing with outgoing versus incoming data.  I had to read this
through a couple times to understand that 'device' deals with the
outgoing data being offered by the client, and 'offers' deal with
incoming data provided by other clients.  I think this could be made
clearer.

> +  <description summary="Primary selection protocol">
> +    This protocol provides the ability to have a primary selection device to
> +    match that of the X server. This primary selection is a shortcut to the
> +    common clipboard selection, where text just needs to be selected in order
> +    to allow copying it elsewhere. The de facto way to perform this action
> +    is the middle mouse button, although it is not limited to this one.

Hardly anyone seems to agree with me, but I typically like to see a
definition of the relevant jargon that the protocol introduces somewhere
around the top of the protocol file such as here.

In this case, an explanation of what 'primary selection' means would be
helpful.  You've mostly got it suggested in this first paragraph, but
perhaps you could say something explicit like, "'Primary selection' is a
copy action that occurs directly by highlighting selected text or
objects with the pointer.  This differs from 'Clipboard selection' which
typically requires some menu or key invocation to copy to the
clipboard."  Or something like that.

> +    Clients wishing to honor primary selection should create a primary
> +    selection source and set it as the selection through
> +    wp_primary_selection_device.set_selection whenever the text selection
> +    changes. In order to minimize calls in pointer-driven text selection,
> +    it should happen only once after the operation finished. Similarly,
> +    a NULL source should be set when text is unselected.
> +
> +    wp_primary_selection_offer objects are first announced through the
> +    wp_primary_selection_device.data_offer event. Immediately after this event,
> +    the primary data offer will emit wp_primary_selection_offer.offer events
> +    to let know of the mime types being offered.
> +
> +    When the primary selection changes, the client with the keyboard focus
> +    will receive wp_primary_selection_device.selection events. Only the client
> +    with the keyboard focus will receive such events with a non-NULL
> +    wp_primary_selection_offer. Across keyboard focus changes, previously
> +    focused clients will receive wp_primary_selection_device.events with a
> +    NULL wp_primary_selection_offer.
> +
> +    In order to request the primary selection data, the client must pass
> +    a recent serial pertaining to the press event that is triggering the
> +    operation, if the compositor deems the serial valid and recent, the
> +    wp_primary_selection_source.send event will happen in the other end
> +    to let the transfer begin. The client owning the primary selection
> +    should write the requested data, and close the file descriptor
> +    immediately.
> +
> +    If the primary selection owner client disappeared during the transfer,
> +    the client reading the data will receive a
> +    wp_primary_selection_device.selection event with a NULL
> +    wp_primary_selection_offer, the client should take this as a hint
> +    to finish the reads related to the no longer existing offer.
> +
> +    The primary selection owner should be checking for errors during
> +    writes, merely cancelling the ongoing transfer if any happened.
> +  </description>

> +  <interface name="zwp_primary_selection_device_manager_v1" version="1">
> +    <description summary="X primary selection emulation">
> +      The primary selection device manager is the base interface of primary
> +      selection, it allows to create wp_primary_selection_source objects, as
> +      well as retrieving the per-seat wp_primary_selection_device objects.
> +    </description>
> +
> +    <request name="create_source">
> +      <description summary="create a new primary selection source">
> +	Create a new primary selection source.
> +      </description>
> +      <arg name="id" type="new_id" interface="zwp_primary_selection_source_v1"/>
> +    </request>
> +
> +    <request name="get_device">
> +      <description summary="primary selection device manager">
> +	Singleton global object that manages the zwp_primary_selection_device_v1
> +	objects for each wl_seat.
> +      </description>
> +      <arg name="id" type="new_id" interface="zwp_primary_selection_device_v1"/>
> +      <arg name="seat" type="object" interface="wl_seat"/>
> +    </request>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the primary selection device manager">
> +	Destroy the primary selection device manager.
> +      </description>
> +    </request>
> +  </interface>

I mentioned above that it's a bit unclear about which parts are incoming
and outgoing.  This manager definition would be a good place to provide
kind of a high level overview of what the other three interfaces in this
protocol do and how they interrelate with each other.

> +  <interface name="zwp_primary_selection_device_v1" version="1">
> +    <request name="set_selection">
> +      <description summary="set the primary selection">
> +	Set the current contents of the primary selection buffer. This clears
> +	anything which was previously held in the primary selection buffer.
> +      </description>
> +      <arg name="source" type="object" interface="zwp_primary_selection_source_v1" allow-null="true"/>
> +    </request>
> +
> +    <event name="data_offer">
> +      <description summary="introduce a new wp_primary_selection_offer">
> +	Introduces a new wp_primary_selection_offer object that may be used
> +	to receive the current primary selection. Immediately following this
> +	event, the new wp_primary_selection_offer object will send
> +	wp_primary_selection_offer.offer events to describe the offered mime
> +	types.
> +      </description>
> +      <arg name="offer" type="new_id" interface="zwp_primary_selection_offer_v1"/>
> +    </event>
> +
> +    <event name="selection">
> +      <description summary="advertise a new primary selection">
> +	The wp_primary_selection_device.selection event is sent to notify the
> +	client of a new primary selection. This event is sent after the
> +	wp_primary_selection.data_offer event introducing this object, and after
> +	the offer has announced its mimetypes through
> +	wp_primary_selection_offer.offer.
> +
> +	The data_offer is valid until a new offer or NULL is received
> +	or until the client loses keyboard focus. The client must destroy the
> +	previous selection data_offer, if any, upon receiving this event.
> +      </description>
> +      <arg name="id" type="object" interface="zwp_primary_selection_offer_v1" allow-null="true"/>
> +    </event>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the primary selection device">
> +	Destroy the primary selection device.
> +      </description>
> +    </request>
> +  </interface>
> +
> +  <interface name="zwp_primary_selection_offer_v1" version="1">
> +    <description summary="offer to transfer primary selection contents">
> +      A wp_primary_selection_offer represents an offer to transfer the contents
> +      of the primary selection clipboard to the client. Similar to
> +      wl_data_offer, the offer also describes the different mime types that the
> +      data can be converted to and provides the mechanisms for transferring the
> +      data directly to the client.
> +    </description>
> +
> +    <request name="receive">
> +      <description summary="request that the data is transferred">
> +	To transfer the contents of the primary selection clipboard, the client
> +	issues this request and indicates the mime type that it wants to
> +	receive. The transfer happens through the passed file descriptor
> +	(typically created with the pipe system call). The source client writes
> +	the data in the mime type representation requested and then closes the
> +	file descriptor.
> +
> +	The receiving client reads from the read end of the pipe until EOF and
> +	closes its end, at which point the transfer is complete.
> +
> +	The given serial may be used by the compositor in order to determine
> +	whether the receive request will be honored or not. Clients should
> +	provide the button or key serial that is triggering the primary
> +	selection request. Compositors should ignore requests with serials
> +	that don't match any recent events, the file descriptor
> +	should be closed immediately in this case.
> +      </description>
> +      <arg name="mime_type" type="string"/>
> +      <arg name="fd" type="fd"/>
> +      <arg name="serial" type="uint" summary="serial of the press event"/>
> +    </request>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the primary selection offer">
> +	Destroy the primary selection offer.
> +      </description>
> +    </request>
> +
> +    <event name="offer">
> +      <description summary="advertise offered mime type">
> +	Sent immediately after creating announcing the wp_primary_selection_offer

"after creation, announcing the"

> +	through wp_primary_selection_device.data_offer. One event is sent per
> +	offered mime type.
> +      </description>
> +      <arg name="mime_type" type="string"/>
> +    </event>
> +  </interface>
> +
> +  <interface name="zwp_primary_selection_source_v1" version="1">
> +    <description summary="offer to replace the contents of the primary selection">
> +      The source side of a wp_primary_selection_offer, it provides a way to
> +      describe the offered data and respond to requests to transfer the
> +      requested contents of the primary selection clipboard.
> +    </description>
> +
> +    <request name="offer">
> +      <description summary="add an offered mime type">
> +	This request adds a mime type to the set of mime types advertised to
> +	targets. Can be called several times to offer multiple types.
> +      </description>
> +      <arg name="mime_type" type="string"/>
> +    </request>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the primary selection source">
> +	Destroy the primary selection source.
> +      </description>
> +    </request>
> +
> +    <event name="send">
> +      <description summary="send the primary selection contents">
> +	Request for the current primary selection contents from the client.
> +	Send the specified mime type over the passed file descriptor, then
> +	close it.
> +      </description>
> +      <arg name="mime_type" type="string"/>
> +      <arg name="fd" type="fd"/>
> +    </event>
> +
> +    <event name="cancelled">
> +      <description summary="request for primary selection contents was canceled">
> +	This primary selection source is no longer valid. The client should
> +	clean up and destroy this primary selection source.
> +      </description>
> +    </event>
> +  </interface>
> +</protocol>

I've also spotted some grammatical issues here and there, but figure
those can be left for a future round of review.  If you CC me I'll be
sure and provide some copyediting later on when the text is further
along in development.

Thanks again for carrying this work forward.

Bryce