summaryrefslogtreecommitdiffstats
path: root/runtime/doc/gui_x11.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/gui_x11.txt')
-rw-r--r--runtime/doc/gui_x11.txt731
1 files changed, 731 insertions, 0 deletions
diff --git a/runtime/doc/gui_x11.txt b/runtime/doc/gui_x11.txt
new file mode 100644
index 0000000..23633f1
--- /dev/null
+++ b/runtime/doc/gui_x11.txt
@@ -0,0 +1,731 @@
+*gui_x11.txt* For Vim version 9.1. Last change: 2022 Apr 03
+
+
+ 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.
+
+==============================================================================
+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 me the 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).
+
+==============================================================================
+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.
+ *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: