[RFC wayland-protocols V3] Add Primary Selection Protocol Version 1
Peter Hutterer
peter.hutterer at who-t.net
Thu Jan 7 16:30:04 PST 2016
On Wed, Jan 06, 2016 at 09:50:36PM -0500, Lyude wrote:
> Signed-off-by: Lyude <cpaul at redhat.com>
> ---
>
> Notes:
> Changes since V2
> * Bunch of grammatical/wording fixes from whot
> * Addition of wp_primary_selection_offer::end_offers, for marking the end of a
> list of mime type offers
> * selection_offers are no longer sent before an input event, and are sent at the
> first opportunity a client has to do a primary selection paste. This decision
> comes from a discussion with Jasper, where a couple of clients (such as emacs)
> were brought up that have their own bindings for primary selection pasting.
> Eventually I will probably work on adding some sort of paste_hint event to
> this so that the compositor can decide what keybinding triggers a primary
> selection paste, I agree with Jasper that it would be best to solve the issue
> of rebinding primary selection pastes after we have the basic protocol for
> primary selection worked out.
>
> Makefile.am | 1 +
> unstable/primary-selection/README | 4 +
> .../primary-selection-unstable-v1.xml | 176 +++++++++++++++++++++
> 3 files changed, 181 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..057ba38
> --- /dev/null
> +++ b/unstable/primary-selection/primary-selection-unstable-v1.xml
> @@ -0,0 +1,176 @@
> +<?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 device to match that of
"to match" means you try to be identical. "similar to" allows to have
differences.
> + the X server. This allows users to select bodies of text, and then paste
> + them in another buffer without having to do the initial copy.
> +
> + The primary selection device manager is also in charge of handling
> + client's requests to indicate that text has been selected, along with
> + handling clients access to selected text.
> + </description>
it'd be nice to have some prose describing the general interaction between
to clients on a high level to understand the order better. I did this for
the tablet protocol and most of the feedback was triggered by the prose, not
the details. and it helped me understand the protocol better too. I
recommend you add a paragraph that outlines the basic intendent event flow.
> +
> + <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>
As I pointed out in the other thread, it's not clear to me when to issue this
request. In response to a middle click action? or once on startup to keep it
around and wait for events?
http://lists.freedesktop.org/archives/wayland-devel/2016-January/026416.html
> +
> + <request name="destroy" type="destructor">
> + <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.
what does the term "clears" mean in this context? specifically, the
receiving client never deals with the selection_source object, so what
happens with a potential in-flight selection_offer when this is called by
the source client?
> + </description>
> + <arg name="source" type="object" interface="zwp_primary_selection_source_v1"/>
> + </request>
> +
> + <event name="selection_offer">
> + <description summary="introduce a new wp_primary_selection_offer">
> + Similar to wl_data_device::data_offer, this event introduces a new
fwiw, don't use the term "new" in specs, by the time the spec is stable it's
not going to be new anymore.
> + wp_primary_selection_offer object that may be used to receive the
> + current primary selection. Immediately folliwng this event, the new
typo: following
> + wp_primary_selection_offer object will send out
> + wp_primary_selection_offer::offer events to describe the mime types it
> + offers.
> + </description>
> + <arg name="offer" type="new_id" interface="zwp_primary_selection_offer_v1"/>
> + </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.
> + </description>
> + <arg name="mime_type" type="string"/>
> + <arg name="fd" type="fd"/>
> + </request>
what happens if the mime type doesn't match one of the offers? what happens
if a correct or invalid mime type is selected and the sending client is
already gone? these need to be spelled out.
also, there is no cancel event, so what happens if a source client does:
d = get_selection_device
s1 = create_selection_source
s1.offer
s1.offer
s1.offer_end
s2.create_selection_source
s2.offer
s2.offer
s2.offer_end
d1.set_selection(s1)
d1.set_selection(s2)
s1.destroy()
the second call should "clear" the first source, but a selection_offer
event will be in-flight for the first source. what happens there?
> +
> + <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 the wp_primary_selection_offer object.
> + One event per offered mime type.
.. and what does the mime type do? yes, I know this *should* be obvious,
but the less room there is to read between the lines the more likely the
specs will be implemented correctly. best add something like:
"The list of mime types is the list of acceptable arguments to the
as argument to the zwp_primary_selection_offer_v1.receive
request for this object."
> + </description>
> + <arg name="mime_type" type="string"/>
> + </event>
> +
> + <event name="end_offers">
> + <description summary="mark the end of the list of available mime types">
> + Sent after we've send offer events for all of the available mime types.
please don't use "we" in specifications. in the end specs always work
against you anyway, you don't want them as part of your team ;)
> + </description>
> + </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">
> + <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>
don't we need a offer_end ("offer_done" as jonas pointed out) here as well?
Or do we rely on the client to do this correctly?
> +
> + <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.
when does the object get destroyed? whenever the client wants? Immediately
after send?
> + </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">
how many l do we use for cancelled? :)
> + This primary selection source has been replaced by another primary
> + selection source. The client should clean up and destroy this primary
> + selection source.
in the second sentence, use the object name here rather than "primary
selection source", less ambiguity.
Cheers,
Peter
> + </description>
> + </event>
> + </interface>
> +</protocol>
> --
> 2.5.0
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
More information about the wayland-devel
mailing list