vim-jp / vimdoc-en / gui_x11

gui_x11 - Vim Documentation

Return to main English | 日本語
gui_x11.txt   For Vim version 9.1.  Last change: 2024 Nov 11


                  VIM REFERENCE MANUAL    by Bram Moolenaar


Vim's Graphical User Interface                          gui-x11 GUI-X11
                                                        Motif
1. Starting the X11 GUI         gui-x11-start
2. GUI Resources                gui-resources
3. Shell Commands               gui-pty
4. Various                      gui-x11-various
5. GTK version                  gui-gtk
6. GNOME version                gui-gnome
7. KDE version                  gui-kde
8. Compiling                    gui-x11-compiling
9. X11 selection mechanism      x11-selection

Other relevant documentation:
gui.txt       For generic items of the GUI.


==============================================================================
1. Starting the X11 GUI                                 gui-x11-start E665

Then you can run the GUI version of Vim in either of these ways:
    gvim [options] [files...]
    vim -g [options] [files...]

So if you call the executable "gvim", or make "gvim" a link to the executable,
then the GUI version will automatically be used.  Additional characters may be
added after "gvim", for example "gvim-5".

You may also start up the GUI from within the terminal version by using one of
these commands:
        :gui [++opt] [+cmd] [-f|-b] [files...]                  :gu :gui
        :gvim [++opt] [+cmd] [-f|-b] [files...]                 :gv :gvim
The "-f" option runs Vim in the foreground.
The "-b" option runs Vim in the background (this is the default).
Also see ++opt and +cmd.

                                                        gui-fork
When the GUI is started, it does a fork() and exits the current process.
When gvim was started from a shell this makes the shell accept further
commands.  If you don't want this (e.g. when using gvim for a mail program
that waits for gvim to exit), start gvim with "gvim -f", "vim -gf" or use
":gui -f".  Don't use "vim -fg", because "-fg" specifies the foreground
color.

When using "vim -f" and then ":gui", Vim will run in the foreground.  The
"-f" argument will be remembered.  To force running Vim in the background use
":gui -b".

"gvim --nofork" does the same as "gvim -f".

When there are running jobs Vim will not fork, because the processes would no
longer be child processes.
                                                                E851 E852
When starting the GUI fails Vim will try to continue running in the terminal.

If you want the GUI to run in the foreground always, include the 'f'
flag in 'guioptions'.  -f.

==============================================================================
2. GUI Resources                        gui-resources .Xdefaults

If using the Motif version of the GUI (not for the KDE, GTK+ or Win32
version), a number of X resources are available.  You should use Vim's class
"Vim" when setting these.  They are as follows:

    Resource name       Meaning 

    reverseVideo        Boolean: should reverse video be used?
    background          Color of background.
    foreground          Color of normal text.
    scrollBackground    Color of trough portion of scrollbars.
    scrollForeground    Color of slider and arrow portions of scrollbars.
    menuBackground      Color of menu backgrounds.
    menuForeground      Color of menu foregrounds.
    tooltipForeground   Color of tooltip and balloon foreground.
    tooltipBackground   Color of tooltip and balloon background.

    font                Name of font used for normal text.
    boldFont            Name of font used for bold text.
    italicFont          Name of font used for italic text.
    boldItalicFont      Name of font used for bold, italic text.
    menuFont            Name of font used for the menus, used when compiled
                        without the +xfontset feature
    menuFontSet         Name of fontset used for the menus, used when compiled
                        with the +xfontset feature
    tooltipFont         Name of the font used for the tooltip and balloons.
                        When compiled with the +xfontset feature this is a
                        fontset name.

    geometry            Initial geometry to use for gvim's window (default
                        is same size as terminal that started it).
    scrollbarWidth      Thickness of scrollbars.
    borderWidth         Thickness of border around text area.

A special font for italic, bold, and italic-bold text will only be used if
the user has specified one via a resource.  No attempt is made to guess what
fonts should be used for these based on the normal text font.

Note that the colors can also be set with the ":highlight" command, using the
"Normal", "Menu", "Tooltip", and "Scrollbar" groups.  Example:
        :highlight Menu guibg=lightblue
        :highlight Tooltip guibg=yellow
        :highlight Scrollbar guibg=lightblue guifg=blue
        :highlight Normal guibg=grey90

                                                        font-sizes
Note: All fonts (except for the menu and tooltip) must be of the same size!!!
If you don't do this, text will disappear or mess up the display.  Vim does
not check the font sizes.  It's the size in screen pixels that must be the
same.  Note that some fonts that have the same point size don't have the same
pixel size!  Additionally, the positioning of the fonts must be the same
(ascent and descent).  You can check this with "xlsfonts -l {fontname}".

If any of these things are also set with Vim commands, e.g. with
":set guifont=Screen15", then this will override the X resources (currently
'guifont' is the only option that is supported).

Here is an example of what you might put in your ~/.Xdefaults file:

        Vim*useSchemes:                 all
        Vim*sgiMode:                    true
        Vim*useEnhancedFSB:             true
        Vim.foreground:                 Black
        Vim.background:                 Wheat
        Vim*fontList:                   7x13

The first three of these are standard resources on Silicon Graphics machines
which make Motif applications look even better, highly recommended!

The "Vim*fontList" is to set the menu font for Motif.  Example:
        Vim*menuBar*fontList:        -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*

NOTE: A more portable, and indeed more correct, way to specify the menu font
in Motif is through the resource:
        Vim.menuFont:        -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
Or, when compiled with the +xfontset feature:
        Vim.menuFontSet:     -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*

Don't use "Vim*geometry" in the defaults.  This will break the menus.  Use
"Vim.geometry" instead.

If you get an error message "Cannot allocate colormap entry for "gray60",
try adding this to your Vim resources (change the colors to your liking):

        Vim*scrollBackground:           Black
        Vim*scrollForeground:           Blue

The resources can also be set with arguments to Vim:

    argument            meaning
                                                        -gui
   -display {display}   Run vim on {display}            -display
   -iconic              Start vim iconified             -iconic
   -background {color}  Use {color} for the background  -background
   -bg {color}          idem                            -bg
   -foreground {color}  Use {color} for normal text     -foreground
   -fg {color}          idem                            -fg
   -ul {color}          idem                            -ul
   -font {font}         Use {font} for normal text      -font
   -fn {font}           idem                            -fn
   -boldfont {font}     Use {font} for bold text        -boldfont
   -italicfont {font}   Use {font} for italic text      -italicfont
   -menufont {font}     Use {font} for menu items       -menufont
   -menufontset {fontset} Use {fontset} for menu items  -menufontset
   -mf {font}           idem                            -mf
   -geometry {geom}     Use {geom} for initial geometry -geometry
   -geom {geom}         idem, see -geometry-example   -geom
   -borderwidth {width} Use a border width of {width}   -borderwidth
   -bw {width}          idem                            -bw
                                                        -scrollbarwidth
   -scrollbarwidth {width}      Use a scrollbar width of {width}
   -sw {width}          idem                            -sw
   -menuheight {height} Use a menu bar height of {height} -menuheight
   -mh {height}         idem                            -mh
                        NOTE: On Motif the value is ignored, the menu height
                        is computed to fit the menus.
   -reverse             Use reverse video               -reverse
   -rv                  idem                            -rv
   +reverse             Don't use reverse video         -+reverse
   +rv                  idem                            -+rv
   -xrm {resource}      Set the specified resource      -xrm

Note about reverse video: Vim checks that the result is actually a light text
on a dark background.  The reason is that some X11 versions swap the colors,
and some don't.  These two examples will both give yellow text on a blue
background:
    gvim -fg Yellow -bg Blue -reverse
    gvim -bg Yellow -fg Blue -reverse

                                                        -geometry-example
An example for the geometry argument:
        gvim -geometry 80x63+8+100
This creates a window with 80 columns and 63 lines at position 8 pixels from
the left and 100 pixels from the top of the screen.

==============================================================================
3. Shell Commands                                       gui-pty

WARNING: Executing an external command from the GUI will not always work.
"normal" commands like "ls", "grep" and "make" mostly work fine.  Commands
that require an intelligent terminal like "less" and "ispell" won't work.
Some may even hang and need to be killed from another terminal.  So be
careful!

There are two ways to do the I/O with a shell command: Pipes and a pseudo-tty.
The default is to use a pseudo-tty.  This should work best on most systems.

Unfortunately, the implementation of the pseudo-tty is different on every Unix
system.  And some systems require root permission.  To avoid running into
problems with a pseudo-tty when you least expect it, test it when not editing
a file.  Be prepared to "kill" the started command or Vim.  Commands like
":r !cat" may hang!

If using a pseudo-tty does not work for you, reset the 'guipty' option:

        :set noguipty

Using a pipe should work on any Unix system, but there are disadvantages:
- Some shell commands will notice that a pipe is being used and behave
  differently.  E.g., ":!ls" will list the files in one column.
- The ":sh" command won't show a prompt, although it will sort of work.
- When using ":make" it's not possible to interrupt with a CTRL-C.

Typeahead while the external command is running is often lost.  This happens
both with a pipe and a pseudo-tty.  This is a known problem, but it seems it
can't be fixed (or at least, it's very difficult).

                                                        gui-pty-erase
When your erase character is wrong for an external command, you should fix
this in your "~/.cshrc" file, or whatever file your shell uses for
initializations.  For example, when you want to use backspace to delete
characters, but hitting backspaces produces "^H" instead, try adding this to
your "~/.cshrc":
        stty erase ^H
The ^H is a real CTRL-H, type it as CTRL-V CTRL-H.

==============================================================================
4. Various                                              gui-x11-various

                                                        gui-x11-printing
The "File/Print" menu simply sends the current buffer to "lpr".  No options or
whatever.  If you want something else, you can define your own print command.
For example:

  :10amenu File.Print :w !lpr -Php3
  :10vmenu File.Print :w !lpr -Php3

                                                        X11-icon
Vim uses a black&white icon by default when compiled with Motif.  A
colored Vim icon is included as $VIMRUNTIME/vim32x32.xpm.  For GTK+, this is
the builtin icon used.  Unfortunately, how you should install it depends on
your window manager.  When you use this, remove the 'i' flag from
'guioptions', to remove the black&white icon:
  :set guioptions-=i

If you use one of the fvwm* family of window managers simply add this line to
your .fvwm2rc configuration file:

  Style "vim"           Icon vim32x32.xpm

Make sure the icon file's location is consistent with the window manager's
ImagePath statement.  Either modify the ImagePath from within your .fvwm2rc or
drop the icon into one the pre-defined directories:

  ImagePath /usr/X11R6/include/X11/pixmaps:/usr/X11R6/include/X11/bitmaps

Note: older versions of fvwm use "IconPath" instead of "ImagePath".

For CDE "dtwm" (a derivative of Motif) add this line in the .Xdefaults:
   Dtwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm

For "mwm" (Motif window manager) the line would be:
   Mwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm


Mouse Pointers Available in X11
                                                X11_mouse_shapes
By using the 'mouseshape' option, the mouse pointer can be automatically
changed whenever Vim enters one of its various modes (e.g., Insert or
Command).  Currently, the available pointers are:

        arrow                   an arrow pointing northwest
        beam                    a I-like vertical bar
        size                    an arrow pointing up and down
        busy                    a wristwatch
        blank                   an invisible pointer
        crosshair               a thin "+" sign
        hand1                   a dark hand pointing northeast
        hand2                   a light hand pointing northwest
        pencil                  a pencil pointing southeast
        question                question_arrow
        right_arrow             an arrow pointing northeast
        up_arrow                an arrow pointing upwards

Additionally, any of the mouse pointers that are built into X11 may be
used by specifying an integer from the X11/cursorfont.h include file.

If a name is used that exists on other systems, but not in X11, the default
"arrow" pointer is used.

==============================================================================
5. GTK version                                  gui-gtk GTK+ GTK GTK3

The GTK version of the GUI works a little bit different.

GTK does _not_ use the traditional X resource settings.  Thus items in your
~/.Xdefaults or app-defaults files are not used.
Many of the traditional X command line arguments are not supported.  (e.g.,
stuff like -bg, -fg, etc).  The ones that are supported are:

    command line argument   resource name       meaning
    -fn  or  -font          .font               font name for the text
    -geom  or  -geometry    .geometry           size of the gvim window
    -rv  or  -reverse       *reverseVideo       white text on black background
    -display                                    display to be used
    -fg -foreground {color}                     foreground color
    -bg -background {color}                     background color

To set the font, see 'guifont'.  For GTK, there's also a menu option that
does this.

Additionally, there are these command line arguments, which are handled by GTK
internally.  Look in the GTK documentation for how they are used:
        --sync
        --gdk-debug
        --gdk-no-debug
        --no-xshm       (not in GTK+ 2)
        --xim-preedit   (not in GTK+ 2)
        --xim-status    (not in GTK+ 2)
        --gtk-debug
        --gtk-no-debug
        --g-fatal-warnings
        --gtk-module
        --display       (GTK+ counterpart of -display; works the same way.)
        --screen        (The screen number; for GTK+ 2.2 multihead support.)

These arguments are ignored when the +netbeans_intg feature is used:
        -xrm
        -mf

As for colors, Vim's color settings (for syntax highlighting) is still
done the traditional Vim way.  See :highlight for more help.

If you want to set the colors of remaining gui components (e.g., the
menubar, scrollbar, whatever), those are GTK specific settings and you
need to set those up in some sort of gtkrc file.  You'll have to refer
to the GTK documentation, however little there is, on how to do this.
See http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html
for more information.
                                                        gtk3-slow
If you are using GTK3 and Vim appears to be slow, try setting the environment
variable $GDK_RENDERING to "image".


Tooltip Colors
                                                        gtk-tooltip-colors
Example, which sets the tooltip colors to black on light-yellow:

        style "tooltips"
        {
                bg[NORMAL] = "#ffffcc"
                fg[NORMAL] = "#000000"
        }

        widget "gtk-tooltips*"          style "tooltips"

Write this in the file ~/.gtkrc and it will be used by GTK+.  For GTK+ 2
you might have to use the file ~/.gtkrc-2.0 instead, depending on your
distribution.

For GTK+ 3, an effect similar to the above can be obtained by adding the
following snippet of CSS code to $XDG_HOME_DIR/gtk-3.0/gtk.css (see the next
section):

For GTK+ 3 < 3.20:

        .tooltip {
                background-color: #ffffcc;
                color: #000000;
        }

For GTK+ 3 >= 3.20:

        tooltip {
            background-color: #ffffcc;
            text-shadow: none;
        }

        tooltip label {
            color: #2e3436;
        }


A Quick Look at GTK+ CSS
                                                        gtk-css
The contents of this subsection apply to GTK+ 3.20 or later which provides
stable support for GTK+ CSS:

        https://developer.gnome.org/gtk3/stable/theming.html

GTK+ uses CSS for styling and layout of widgets.  In this subsection, we'll
have a quick look at GTK+ CSS through simple, illustrative examples.

You can usually edit the config with:
        vim $HOME/.config/gtk-3.0/gtk.css


Example 1.  Empty Space Adjustment

By default, the toolbar and the tabline of the GTK+ 3 GUI are somewhat larger
than those of the GTK+ 2 GUI.  Some people may want to make them look similar
to the GTK+ 2 GUI in size.

To do that, we'll try reducing empty space around icons and labels that looks
apparently superfluous.

Add the following lines to $XDG_HOME_DIR/gtk-3.0/gtk.css (usually,
$HOME/.config/gtk-3.0/gtk.css):

        toolbar button {
            margin-top: -2px;
            margin-right: 0px;
            margin-bottom: -2px;
            margin-left: 0px;

            padding-top: 0px;
            padding-right: 0px;
            padding-bottom: 0px;
            padding-left: 0px
        }

        notebook tab {
            margin-top: -1px;
            margin-right: 3px;
            margin-bottom: -1px;
            margin-left: 3px;

            padding-top: 0px;
            padding-right: 0px;
            padding-bottom: 0px;
            padding-left: 0px
        }

Since it's a CSS, they can be rewritten using shorthand:

        toolbar button {
            margin: -2px 0px;
            padding: 0px;
        }

        notebook tab {
            margin: -1px 3px;
            padding: 0px
        }

Note: You might want to use 'toolbariconsize' to adjust the icon size, too.

Note: Depending on the icon theme and/or the font in use, some extra tweaks
may be needed for a satisfactory result.

Note: In addition to margin and padding, you can use border.  For details,
refer to the box model of CSS, e.g.,

        https://www.w3schools.com/css/css_boxmodel.asp

Example 2.  More Than Just Colors

GTK+ CSS supports gradients as well:

        tooltip {
            background-image: -gtk-gradient(linear,
                                            0 0, 0 1,
                                            color-stop(0, #344752),
                                            color-stop(0.5, #546772),
                                            color-stop(1, #243742));
        }

        tooltip label {
            color: #f3f3f3;
        }

Gradients can be used to make a GUI element visually distinguishable from
others without relying on high contrast. Accordingly, effective use of them is
a useful technique to give a theme a sense of unity in color and luminance.

Note: Theming can be difficult since it must make every application look
equally good; making a single application more charming often gets others
unexpectedly less attractive or even deteriorates their usability.  Keep this
in mind always when you try improving a theme.


Example 3.  border color

To eliminate borders when maximized:

    @define-color bg_color #1B2B34;
    #vim-main-window {
        background-color: @bg_color;
    }


Using Vim as a GTK+ plugin
                                                        gui-gtk-socketid
When the GTK+ version of Vim starts up normally, it creates its own top level
window (technically, a 'GtkWindow').  GTK+ provides an embedding facility with
its GtkSocket and GtkPlug widgets.  If one GTK+ application creates a
GtkSocket widget in one of its windows, an entirely different GTK+ application
may embed itself into the first application by creating a top-level GtkPlug
widget using the socket's ID.

If you pass Vim the command-line option '--socketid' with a decimal or
hexadecimal value, Vim will create a GtkPlug widget using that value instead
of the normal GtkWindow.  This enables Vim to act as a GTK+ plugin.

This really is a programmer's interface, and is of no use without a supporting
application to spawn the Vim correctly.  For more details on GTK+ sockets, see
http://www.gtk.org/api/

Note that this feature requires the latest GTK version.  GTK 1.2.10 still has
a small problem.  The socket feature has not yet been tested with GTK+ 2 --
feel free to volunteer.

==============================================================================
6. GNOME version                                gui-gnome Gnome GNOME

The GNOME GUI works just like the GTK+ version.  See GTK+ above for how it
works.  It looks a bit different though, and implements one important feature
that's not available in the plain GTK+ GUI:  Interaction with the session
manager. gui-gnome-session

These are the different looks:
- Uses GNOME dialogs (GNOME 1 only).  The GNOME 2 GUI uses the same nice
  dialogs as the GTK+ 2 version.
- Uses the GNOME dock, so that the toolbar and menubar can be moved to
  different locations other than the top (e.g., the toolbar can be placed on
  the left, right, top, or bottom).  The placement of the menubar and
  toolbar is only saved in the GNOME 2 version.
- That means the menubar and toolbar handles are back!  Yeah!  And the
  resizing grid still works too.

GNOME is compiled with if it was found by configure and the
--enable-gnome-check argument was used.

Note: Avoid use of --enable-gnome-check with GTK+ 3 GUI build.  The
functionality mentioned above is consolidated in GTK+ 3.


GNOME session support
                                        gui-gnome-session gnome-session
On logout, Vim shows the well-known exit confirmation dialog if any buffers
are modified.  Clicking [Cancel] will stop the logout process.  Otherwise the
current session is stored to disk by using the :mksession command, and
restored the next time you log in.

The GNOME session support should also work with the KDE session manager.
If you are experiencing any problems please report them as bugs.

Note: The automatic session save works entirely transparent, in order to
avoid conflicts with your own session files, scripts and autocommands.  That
means in detail:
- The session file is stored to a separate directory (usually $HOME/.gnome2).
'sessionoptions' is ignored, and a hardcoded set of appropriate flags is
  used instead:
        blank,curdir,folds,globals,help,options,tabpages,winsize
- The internal variable v:this_session is not changed when storing the
  session.  Also, it is restored to its old value when logging in again.

The position and size of the GUI window is not saved by Vim since doing so
is the window manager's job.  But if compiled with GTK+ 2 support, Vim helps
the WM to identify the window by restoring the window role (using the --role
command line argument).

==============================================================================
7. KDE version                                  gui-kde kde KDE KVim
                                                        gui-x11-kde
There is no KDE version of Vim.  There has been some work on a port using the
Qt toolkit, but it never worked properly and it has been abandoned.  Work
continues on Yzis: https://github.com/chrizel/Yzis but it seems also
abandoned.

==============================================================================
8. Compiling                                            gui-x11-compiling

If using X11, Vim's configure will by default first try to find the necessary
GTK+ files on your system.  When both GTK+ 2 and GTK+ 3 are available, GTK+ 2
will be chosen unless --enable-gui=gtk3 is passed explicitly to configure.

If the GTK+ files cannot be found, then the Motif files will be searched for.
If both fail, the GUI will be disabled.

For GTK+, Vim's configuration process uses pkg-config(1) to check if the
GTK+ required for a specified build is properly installed and usable.
Accordingly, it is a good idea to make sure before running configure that
your system has a working pkg-config together with the .pc file of the
required GTK+.  For that, say, run the following on the command line to see if
your pkg-config works with your GTK+ 2:

    $ pkg-config --modversion gtk+-2.0

Replace gtk+-2.0 with gtk+-3.0 for GTK+ 3. If you get the correct version
number of your GTK+, you can proceed; if not, you probably need to do some
system administration chores to set up pkg-config and GTK+ correctly.

The GTK+ 2 GUI is built by default.  Therefore, you usually don't need to pass
any options such as --enable-gui=gtk2 to configure and build that.

Optionally, the GTK+ 2 GUI can consolidate the GNOME 2 support.  This support
is enabled by passing --enable-gnome-check to configure.

If you want to build the GTK+ 3 GUI, you have to pass --enable-gui=gtk3
explicitly to configure, and avoid passing --enable-gnome-check to that, as
the functionality of the GNOME 2 support has already been consolidated in
GTK+ 3.

Otherwise, if you are using Motif, when you have the Motif files in a
directory where configure doesn't look, edit the Makefile to enter the names
of the directories.  Search for "GUI_INC_LOC" for an example to set
the Motif directories.

                                                        gui-x11-gtk
Currently, Vim supports both GTK+ 2 and GTK+ 3.

The GTK+ 2 GUI requires GTK+ 2.2 or later.

Although the GTK+ 3 GUI is written in such a way that the source code can be
compiled against all versions of the 3.x series, we recommend GTK+ 3.10 or
later because of its substantial implementation changes in redraw done at
that version.

                                                        gui-x11-motif
For Motif, you need at least Motif version 1.2 and/or X11R5.  Motif 2.0 and
X11R6 are OK.  Motif 1.1 and X11R4 might work, no guarantee (there may be a
few problems, but you might make it compile and run with a bit of work, please
send patches if you do).  The newest releases of LessTif have been reported to
work fine too.

                                            gui-x11-athena gui-x11-neXtaw
Support for the Athena GUI and neXtaw was removed in patch 8.2.4677.

                                                        gui-x11-misc
In general, do not try to mix files from different GTK+, Motif and X11
versions.  This will cause problems.  For example, using header files for
X11R5 with a library for X11R6 probably doesn't work (although the linking
won't give an error message, Vim will crash later).

                                                        gui-wayland
Initial support for the Wayland display server protocol has landed in patch
9.1.0064. To enable it, you need to set the environment variable
"$GVIM_ENABLE_WAYLAND" in your shell.

Note: The Wayland protocol is subject to some restrictions, so the following
functions won't work: getwinpos()getwinposx()getwinposy() and the
v:windowid variable won't be available.

==============================================================================
9. X11 selection mechanism                              x11-selection

If using X11, in either the GUI or an xterm with an X11-aware Vim, then Vim
provides varied access to the X11 selection and clipboard.  These are accessed
by using the two selection registers "* and "+.

X11 provides two basic types of global store, selections and cut-buffers,
which differ in one important aspect: selections are "owned" by an
application, and disappear when that application (e.g., Vim) exits, thus
losing the data, whereas cut-buffers, are stored within the X-server itself
and remain until written over or the X-server exits (e.g., upon logging out).

The contents of selections are held by the originating application (e.g., upon
a copy), and only passed on to another application when that other application
asks for them (e.g., upon a paste).

The contents of cut-buffers are immediately written to, and are then
accessible directly from the X-server, without contacting the originating
application.

                                                        quoteplus quote+
There are three documented X selections: PRIMARY (which is expected to
represent the current visual selection - as in Vim's Visual mode), SECONDARY
(which is ill-defined) and CLIPBOARD (which is expected to be used for
cut, copy and paste operations).

Of these three, Vim uses PRIMARY when reading and writing the "* register
(hence when the X11 selections are available, Vim sets a default value for
'clipboard' of "autoselect"), and CLIPBOARD when reading and writing the "+
register.  Vim does not access the SECONDARY selection.

This applies both to the GUI and the terminal version.  For non-X11 systems
the plus and the star register both use the system clipboard.

Examples: (assuming the default option values)
- Select a URL in Visual mode in Vim.  Go to your browser and click the
  middle mouse button in the URL text field.  The selected text will be
  inserted (hopefully!).  Note: in Firefox you can set the
  middlemouse.contentLoadURL preference to true in about:config, then the
  selected URL will be used when pressing middle mouse button in most places
  in the window.
- Select some text in your browser by dragging with the mouse.  Go to Vim and
  press the middle mouse button: The selected text is inserted.
- Select some text in Vim and do "+y.  Go to your browser, select some text in
  a textfield by dragging with the mouse.  Now use the right mouse button and
  select "Paste" from the popup menu.  The selected text is overwritten by the
  text from Vim.
Note that the text in the "+ register remains available when making a Visual
selection, which makes other text available in the "* register.  That allows
overwriting selected text.

                                                                W23
When you are yanking into the "* or "+ register and Vim cannot establish a
connection to the X11 selection (or clipboard), it will use register 0 and
output a warning:

  Warning: Clipboard register not available, using register 0

                                                        x11-cut-buffer
There are, by default, 8 cut-buffers: CUT_BUFFER0 to CUT_BUFFER7.  Vim only
uses CUT_BUFFER0, which is the one that xterm uses by default.

Whenever Vim is about to become unavailable (either via exiting or becoming
suspended), and thus unable to respond to another application's selection
request, it writes the contents of any owned selection to CUT_BUFFER0.  If the
"+ CLIPBOARD selection is owned by Vim, then this is written in preference,
otherwise if the "* PRIMARY selection is owned by Vim, then that is written.

Similarly, when Vim tries to paste from "* or "+ (either explicitly, or, in
the case of the "* register, when the middle mouse button is clicked), if the
requested X selection is empty or unavailable, Vim reverts to reading the
current value of the CUT_BUFFER0.

Note that when text is copied to CUT_BUFFER0 in this way, the type of
selection (character, line or block) is always lost, even if it is a Vim which
later pastes it.

Xterm, by default, always writes visible selections to both PRIMARY and
CUT_BUFFER0.  When it pastes, it uses PRIMARY if this is available, or else
falls back upon CUT_BUFFER0.  For this reason, when cutting and pasting
between Vim and an xterm, you should use the "* register.  Xterm doesn't use
CLIPBOARD, thus the "+ doesn't work with xterm.

Most newer applications will provide their current selection via PRIMARY ("*)
and use CLIPBOARD ("+) for cut/copy/paste operations.  You thus have access to
both by choosing to use either of the "* or "+ registers.


 vim:tw=78:sw=4:ts=8:noet:ft=help:norl: