On Wed, Jan 06, 2016 at 09:50:36PM -0500, Lyude wrote: > Signed-off-by: Lyude <cp...@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 <cp...@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@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/wayland-devel > _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
