patch 9.1.1485: missing Wayland clipboard support
Problem: missing Wayland clipboard support
Solution: make it work (Foxe Chen)
fixes: #5157
closes: #17097
Signed-off-by: Foxe Chen <chen.foxe@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/doc/wayland.txt b/runtime/doc/wayland.txt
new file mode 100644
index 0000000..b228dc1
--- /dev/null
+++ b/runtime/doc/wayland.txt
@@ -0,0 +1,117 @@
+*wayland.txt* For Vim version 9.1. Last change: 2025 Jun 27
+
+
+ VIM REFERENCE MANUAL by Bram Moolenaar
+
+
+Wayland Protocol Support *wayland*
+
+1. Useful Wayland information |wayland-useful|
+2. Wayland selections |wayland-selections|
+
+==============================================================================
+1. Useful Wayland information *wayland-useful*
+
+ *wayland-seat*
+Functionality such as the clipboard for Wayland requires a seat to use. A
+Wayland seat can consist of a keyboard, pointer, and touch device(s). The
+seat to use can be set with the 'wlseat' option. Only useful if you use
+multiple Wayland seats in the same Wayland session.
+
+ *wayland-gui*
+See |gui-wayland|. Please note that when using the GUI, Vim uses the toolkit
+such as GTK for accessing the clipboard, and does not access the clipboard
+though Wayland. You can check this though the |v:clipmethod| variable, which
+should equal to "none" when running the GUI.
+
+Wayland commands:
+ *:wlrestore* *:wl*
+:wl[estore] [display] Reinitializes the connection to the wayland compositor.
+ Useful when running Vim in a screen/tmux session that
+ continues running after the Wayland compositor
+ restarts.
+
+ [display] should be in the format of the
+ $WAYLAND_DISPLAY environment variable (e.g.
+ "wayland-0"). If [display] is omitted, then it
+ reinitializes the connection using the same value as
+ was used for the previous execution of this command.
+ If the value was never specified, then it uses the
+ value of $WAYLAND_DISPLAY environment variable. This
+ will also update |v:clipmethod|.
+ {only available when compiled with the |+wayland| feature}
+
+Wayland errors:
+ *E1548*
+Vim failed communicating with the wayland compositor. This is likely due to
+the Wayland compositor process being killed. Try the `:wlrestore` command to
+try connecting again.
+
+==============================================================================
+2. Wayland Selections *wayland-selections*
+
+Vim supports the wlr-data-control-unstable-v1 and ext-data-control-v1
+protocols, for accessing the current Wayland selection. These are the best
+case scenario protocols, see |wayland-focus-steal|. Selection in this case
+essentially means the "clipboard." You can check if your Wayland compositor
+supports either of these protocols by running the wayland-info command, which
+should be bunded with libwayland on your system: >
+ wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
+<If grep finds a match, then you have either or both protocols on your system.
+If you don't get any match, then please see |wayland-focus-steal| for more
+information.
+
+If you come from X11, then the regular wayland selection is equivalent to the
+CLIPBOARD selection in X11, and the primary wayland selection equates to the
+X11 primary selection. Accessing these selections is the same as X11 in Vim,
+in which the + register is the regular selection, and the * register is the
+primary selection, note that your compositor may not support primary
+selections, see |wayland-primary-selection| for more details.
+
+ *wayland-persist*
+If you use X11 cut buffers, no such things exist on Wayland. Instead to
+emulate such functionality, a separate clipboard manager must be used in order
+to persist selection data when a Wayland client exists.
+
+ *wayland-and-x11*
+If your version of Vim comes compiled with both X11 and Wayland support, then
+Vim determines which one to use when accessing the clipboard using the
+'clipmethod' option.
+
+ *wayland-primary-selection*
+If you find X11 style primary selections useful, Wayland also implements this
+behaviour in its own protocols:
+
+- The primary selection protocol is the most widely supported, but requires
+ focus in order to be used, see |wayland-focus-steal|.
+
+- Data control protocol available on your system, such as the ext or wlr
+ protocols, then primary selection is also supported. This is unless you are
+ using version 1 (not the same as the 'v1' in the protocol name), of the
+ wlr-data-control protocol. Then the primary selection protocol will be used
+ as a fallback.
+
+ *wayland-focus-steal* *wayland-gnome*
+If you are using the GNOME desktop environment on Wayland, as of this writing,
+there is no method of accessing/modifying the clipboard for external clients
+such as Vim without being focused. Focused in this case means the client has
+received some sort of input event, such as a window being focused. This is
+what the wlr-data-control-unstable-v1 and ext-data-control-v1 protocols solve.
+If your Wayland compositor does not support the above protocols, then the
+above explanation applies.
+
+To solve this problem, Vim implements a way of gaining focus in order to
+access the clipboard, by creating a temporary transparent top-level surface.
+This is by default disabled and can be enabled via the 'wlsteal' option.
+Moreover, a seat that has a keyboard is also required, see 'wlseat', and the
+xdg-shell protocol must be available.
+
+Note that this method can have several side effects from the result of focus
+stealing. For example, if you have a taskbar that shows currently opened apps
+in your desktop environment, then when Vim attempts to steal focus, it may
+"flicker," as if a window was opened then immediately closed after.
+Additionally, if you are in fullscreen mode, this focus stealing won't work,
+because the created surface won't ever gain focus. If this happens, Vim will
+seem to freeze temporarily, see 'wltimeoutlen' for more information.
+
+ vim:tw=78:sw=4:ts=8:noet:ft=help:norl:js