diff options
Diffstat (limited to 'runtime/doc/gui_x11.txt')
| -rw-r--r-- | runtime/doc/gui_x11.txt | 738 |
1 files changed, 738 insertions, 0 deletions
diff --git a/runtime/doc/gui_x11.txt b/runtime/doc/gui_x11.txt new file mode 100644 index 0000000..76e2ac2 --- /dev/null +++ b/runtime/doc/gui_x11.txt @@ -0,0 +1,738 @@ +*gui_x11.txt* For Vim version 8.1. Last change: 2018 May 06 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Vim's Graphical User Interface *gui-x11* *GUI-X11* + *Athena* *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. + +{Vi does not have any of these commands} + +============================================================================== +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 "gvim -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 or Athena 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. + menuHeight Height of the menu bar (only for Athena). + +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-*-*-*-*-*-*-* +With Athena: > + Vim*menuBar*SmeBSB*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-* + Vim*menuBar*MenuButton*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-* + +NOTE: A more portable, and indeed more correct, way to specify the menu font +in either Motif or Athena 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 or Athena. 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. + + +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. + +============================================================================== +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. +Finally, if this fails, the Athena files will be searched for. If all three +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 or Athena, when you have the Motif or Athena +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, "CONF_OPT_X" for Athena. + + *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 me the patches if you do). The newest releases of LessTif have been +reported to work fine too. + + *gui-x11-athena* +The Athena version uses the Xaw widget set by default. If you have the 3D +version, you might want to link with Xaw3d instead. This will make the +menus look a bit better. Edit the Makefile and look for "XAW_LIB". The +scrollbars will remain the same, because Vim has its own, which are already +3D (in fact, they look more like Motif). + + *gui-x11-neXtaw* +The neXtaw version is mostly like Athena, but uses different widgets. + + *gui-x11-misc* +In general, do not try to mix files from different GTK+, Motif, Athena 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). + +============================================================================== +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. + +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. + *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: |