Discussion:
[RFC wayland-protocols 1/1] Add Primary Selection Protocol Version 1
(too old to reply)
c***@redhat.com
2015-12-09 23:29:31 UTC
Permalink
From: Lyude <***@redhat.com>

Signed-off-by: Lyude <***@redhat.com>
---
Makefile.am | 1 +
unstable/primary-selection/README | 4 +
.../primary-selection-unstable-v1.xml | 87 ++++++++++++++++++++++
3 files changed, 92 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 <***@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..f63c675
--- /dev/null
+++ b/unstable/primary-selection/primary-selection-unstable-v1.xml
@@ -0,0 +1,87 @@
+<?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
+ 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.
+
+ 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
+ to selected text.
+ </description>
+
+ <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>
+ </interface>
+
+ <interface name="zwp_primary_selection_device_v1" version="1">
+ <request name="selection_set">
+ <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.
+ </description>
+ <arg name="source" type="object" interface="wl_data_source"
+ summary="The wl_data_source containing the data to set the contents of the primary selection buffer to"/>
+ </request>
+
+ <event name="selection_changed">
+ <description summary="another client changed the contents of the primary selection buffer">
+ Sent when another client has changed the contents of the primary
+ selection to a client that previously owned the contents of the primary
+ selection.
+ </description>
+ </event>
+
+ <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
+ primary selection as middle clicks. This is to ensure the behavior is
+ identical to that of primary selection pasting in X.
+
+ 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.
+ </description>
+ <arg name="offer" type="new_id" interface="wl_data_offer"
+ summary="The wl_data_offer containing the contents of the primary selection"/>
+ </event>
+ </interface>
+</protocol>
--
2.5.0
Giulio Camuffo
2015-12-11 09:04:07 UTC
Permalink
Post by c***@redhat.com
---
Makefile.am | 1 +
unstable/primary-selection/README | 4 +
.../primary-selection-unstable-v1.xml | 87 ++++++++++++++++++++++
3 files changed, 92 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
+
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..f63c675
--- /dev/null
+++ b/unstable/primary-selection/primary-selection-unstable-v1.xml
@@ -0,0 +1,87 @@
+<?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
+
+ 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
+ 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.
+
+ 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
+ to selected text.
+ </description>
+
+ <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>
+ </interface>
+
+ <interface name="zwp_primary_selection_device_v1" version="1">
+ <request name="selection_set">
set_selection sounds nicer to me than selection_set.
Post by c***@redhat.com
+ <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.
+ </description>
+ <arg name="source" type="object" interface="wl_data_source"
+ summary="The wl_data_source containing the data to set the contents of the primary selection buffer to"/>
+ </request>
+
+ <event name="selection_changed">
+ <description summary="another client changed the contents of the primary selection buffer">
+ Sent when another client has changed the contents of the primary
+ selection to a client that previously owned the contents of the primary
+ selection.
+ </description>
+ </event>
+
+ <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
+ primary selection as middle clicks. This is to ensure the behavior is
+ identical to that of primary selection pasting in X.
+
+ 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.
+ </description>
+ <arg name="offer" type="new_id" interface="wl_data_offer"
You cannot create new wl_data_offer objects here. Interfaces should
only have one factory interface, and wl_data_offer has
wl_data_something already, otherwise you cannot bump the interface
version anymore. You should create your wp_primary_offer interface or
something.

--
Giulio
Post by c***@redhat.com
+ summary="The wl_data_offer containing the contents of the primary selection"/>
+ </event>
+ </interface>
+</protocol>
--
2.5.0
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Pekka Paalanen
2015-12-14 07:59:39 UTC
Permalink
On Fri, 11 Dec 2015 11:04:07 +0200
Post by Giulio Camuffo
Post by c***@redhat.com
---
Makefile.am | 1 +
unstable/primary-selection/README | 4 +
.../primary-selection-unstable-v1.xml | 87 ++++++++++++++++++++++
3 files changed, 92 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
+
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..f63c675
--- /dev/null
+++ b/unstable/primary-selection/primary-selection-unstable-v1.xml
@@ -0,0 +1,87 @@
+<?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
+
+ 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
+ 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.
+
+ 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
+ to selected text.
+ </description>
+
+ <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>
+ </interface>
+
+ <interface name="zwp_primary_selection_device_v1" version="1">
+ <request name="selection_set">
set_selection sounds nicer to me than selection_set.
Post by c***@redhat.com
+ <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.
+ </description>
+ <arg name="source" type="object" interface="wl_data_source"
+ summary="The wl_data_source containing the data to set the contents of the primary selection buffer to"/>
+ </request>
+
+ <event name="selection_changed">
+ <description summary="another client changed the contents of the primary selection buffer">
+ Sent when another client has changed the contents of the primary
+ selection to a client that previously owned the contents of the primary
+ selection.
+ </description>
+ </event>
+
+ <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
+ primary selection as middle clicks. This is to ensure the behavior is
+ identical to that of primary selection pasting in X.
+
+ 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.
+ </description>
+ <arg name="offer" type="new_id" interface="wl_data_offer"
You cannot create new wl_data_offer objects here. Interfaces should
only have one factory interface, and wl_data_offer has
wl_data_something already, otherwise you cannot bump the interface
version anymore. You should create your wp_primary_offer interface or
something.
Also, it seems all interfaces are missing destructor protocol. For
guidance, see:
http://ppaalanen.blogspot.fi/2014/07/wayland-protocol-design-object-lifespan.html


Thanks,
pq
Lyude
2015-12-14 15:39:05 UTC
Permalink
I don't think you need the word "primary" in there. It can be called the
selection. The other thing this is confused with is called the "clipboard".
Glad to see you reusing the dnd protocol. X selection and middle-button paste
is really a form of DnD, but with the advantage that the user can rearrage and
open and close windows between when they start and finish the drag.
Alright I'm a bit confused here since I'm getting conflicting opinions on this.
Should we be reusing the dnd protocol or not? Giulio seems to think we shouldn't
be reusing the data offer objects here, but I would have thought that makes the
most sense here seeing as the functionality of a wp_primary_(offer|source) would
be pretty much identical to the wl_data_(offer|source) objects.
Post by c***@redhat.com
---
  Makefile.am                                        |  1 +
  unstable/primary-selection/README                  |  4 +
  .../primary-selection-unstable-v1.xml              | 87
++++++++++++++++++++++
  3 files changed, 92 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
+
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..f63c675
--- /dev/null
+++ b/unstable/primary-selection/primary-selection-unstable-v1.xml
@@ -0,0 +1,87 @@
+<?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
+
+    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
+      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.
+
+      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
+      to selected text.
+    </description>
+
+    <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>
+  </interface>
+
+  <interface name="zwp_primary_selection_device_v1" version="1">
+    <request name="selection_set">
set_selection sounds nicer to me than selection_set.
+      <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.
+      </description>
+      <arg name="source" type="object" interface="wl_data_source"
+        summary="The wl_data_source containing the data to set the
contents of the primary selection buffer to"/>
+    </request>
+
+    <event name="selection_changed">
+      <description summary="another client changed the contents of the
primary selection buffer">
+        Sent when another client has changed the contents of the primary
+        selection to a client that previously owned the contents of the
primary
+        selection.
+      </description>
+    </event>
+
+    <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
+        primary selection as middle clicks. This is to ensure the
behavior is
+        identical to that of primary selection pasting in X.
+
+        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.
+      </description>
+      <arg name="offer" type="new_id" interface="wl_data_offer"
You cannot create new wl_data_offer objects here. Interfaces should
only have one factory interface, and wl_data_offer has
wl_data_something already, otherwise you cannot bump the interface
version anymore. You should create your wp_primary_offer interface or
something.
--
Giulio
+        summary="The wl_data_offer containing the contents of the primary
selection"/>
+    </event>
+  </interface>
+</protocol>
--
2.5.0
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
--
Cheers,
Lyude
Pekka Paalanen
2015-12-14 17:13:28 UTC
Permalink
On Mon, 14 Dec 2015 10:39:05 -0500
Post by Lyude
I don't think you need the word "primary" in there. It can be called the
selection. The other thing this is confused with is called the "clipboard".
Glad to see you reusing the dnd protocol. X selection and middle-button paste
is really a form of DnD, but with the advantage that the user can rearrage and
open and close windows between when they start and finish the drag.
Alright I'm a bit confused here since I'm getting conflicting opinions on this.
Should we be reusing the dnd protocol or not? Giulio seems to think we shouldn't
be reusing the data offer objects here, but I would have thought that makes the
most sense here seeing as the functionality of a wp_primary_(offer|source) would
be pretty much identical to the wl_data_(offer|source) objects.
Giulio is right.

You must not break the versioning (hierarchy) of protocol objects.
See:
http://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Versioning

Having two different global interfaces that (or their child
interfaces, i.e. the interfaces of objects that can be created from
these) can create objects with the same interface will not allow
that interface to be extended, because the interface version becomes
ambiguous.

Examples of interfaces that are already impossible to extend are
wl_buffer and wl_callback. For wl_buffer there is a good reason to
break the rule and take the hit of being stuck at version 1
forever, but I think it was more of an accident than intentional
design originally.


Thanks,
pq
Pekka Paalanen
2015-12-14 20:34:32 UTC
Permalink
On Mon, 14 Dec 2015 10:45:25 -0800
Post by Pekka Paalanen
On Mon, 14 Dec 2015 10:39:05 -0500
Post by Lyude
I don't think you need the word "primary" in there. It can be called
the
Post by Lyude
selection. The other thing this is confused with is called the
"clipboard".
Post by Lyude
Glad to see you reusing the dnd protocol. X selection and
middle-button paste
Post by Lyude
is really a form of DnD, but with the advantage that the user can
rearrage and
Post by Lyude
open and close windows between when they start and finish the drag.
Alright I'm a bit confused here since I'm getting conflicting opinions
on this.
Post by Lyude
Should we be reusing the dnd protocol or not? Giulio seems to think we
shouldn't
Post by Lyude
be reusing the data offer objects here, but I would have thought that
makes the
Post by Lyude
most sense here seeing as the functionality of a
wp_primary_(offer|source) would
Post by Lyude
be pretty much identical to the wl_data_(offer|source) objects.
Giulio is right.
You must not break the versioning (hierarchy) of protocol objects.
http://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Versioning
Having two different global interfaces that (or their child
interfaces, i.e. the interfaces of objects that can be created from
these) can create objects with the same interface will not allow
that interface to be extended, because the interface version becomes
ambiguous.
Examples of interfaces that are already impossible to extend are
wl_buffer and wl_callback. For wl_buffer there is a good reason to
break the rule and take the hit of being stuck at version 1
forever, but I think it was more of an accident than intentional
design originally.
He is not creating the DnD objects with the new api, just reusing them.
<arg name="offer" type="new_id" interface="wl_data_offer"

So what do you think that does if not create objects of type
wl_data_offer?


Thanks,
pq
Lyude
2015-12-14 21:20:14 UTC
Permalink
Post by Pekka Paalanen
On Mon, 14 Dec 2015 10:39:05 -0500
Post by Lyude
I don't think you need the word "primary" in there. It can be called the
selection. The other thing this is confused with is called the
"clipboard".
Post by Lyude
Glad to see you reusing the dnd protocol. X selection and middle-button
paste
Post by Lyude
is really a form of DnD, but with the advantage that the user can
rearrage and
Post by Lyude
open and close windows between when they start and finish the drag.
Alright I'm a bit confused here since I'm getting conflicting opinions on
this.
Post by Lyude
Should we be reusing the dnd protocol or not? Giulio seems to think we
shouldn't
Post by Lyude
be reusing the data offer objects here, but I would have thought that
makes the
Post by Lyude
most sense here seeing as the functionality of a wp_primary_(offer|source)
would
Post by Lyude
be pretty much identical to the wl_data_(offer|source) objects.
Giulio is right.
You must not break the versioning (hierarchy) of protocol objects.
http://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Versioning
Having two different global interfaces that (or their child
interfaces, i.e. the interfaces of objects that can be created from
these) can create objects with the same interface will not allow
that interface to be extended, because the interface version becomes
ambiguous.
Examples of interfaces that are already impossible to extend are
wl_buffer and wl_callback. For wl_buffer there is a good reason to
break the rule and take the hit of being stuck at version 1
forever, but I think it was more of an accident than intentional
design originally.
He is not creating the DnD objects with the new api, just reusing them.
*She, not he please :)

Anyway, if that's the case I'll probably look into just creating an event that
has text from the primary selection as opposed to a wl_data_offer. This would
also get rid of the need to support non-text objects in this protocol anyway
(which X doesn't support to begin with, so that's no big deal).
 
--
Cheers,
Lyude
Pekka Paalanen
2015-12-15 07:06:24 UTC
Permalink
On Mon, 14 Dec 2015 16:20:14 -0500
Post by Lyude
Post by Pekka Paalanen
On Mon, 14 Dec 2015 10:39:05 -0500
Post by Lyude
I don't think you need the word "primary" in there. It can be called the
selection. The other thing this is confused with is called the
"clipboard".
Post by Lyude
Glad to see you reusing the dnd protocol. X selection and middle-button
paste
Post by Lyude
is really a form of DnD, but with the advantage that the user can
rearrage and
Post by Lyude
open and close windows between when they start and finish the drag.
Alright I'm a bit confused here since I'm getting conflicting opinions on
this.
Post by Lyude
Should we be reusing the dnd protocol or not? Giulio seems to think we
shouldn't
Post by Lyude
be reusing the data offer objects here, but I would have thought that
makes the
Post by Lyude
most sense here seeing as the functionality of a wp_primary_(offer|source)
would
Post by Lyude
be pretty much identical to the wl_data_(offer|source) objects.
Giulio is right.
You must not break the versioning (hierarchy) of protocol objects.
http://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Versioning
Having two different global interfaces that (or their child
interfaces, i.e. the interfaces of objects that can be created from
these) can create objects with the same interface will not allow
that interface to be extended, because the interface version becomes
ambiguous.
Examples of interfaces that are already impossible to extend are
wl_buffer and wl_callback. For wl_buffer there is a good reason to
break the rule and take the hit of being stuck at version 1
forever, but I think it was more of an accident than intentional
design originally.
He is not creating the DnD objects with the new api, just reusing them.
*She, not he please :)
Anyway, if that's the case I'll probably look into just creating an event that
has text from the primary selection as opposed to a wl_data_offer. This would
also get rid of the need to support non-text objects in this protocol anyway
(which X doesn't support to begin with, so that's no big deal).
That will put a size limit on the selection. A limit that users might
actually hit, since it's not too many pages. I forget the
implementation details in libwayland on what the limit actually is, but
it might be one page per message. I don't think we have documented the
limit anywhere, and you cannot deduce it from the wire format.

You might want to confirm what the limit is and if it's ok.


Thanks,
pq
Hans de Goede
2015-12-15 13:07:20 UTC
Permalink
Hi,
Post by Lyude
Post by Pekka Paalanen
On Mon, 14 Dec 2015 10:39:05 -0500
Post by Lyude
I don't think you need the word "primary" in there. It can be called the
selection. The other thing this is confused with is called the
"clipboard".
Post by Lyude
Glad to see you reusing the dnd protocol. X selection and middle-button
paste
Post by Lyude
is really a form of DnD, but with the advantage that the user can
rearrage and
Post by Lyude
open and close windows between when they start and finish the drag.
Alright I'm a bit confused here since I'm getting conflicting opinions on
this.
Post by Lyude
Should we be reusing the dnd protocol or not? Giulio seems to think we
shouldn't
Post by Lyude
be reusing the data offer objects here, but I would have thought that
makes the
Post by Lyude
most sense here seeing as the functionality of a wp_primary_(offer|source)
would
Post by Lyude
be pretty much identical to the wl_data_(offer|source) objects.
Giulio is right.
You must not break the versioning (hierarchy) of protocol objects.
http://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Versioning
Having two different global interfaces that (or their child
interfaces, i.e. the interfaces of objects that can be created from
these) can create objects with the same interface will not allow
that interface to be extended, because the interface version becomes
ambiguous.
Examples of interfaces that are already impossible to extend are
wl_buffer and wl_callback. For wl_buffer there is a good reason to
break the rule and take the hit of being stuck at version 1
forever, but I think it was more of an accident than intentional
design originally.
He is not creating the DnD objects with the new api, just reusing them.
*She, not he please :)
Anyway, if that's the case I'll probably look into just creating an event that
has text from the primary selection as opposed to a wl_data_offer. This would
also get rid of the need to support non-text objects in this protocol anyway
(which X doesn't support to begin with, so that's no big deal).
That "which X doesn't support to begin with" is not true. If you look
e.g. the clipboard code in the spice-vdagent:

http://cgit.freedesktop.org/spice/linux/vd_agent/tree/src/vdagent-x11.c#n883

(Just an example of code I happen to be familiar with) then you will see that
the handling of the primary selection and the clipboard selection is 100% identical
from a client clipboard pov. X has an (infinite) number of Selection buffers
of which in practice only the Primary and Clipboard ones are used, you can create
more if you want though :) And all these selection buffers work identical.

If you e.g. under X select a bit of text with a hyperlink in it in firefox and
then middle button paste it in libreoffice writer, the hyperlink comes along
with the text because libreoffice asks firefox in which forms the primary
selection is available by first doing a XConvertSelection with a target
of TARGETS, then sees html in the list of available formats and then
requests the _primary_ selection in html format.

Regards,

Hans
Lyude
2015-12-18 17:03:46 UTC
Permalink
Signed-off-by: Lyude <***@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 <***@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
+ 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.
+
+ 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
+ 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.
+ </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
+ primary selection as middle clicks. This is to ensure the behavior is
+ identical to that of primary selection pasting in X.
+
+ 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.
+ </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.
+ </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">
+ <description summary="advertise offered mime type">
+ Sent immediately after creating the wp_primary_selection_offer object.
+ One event 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">
+ 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>
+
+ <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>
--
2.5.0
Michal Suchanek
2015-12-18 20:17:47 UTC
Permalink
Post by c***@redhat.com
+ <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
+ primary selection as middle clicks. This is to ensure the behavior is
+ identical to that of primary selection pasting in X.
+
+ 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.
+ </description>
+ <arg name="offer" type="new_id" interface="zwp_primary_selection_offer_v1"/>
+ </event>
+
Why this?

Is this an artifact of cut&paste from DnD spec?

Drop is something initiated by dropping an object from the outside but
paste is something the application initiates by itself. The primary
selection is something that sits there all the time ready to be pasted
unlike dropped objects which appear and disappear momentarily.

It is customary in current desktop that paste happens on middle click
but that is something that is just configured in every toolkit
separately to work the same across whole desktop. The application
itself should decide if and on what event it tries to pull the primary
selection content. Note also that there are cut buffer managers that
just pull and store the primary buffer content every time it is set so
if X compatibility is desired setting the paste buffer should generate
an event.

Thanks

Michal
Lyude
2015-12-21 23:20:13 UTC
Permalink
Post by Michal Suchanek
+    <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
+        primary selection as middle clicks. This is to ensure the behavior
is
+        identical to that of primary selection pasting in X.
+
+        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.
+      </description>
+      <arg name="offer" type="new_id"
interface="zwp_primary_selection_offer_v1"/>
+    </event>
+
Why this?
Is this an artifact of cut&paste from DnD spec?
Drop is something initiated by dropping an object from the outside but
paste is something the application initiates by itself. The primary
selection is something that sits there all the time ready to be pasted
unlike dropped objects which appear and disappear momentarily.
It is customary in current desktop that paste happens on middle click
but that is something that is just configured in every toolkit
separately to work the same across whole desktop. The application
itself should decide if and on what event it tries to pull the primary
selection content. Note also that there are cut buffer managers that
just pull and store the primary buffer content every time it is set so
if X compatibility is desired setting the paste buffer should generate
an event.
The reason for this is that we want to be able to allow compositors to easily
bind primary selection pasting to more then just middle clicks, without having
to have some sort of global configuration. The idea is that you just send the
offer before the actual input event, and no matter what the actual input event
is the client can easily tell that it's meant to trigger a primary selection
paste and handle it appropriately.
Post by Michal Suchanek
Thanks
Michal
--
Cheers,
Lyude
Michael Catanzaro
2015-12-18 23:25:22 UTC
Permalink
+  <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
+      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.
"without having to do the initial copy"
Pekka Paalanen
2015-12-21 07:27:27 UTC
Permalink
On Fri, 18 Dec 2015 12:03:46 -0500
Post by Lyude
---
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
+
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
+
+ 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
+ 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.
+
+ 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
+ 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">
Hi

Missing type="destructor". I think you might be leaking client memory
and maybe even mess up the object id accounting when the server destroys
the wl_resource but the client didn't destroy the wl_proxy.

I wonder if wayland-scanner should actually detect this and warn,
because if there is no request called "destroy", it will generate a
*_destroy() function regardless which only destroys the proxy but will
not send any message. So having a request called "destroy" that does
not actually destroy the proxy would be quite confusing.
Post by Lyude
+ <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.
+ </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
+ primary selection as middle clicks. This is to ensure the behavior is
+ identical to that of primary selection pasting in X.
+
+ 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.
+ </description>
+ <arg name="offer" type="new_id" interface="zwp_primary_selection_offer_v1"/>
+ </event>
+
+ <request name="destroy">
And here.
Post by Lyude
+ <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>
+
+ <request name="destroy">
And here.
Post by Lyude
+ <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.
+ </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">
+ <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">
And here.
Post by Lyude
+ <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 didn't check anything else than destructors.


Thanks,
pq
Derek Foreman
2015-12-21 19:42:49 UTC
Permalink
Post by Pekka Paalanen
On Fri, 18 Dec 2015 12:03:46 -0500
Post by Lyude
---
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
+
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
+
+ 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
+ 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.
+
+ 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
+ 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">
Hi
Missing type="destructor". I think you might be leaking client memory
and maybe even mess up the object id accounting when the server destroys
the wl_resource but the client didn't destroy the wl_proxy.
I wonder if wayland-scanner should actually detect this and warn,
because if there is no request called "destroy", it will generate a
*_destroy() function regardless which only destroys the proxy but will
not send any message. So having a request called "destroy" that does
not actually destroy the proxy would be quite confusing.
Pretty sure we fail hard, not just warn, if you have a non-destructor
called destroy.

Error looks like:
<stdin>:118: error: destroy request should be a destructor type

Either the check is broken or this protocol's never been formally
introduced to the scanner. ;)

Thanks,
Derek
Post by Pekka Paalanen
Post by Lyude
+ <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.
+ </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
+ primary selection as middle clicks. This is to ensure the behavior is
+ identical to that of primary selection pasting in X.
+
+ 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.
+ </description>
+ <arg name="offer" type="new_id" interface="zwp_primary_selection_offer_v1"/>
+ </event>
+
+ <request name="destroy">
And here.
Post by Lyude
+ <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>
+
+ <request name="destroy">
And here.
Post by Lyude
+ <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.
+ </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">
+ <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">
And here.
Post by Lyude
+ <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 didn't check anything else than destructors.
Thanks,
pq
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Lyude
2015-12-21 23:21:48 UTC
Permalink
Post by Derek Foreman
Post by Pekka Paalanen
On Fri, 18 Dec 2015 12:03:46 -0500
---
    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
+
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
+
+    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
+      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.
+
+      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
+      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">
Hi
Missing type="destructor". I think you might be leaking client memory
and maybe even mess up the object id accounting when the server destroys
the wl_resource but the client didn't destroy the wl_proxy.
I wonder if wayland-scanner should actually detect this and warn,
because if there is no request called "destroy", it will generate a
*_destroy() function regardless which only destroys the proxy but will
not send any message. So having a request called "destroy" that does
not actually destroy the proxy would be quite confusing.
Pretty sure we fail hard, not just warn, if you have a non-destructor
called destroy.
<stdin>:118: error: destroy request should be a destructor type
Either the check is broken or this protocol's never been formally
introduced to the scanner. ;)
Yep, I got caught up in some other work and when I was sending this I completely
forgot to actually test to see if it worked in the scanner or not. I'll make
sure to add the destructors and check with wayland-scanner before sending out
the next version.

Other then the destructors, does the overall protocol look fine to everyone?
Post by Derek Foreman
Thanks,
Derek
Post by Pekka Paalanen
+      <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.
+      </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
+        primary selection as middle clicks. This is to ensure the
behavior is
+        identical to that of primary selection pasting in X.
+
+        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.
+      </description>
+      <arg name="offer" type="new_id"
interface="zwp_primary_selection_offer_v1"/>
+    </event>
+
+    <request name="destroy">
And here.
+      <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>
+
+    <request name="destroy">
And here.
+      <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.
+      </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">
+      <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">
And here.
+      <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 didn't check anything else than destructors.
Thanks,
pq
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
--
Cheers,
Lyude
Bill Spitzak
2015-12-18 19:34:39 UTC
Permalink
Post by Lyude
---
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
I do not like the fact that a program has to create both a
wl_primary_selection_offer and a wl_data_offer on any selection (yes it can
defer the second one until the user starts a drag, but it still would be
nice to reuse the same one for both). Still not a huge problem, like in
many other cases the two proxies can be stuffed into the same higher-level
api object.

Some assurance that the abilities of both will be kept identical would
help, however. I don't want some data transfers to be impossible depending
on whether the user does dnd or middle-click paste.
Post by Lyude
+ <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>
Also, looking at what happened to wl_pointer, it appears the design of
Wayland is to not have any "singletons" except the globally-advertised
objects. I'm not sure if this has any visible effects on your api because
there is no actual state stored on the object, and you must already support
creating more than one, but it might make sense to get rid of the words
"Singleton global".

+ <interface name="zwp_primary_selection_device_v1" version="1">
Post by Lyude
+ <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.
+ </description>
+ <arg name="source" type="object"
interface="zwp_primary_selection_source_v1"/>
+ </request>
Please don't require the "window is focused". The rules used by the
compositor to accept/reject these offers should be defined by the
compositor (a possible rule is that the window either got a mouse click or
a keystroke from the seat). Clicking in a window should never be required
to cause focus/activate/raise by the low-level api, that is instead part of
the desktop and client definition.

+ <event name="selection_offer">
Post by Lyude
+ <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
+ primary selection as middle clicks. This is to ensure the behavior is
+ identical to that of primary selection pasting in X.
+
+ 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.
+ </description>
+ <arg name="offer" type="new_id"
interface="zwp_primary_selection_offer_v1"/>
+ </event>
I think it would be better to send this to the client when it gets any
focus from the seat, and also if the selection is changed while it has
focus. Then the client is able to free to use any method to do the paste
(though of course using the middle mouse is encouraged). Also means there
is not redundant events if the user clicks the middle mouse many times (a
lot of programs use the middle-mouse drag as a pan operation).

+ <event name="send">
Post by Lyude
+ <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>
May want to point out that this can happen more than once (ie the middle
mouse button is clicked more than once per set_selection).

+ <event name="cancelled">
Post by Lyude
+ <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>
I would guess this event is also sent if the compositor refuses the
set_selection request?
Michal Suchanek
2015-12-23 12:09:51 UTC
Permalink
Post by Bill Spitzak
Post by Lyude
---
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
I do not like the fact that a program has to create both a
wl_primary_selection_offer and a wl_data_offer on any selection (yes it can
defer the second one until the user starts a drag, but it still would be
nice to reuse the same one for both). Still not a huge problem, like in many
other cases the two proxies can be stuffed into the same higher-level api
object.
Some assurance that the abilities of both will be kept identical would help,
however. I don't want some data transfers to be impossible depending on
whether the user does dnd or middle-click paste.
Post by Lyude
+ <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>
Also, looking at what happened to wl_pointer, it appears the design of
Wayland is to not have any "singletons" except the globally-advertised
objects. I'm not sure if this has any visible effects on your api because
there is no actual state stored on the object, and you must already support
creating more than one, but it might make sense to get rid of the words
"Singleton global".
Post by Lyude
+ <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.
+ </description>
+ <arg name="source" type="object"
interface="zwp_primary_selection_source_v1"/>
+ </request>
Please don't require the "window is focused". The rules used by the
compositor to accept/reject these offers should be defined by the compositor
(a possible rule is that the window either got a mouse click or a keystroke
from the seat). Clicking in a window should never be required to cause
focus/activate/raise by the low-level api, that is instead part of the
desktop and client definition.
So when a window is once clicked it can from then on arbitrarily set
primary selection?

Or is there a timeout? How long?

You cannot possibly tie the setting of the selection to a particular
click. I mean the user does something, as a result the application
gets an event, the application processes the event, and as a result it
finds out it would be a good idea to set the selection. Where does the
fact that the user clicked the window sometime in the past help when
the request to set the selection actually arrives?
Post by Bill Spitzak
Post by Lyude
+ <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
+ primary selection as middle clicks. This is to ensure the behavior is
+ identical to that of primary selection pasting in X.
+
+ 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.
+ </description>
+ <arg name="offer" type="new_id"
interface="zwp_primary_selection_offer_v1"/>
+ </event>
I think it would be better to send this to the client when it gets any focus
from the seat, and also if the selection is changed while it has focus. Then
the client is able to free to use any method to do the paste (though of
course using the middle mouse is encouraged). Also means there is not
redundant events if the user clicks the middle mouse many times (a lot of
programs use the middle-mouse drag as a pan operation).
Same. If setting selection should not require focus why pulling the
selection should?

If middle-clicking a window is encouraged to perform a paste and it is
not encouraged to imply that the middle click did anything to the
window focus then it is advisable to not depend on focus state for
pasting.

The thing with focus here is probably meant to add some security so
that some arbitrary applications do not use the primary paste buffer
for exchanging arbitrary data without any user action.

As pointed out focus cannot be relied on to be of any value for
determining copy and paste ability.

so there are a few options here

1) find a flag that *can* be relied on to set copy and paste
capability - something that is user-visible and user-controlled and
does not get into the way of usual copy and paste workflow

2) just say that primary selection is inherently insecure and allow
free access to most applications possibly excluding some applications
which are deemed untrusted - pretty much current X situation

3) control the copy and paste in compositor or dedicated paste manager
- the application can only get access to paste buffer in response to a
paste event which it gets from outside. Then the binding of input
events is indeed not determined by the application but by the
compositor.

In this case
- even if middle click is the default event that triggers a paste it
should not be part of the specification that it's a middle click. Any
input event can trigger a paste event.
- the paste event should reference the input event in question so
that the application can ignore the input even if it decides to handle
the paste event.

Thanks

Michal
Peter Hutterer
2016-01-04 05:05:24 UTC
Permalink
Post by Lyude
---
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
+
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
+
+ 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?
Post by Lyude
+ 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?
Post by Lyude
+
+ 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'"
Post by Lyude
+ 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.
Post by Lyude
+ </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/
Post by Lyude
+ 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."
Post by Lyude
+
+ 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 :)
Post by Lyude
+ </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."
Post by Lyude
+ </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.
Post by Lyude
+ <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/
Post by Lyude
+ </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.
Post by Lyude
+ <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.

Cheers,
Peter

* it probably needs to do that anyway, even if we add events.
Peter Hutterer
2016-01-04 06:28:13 UTC
Permalink
Post by Peter Hutterer
Post by c***@redhat.com
+ 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
+ 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
"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 :)
"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.
I really do not like this key assignment being something the compositor is
in charge of. A client may have a very good reason to use middle-click for
something else, yet still want the ability to paste from the selection.
this is still possible with the current proposal.
Also it seems like you will send this on *every* middle click. Some clients
require clicking the middle button a lot without pasting (it is very common
to use it as a pan control in 2D/3D).
your average touchpad sends events at 80hz. most of those translate into
some sort of pointer movement and wl_pointer events that are ignored by the
client unless they trigger something specific. even if you use a lot of
panning, I think we disagree on what "a lot" is in the context of input
events :)
It seems like it would be much better to send this event when to surfaces
with various foci (keyboard, mouse, etc) when the selection changes, and
also when a surface gets a focus and the selection has changed since it last
had focus.
in the normal use-case you will get a lot more focus changes than middle
clicks.

Cheers,
Peter
Post by Peter Hutterer
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.
* 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.
These problems apply to (and have been solved by?) the DnD offer objects
already. Copy that exactly. If there is a bug it needs to be fixed in both
of them.
Bill Spitzak
2016-01-04 06:37:47 UTC
Permalink
Post by Peter Hutterer
I really do not like this key assignment being something the compositor is
in charge of. A client may have a very good reason to use middle-click for
something else, yet still want the ability to paste from the selection.
this is still possible with the current proposal.
I think you are talking about the client optionally using the middle
click for paste or for something else, perhaps depending on where they
click. That is certainly important.

As far as I can tell this is purposely preventing clients from using a
keystroke or shift+click or any other action to trigger a paste from the
selection. That seems wrong to me. Also, despite the comment, it is not
"identical to that of primary selection pasting in X". X lets the client
grab the selection buffer at any moment, nothing in the X protocol ties
it to the middle mouse button.
Post by Peter Hutterer
Also it seems like you will send this on *every* middle click. Some clients
require clicking the middle button a lot without pasting (it is very common
to use it as a pan control in 2D/3D).
in the normal use-case you will get a lot more focus changes than middle
clicks.
Not if middle-click is used for panning. That's why I mentioned it.

You are correct though that it is probably irrelevant. Though I am a bit
concerned that this event includes an object with a new id, and all the
necessary work on both the compositor and client to track it.
Peter Hutterer
2016-01-05 04:33:16 UTC
Permalink
Post by Peter Hutterer
I really do not like this key assignment being something the compositor is
in charge of. A client may have a very good reason to use middle-click for
something else, yet still want the ability to paste from the selection.
this is still possible with the current proposal.
I think you are talking about the client optionally using the middle click
for paste or for something else, perhaps depending on where they click. That
is certainly important.
As far as I can tell this is purposely preventing clients from using a
keystroke or shift+click or any other action to trigger a paste from the
selection.
yeah, you're right. This could be alleviated by having a request in the
client to say "hey, I'd like to paste" that the compositor again controls
(haven't thought about this in detail though), but this seems something that
we can add when there is a real demand for it.
That seems wrong to me. Also, despite the comment, it is not
"identical to that of primary selection pasting in X". X lets the client
grab the selection buffer at any moment, nothing in the X protocol ties it
to the middle mouse button.
no but it does it by convention which in the 90% case is the same. having
the buffer accessible by anything at any time is a security issue, moving
the control over to the compositor makes it less so.
Post by Peter Hutterer
Also it seems like you will send this on *every* middle click. Some clients
require clicking the middle button a lot without pasting (it is very common
to use it as a pan control in 2D/3D).
in the normal use-case you will get a lot more focus changes than middle
clicks.
Not if middle-click is used for panning. That's why I mentioned it.
You are correct though that it is probably irrelevant. Though I am a bit
concerned that this event includes an object with a new id, and all the
necessary work on both the compositor and client to track it.
one of the big benefits that input related stuff has is that you don't need
to care too much about resources. yes, this protocol involves creating and
destroying objects on every middle click. Compared to the textures you just
had to load to display the web browser, this is peanuts. Crushed into very
small pieces :)

Cheers,
Peter
Bill Spitzak
2016-01-05 06:04:49 UTC
Permalink
Post by Peter Hutterer
Post by Bill Spitzak
Post by Peter Hutterer
Also it seems like you will send this on *every* middle click. Some clients
require clicking the middle button a lot without pasting (it is very common
to use it as a pan control in 2D/3D).
in the normal use-case you will get a lot more focus changes than middle
clicks.
Not if middle-click is used for panning. That's why I mentioned it.
You are correct though that it is probably irrelevant. Though I am a bit
concerned that this event includes an object with a new id, and all the
necessary work on both the compositor and client to track it.
one of the big benefits that input related stuff has is that you don't need
to care too much about resources. yes, this protocol involves creating and
destroying objects on every middle click. Compared to the textures you just
had to load to display the web browser, this is peanuts. Crushed into very
small pieces :)
Maybe it should only send the newid if the selection has changed. The
client can keep the old object around until it is destroyed, even if it
gets many clicks.

ie. when the selection changes, any old offers get the destroyed event.
But clients do not get the new offer until they get another middle
click. If the user clicks many times only one offer proxy is created.

The overhead may not be so minimal in creating/destroying local objects
in some languages such as Python, so it does seem nice to avoid this. A
bigger concern is that if more events are decided to be "pasteable" by
the compostior, it will have to send the offer even more times (imagine
if it is decided that any keystroke can paste). This rule means it only
has to send it before the first such event.
Michal Suchanek
2016-01-05 15:47:13 UTC
Permalink
Hello,
Post by Peter Hutterer
Post by Bill Spitzak
Post by Peter Hutterer
Also it seems like you will send this on *every* middle click. Some clients
require clicking the middle button a lot without pasting (it is very common
to use it as a pan control in 2D/3D).
in the normal use-case you will get a lot more focus changes than middle
clicks.
Not if middle-click is used for panning. That's why I mentioned it.
You are correct though that it is probably irrelevant. Though I am a bit
concerned that this event includes an object with a new id, and all the
necessary work on both the compositor and client to track it.
one of the big benefits that input related stuff has is that you don't need
to care too much about resources. yes, this protocol involves creating and
destroying objects on every middle click. Compared to the textures you just
had to load to display the web browser, this is peanuts. Crushed into very
small pieces :)
Maybe it should only send the newid if the selection has changed. The client
can keep the old object around until it is destroyed, even if it gets many
clicks.
ie. when the selection changes, any old offers get the destroyed event. But
clients do not get the new offer until they get another middle click. If the
user clicks many times only one offer proxy is created.
The overhead may not be so minimal in creating/destroying local objects in
some languages such as Python, so it does seem nice to avoid this. A bigger
concern is that if more events are decided to be "pasteable" by the
compostior, it will have to send the offer even more times (imagine if it is
decided that any keystroke can paste). This rule means it only has to send
it before the first such event.
Actually, this sounds reasonable.

When there is a selection set and an application receives any input
event it will also receive a paste offer. It can then act on that
offer any time until a new selection is set. It does need any new
offer until new selection is set.

When concerned about pasting into the wrong application the user can
unmap/minimize/whatever the application window so it cannot receive
input events.

There is only slight problem with paste buffer managers and download
managers which try to watch for paste buffer changes in the background
without receiving any input. This can be probably amended by setting
different paste policies (filters for events that allow access to the
paste buffer) for different applications.

Thanks

Michal
Bill Spitzak
2016-01-05 23:31:03 UTC
Permalink
Post by c***@redhat.com
Post by Bill Spitzak
Maybe it should only send the newid if the selection has changed. The
client
Post by Bill Spitzak
can keep the old object around until it is destroyed, even if it gets
many
Post by Bill Spitzak
clicks.
ie. when the selection changes, any old offers get the destroyed event.
But
Post by Bill Spitzak
clients do not get the new offer until they get another middle click. If
the
Post by Bill Spitzak
user clicks many times only one offer proxy is created.
The overhead may not be so minimal in creating/destroying local objects
in
Post by Bill Spitzak
some languages such as Python, so it does seem nice to avoid this. A
bigger
Post by Bill Spitzak
concern is that if more events are decided to be "pasteable" by the
compostior, it will have to send the offer even more times (imagine if
it is
Post by Bill Spitzak
decided that any keystroke can paste). This rule means it only has to
send
Post by Bill Spitzak
it before the first such event.
Actually, this sounds reasonable.
When there is a selection set and an application receives any input
event it will also receive a paste offer. It can then act on that
offer any time until a new selection is set. It does need any new
offer until new selection is set.
When concerned about pasting into the wrong application the user can
unmap/minimize/whatever the application window so it cannot receive
input events.
Actually with this design, a user can be certain that no other app can see
the selected text unless they actually click the middle mouse in that app
after making the selection. Even with the more extreme versions I think
will eventually appear, the app probably will not see the selection unless
they type a key or click in it. This may make it safe to select passwords
and other sensitive data.
Post by c***@redhat.com
There is only slight problem with paste buffer managers and download
managers which try to watch for paste buffer changes in the background
without receiving any input. This can be probably amended by setting
different paste policies (filters for events that allow access to the
paste buffer) for different applications.
Yea it would prevent that. Maybe those could require special privledges,
and they will get the event with the offer on all changes.
Jonas Ådahl
2016-01-05 01:09:04 UTC
Permalink
Post by Peter Hutterer
Post by Lyude
---
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
+
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
+
+ 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?
Post by Lyude
+ 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?
Post by Lyude
+
+ 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'"
Post by Lyude
+ 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.
Post by Lyude
+ </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/
Post by Lyude
+ 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
"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 :)
"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."
Post by Lyude
+
+ 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 :)
Post by Lyude
+ </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."
Post by Lyude
+ </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.
This name comes from the data device protocol from wayland.xml and I
think it's better to keep them consistent even though the event/request
name does not include "mime type".
Post by Peter Hutterer
Post by Lyude
+ <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/
Post by Lyude
+ </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.
Same as with the related event. This would make the protocol differ more
from the one it is based upon.
Post by Peter Hutterer
Post by Lyude
+ <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.
* 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?
The source will complete its calls to .offer() before setting the
selection. The .set_selection is the committing request.

The offer will have received all .offer events before .selection_offer.
Post by Peter Hutterer
* 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.
Wouldn't wp_primary_selection_device.selection_offer(NULL) be the
equivalent of a "cancel" of the offer?


Jonas
Post by Peter Hutterer
Cheers,
Peter
* it probably needs to do that anyway, even if we add events.
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Lyude
2016-01-05 15:28:22 UTC
Permalink
Post by Peter Hutterer
---
    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
+
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
+
+    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
"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 :)
"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.
* 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.
Post by Peter Hutterer
Cheers,
   Peter
* it probably needs to do that anyway, even if we add events.
--
Cheers,
Lyude
Lyude
2016-01-07 02:50:36 UTC
Permalink
Signed-off-by: Lyude <***@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 <***@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
+ 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>
+
+ <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" 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.
+ </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
+ wp_primary_selection_offer object that may be used to receive the
+ current primary selection. Immediately folliwng this event, the new
+ 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>
+
+ <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.
+ </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.
+ </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>
+
+ <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 has been replaced by another primary
+ selection source. The client should clean up and destroy this primary
+ selection source.
+ </description>
+ </event>
+ </interface>
+</protocol>
--
2.5.0
Jonas Ådahl
2016-01-07 03:42:00 UTC
Permalink
Post by Lyude
---
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.
Does this mean that the offer always comes on keyboard focus? Or pointer
focus? Or touch focus? Or does it come a user interaction of some kind?
And after that it may retrieve the primary selection at any point? Could
it not be done as request that is a response to an input event carrying
a serial, where the serial can be used to match the request to the
triggering user interaction. Or would that break some expectations of
the primary selection use case (i.e. retrieve not from a user
interaction)?
Post by Lyude
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
+
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">
This should be "primary_selection_unstable_v1".
Post by Lyude
+ <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
+
+ 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
+ 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.
Hmm. Should this be in a <description/> in the <protocol/> instead
maybe? I also wonder if it should be worded a bit differently. It
doesn't allow "users" anything, it just enables clients and compositors
to allow users. It doesn't necessarily require selecting text and no
initial copy, even though that is the common use case, so maybe that
should be reflected.

I also don't know what "buffer" means here. I used to "paste" URLs
directly onto a firefox tab to make it load the URL for example.
Post by Lyude
+
+ 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>
+
+ <request name="create_primary_selection_source">
+ <description summary="create a new primary selection source">
+ Create a new primary selection source.
nit: At some point we ended up with "tabs" were the way to go for
protocol files. If you wan't to stay consistent, I suggest you change to
that.
Post by Lyude
+ </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" 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.
+ </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
+ wp_primary_selection_offer object that may be used to receive the
+ current primary selection. Immediately folliwng this event, the new
+ 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>
+
+ <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.
+ </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.
+ </description>
+ </event>
nit: Before "done" has been name used to determine the end of a series of
events. Maybe "offers_done"?
Post by Lyude
+ </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>
+
+ <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 has been replaced by another primary
+ selection source. The client should clean up and destroy this primary
+ selection source.
I think it'd be better to be more generic or allowing here, so that we
don't end up like in wl_data_source. In other words, it may not only be
because it was replaced, it may be some other reason (without specifying
what reason).


Jonas
Post by Lyude
+ </description>
+ </event>
+ </interface>
+</protocol>
--
2.5.0
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Michal Suchanek
2016-01-07 09:37:18 UTC
Permalink
Post by Jonas Ådahl
Post by Lyude
---
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.
Does this mean that the offer always comes on keyboard focus? Or pointer
focus? Or touch focus? Or does it come a user interaction of some kind?
And after that it may retrieve the primary selection at any point? Could
it not be done as request that is a response to an input event carrying
a serial, where the serial can be used to match the request to the
triggering user interaction. Or would that break some expectations of
the primary selection use case (i.e. retrieve not from a user
interaction)?
The primary selection expectation in X is that an application can
retrieve it at any time.

It has been pointed out that focus is not what it used to be in X and
and hence is not useful for determining paste ability.

Also the application should be responsible for determining what action
(if any) triggers paste and it gives no useful information if the
paste request is tied to an input event, anyway.

However, the compositor can and should apply a policy to pastes and
not send the paste offer to all applications as soon as a selection is
set.

One way to do that and preserve the feel of X primary selection is to
send an offer once an application receives user input (event) after a
selection was set. That way applications can decide which user action
triggers a paste using application-specific bindings. As the offer is
invalidated once new selection is set an application cannot get
arbitrary pastes from the paste buffer without user action. If desired
different non-default policy on pastes (event filters) can be applied
to different applications to accommodate both paste managers that
should receive paste offer as soon as selection is set and sandboxed
applications that should not have access to the paste buffer.

Thanks

Michal
Lyude
2016-01-07 18:15:41 UTC
Permalink
Post by Michal Suchanek
Post by Jonas Ådahl
---
                              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.
Does this mean that the offer always comes on keyboard focus? Or pointer
focus? Or touch focus? Or does it come a user interaction of some kind?
And after that it may retrieve the primary selection at any point? Could
it not be done as request that is a response to an input event carrying
a serial, where the serial can be used to match the request to the
triggering user interaction. Or would that break some expectations of
the primary selection use case (i.e. retrieve not from a user
interaction)?
The primary selection expectation in X is that an application can
retrieve it at any time.
I knew I was missing something in this. So, that's basically what it's like now.
A client should be able to expect to get a request the first time something gets
set in the primary selection. So, it is basically the same as X. I'll make sure
to clarify this in the description.
Post by Michal Suchanek
It has been pointed out that focus is not what it used to be in X and
and hence is not useful for determining paste ability.
Also the application should be responsible for determining what action
(if any) triggers paste and it gives no useful information if the
paste request is tied to an input event, anyway.
However, the compositor can and should apply a policy to pastes and
not send the paste offer to all applications as soon as a selection is
set.
One way to do that and preserve the feel of X primary selection is to
send an offer once an application receives user input (event) after a
selection was set. That way applications can decide which user action
triggers a paste using application-specific bindings. As the offer is
invalidated once new selection is set an application cannot get
arbitrary pastes from the paste buffer without user action. If desired
different non-default policy on pastes (event filters) can be applied
to different applications to accommodate both paste managers that
should receive paste offer as soon as selection is set and sandboxed
applications that should not have access to the paste buffer.
Thanks
Michal
--
Cheers,
Lyude
Peter Hutterer
2016-01-08 00:16:54 UTC
Permalink
Post by Lyude
Post by Michal Suchanek
Post by Jonas Ådahl
---
                              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.
Does this mean that the offer always comes on keyboard focus? Or pointer
focus? Or touch focus? Or does it come a user interaction of some kind?
And after that it may retrieve the primary selection at any point? Could
it not be done as request that is a response to an input event carrying
a serial, where the serial can be used to match the request to the
triggering user interaction. Or would that break some expectations of
the primary selection use case (i.e. retrieve not from a user
interaction)?
The primary selection expectation in X is that an application can
retrieve it at any time.
I knew I was missing something in this. So, that's basically what it's like now.
A client should be able to expect to get a request the first time something gets
set in the primary selection. So, it is basically the same as X. I'll make sure
to clarify this in the description.
they way I read the current protocol, you're planning on this:
the receiving client gets a selection manager and a selection device, but
there is no way of requesting the selection, you simply get the event
whenever a source sets it. the client needs to hold this until a paste
action happens, handling all cancelled events until then. that seems
inefficient, and potentially leaks information since you know when the
client selected something.

what I'm missing is a request on the selection device that says "gimme the
offer now", followed by the selection_offer event.
unless you're intending to make the get_primary_selection_device() to be
that request, i.e. a client should issue this request in response to
the middle click. That works, I think, but it needs to be documented.

Cheers,
Peter
Post by Lyude
Post by Michal Suchanek
It has been pointed out that focus is not what it used to be in X and
and hence is not useful for determining paste ability.
Also the application should be responsible for determining what action
(if any) triggers paste and it gives no useful information if the
paste request is tied to an input event, anyway.
However, the compositor can and should apply a policy to pastes and
not send the paste offer to all applications as soon as a selection is
set.
One way to do that and preserve the feel of X primary selection is to
send an offer once an application receives user input (event) after a
selection was set. That way applications can decide which user action
triggers a paste using application-specific bindings. As the offer is
invalidated once new selection is set an application cannot get
arbitrary pastes from the paste buffer without user action. If desired
different non-default policy on pastes (event filters) can be applied
to different applications to accommodate both paste managers that
should receive paste offer as soon as selection is set and sandboxed
applications that should not have access to the paste buffer.
Thanks
Michal
--
Cheers,
Lyude
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Bill Spitzak
2016-01-07 19:00:41 UTC
Permalink
Post by Jonas Ådahl
Does this mean that the offer always comes on keyboard focus? Or pointer
focus? Or touch focus? Or does it come a user interaction of some kind?
I think the last one is the intention here. The offer will come just before
an event that the compositor consideres a possible "paste event". The
original proposal was for this to be limited to middle mouse down, but it
sounds like it will be on all button and key down events. I now think the
idea is good, it prevents a client from passively watching the contents of
the selection, and may mean it is safe to select passwords and other
sensitive information. I also will contradict what I said before, it seems
good to not tie this to focus, so that simply moving the mouse does not
give clients the ability to peek at the selection.

And after that it may retrieve the primary selection at any point?


Yes, until the selection is changed. At that point it will get a destroyed
event on the offer, but it won't get another offer until the next "paste
event".

Could
Post by Jonas Ådahl
it not be done as request that is a response to an input event carrying
a serial, where the serial can be used to match the request to the
triggering user interaction. Or would that break some expectations of
the primary selection use case (i.e. retrieve not from a user
interaction)?
I think that would make it impossible to emulate the X11 interface. Also it
adds round trips.

X11 just has a "selection was changed" event, and the ability to read the
selection. I think this can be mapped from this api without giving the X11
clients any more ability to peek at the selection, by having the
destruction of the offer act as though the selection was changed to an
empty string, and the new offer act as though the selection was changed yet
again. So a middle-mouse click will give an X11 client a selection changed
event followed immediately by the mouse click.

Something I do realize is necessary: the client making the selection needs
an indication that another client has made a selection. This is so it can
redraw highlighting to show the fact that it no longer has the selection
(I'm not saying this is required, but it is a behavior that should be
possible). Right now this sends destruct events to the clients that got the
offer, but I don't think anything is sent to the source client. I think
this needs to be another event on the primary_selection_device.
Peter Hutterer
2016-01-08 00:30:04 UTC
Permalink
Post by Lyude
---
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
+
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
+
+ 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.
Post by Lyude
+ 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.
Post by Lyude
+
+ <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
Post by Lyude
+
+ <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?
Post by Lyude
+ </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.
Post by Lyude
+ wp_primary_selection_offer object that may be used to receive the
+ current primary selection. Immediately folliwng this event, the new
typo: following
Post by Lyude
+ 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?
Post by Lyude
+
+ <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."
Post by Lyude
+ </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 ;)
Post by Lyude
+ </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?
Post by Lyude
+
+ <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?
Post by Lyude
+ </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? :)
Post by Lyude
+ 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
Post by Lyude
+ </description>
+ </event>
+ </interface>
+</protocol>
--
2.5.0
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Carlos Garnacho
2016-02-04 18:26:59 UTC
Permalink
Hi!,

Chiming in late...
Post by Lyude
---
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
+
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
+
+ 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
+ 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>
+
+ <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>
The name of these two requests feel a bit redundant, they end up in:

zwp_primary_selection_device_manager_v1_create_primary_selection_source
zwp_primary_selection_device_manager_v1_get_primary_selection_device

"primary selection" is twice on both, and the functions are close to
the 80 chars limit :). I'd suggest "create_source" and "get_device",
the "primary selection" nature is already implicit in the protocol
name/prefix, and the returned types.
Post by Lyude
+
+ <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.
+ </description>
+ <arg name="source" type="object" interface="zwp_primary_selection_source_v1"/>
wl_data_device.set_selection allows unsetting the current selection by
passing NULL. I think it'd be worth allowing this too for the same
reasons, clients might want to unset the selection (eg. gtk+ clears
the primary selection when the client is the owner of the primary
selection data and you unselect the text).

This arg might need allow-null="true" then.
Post by Lyude
+ </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
+ wp_primary_selection_offer object that may be used to receive the
+ current primary selection. Immediately folliwng this event, the new
+ 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>
+
+ <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.
+ </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.
+ </description>
Here I see a slight difference with wl_data_device and wl_data_offer
that would be great to even out, as it better allows clients to
abstract wl_data_* and zwp_primary_selection_* in common interfaces.

In zwp_primary_selection, you first receive a
zwp_primary_selection_device_v1.selection_offer, and then this event
in zwp_primary_selection_offer_v1, whereas in the wayland core
protocol both the "offer introduction" and the "offer being put to
use" events happen both on wl_data_device (.data_offer and .selection,
respectively).

This event can be maybe seen as belonging to the offer (it's state of
the offer, at least), but I admit I'm more sold on the final event
where you can start using the offer to be a device one.

Cheers
Carlos
Carlos Garnacho
2016-02-20 00:31:59 UTC
Permalink
From: Lyude <***@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 <***@redhat.com>
Signed-off-by: Carlos Garnacho <***@gnome.org>
---
After having talked with Lyude, I'll be trying to move this ahead.

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>
+
+ <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.
+
+ 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>
+
+ <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
+ 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>
--
2.5.0
Jonas Ådahl
2016-02-22 07:53:38 UTC
Permalink
Post by Carlos Garnacho
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.
---
After having talked with Lyude, I'll be trying to move this ahead.
- 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.
Overall good. Some comments inline. With those fixed, this is
Post by Carlos Garnacho
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
+
+Lyude <cpaul at redhat.com>
Any reason for the "anti-spam" thing here? The E-mail address is already
available all over the place anyway (commit author, commit body).
Post by Carlos Garnacho
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
2016 now as well?
Post by Carlos Garnacho
+
+ 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
+
+ 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>
+
+ <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.
+
+ 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.
Does this mean that a client may not create one source object, and just
keep the same as text is selected, while only setting a NULL source if
text was unselected?
Post by Carlos Garnacho
+
+ 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.
This should contain information that it is a singleton global object.
Post by Carlos Garnacho
+ </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.
The summary and description seems to describe manager interface.
Post by Carlos Garnacho
+ </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>
+
+ <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 doesn't set any buffer content any more, it just sets the source
object.
Post by Carlos Garnacho
+ </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
"transeferred as" instead of "converted to". Whether any conversion is
done is an implementation detail.
Post by Carlos Garnacho
+ 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
+ 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>
--
2.5.0
_______________________________________________
wayland-devel mailing list
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Carlos Garnacho
2016-02-22 10:42:02 UTC
Permalink
Hey Jonas,
Post by Jonas Ådahl
Post by Carlos Garnacho
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.
---
After having talked with Lyude, I'll be trying to move this ahead.
- 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.
Overall good. Some comments inline. With those fixed, this is
Thanks for the review!
Post by Jonas Ådahl
Post by Carlos Garnacho
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
+
+Lyude <cpaul at redhat.com>
Any reason for the "anti-spam" thing here? The E-mail address is already
available all over the place anyway (commit author, commit body).
Post by Carlos Garnacho
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
2016 now as well?
Post by Carlos Garnacho
+
+ 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
+
+ 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>
+
+ <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.
+
+ 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.
Does this mean that a client may not create one source object, and just
keep the same as text is selected, while only setting a NULL source if
text was unselected?
Right, that may be a possibility, actually a client choice. I guess it
depends on what do we want the wp_primary_selection_device.selection
event to mean, whether it just conveys ownership, or whether it really
signals that the selection content changed. This is certainly easier
in the core protocol since both meanings match to some extent.

I'm also struggling to think usecases where the offered mimetypes
might change during selection, but I don't think that's too likely.
Eg. a rich text widget wants to offer plain text amongst others,
despite the user selecting text+images there. That said, at least in
gtk+ this is a choice of the widget.

I'm folding in your other suggestions, and am thinking in ways to
improve the wording here. I'm actually ok with the .selection event
conveying only ownership. AFAICT such behavior could only break
clipboard managers, which we don't contemplate anyway.

Cheers,
Carlos
Michal Suchanek
2016-02-22 13:25:35 UTC
Permalink
Hello,
Post by Carlos Garnacho
+
+ <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.
+
+ 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
Why keyboard focus?

Since paste is done mainly using mouse this has nothing to do with
keyboard focus.
Post by Carlos Garnacho
+ 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
Why press event when it has an offer event to base the request on?

There is no need to involve other unrelated events.

IMHO the fact that the application receives ANY input event suffices.
eg. a pointer entry event.

Otherwise you are going to have very fragile protocol that often fails
because the application did not happen to receive whatever even is
requested by the protocol.

It's even worse with the keyboard focus. If the event that triggers
the paste also triggers getting keyboard focus you are going to have
protocol open to all kind of ugly race conditions. If it does not
trigger getting the keyboard focus the paste just fails.

There are point-to-type and click-to-type keyboard focus models which
should be both supported by the primary selection protocol.

Thanks

Michal
Carlos Garnacho
2016-02-22 14:57:11 UTC
Permalink
Hi Michal,
Post by Michal Suchanek
Hello,
Post by Carlos Garnacho
+
+ <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.
+
+ 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
Why keyboard focus?
Since paste is done mainly using mouse this has nothing to do with
keyboard focus.
Doing this so allows us to behave just the same than we do with the
core protocol selection, slightly divergent protocols make sharing
code harder.

Conceptually, it also makes some sense to me. I argue that a logical
"key" focus is needed in compositors, even on lack of wl_keyboard
capabilities. Things that IMO make sense to tie together in this
focus, per-seat are:
- wl_keyboard focus
- wp_text_input focus
- focus por (possibly several) pads/buttonsets
- clipboard selection
- primary selection

Of course these are only guidelines, and compositors may attempt to
implement split foci for these. But still, selection should be tied to
some definite focus, the other option is broadcasting, and I'd very
much prefer not to do that.

I may try to change the wording just to suggest it's loosely attached
to keyboard focus though.
Post by Michal Suchanek
Post by Carlos Garnacho
+ 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
Why press event when it has an offer event to base the request on?
There is no need to involve other unrelated events.
IIRC The first protocol drafts attempted to limit the circumstances in
which a client could read the primary selection. This is a change of
approach.
Post by Michal Suchanek
IMHO the fact that the application receives ANY input event suffices.
eg. a pointer entry event.
Do you mean wl_pointer.enter should be enough to have the application
read the primary selection? seems open to data leaks to me.

This serial event is meant to check for user interaction rather than
"any input event", so just focusing a client is not enough to have it
retrieve the primary selection.
Post by Michal Suchanek
Otherwise you are going to have very fragile protocol that often fails
because the application did not happen to receive whatever even is
requested by the protocol.
Note that it just mentions a press event, but does no mention of the
interface/device it comes from. It can be the serial received on
wl_pointer.button, wl_keyboard.key, wl_touch.down,
wp_tablet_tool.down, ... compositors should ideally check all input
interfaces.
Post by Michal Suchanek
It's even worse with the keyboard focus. If the event that triggers
the paste also triggers getting keyboard focus you are going to have
protocol open to all kind of ugly race conditions. If it does not
trigger getting the keyboard focus the paste just fails.
Where do you see race conditions? Because focus is handled by the
compositor before event emission, AFAICT the client would receive the
following event sequence:

-->
wl_keyboard.enter
wl_data_device.data_offer
wl_data_offer.offer
[...]
wl_data_device.selection
zwp_primary_selection_device_v1.data_offer
zwp_primary_selection_offer_v1.offer
[...]
zwp_primary_selection_device_v1.selection
wl_pointer.button (..., serial_you_want_to_pass)

<--
zwp_primary_selection_offer_v1.receive (..., serial_you_want_to_pass)

Which results in the expected action to take place.
Post by Michal Suchanek
There are point-to-type and click-to-type keyboard focus models which
should be both supported by the primary selection protocol.
I think both models agree in that the window will be focused after you
clicked on it.

Cheers,
Carlos
Michal Suchanek
2016-02-22 15:53:43 UTC
Permalink
Post by Carlos Garnacho
Hi Michal,
Post by Michal Suchanek
Hello,
Post by Carlos Garnacho
+
+ <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.
+
+ 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
Why keyboard focus?
Since paste is done mainly using mouse this has nothing to do with
keyboard focus.
Doing this so allows us to behave just the same than we do with the
core protocol selection, slightly divergent protocols make sharing
code harder.
Conceptually, it also makes some sense to me. I argue that a logical
"key" focus is needed in compositors, even on lack of wl_keyboard
capabilities. Things that IMO make sense to tie together in this
- wl_keyboard focus
- wp_text_input focus
- focus por (possibly several) pads/buttonsets
- clipboard selection
- primary selection
Of course these are only guidelines, and compositors may attempt to
implement split foci for these. But still, selection should be tied to
some definite focus, the other option is broadcasting, and I'd very
much prefer not to do that.
I may try to change the wording just to suggest it's loosely attached
to keyboard focus though.
If you put an Insert sticker on your pad button and bind pasting to
that pad button and the pad focus is not tied to keyboard focus you
have potentially a problem there.
Post by Carlos Garnacho
Post by Michal Suchanek
Post by Carlos Garnacho
+ 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
Why press event when it has an offer event to base the request on?
There is no need to involve other unrelated events.
IIRC The first protocol drafts attempted to limit the circumstances in
which a client could read the primary selection. This is a change of
approach.
Post by Michal Suchanek
IMHO the fact that the application receives ANY input event suffices.
eg. a pointer entry event.
Do you mean wl_pointer.enter should be enough to have the application
read the primary selection? seems open to data leaks to me.
This serial event is meant to check for user interaction rather than
"any input event", so just focusing a client is not enough to have it
retrieve the primary selection.
And why is clicking enough and focusing not?

Accidentally clicking an application can happen as much as
accidentally pointing at it. With touch interface it's pretty much the
same thing. With click-to-focus also. If you want to prevent data
leaks you can unmap windows that should not receive the paste or use a
compositor with per-application access policy for clipboards.

So instead of saying that a button down event should trigger paste in
the protocol specification it is wiser to say that sending the paste
offer to a client can happen at the discretion of the compositor and
suggest some reasonable policy.

Compositor should be free to implement any policy the author finds
reasonable including broadcast on selection change, point to paste,
button press to paste, and per-application different policies.
Post by Carlos Garnacho
Post by Michal Suchanek
Otherwise you are going to have very fragile protocol that often fails
because the application did not happen to receive whatever even is
requested by the protocol.
Note that it just mentions a press event, but does no mention of the
interface/device it comes from. It can be the serial received on
wl_pointer.button, wl_keyboard.key, wl_touch.down,
wp_tablet_tool.down, ... compositors should ideally check all input
interfaces.
They need not check anything convoluted if they check that the client
is allowed to paste on sending the offer and only check that the
client acts on valid offer.

So instead of doing some check that it's ok to send offer and then
another check to see if some random event is pasty enough to act on a
paste request you just check that the client is allowed to receive the
offer.
Post by Carlos Garnacho
Post by Michal Suchanek
It's even worse with the keyboard focus. If the event that triggers
the paste also triggers getting keyboard focus you are going to have
protocol open to all kind of ugly race conditions. If it does not
trigger getting the keyboard focus the paste just fails.
Where do you see race conditions? Because focus is handled by the
compositor before event emission, AFAICT the client would receive the
-->
wl_keyboard.enter
wl_data_device.data_offer
wl_data_offer.offer
[...]
wl_data_device.selection
zwp_primary_selection_device_v1.data_offer
zwp_primary_selection_offer_v1.offer
[...]
zwp_primary_selection_device_v1.selection
wl_pointer.button (..., serial_you_want_to_pass)
<--
zwp_primary_selection_offer_v1.receive (..., serial_you_want_to_pass)
Which results in the expected action to take place.
Post by Michal Suchanek
There are point-to-type and click-to-type keyboard focus models which
should be both supported by the primary selection protocol.
I think both models agree in that the window will be focused after you
clicked on it.
ok, so this should work so long as the compositor likes the random
event serial you pick.

Thanks

Michal
Carlos Garnacho
2016-02-22 18:23:13 UTC
Permalink
Hi Michal,
Post by Michal Suchanek
Post by Carlos Garnacho
Hi Michal,
Post by Michal Suchanek
Hello,
Post by Carlos Garnacho
+
+ <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.
+
+ 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
Why keyboard focus?
Since paste is done mainly using mouse this has nothing to do with
keyboard focus.
Doing this so allows us to behave just the same than we do with the
core protocol selection, slightly divergent protocols make sharing
code harder.
Conceptually, it also makes some sense to me. I argue that a logical
"key" focus is needed in compositors, even on lack of wl_keyboard
capabilities. Things that IMO make sense to tie together in this
- wl_keyboard focus
- wp_text_input focus
- focus por (possibly several) pads/buttonsets
- clipboard selection
- primary selection
Of course these are only guidelines, and compositors may attempt to
implement split foci for these. But still, selection should be tied to
some definite focus, the other option is broadcasting, and I'd very
much prefer not to do that.
I may try to change the wording just to suggest it's loosely attached
to keyboard focus though.
If you put an Insert sticker on your pad button and bind pasting to
that pad button and the pad focus is not tied to keyboard focus you
have potentially a problem there.
Right, that's why I suggest having those reunited in a single logical
focus. Anything else is plagued of corner cases.
Post by Michal Suchanek
Post by Carlos Garnacho
Post by Michal Suchanek
Post by Carlos Garnacho
+ 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
Why press event when it has an offer event to base the request on?
There is no need to involve other unrelated events.
IIRC The first protocol drafts attempted to limit the circumstances in
which a client could read the primary selection. This is a change of
approach.
Post by Michal Suchanek
IMHO the fact that the application receives ANY input event suffices.
eg. a pointer entry event.
Do you mean wl_pointer.enter should be enough to have the application
read the primary selection? seems open to data leaks to me.
This serial event is meant to check for user interaction rather than
"any input event", so just focusing a client is not enough to have it
retrieve the primary selection.
And why is clicking enough and focusing not?
Accidentally clicking an application can happen as much as
accidentally pointing at it.
Citation needed :). Windows can be certainly arranged so that it's not
possible to move the pointer between app A and B without going through
a third application. The problem with doing this on pointer focus is
that situations like this come off the very nature of a 2D compositor.
Tying this to user interaction kills most of the concerns here, the
situation where the user accidentally clicks on an app that happens to
be malicious and request the clipboard on any interaction should be
unlikely enough, plus it'd make a lousy malicious app.
Post by Michal Suchanek
With touch interface it's pretty much the
same thing. With click-to-focus also. If you want to prevent data
leaks you can unmap windows that should not receive the paste or use a
compositor with per-application access policy for clipboards.
Those are all compositor dependent policies, I think something should
be done at the protocol level.
Post by Michal Suchanek
So instead of saying that a button down event should trigger paste in
the protocol specification
Nothing like that is mentioned. Wording is deliberately ambiguous as
to which event triggers primary selection paste.
Post by Michal Suchanek
it is wiser to say that sending the paste
offer to a client can happen at the discretion of the compositor and
suggest some reasonable policy.
What is unreasonable about serial checking?
Post by Michal Suchanek
Compositor should be free to implement any policy the author finds
reasonable including broadcast on selection change, point to paste,
button press to paste, and per-application different policies.
So you want the protocol to be purposely ambigous on data leak situations?

Let's take the most extreme case, primary selection can be broadcasted
and clients can be free to read data right away. You've just allowed
compositors to replicate all the flaws of X11 primary selection.

Cheers,
Carlos
Michal Suchanek
2016-02-23 09:32:04 UTC
Permalink
Post by Carlos Garnacho
Hi Michal,
Post by Michal Suchanek
Post by Carlos Garnacho
Hi Michal,
Post by Michal Suchanek
Hello,
Post by Carlos Garnacho
+
+ <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.
+
+ 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
Why keyboard focus?
Since paste is done mainly using mouse this has nothing to do with
keyboard focus.
Doing this so allows us to behave just the same than we do with the
core protocol selection, slightly divergent protocols make sharing
code harder.
Conceptually, it also makes some sense to me. I argue that a logical
"key" focus is needed in compositors, even on lack of wl_keyboard
capabilities. Things that IMO make sense to tie together in this
- wl_keyboard focus
- wp_text_input focus
- focus por (possibly several) pads/buttonsets
- clipboard selection
- primary selection
Of course these are only guidelines, and compositors may attempt to
implement split foci for these. But still, selection should be tied to
some definite focus, the other option is broadcasting, and I'd very
much prefer not to do that.
I may try to change the wording just to suggest it's loosely attached
to keyboard focus though.
If you put an Insert sticker on your pad button and bind pasting to
that pad button and the pad focus is not tied to keyboard focus you
have potentially a problem there.
Right, that's why I suggest having those reunited in a single logical
focus. Anything else is plagued of corner cases.
That's totally not going to work. When you have multiple touch panels
you can touch multiple places. Are you proposing that on whichever
panel you happen to touch first locks the other panel from working or
on whichever panel you touch last steals the touch on the earlier
panel?

I do not think either is expected behaviour.
Post by Carlos Garnacho
Post by Michal Suchanek
Post by Carlos Garnacho
Post by Michal Suchanek
Post by Carlos Garnacho
+ 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
Why press event when it has an offer event to base the request on?
There is no need to involve other unrelated events.
IIRC The first protocol drafts attempted to limit the circumstances in
which a client could read the primary selection. This is a change of
approach.
Post by Michal Suchanek
IMHO the fact that the application receives ANY input event suffices.
eg. a pointer entry event.
Do you mean wl_pointer.enter should be enough to have the application
read the primary selection? seems open to data leaks to me.
This serial event is meant to check for user interaction rather than
"any input event", so just focusing a client is not enough to have it
retrieve the primary selection.
And why is clicking enough and focusing not?
Accidentally clicking an application can happen as much as
accidentally pointing at it.
Citation needed :). Windows can be certainly arranged so that it's not
possible to move the pointer between app A and B without going through
a third application. The problem with doing this on pointer focus is
That can happen only with relative axis. With absolute axis you can
point anywhere anytime without going through anywhere else. Let's say
that for the sake of rodent users it is better to consider entry and
motion events insignificant.
Post by Carlos Garnacho
that situations like this come off the very nature of a 2D compositor.
Tying this to user interaction kills most of the concerns here, the
situation where the user accidentally clicks on an app that happens to
be malicious and request the clipboard on any interaction should be
unlikely enough, plus it'd make a lousy malicious app.
Post by Michal Suchanek
With touch interface it's pretty much the
same thing. With click-to-focus also. If you want to prevent data
leaks you can unmap windows that should not receive the paste or use a
compositor with per-application access policy for clipboards.
Those are all compositor dependent policies, I think something should
be done at the protocol level.
Post by Michal Suchanek
So instead of saying that a button down event should trigger paste in
the protocol specification
Nothing like that is mentioned. Wording is deliberately ambiguous as
to which event triggers primary selection paste.
Post by Michal Suchanek
it is wiser to say that sending the paste
offer to a client can happen at the discretion of the compositor and
suggest some reasonable policy.
What is unreasonable about serial checking?
How is the serial related to the paste? How is the application
supposed to pick serial so it can receive the paste? You can pick the
event which triggers the paste in the application logic. Will that
mean that when compositor fails to check events from a device (or the
application uses a device exclusively and possibly directly drives the
hardware) binding to some buttons will work and binding to other
buttons will fail?

Why is checking that the application can receive an offer when the
offer is sent not sufficient for the application to receive the paste?

When you want to prevent applications from receiving a paste in the
future you can always change the selection.
Post by Carlos Garnacho
Post by Michal Suchanek
Compositor should be free to implement any policy the author finds
reasonable including broadcast on selection change, point to paste,
button press to paste, and per-application different policies.
So you want the protocol to be purposely ambigous on data leak situations?
Let's take the most extreme case, primary selection can be broadcasted
and clients can be free to read data right away. You've just allowed
compositors to replicate all the flaws of X11 primary selection.
And you have allowed all the legacy X11 clients to perform flawlessly.

So it's fine to suggest reasonable default policy for compositor
implementors but it's also fine to allow for different policies.

I would not mandate broadcasting the selection changes
indiscriminately. However, if people are concerned about applications
that listen for the broadcasts in X11 land it should be possible to
set up special policy for them so they can receive the broadcasts in
Wayland as well. Similarly when an application is supposed to run
sandboxed and there is enough concern about information leak through
clipboard it should be possible to set up a policy for it to never
receive selection offers.

Thanks

Michal
Michal Suchanek
2016-02-23 22:39:04 UTC
Permalink
Post by Michal Suchanek
Post by Carlos Garnacho
Right, that's why I suggest having those reunited in a single logical
focus. Anything else is plagued of corner cases.
That's totally not going to work. When you have multiple touch panels
you can touch multiple places. Are you proposing that on whichever
panel you happen to touch first locks the other panel from working or
on whichever panel you touch last steals the touch on the earlier
panel?
I do not think either is expected behaviour.
What? Absolutely this is the expected behavior. All the touch events go to
the same client as the first touch event. For a more obvioius example,
keystrokes and modifier states need to be sent to the client that you are
pressing a mouse button on, even if the "keyboard focus" is some other
client. There is only one focus for every single thing in the seat, the
thing you are calling the "keyboard focus" is just a helper for what that
focus is when no mouse buttons are held down.
If you want them to go to different clients, put the touch panels on
different seats.
I fully agree that having "number of focus" != "number of seats" is going to
be plagued with corner cases.
Post by Michal Suchanek
Post by Carlos Garnacho
Citation needed :). Windows can be certainly arranged so that it's not
possible to move the pointer between app A and B without going through
a third application. The problem with doing this on pointer focus is
That can happen only with relative axis. With absolute axis you can
point anywhere anytime without going through anywhere else. Let's say
that for the sake of rodent users it is better to consider entry and
motion events insignificant.
Who cares that it can't happen for absolute axis. It does happen for
relative and those exist, even if you personally don't own a mouse.
Post by Michal Suchanek
Post by Carlos Garnacho
What is unreasonable about serial checking?
How is the serial related to the paste? How is the application
supposed to pick serial so it can receive the paste? You can pick the
event which triggers the paste in the application logic. Will that
mean that when compositor fails to check events from a device (or the
application uses a device exclusively and possibly directly drives the
hardware) binding to some buttons will work and binding to other
buttons will fail?
It's really easy: the client sends the event it thinks triggered the paste.
The compositor checks to make sure it is an event that really existed and
that it counts as some active user interaction (ie it is a mouse or keyboard
click). If the client sends a fake event or a focus-in event or anything
else the compositor does not like, it will not get access to the clipboard
data.
The entire point of this is so that it would be possible to put sensitive
data into the selection, because client cannot look at it without the user
doing something obvious, such as clicking. Moving the mouse around should
not cause clients to be able to look at the selection.
Post by Michal Suchanek
Post by Carlos Garnacho
Let's take the most extreme case, primary selection can be broadcasted
and clients can be free to read data right away. You've just allowed
compositors to replicate all the flaws of X11 primary selection.
And you have allowed all the legacy X11 clients to perform flawlessly.
Except that the user has to be careful to not select passwords or banking
numbers or anything else sensitive.
Post by Michal Suchanek
So it's fine to suggest reasonable default policy for compositor
implementors but it's also fine to allow for different policies.
I would not mandate broadcasting the selection changes
indiscriminately. However, if people are concerned about applications
that listen for the broadcasts in X11 land it should be possible to
set up special policy for them so they can receive the broadcasts in
Wayland as well. Similarly when an application is supposed to run
sandboxed and there is enough concern about information leak through
clipboard it should be possible to set up a policy for it to never
receive selection offers.
It sounds like you are basically saying "paste does not work unless the
client is specially privileged".
You are saying that also. You say that the client must have keyboard
focus to receive pastes.

What I add is that different policies might be viable and useful and
the protocol should not preclude the compositor from using different
policies.
The reason for the serial is so that the compositor can decide whether to
honor a request for the clipboard. You can still have specially privileged
clients that can get it for any event, this is for "normal" clients so that
paste works.
And since there is already policy in place that gives client(s) the
privilege to receive pastes it is redundant to check a client-supplied
random input event serial number when the client must already pass a
policy check to receive a paste offer in the first place. It might
also prevent policies that would allow pasting into applications that
do not use (compositor visible) input to trigger the paste.
I think you may be fretting too much about X11 compatibility. I would just
assume that X11 clients do not request the clipboard contents until after
the event that triggers the paste. The X11 emulator can then guess the
triggering event and send it to Wayland. There is no need to give X11
clients more powers than Wayland ones.
It is irrelevant if the application is native Wayland application or a
X11 application. There is use for the clipboard change broadcasts in
X11 so they can be useful in similar ways in Wayland. Besides the
obvious clip managers there are eg. download managers that collect
subsequently selected URLs or remote control applications that forward
the clipboard to another machine.

Thanks

Michal
Jonas Ådahl
2016-02-24 04:33:10 UTC
Permalink
Post by Carlos Garnacho
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.
---
After having talked with Lyude, I'll be trying to move this ahead.
- 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
+
+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
+
+ 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>
+
+ <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.
+
+ 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>
+
+ <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"/>
While reviewing the implementation, I noticed that while
wl_data_device.set_selection takes a serial, the set_selection here
doesn't. Does this mean that a client can set the selection without
foucus and without any user interaction?

It seems reasonable to me to require this as (not only offer.receive)
would require a valid serial to have any effect.


Jonas
Post by Carlos Garnacho
+ </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
+ 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>
--
2.5.0
_______________________________________________
wayland-devel mailing list
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Michal Suchanek
2016-02-24 09:25:19 UTC
Permalink
Post by Jonas Ådahl
Post by Carlos Garnacho
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.
---
After having talked with Lyude, I'll be trying to move this ahead.
- 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
+
+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
+
+ 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>
+
+ <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.
+
+ 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>
+
+ <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"/>
While reviewing the implementation, I noticed that while
wl_data_device.set_selection takes a serial, the set_selection here
doesn't. Does this mean that a client can set the selection without
foucus and without any user interaction?
It seems reasonable to me to require this as (not only offer.receive)
would require a valid serial to have any effect.
Actually it seems reasonable to not require a serial for anything. If
the application has a valid offer for the current selection it should
be able to get it or set a new one (unless it's for some reason denied
one of the operations altogether).

That's one place to check the policy and it works with middle mouse
button paste, any other event the compositor knows of, any even the
compositor dose not know of ( such as remote desktop/remote control
apps, input devices used directly by the application, .. ) and
anything else.

Thanks

Michal
Jonas Ådahl
2016-02-24 09:54:01 UTC
Permalink
Post by Michal Suchanek
Post by Jonas Ådahl
Post by Carlos Garnacho
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.
---
After having talked with Lyude, I'll be trying to move this ahead.
- 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
+
+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
+
+ 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>
+
+ <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.
+
+ 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>
+
+ <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"/>
While reviewing the implementation, I noticed that while
wl_data_device.set_selection takes a serial, the set_selection here
doesn't. Does this mean that a client can set the selection without
foucus and without any user interaction?
It seems reasonable to me to require this as (not only offer.receive)
would require a valid serial to have any effect.
Actually it seems reasonable to not require a serial for anything. If
the application has a valid offer for the current selection it should
be able to get it or set a new one (unless it's for some reason denied
one of the operations altogether).
The serial is there to make it possible to match an event in the server
with the received event on the client. We cannot know what event a
client is responding to without such an serial.

The comment above is about adding a requirement that the set_selection
(which sets a source object as the primary selection) is in response to
an event of some kind (I'd say click/press/release/touch-down/touch-up
etc). Exactly what that event is is up to the compositor, but we should
set up expectations on what type of events it is, so that clients don't
start trying to set selections or receive offers on only wl_pointer
enter if that most likely will not work.
Post by Michal Suchanek
That's one place to check the policy and it works with middle mouse
button paste, any other event the compositor knows of, any even the
compositor dose not know of ( such as remote desktop/remote control
apps, input devices used directly by the application, .. ) and
anything else.
Not sure what it is you are talking about here. In Wayland the
compositor is definitely aware of remote desktop and other "remote
control" systems. Applications has no way of injecting events in the
event stream via the Wayland protocol and that is by design.


Jonas
Post by Michal Suchanek
Thanks
Michal
Michal Suchanek
2016-03-01 10:34:56 UTC
Permalink
Post by Jonas Ådahl
Post by Michal Suchanek
Post by Jonas Ådahl
Post by Carlos Garnacho
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.
---
After having talked with Lyude, I'll be trying to move this ahead.
- 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
+
+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
+
+ 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>
+
+ <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.
+
+ 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>
+
+ <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"/>
While reviewing the implementation, I noticed that while
wl_data_device.set_selection takes a serial, the set_selection here
doesn't. Does this mean that a client can set the selection without
foucus and without any user interaction?
It seems reasonable to me to require this as (not only offer.receive)
would require a valid serial to have any effect.
Actually it seems reasonable to not require a serial for anything. If
the application has a valid offer for the current selection it should
be able to get it or set a new one (unless it's for some reason denied
one of the operations altogether).
The serial is there to make it possible to match an event in the server
with the received event on the client. We cannot know what event a
client is responding to without such an serial.
The comment above is about adding a requirement that the set_selection
(which sets a source object as the primary selection) is in response to
an event of some kind (I'd say click/press/release/touch-down/touch-up
etc). Exactly what that event is is up to the compositor, but we should
set up expectations on what type of events it is, so that clients don't
start trying to set selections or receive offers on only wl_pointer
enter if that most likely will not work.
It's reasonable so long as it is a selection offer serial. However,
you require an unrelated and possibly hard to figure out input event
serial making the protocol needlessly vague and fragile.
Post by Jonas Ådahl
Post by Michal Suchanek
That's one place to check the policy and it works with middle mouse
button paste, any other event the compositor knows of, any even the
compositor dose not know of ( such as remote desktop/remote control
apps, input devices used directly by the application, .. ) and
anything else.
Not sure what it is you are talking about here. In Wayland the
compositor is definitely aware of remote desktop and other "remote
control" systems. Applications has no way of injecting events in the
event stream via the Wayland protocol and that is by design.
OK, so let's take an example of an application that uses a special
controller directly without going through the compositor. Then pasting
using one button (compositor controlled) will work and pasting using
other button (directly application-controlled) will not. We cannot
expect that wayland will at all times have driver for every input
controller under the sun so things like this will probably happen.
Users will probably not find it too strange that pasting using special
controller button will fail at the same time pasting using a mouse
button would.

Another application is remote control client showing a remote desktop.
Looking at the current remote wayland solution wayland protocol does
not seem to be used even for remote wayland desktops. For other
desktops it cannot be used at all. A paste on the remote desktop may
be triggered by an event that was caused locally and went through the
local compositor or an event that was forwarded by another client from
another location or an event that happened on the physical seat if one
exists. Either way inferring a local event that triggered the paste is
pretty much impossible even if one existed in the first place. Even if
wayland protocol was used on the wire you would need to keep a
dictionary of event serials so you can translate remote event serials
to local event serials. What event serial should the remote desktop
client application supply when forwarding the local clipboard seems to
be the right thing according to its clipboard handling settings?

Thanks

Michal
Jonas Ådahl
2016-02-24 06:53:05 UTC
Permalink
Post by Carlos Garnacho
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.
---
After having talked with Lyude, I'll be trying to move this ahead.
- 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
+
+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
+
+ 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>
+
+ <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.
+
+ 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>
+
+ <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">
Another nit: This should rather be "primary_selection_offer" or just "offer". In
the other interface its called "data_offer" because it advertises a new
wl_data_offer. We advertise a wp_primary_selection_offer.


Jonas
Post by Carlos Garnacho
+ <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
+ 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>
--
2.5.0
_______________________________________________
wayland-devel mailing list
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Bryce Harrington
2016-03-11 21:48:43 UTC
Permalink
Post by Carlos Garnacho
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.
---
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?
Post by Carlos Garnacho
- 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
+
+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
+
+ 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.
Post by Carlos Garnacho
+ <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.
Post by Carlos Garnacho
+ 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.
Post by Carlos Garnacho
+ <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"
Post by Carlos Garnacho
+ 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

Continue reading on narkive:
Loading...