vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

wayland.txt (5469B)


      1 *wayland.txt*	For Vim version 9.2.  Last change: 2026 Sep 14
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 Wayland Protocol Support				*wayland*
      8 
      9 1. Useful Wayland information	|wayland-useful|
     10 2. Wayland selections		|wayland-selections|
     11 
     12 ==============================================================================
     13 1. Useful Wayland information				*wayland-useful*
     14 
     15 							*wayland-seat*
     16 Functionality such as the clipboard for Wayland requires a seat to use.  A
     17 Wayland seat can consist of a keyboard, pointer, and touch device(s).  The
     18 seat to use can be set with the 'wlseat' option.  Only useful if you use
     19 multiple Wayland seats in the same Wayland session.  If you don't know what
     20 this is means, then it likely does not matter for you.
     21 
     22 							*wayland-gui*
     23 See |gui-wayland|.  Please note that when using the GUI, Vim uses the toolkit
     24 such as GTK for accessing the clipboard, and does not access the clipboard
     25 though Wayland.  You can check this though the |v:clipmethod| variable, which
     26 should equal to "none" when running the GUI.
     27 
     28 Wayland commands:
     29 							*:wlrestore* *:wl*
     30 :wl[restore] [display]	Reinitializes the connection to the Wayland
     31 			compositor.
     32 			Useful when running Vim in a screen/tmux session that
     33 			continues running after the Wayland compositor
     34 			restarts.
     35 
     36 			[display] should be in the format of the
     37 			$WAYLAND_DISPLAY environment variable (e.g.
     38 			"wayland-0").  If [display] is omitted, then it
     39 			reinitializes the connection using the same value as
     40 			was used for the previous execution of this command.
     41 			If the value was never specified, then it uses the
     42 			value of $WAYLAND_DISPLAY environment variable.  This
     43 			will also update |v:clipmethod|.
     44 			{only available when compiled with the |+wayland|
     45 			feature}
     46 
     47 Wayland errors:
     48 							*E1548*
     49 Vim failed communicating with the Wayland compositor.  This is likely due to
     50 the Wayland compositor process being killed.  Try the `:wlrestore` command to
     51 try connecting again.
     52 
     53 ==============================================================================
     54 2. Wayland Selections					*wayland-selections*
     55 
     56 Vim supports the wlr-data-control-unstable-v1 and ext-data-control-v1
     57 protocols, for accessing the current Wayland selection. Selection in this case
     58 essentially means the "clipboard."  You can check if your Wayland compositor
     59 supports either of these protocols by running the wayland-info command, which
     60 should be bundled with libwayland on your system: >
     61 	wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
     62 <If grep finds a match, then you have either or both protocols on your system.
     63 
     64 Some compositors that are known to support either or both protocols:
     65     1. KWin (KDE)
     66     2. wlroots based (Sway, Labwc)
     67     3. Niri
     68     4. Hyprland
     69     5. Wayfire
     70 
     71 If you come from X11, then the regular Wayland selection is equivalent to the
     72 CLIPBOARD selection in X11, and the primary Wayland selection equates to the
     73 X11 PRIMARY selection.  Accessing these selections is the same as X11 in Vim,
     74 in which the + register is the regular selection, and the * register is the
     75 primary selection.  Note that your compositor may not support primary
     76 selections, see |wayland-primary-selection| for more details.
     77 
     78 							*wayland-persist*
     79 If you use X11 cut buffers, no such things exist on Wayland.  Instead to
     80 emulate such functionality, a separate clipboard manager must be used in order
     81 to persist selection data when a Wayland client exits.
     82 
     83 							*wayland-and-x11*
     84 If your version of Vim comes compiled with both X11 and Wayland support, then
     85 Vim determines which one to use when accessing the clipboard using the
     86 'clipmethod' option.
     87 
     88 						*wayland-primary-selection*
     89 If you find X11 style primary selections useful, Wayland also implements this
     90 feature using the protocols that Vim supports.  This is unless you are using
     91 version 1 (not the same as the 'v1' in the protocol name), of the
     92 wlr-data-control protocol, then primary selection will not be supported. You
     93 can check this using >
     94 	wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
     95 If the "version:" entry for "zwlr_data_control_manager_v1" is "2" or greater,
     96 then primary selection is supported.  If you also get
     97 "ext_data_control_manager_v1", then Vim will use that protocol instead, which
     98 has primary selection support builtin into it.
     99 
    100 If your Wayland compositor does not support the wlr-data-control-v1 or the
    101 ext-data-control-v1 protocol, Vim cannot access the clipboard directly through
    102 the Wayland protocol.  External tools such as wl-clipboard can be used instead
    103 via a user-defined |clipboard-providers|.
    104 
    105 Example: define a provider that shells out to `wl-copy` and `wl-paste`: >vim9
    106 
    107     vim9script
    108 
    109     def Available(): bool
    110 	return executable('wl-copy') && executable('wl-paste')
    111     enddef
    112 
    113     def Copy(reg: string, type: string, str: list<string>)
    114 	var args = "wl-copy"
    115 
    116 	if reg == "*"
    117 	    args ..= " -p"
    118 	endif
    119 
    120 	silent system(args, str)
    121     enddef
    122 
    123     def Paste(reg: string): tuple<string, list<string>>
    124 	var args = "wl-paste --type text/plain;charset=utf-8"
    125 
    126 	if reg == "*"
    127 	    args ..= " -p"
    128 	endif
    129 
    130 	silent return ("", systemlist(args))
    131     enddef
    132 
    133     v:clipproviders["wl_clipboard"] = {
    134 	available: Available,
    135 	copy: {
    136 	    "+": Copy,
    137 	    "*": Copy
    138 	},
    139 	paste: {
    140 	    "+": Paste,
    141 	    "*": Paste
    142 	}
    143     }
    144 
    145     set clipmethod=wl_clipboard
    146 
    147 
    148 This relies on the wl-clipboard package being installed
    149 (https://github.com/bugaevc/wl-clipboard).
    150 
    151  vim:tw=78:ts=8:noet:ft=help:norl