[RFC v2] Add Primary Selection Protocol Version 1
Lyude
cpaul at redhat.com
Tue Jan 5 07:28:22 PST 2016
On Mon, 2016-01-04 at 15:05 +1000, Peter Hutterer wrote:
> On Fri, Dec 18, 2015 at 12:03:46PM -0500, Lyude wrote:
> > Signed-off-by: Lyude <cpaul at redhat.com>
> > ---
> > Changes
> > * Add new interfaces to replace reuse of wl_data_(source|offer)
> > * Get rid of the selection changed event since we now have our own version
> > of wl_data_(source|offer), and clients can just assume destroyed events
> > indicate that their data in the primary clipboard has been replaced.
> > * Get rid of summary on arguments, I noticed most of the official wayland
> > protocol doesn't actually use these, and they were mostly redundant
> > anyway.
> > * s/selection_set/set_selection/
> > * Add destructor requests for all interfaces
> >
> > Makefile.am | 1 +
> > unstable/primary-selection/README | 4 +
> > .../primary-selection-unstable-v1.xml | 178
> > +++++++++++++++++++++
> > 3 files changed, 183 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 5926a41..582a49e 100644
> > --- a/Makefile.am
> > +++ b/Makefile.am
> > @@ -5,6 +5,7 @@ unstable_protocols =
> > \
> > unstable/text-input/text-input-unstable-v1.xml
> > \
> > unstable/input-method/input-method-unstable-v1.xml
> > \
> > unstable/xdg-shell/xdg-shell-unstable-v5.xml
> > \
> > + unstable/primary-selection/primary-selection-unstable-v1.xml
> > \
> > $(NULL)
> >
> > nobase_dist_pkgdata_DATA =
> > \
> > diff --git a/unstable/primary-selection/README b/unstable/primary-
> > selection/README
> > new file mode 100644
> > index 0000000..2dfce3d
> > --- /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..32a4660
> > --- /dev/null
> > +++ b/unstable/primary-selection/primary-selection-unstable-v1.xml
> > @@ -0,0 +1,178 @@
> > +<?xml version="1.0" encoding="UTF-8"?>
> > +
> > +<protocol name="primary_selection">
> > + <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>
> > +
> > + <interface name="zwp_primary_selection_device_manager_v1" version="1">
> > + <description summary="X primary selection emulation">
> > + Provides the ability to have a primary selection buffer to match that
> > of
>
> there's confusion with the "buffer" vs "device". you create a device, but
> then you read a buffer? why not create a buffer, or alternatively, why not
> read from the device?
>
> > + the X server. This allows users to select bodies of text, and then
> > paste
> > + them in another buffer without having to do the initial paste.
>
> s/paste/copy/, right?
>
> > +
> > + The primary buffer manager is in charge of handling client's requests
> > to
> > + indicate that text has been selection, along with handling client's
> > access
>
> "has been selected"
> "clients'"
>
>
> > + to selected text.
> > + </description>
> > +
> > + <request name="create_primary_selection_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_primary_selection_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">
> > + <description summary="destroy the primary selection device manager">
> > + Destroy the primary selection device manager.
> > + </description>
> > + </request>
> > + </interface>
> > +
> > + <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.
> > +
> > + This request can only be used while the window is focused.
>
> you need to define what "can only be used" means here. Most likely "has no
> effect unless", because the other option would be to send a protocol error
> and be prone to race conditions if the focus changes while the request is
> in-flight.
>
> And the issue with using "focused" as a term has been pointed out already,
> it's safer to make this a compositor-specific policy/behaviour that may or
> may not be tied to the window focus (which has separate touch, keyboard and
> pointer foci anyway). If a middle-click triggers a focus change, the
> compositor must arrange the events so that the order is wl_pointer.enter,
> selection stuff, wl_pointer.button to make sure the focus is correct.
>
> > + </description>
> > + <arg name="source" type="object"
> > interface="zwp_primary_selection_source_v1"/>
> > + </request>
> > +
> > + <event name="selection_offer">
> > + <description summary="primary selection buffer is ready for reading">
> > + Sent when the client has permission to read from the primary
> > selection
> > + buffer.
> > +
> > + This event is sent whenever the client receives a middle click, and
> > will
> > + be received by the client before the actual middle click event.
> > While
> > + the compositor is free to bind this event to another input event
> > (such
> > + as a keyboard shortcut), the client should always treat pastes from
> > the
>
> s/pastes/selection_offer events/
>
> > + primary selection as middle clicks. This is to ensure the behavior
> > is
> > + identical to that of primary selection pasting in X.
>
> Not a big fan of this, the intent is good but the wording needs improvement.
> Unless you somehow pair the event with a middle click, a client cannot know
> if the middle click triggered the paste or a keyboard shortcut, followed by
> a middle click. I would argue for wording that requires this event to be in
> the same wl_{pointer|touch|keyboard}.frame as the triggering event.
>
> Let's assume an application that binds middle click to full-screen, for
> argument's sake:
> "treat pastes from the primary selection as middle clicks."
> This would mean that if you receive a selection_offer event the client must
> full-screen the application because the event is to be treated like a
> middle click :)
>
> Suggested rewording:
> "This event is typically sent whenever the user executes a middle click
> though the compositor may bind this event to other user input sequences. If
> applicable, the selection_offer event is sent in the same wl_pointer.frame,
> wl_touch.frame or wl_keyboard.frame as the triggering event.
>
> To ensure identical behavior to primary selection pasting in X, a client
> should interpret a selection_offer event as paste event."
>
> > +
> > + It is up to the client to decide whether or not it is appropriate
> > to
> > + read from the primary buffer and paste it's contents.
>
> iirc "whether" means you can skip "or not", it's superfluous. Not going to
> fight over that though :)
>
> > + </description>
> > + <arg name="offer" type="new_id"
> > interface="zwp_primary_selection_offer_v1"/>
> > + </event>
> > +
> > + <request name="destroy">
> > + <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.
>
> "... and the selection offer should be destroyed."
>
> > + </description>
> > + <arg name="mime_type" type="string"/>
> > + <arg name="fd" type="fd"/>
> > + </request>
> > +
> > + <request name="destroy">
> > + <description summary="destroy the primary selection offer">
> > + Destroy the primary selection offer.
> > + </description>
> > + </request>
> > +
> > + <event name="offer">
>
> This needs a "mime"-related name, not an "offer", maybe
> "mime_type_available" or so. also, in the tablet interface we just added a
> "done" event, I think it's worth adding this to delineate the end of
> available mime-types.
>
> > + <description summary="advertise offered mime type">
> > + Sent immediately after creating the wp_primary_selection_offer
> > object.
> > + One event per offered mime type.
>
> s/offered/available/
>
> > + </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">
> > + Similar to the relationship between a wl_data_offer and a
> > wl_data_source
> > + object, the wp_primary_selection_source object is the source side of
> > + wp_primary_selection_offer, it provides a way to describe the offered
> > + data and respond to requests to transfer the new contents of the
> > primary
> > + selection clipboard.
> > + </description>
> > +
> > + <request name="offer">
>
> "add_mime_type" would be a lot more expressive.
>
> > + <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">
> > + <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 has been replaced by another primary
> > + selection source. The client should clean up and destroy this
> > primary
> > + selection source.
> > + </description>
> > + </event>
> > + </interface>
> > +</protocol>
>
> I'm missing something or I'm misunderstanding how this is supposed to work.
> When I highlight something, the source adds the mimetypes available. A middle
> click triggers the selection_offer event and the "offer" events on that
> object. the client calls "receive" which converts to the "send" event in the
> other client and data is exchanged over the fd.
>
> Two problems:
> * the source client has no way of finalising the list of mimetypes. What
> happens if a mimetype is added after the selection_offer event was sent to
> the receiving client?
> * what happens if the source client goes away between selection_offer and
> the receiving client's receive? does the protocol guarantee an empty fd*?
> I think you need a cancel event on the selection_offer object.
I agree with everything except for this last bit; I don't think we need to worry
about the client dying. If the receiving client dies during this midway point
and we don't handle it then the source client would just run into an error like
EBADFD or something along those lines, which is pretty self explanatory IMO.
>
> Cheers,
> Peter
>
> * it probably needs to do that anyway, even if we add events.
--
Cheers,
Lyude
More information about the wayland-devel
mailing list