blob: b228dc158a8e953254820f9176cb78d78d3cea75 [file] [log] [blame]
Foxe Chenb90c2392025-06-27 21:10:35 +02001*wayland.txt* For Vim version 9.1. Last change: 2025 Jun 27
2
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Wayland Protocol Support *wayland*
8
91. Useful Wayland information |wayland-useful|
102. Wayland selections |wayland-selections|
11
12==============================================================================
131. Useful Wayland information *wayland-useful*
14
15 *wayland-seat*
16Functionality such as the clipboard for Wayland requires a seat to use. A
17Wayland seat can consist of a keyboard, pointer, and touch device(s). The
18seat to use can be set with the 'wlseat' option. Only useful if you use
19multiple Wayland seats in the same Wayland session.
20
21 *wayland-gui*
22See |gui-wayland|. Please note that when using the GUI, Vim uses the toolkit
23such as GTK for accessing the clipboard, and does not access the clipboard
24though Wayland. You can check this though the |v:clipmethod| variable, which
25should equal to "none" when running the GUI.
26
27Wayland commands:
28 *:wlrestore* *:wl*
29:wl[estore] [display] Reinitializes the connection to the wayland compositor.
30 Useful when running Vim in a screen/tmux session that
31 continues running after the Wayland compositor
32 restarts.
33
34 [display] should be in the format of the
35 $WAYLAND_DISPLAY environment variable (e.g.
36 "wayland-0"). If [display] is omitted, then it
37 reinitializes the connection using the same value as
38 was used for the previous execution of this command.
39 If the value was never specified, then it uses the
40 value of $WAYLAND_DISPLAY environment variable. This
41 will also update |v:clipmethod|.
42 {only available when compiled with the |+wayland| feature}
43
44Wayland errors:
45 *E1548*
46Vim failed communicating with the wayland compositor. This is likely due to
47the Wayland compositor process being killed. Try the `:wlrestore` command to
48try connecting again.
49
50==============================================================================
512. Wayland Selections *wayland-selections*
52
53Vim supports the wlr-data-control-unstable-v1 and ext-data-control-v1
54protocols, for accessing the current Wayland selection. These are the best
55case scenario protocols, see |wayland-focus-steal|. Selection in this case
56essentially means the "clipboard." You can check if your Wayland compositor
57supports either of these protocols by running the wayland-info command, which
58should be bunded with libwayland on your system: >
59 wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
60<If grep finds a match, then you have either or both protocols on your system.
61If you don't get any match, then please see |wayland-focus-steal| for more
62information.
63
64If you come from X11, then the regular wayland selection is equivalent to the
65CLIPBOARD selection in X11, and the primary wayland selection equates to the
66X11 primary selection. Accessing these selections is the same as X11 in Vim,
67in which the + register is the regular selection, and the * register is the
68primary selection, note that your compositor may not support primary
69selections, see |wayland-primary-selection| for more details.
70
71 *wayland-persist*
72If you use X11 cut buffers, no such things exist on Wayland. Instead to
73emulate such functionality, a separate clipboard manager must be used in order
74to persist selection data when a Wayland client exists.
75
76 *wayland-and-x11*
77If your version of Vim comes compiled with both X11 and Wayland support, then
78Vim determines which one to use when accessing the clipboard using the
79'clipmethod' option.
80
81 *wayland-primary-selection*
82If you find X11 style primary selections useful, Wayland also implements this
83behaviour in its own protocols:
84
85- The primary selection protocol is the most widely supported, but requires
86 focus in order to be used, see |wayland-focus-steal|.
87
88- Data control protocol available on your system, such as the ext or wlr
89 protocols, then primary selection is also supported. This is unless you are
90 using version 1 (not the same as the 'v1' in the protocol name), of the
91 wlr-data-control protocol. Then the primary selection protocol will be used
92 as a fallback.
93
94 *wayland-focus-steal* *wayland-gnome*
95If you are using the GNOME desktop environment on Wayland, as of this writing,
96there is no method of accessing/modifying the clipboard for external clients
97such as Vim without being focused. Focused in this case means the client has
98received some sort of input event, such as a window being focused. This is
99what the wlr-data-control-unstable-v1 and ext-data-control-v1 protocols solve.
100If your Wayland compositor does not support the above protocols, then the
101above explanation applies.
102
103To solve this problem, Vim implements a way of gaining focus in order to
104access the clipboard, by creating a temporary transparent top-level surface.
105This is by default disabled and can be enabled via the 'wlsteal' option.
106Moreover, a seat that has a keyboard is also required, see 'wlseat', and the
107xdg-shell protocol must be available.
108
109Note that this method can have several side effects from the result of focus
110stealing. For example, if you have a taskbar that shows currently opened apps
111in your desktop environment, then when Vim attempts to steal focus, it may
112"flicker," as if a window was opened then immediately closed after.
113Additionally, if you are in fullscreen mode, this focus stealing won't work,
114because the created surface won't ever gain focus. If this happens, Vim will
115seem to freeze temporarily, see 'wltimeoutlen' for more information.
116
117 vim:tw=78:sw=4:ts=8:noet:ft=help:norl:js