codekingpro/portable-devtools
114k
1*gui_x11.txt* For Vim version 9.2. Last change: 2026 Feb 142 3 4 VIM REFERENCE MANUAL by Bram Moolenaar5 6 7Vim's Graphical User Interface *gui-x11* *GUI-X11*8 *Motif*91. Starting the X11 GUI |gui-x11-start|102. GUI Resources |gui-resources|113. Shell Commands |gui-pty|124. Various |gui-x11-various|135. GTK version |gui-gtk|146. GNOME version |gui-gnome|157. KDE version |gui-kde|168. Compiling |gui-x11-compiling|179. X11 selection mechanism |x11-selection|18 19Other relevant documentation:20|gui.txt| For generic items of the GUI.21 22 23==============================================================================241. Starting the X11 GUI *gui-x11-start* *E665*25 26Then you can run the GUI version of Vim in either of these ways:27 gvim [options] [files...]28 vim -g [options] [files...]29 30So if you call the executable "gvim", or make "gvim" a link to the executable,31then the GUI version will automatically be used. Additional characters may be32added after "gvim", for example "gvim-5".33 34You may also start up the GUI from within the terminal version by using one of35these commands:36 :gui [++opt] [+cmd] [-f|-b] [files...] *:gu* *:gui*37 :gvim [++opt] [+cmd] [-f|-b] [files...] *:gv* *:gvim*38The "-f" option runs Vim in the foreground.39The "-b" option runs Vim in the background (this is the default).40Also see |++opt| and |+cmd|.41 42 *gui-fork*43When the GUI is started, it does a fork() and exits the current process.44When gvim was started from a shell this makes the shell accept further45commands. If you don't want this (e.g. when using gvim for a mail program46that waits for gvim to exit), start gvim with "gvim -f", "vim -gf" or use47":gui -f". Don't use "vim -fg", because "-fg" specifies the foreground48color.49 50When using "vim -f" and then ":gui", Vim will run in the foreground. The51"-f" argument will be remembered. To force running Vim in the background use52":gui -b".53 54"gvim --nofork" does the same as "gvim -f".55 56When there are running jobs Vim will not fork, because the processes would no57longer be child processes.58 *E851* *E852*59When starting the GUI fails Vim will try to continue running in the terminal.60 61If you want the GUI to run in the foreground always, include the 'f'62flag in 'guioptions'. |-f|.63 64==============================================================================652. GUI Resources *gui-resources* *.Xdefaults*66 67If using the Motif version of the GUI (not for the KDE, GTK+ or Win3268version), a number of X resources are available. You should use Vim's class69"Vim" when setting these. They are as follows:70 71 Resource name Meaning ~72 73 reverseVideo Boolean: should reverse video be used?74 background Color of background.75 foreground Color of normal text.76 scrollBackground Color of trough portion of scrollbars.77 scrollForeground Color of slider and arrow portions of scrollbars.78 menuBackground Color of menu backgrounds.79 menuForeground Color of menu foregrounds.80 tooltipForeground Color of tooltip and balloon foreground.81 tooltipBackground Color of tooltip and balloon background.82 83 font Name of font used for normal text.84 boldFont Name of font used for bold text.85 italicFont Name of font used for italic text.86 boldItalicFont Name of font used for bold, italic text.87 menuFont Name of font used for the menus, used when compiled88 without the |+xfontset| feature89 menuFontSet Name of fontset used for the menus, used when compiled90 with the |+xfontset| feature91 tooltipFont Name of the font used for the tooltip and balloons.92 When compiled with the |+xfontset| feature this is a93 fontset name.94 95 geometry Initial geometry to use for gvim's window (default96 is same size as terminal that started it).97 scrollbarWidth Thickness of scrollbars.98 borderWidth Thickness of border around text area.99 100A special font for italic, bold, and italic-bold text will only be used if101the user has specified one via a resource. No attempt is made to guess what102fonts should be used for these based on the normal text font.103 104Note that the colors can also be set with the ":highlight" command, using the105"Normal", "Menu", "Tooltip", and "Scrollbar" groups. Example: >106 :highlight Menu guibg=lightblue107 :highlight Tooltip guibg=yellow108 :highlight Scrollbar guibg=lightblue guifg=blue109 :highlight Normal guibg=grey90110<111 *font-sizes*112Note: All fonts (except for the menu and tooltip) must be of the same size!!!113If you don't do this, text will disappear or mess up the display. Vim does114not check the font sizes. It's the size in screen pixels that must be the115same. Note that some fonts that have the same point size don't have the same116pixel size! Additionally, the positioning of the fonts must be the same117(ascent and descent). You can check this with "xlsfonts -l {fontname}".118 119If any of these things are also set with Vim commands, e.g. with120":set guifont=Screen15", then this will override the X resources (currently121'guifont' is the only option that is supported).122 123Here is an example of what you might put in your ~/.Xdefaults file: >124 125 Vim*useSchemes: all126 Vim*sgiMode: true127 Vim*useEnhancedFSB: true128 Vim.foreground: Black129 Vim.background: Wheat130 Vim*fontList: 7x13131 132The first three of these are standard resources on Silicon Graphics machines133which make Motif applications look even better, highly recommended!134 135The "Vim*fontList" is to set the menu font for Motif. Example: >136 Vim*menuBar*fontList: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*137 138NOTE: A more portable, and indeed more correct, way to specify the menu font139in Motif is through the resource: >140 Vim.menuFont: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*141Or, when compiled with the |+xfontset| feature: >142 Vim.menuFontSet: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*143 144Don't use "Vim*geometry" in the defaults. This will break the menus. Use145"Vim.geometry" instead.146 147If you get an error message "Cannot allocate colormap entry for "gray60",148try adding this to your Vim resources (change the colors to your liking): >149 150 Vim*scrollBackground: Black151 Vim*scrollForeground: Blue152 153The resources can also be set with arguments to Vim:154 155 argument meaning ~156 *-gui*157 -display {display} Run vim on {display} *-display*158 -iconic Start vim iconified *-iconic*159 -background {color} Use {color} for the background *-background*160 -bg {color} idem *-bg*161 -foreground {color} Use {color} for normal text *-foreground*162 -fg {color} idem *-fg*163 -ul {color} idem *-ul*164 -font {font} Use {font} for normal text *-font*165 -fn {font} idem *-fn*166 -boldfont {font} Use {font} for bold text *-boldfont*167 -italicfont {font} Use {font} for italic text *-italicfont*168 -menufont {font} Use {font} for menu items *-menufont*169 -menufontset {fontset} Use {fontset} for menu items *-menufontset*170 -mf {font} idem *-mf*171 -geometry {geom} Use {geom} for initial geometry *-geometry*172 -geom {geom} idem, see |-geometry-example| *-geom*173 -borderwidth {width} Use a border width of {width} *-borderwidth*174 -bw {width} idem *-bw*175 *-scrollbarwidth*176 -scrollbarwidth {width} Use a scrollbar width of {width}177 -sw {width} idem *-sw*178 -menuheight {height} Use a menu bar height of {height} *-menuheight*179 -mh {height} idem *-mh*180 NOTE: On Motif the value is ignored, the menu height181 is computed to fit the menus.182 -reverse Use reverse video *-reverse*183 -rv idem *-rv*184 +reverse Don't use reverse video *-+reverse*185 +rv idem *-+rv*186 -xrm {resource} Set the specified resource *-xrm*187 188Note about reverse video: Vim checks that the result is actually a light text189on a dark background. The reason is that some X11 versions swap the colors,190and some don't. These two examples will both give yellow text on a blue191background:192 gvim -fg Yellow -bg Blue -reverse193 gvim -bg Yellow -fg Blue -reverse194 195 *-geometry-example*196An example for the geometry argument: >197 gvim -geometry 80x63+8+100198This creates a window with 80 columns and 63 lines at position 8 pixels from199the left and 100 pixels from the top of the screen.200 201==============================================================================2023. Shell Commands *gui-pty*203 204WARNING: Executing an external command from the GUI will not always work.205"normal" commands like "ls", "grep" and "make" mostly work fine. Commands206that require an intelligent terminal like "less" and "ispell" won't work.207Some may even hang and need to be killed from another terminal. So be208careful!209 210There are two ways to do the I/O with a shell command: Pipes and a pseudo-tty.211The default is to use a pseudo-tty. This should work best on most systems.212 213Unfortunately, the implementation of the pseudo-tty is different on every Unix214system. And some systems require root permission. To avoid running into215problems with a pseudo-tty when you least expect it, test it when not editing216a file. Be prepared to "kill" the started command or Vim. Commands like217":r !cat" may hang!218 219If using a pseudo-tty does not work for you, reset the 'guipty' option: >220 221 :set noguipty222 223Using a pipe should work on any Unix system, but there are disadvantages:224- Some shell commands will notice that a pipe is being used and behave225 differently. E.g., ":!ls" will list the files in one column.226- The ":sh" command won't show a prompt, although it will sort of work.227- When using ":make" it's not possible to interrupt with a CTRL-C.228 229Typeahead while the external command is running is often lost. This happens230both with a pipe and a pseudo-tty. This is a known problem, but it seems it231can't be fixed (or at least, it's very difficult).232 233 *gui-pty-erase*234When your erase character is wrong for an external command, you should fix235this in your "~/.cshrc" file, or whatever file your shell uses for236initializations. For example, when you want to use backspace to delete237characters, but hitting backspaces produces "^H" instead, try adding this to238your "~/.cshrc": >239 stty erase ^H240The ^H is a real CTRL-H, type it as CTRL-V CTRL-H.241 242==============================================================================2434. Various *gui-x11-various*244 245 *gui-x11-printing*246The "File/Print" menu simply sends the current buffer to "lpr". No options or247whatever. If you want something else, you can define your own print command.248For example: >249 250 :10amenu File.Print :w !lpr -Php3251 :10vmenu File.Print :w !lpr -Php3252<253 *X11-icon*254Vim uses a black&white icon by default when compiled with Motif. A255colored Vim icon is included as $VIMRUNTIME/vim32x32.xpm. For GTK+, this is256the builtin icon used. Unfortunately, how you should install it depends on257your window manager. When you use this, remove the 'i' flag from258'guioptions', to remove the black&white icon: >259 :set guioptions-=i260 261If you use one of the fvwm* family of window managers simply add this line to262your .fvwm2rc configuration file: >263 264 Style "vim" Icon vim32x32.xpm265 266Make sure the icon file's location is consistent with the window manager's267ImagePath statement. Either modify the ImagePath from within your .fvwm2rc or268drop the icon into one the pre-defined directories: >269 270 ImagePath /usr/X11R6/include/X11/pixmaps:/usr/X11R6/include/X11/bitmaps271 272Note: older versions of fvwm use "IconPath" instead of "ImagePath".273 274For CDE "dtwm" (a derivative of Motif) add this line in the .Xdefaults: >275 Dtwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm276 277For "mwm" (Motif window manager) the line would be: >278 Mwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm279 280 281Mouse Pointers Available in X11 ~282 *X11_mouse_shapes*283By using the 'mouseshape' option, the mouse pointer can be automatically284changed whenever Vim enters one of its various modes (e.g., Insert or285Command). Currently, the available pointers are:286 287 arrow an arrow pointing northwest288 beam a I-like vertical bar289 size an arrow pointing up and down290 busy a wristwatch291 blank an invisible pointer292 crosshair a thin "+" sign293 hand1 a dark hand pointing northeast294 hand2 a light hand pointing northwest295 pencil a pencil pointing southeast296 question question_arrow297 right_arrow an arrow pointing northeast298 up_arrow an arrow pointing upwards299 300Additionally, any of the mouse pointers that are built into X11 may be301used by specifying an integer from the X11/cursorfont.h include file.302 303If a name is used that exists on other systems, but not in X11, the default304"arrow" pointer is used.305 306==============================================================================3075. GTK version *gui-gtk* *GTK+* *GTK* *GTK3*308 309The GTK version of the GUI works a little bit different.310 311GTK does _not_ use the traditional X resource settings. Thus items in your312~/.Xdefaults or app-defaults files are not used.313Many of the traditional X command line arguments are not supported. (e.g.,314stuff like -bg, -fg, etc). The ones that are supported are:315 316 command line argument resource name meaning ~317 -fn or -font .font font name for the text318 -geom or -geometry .geometry size of the gvim window319 -rv or -reverse *reverseVideo white text on black background320 -display display to be used321 -fg -foreground {color} foreground color322 -bg -background {color} background color323 324To set the font, see 'guifont'. For GTK, there's also a menu option that does325this.326 327Additionally, there are these command line arguments, which are handled by GTK328internally. Look in the GTK documentation for how they are used:329 --sync330 --gdk-debug331 --gdk-no-debug332 --no-xshm (not in GTK+ 2)333 --xim-preedit (not in GTK+ 2)334 --xim-status (not in GTK+ 2)335 --gtk-debug336 --gtk-no-debug337 --g-fatal-warnings338 --gtk-module339 --display (GTK+ counterpart of -display; works the same way.)340 --screen (The screen number; for GTK+ 2.2 multihead support.)341 342These arguments are ignored when the |+netbeans_intg| feature is used:343 -xrm344 -mf345 346As for colors, Vim's color settings (for syntax highlighting) is still347done the traditional Vim way. See |:highlight| for more help.348 349If you want to set the colors of remaining gui components (e.g., the350menubar, scrollbar, whatever), those are GTK specific settings and you351need to set those up in some sort of gtkrc file. You'll have to refer352to the GTK documentation, however little there is, on how to do this.353See https://www.manpagez.com/html/gtk2/gtk2-2.24.24/gtk2-Resource-Files.php354for more information.355 *gtk3-slow*356If you are using GTK3 and Vim appears to be slow, try setting the environment357variable $GDK_RENDERING to "image".358 359 360Tooltip Colors ~361 *gtk-tooltip-colors*362Example, which sets the tooltip colors to black on light-yellow: >363 364 style "tooltips"365 {366 bg[NORMAL] = "#ffffcc"367 fg[NORMAL] = "#000000"368 }369 370 widget "gtk-tooltips*" style "tooltips"371 372Write this in the file ~/.gtkrc and it will be used by GTK+. For GTK+ 2373you might have to use the file ~/.gtkrc-2.0 instead, depending on your374distribution.375 376For GTK+ 3, an effect similar to the above can be obtained by adding the377following snippet of CSS code to $XDG_HOME_DIR/gtk-3.0/gtk.css (see the next378section):379 380For GTK+ 3 < 3.20: >381 382 .tooltip {383 background-color: #ffffcc;384 color: #000000;385 }386<387For GTK+ 3 >= 3.20: >388 389 tooltip {390 background-color: #ffffcc;391 text-shadow: none;392 }393 394 tooltip label {395 color: #2e3436;396 }397<398 399A Quick Look at GTK+ CSS ~400 *gtk-css*401The contents of this subsection apply to GTK+ 3.20 or later which provides402stable support for GTK+ CSS:403 404 https://developer.gnome.org/gtk3/stable/theming.html405 406GTK+ uses CSS for styling and layout of widgets. In this subsection, we'll407have a quick look at GTK+ CSS through simple, illustrative examples.408 409You can usually edit the config with: >410 vim $HOME/.config/gtk-3.0/gtk.css411 412 413Example 1. Empty Space Adjustment ~414 415By default, the toolbar and the tabline of the GTK+ 3 GUI are somewhat larger416than those of the GTK+ 2 GUI. Some people may want to make them look similar417to the GTK+ 2 GUI in size.418 419To do that, we'll try reducing empty space around icons and labels that looks420apparently superfluous.421 422Add the following lines to $XDG_HOME_DIR/gtk-3.0/gtk.css (usually,423$HOME/.config/gtk-3.0/gtk.css): >424 425 toolbar button {426 margin-top: -2px;427 margin-right: 0px;428 margin-bottom: -2px;429 margin-left: 0px;430 431 padding-top: 0px;432 padding-right: 0px;433 padding-bottom: 0px;434 padding-left: 0px435 }436 437 notebook tab {438 margin-top: -1px;439 margin-right: 3px;440 margin-bottom: -1px;441 margin-left: 3px;442 443 padding-top: 0px;444 padding-right: 0px;445 padding-bottom: 0px;446 padding-left: 0px447 }448<449Since it's a CSS, they can be rewritten using shorthand: >450 451 toolbar button {452 margin: -2px 0px;453 padding: 0px;454 }455 456 notebook tab {457 margin: -1px 3px;458 padding: 0px459 }460<461Note: You might want to use 'toolbariconsize' to adjust the icon size, too.462 463Note: Depending on the icon theme and/or the font in use, some extra tweaks464may be needed for a satisfactory result.465 466Note: In addition to margin and padding, you can use border. For details,467refer to the box model of CSS, e.g.,468 469 https://www.w3schools.com/css/css_boxmodel.asp470 471Example 2. More Than Just Colors ~472 473GTK+ CSS supports gradients as well: >474 475 tooltip {476 background-image: -gtk-gradient(linear,477 0 0, 0 1,478 color-stop(0, #344752),479 color-stop(0.5, #546772),480 color-stop(1, #243742));481 }482 483 tooltip label {484 color: #f3f3f3;485 }486<487Gradients can be used to make a GUI element visually distinguishable from488others without relying on high contrast. Accordingly, effective use of them is489a useful technique to give a theme a sense of unity in color and luminance.490 491Note: Theming can be difficult since it must make every application look492equally good; making a single application more charming often gets others493unexpectedly less attractive or even deteriorates their usability. Keep this494in mind always when you try improving a theme.495 496 497Example 3. border color ~498 499To eliminate borders when maximized: >500 501 @define-color bg_color #1B2B34;502 #vim-main-window {503 background-color: @bg_color;504 }505 506 507Using Vim as a GTK+ plugin ~508 *gui-gtk-socketid*509When the GTK+ version of Vim starts up normally, it creates its own top level510window (technically, a 'GtkWindow'). GTK+ provides an embedding facility with511its GtkSocket and GtkPlug widgets. If one GTK+ application creates a512GtkSocket widget in one of its windows, an entirely different GTK+ application513may embed itself into the first application by creating a top-level GtkPlug514widget using the socket's ID.515 516If you pass Vim the command-line option '--socketid' with a decimal or517hexadecimal value, Vim will create a GtkPlug widget using that value instead518of the normal GtkWindow. This enables Vim to act as a GTK+ plugin.519 520This really is a programmer's interface, and is of no use without a supporting521application to spawn the Vim correctly. For more details on GTK+ sockets, see522https://www.gtk.org/docs/apis/index523 524Note that this feature requires the latest GTK version. GTK 1.2.10 still has525a small problem. The socket feature has not yet been tested with GTK+ 2 --526feel free to volunteer.527 528==============================================================================5296. GNOME version *gui-gnome* *Gnome* *GNOME*530 531The GNOME GUI works just like the GTK+ version. See |GTK+| above for how it532works. It looks a bit different though, and implements one important feature533that's not available in the plain GTK+ GUI: Interaction with the session534manager. |gui-gnome-session|535 536These are the different looks:537- Uses GNOME dialogs (GNOME 1 only). The GNOME 2 GUI uses the same nice538 dialogs as the GTK+ 2 version.539- Uses the GNOME dock, so that the toolbar and menubar can be moved to540 different locations other than the top (e.g., the toolbar can be placed on541 the left, right, top, or bottom). The placement of the menubar and542 toolbar is only saved in the GNOME 2 version.543- That means the menubar and toolbar handles are back! Yeah! And the544 resizing grid still works too.545 546GNOME is compiled with if it was found by configure and the547--enable-gnome-check argument was used.548 549Note: Avoid use of --enable-gnome-check with GTK+ 3 GUI build. The550functionality mentioned above is consolidated in GTK+ 3.551 552 553GNOME session support ~554 *gui-gnome-session* *gnome-session*555On logout, Vim shows the well-known exit confirmation dialog if any buffers556are modified. Clicking [Cancel] will stop the logout process. Otherwise the557current session is stored to disk by using the |:mksession| command, and558restored the next time you log in.559 560The GNOME session support should also work with the KDE session manager.561If you are experiencing any problems please report them as bugs.562 563Note: The automatic session save works entirely transparent, in order to564avoid conflicts with your own session files, scripts and autocommands. That565means in detail:566- The session file is stored to a separate directory (usually $HOME/.gnome2).567- 'sessionoptions' is ignored, and a hardcoded set of appropriate flags is568 used instead: >569 blank,curdir,folds,globals,help,options,tabpages,winsize570- The internal variable |v:this_session| is not changed when storing the571 session. Also, it is restored to its old value when logging in again.572 573The position and size of the GUI window is not saved by Vim since doing so574is the window manager's job. But if compiled with GTK+ 2 support, Vim helps575the WM to identify the window by restoring the window role (using the |--role|576command line argument).577 578==============================================================================5797. KDE version *gui-kde* *kde* *KDE* *KVim*580 *gui-x11-kde*581There is no KDE version of Vim. There has been some work on a port using the582Qt toolkit, but it never worked properly and it has been abandoned. Work583continues on Yzis: https://github.com/chrizel/Yzis but it seems also584abandoned.585 586==============================================================================5878. Compiling *gui-x11-compiling*588 589If using X11, Vim's configure will by default first try to find the necessary590GTK+ files on your system. When both GTK+ 2 and GTK+ 3 are available, GTK+ 2591will be chosen unless --enable-gui=gtk3 is passed explicitly to configure.592 593If the GTK+ files cannot be found, then the Motif files will be searched for.594If both fail, the GUI will be disabled.595 596For GTK+, Vim's configuration process uses pkg-config(1) to check if the597GTK+ required for a specified build is properly installed and usable.598Accordingly, it is a good idea to make sure before running configure that599your system has a working pkg-config together with the .pc file of the600required GTK+. For that, say, run the following on the command line to see if601your pkg-config works with your GTK+ 2: >602 603 $ pkg-config --modversion gtk+-2.0604 605Replace gtk+-2.0 with gtk+-3.0 for GTK+ 3. If you get the correct version606number of your GTK+, you can proceed; if not, you probably need to do some607system administration chores to set up pkg-config and GTK+ correctly.608 609The GTK+ 2 GUI is built by default. Therefore, you usually don't need to pass610any options such as --enable-gui=gtk2 to configure and build that.611 612Optionally, the GTK+ 2 GUI can consolidate the GNOME 2 support. This support613is enabled by passing --enable-gnome-check to configure.614 615If you want to build the GTK+ 3 GUI, you have to pass --enable-gui=gtk3616explicitly to configure, and avoid passing --enable-gnome-check to that, as617the functionality of the GNOME 2 support has already been consolidated in618GTK+ 3.619 620Otherwise, if you are using Motif, when you have the Motif files in a621directory where configure doesn't look, edit the Makefile to enter the names622of the directories. Search for "GUI_INC_LOC" for an example to set623the Motif directories.624 625 *gui-x11-gtk*626Currently, Vim supports both GTK+ 2 and GTK+ 3.627 628The GTK+ 2 GUI requires GTK+ 2.2 or later.629 630Although the GTK+ 3 GUI is written in such a way that the source code can be631compiled against all versions of the 3.x series, we recommend GTK+ 3.10 or632later because of its substantial implementation changes in redraw done at633that version.634 635 *gui-x11-motif*636For Motif, you need at least Motif version 1.2 and/or X11R5. Motif 2.0 and637X11R6 are OK. Motif 1.1 and X11R4 might work, no guarantee (there may be a638few problems, but you might make it compile and run with a bit of work, please639send patches if you do). The newest releases of LessTif have been reported to640work fine too.641 642 *gui-x11-athena* *gui-x11-neXtaw*643Support for the Athena GUI and neXtaw was removed in patch 8.2.4677.644 645 *gui-x11-misc*646In general, do not try to mix files from different GTK+, Motif and X11647versions. This will cause problems. For example, using header files for648X11R5 with a library for X11R6 probably doesn't work (although the linking649won't give an error message, Vim will crash later).650 651 *gui-wayland*652Support for the Wayland display server protocol has landed in patch 9.1.0064.653 654Note: The Wayland protocol is subject to some restrictions, so the following655functions won't work: |getwinpos()|, |getwinposx()|, |getwinposy()| and the656|v:windowid| variable won't be available.657 658==============================================================================6599. X11 selection mechanism *x11-selection*660 661If using X11, in either the GUI or an xterm with an X11-aware Vim, then Vim662provides varied access to the X11 selection and clipboard. These are accessed663by using the two selection registers "* and "+.664 665X11 provides two basic types of global store, selections and cut-buffers,666which differ in one important aspect: selections are "owned" by an667application, and disappear when that application (e.g., Vim) exits, thus668losing the data, whereas cut-buffers, are stored within the X-server itself669and remain until written over or the X-server exits (e.g., upon logging out).670 671The contents of selections are held by the originating application (e.g., upon672a copy), and only passed on to another application when that other application673asks for them (e.g., upon a paste).674 675The contents of cut-buffers are immediately written to, and are then676accessible directly from the X-server, without contacting the originating677application.678 679 *quoteplus* *quote+*680There are three documented X selections: PRIMARY (which is expected to681represent the current visual selection - as in Vim's Visual mode), SECONDARY682(which is ill-defined) and CLIPBOARD (which is expected to be used for683cut, copy and paste operations).684 685Of these three, Vim uses PRIMARY when reading and writing the "* register686(hence when the X11 selections are available, Vim sets a default value for687'clipboard' of "autoselect"), and CLIPBOARD when reading and writing the "+688register. Vim does not access the SECONDARY selection.689 690This applies both to the GUI and the terminal version. For non-X11 systems691the plus and the star register both use the system clipboard.692 693Examples: (assuming the default option values)694- Select a URL in Visual mode in Vim. Go to your browser and click the695 middle mouse button in the URL text field. The selected text will be696 inserted (hopefully!). Note: in Firefox you can set the697 middlemouse.contentLoadURL preference to true in about:config, then the698 selected URL will be used when pressing middle mouse button in most places699 in the window.700- Select some text in your browser by dragging with the mouse. Go to Vim and701 press the middle mouse button: The selected text is inserted.702- Select some text in Vim and do "+y. Go to your browser, select some text in703 a textfield by dragging with the mouse. Now use the right mouse button and704 select "Paste" from the popup menu. The selected text is overwritten by the705 text from Vim.706Note that the text in the "+ register remains available when making a Visual707selection, which makes other text available in the "* register. That allows708overwriting selected text.709 710 *W23*711When you are yanking into the "* or "+ register and Vim cannot establish a712connection to the X11 selection (or clipboard), it will use register 0 and713output a warning:714 715 Warning: Clipboard register not available, using register 0 ~716 717Note: This also applies to the Wayland clipboard feature as well.718 719 *W24*720Vim comes in different flavors, from a tiny build, that just tries to be721compatible to original Vi, to enhanced builds which include many improvements722(like a GUI). However, on servers and embedded systems, Vim is typically723compiled without clipboard support, since this feature requires X11 libraries724to be present. Check the ":version" output for the flag |+clipboard| or725-clipboard. The former means clipboard support is present while the latter726means your Vim does not contain clipboard support.727 728In the case when you are trying to access the "* or "+ register and Vim has729no clipboard support, you will see this warning:730 731 Warning: Clipboard register not available. See :h W24~732 733If you have a vim with no clipboard support but would like to use the734clipboard, try to install a more enhanced Vim package like vim-enhanced or735vim-gtk3 (the gui packages usually also come with a terminal Vim that has736clipboard support included).737 738 *x11-cut-buffer*739There are, by default, 8 cut-buffers: CUT_BUFFER0 to CUT_BUFFER7. Vim only740uses CUT_BUFFER0, which is the one that xterm uses by default.741 742Whenever Vim is about to become unavailable (either via exiting or becoming743suspended), and thus unable to respond to another application's selection744request, it writes the contents of any owned selection to CUT_BUFFER0. If the745"+ CLIPBOARD selection is owned by Vim, then this is written in preference,746otherwise if the "* PRIMARY selection is owned by Vim, then that is written.747 748Similarly, when Vim tries to paste from "* or "+ (either explicitly, or, in749the case of the "* register, when the middle mouse button is clicked), if the750requested X selection is empty or unavailable, Vim reverts to reading the751current value of the CUT_BUFFER0.752 753Note that when text is copied to CUT_BUFFER0 in this way, the type of754selection (character, line or block) is always lost, even if it is a Vim which755later pastes it.756 757Xterm, by default, always writes visible selections to both PRIMARY and758CUT_BUFFER0. When it pastes, it uses PRIMARY if this is available, or else759falls back upon CUT_BUFFER0. For this reason, when cutting and pasting760between Vim and an xterm, you should use the "* register. Xterm doesn't use761CLIPBOARD, thus the "+ doesn't work with xterm.762 763Most newer applications will provide their current selection via PRIMARY ("*)764and use CLIPBOARD ("+) for cut/copy/paste operations. You thus have access to765both by choosing to use either of the "* or "+ registers.766 767 768 vim:tw=78:sw=4:ts=8:noet:ft=help:norl:769