vim

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

gui_x11.txt (32669B)


      1 *gui_x11.txt*	For Vim version 9.2.  Last change: 2026 Aug 10
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 Vim's Graphical User Interface				*gui-x11* *GUI-X11*
      8 							*Motif*
      9 1. Starting the X11 GUI		|gui-x11-start|
     10 2. GUI Resources		|gui-resources|
     11 3. Shell Commands		|gui-pty|
     12 4. Various			|gui-x11-various|
     13 5. GTK version			|gui-gtk|
     14 6. GNOME version		|gui-gnome|
     15 7. KDE version			|gui-kde|
     16 8. Compiling			|gui-x11-compiling|
     17 9. X11 selection mechanism	|x11-selection|
     18 
     19 Other relevant documentation:
     20 |gui.txt|	For generic items of the GUI.
     21 
     22 
     23 ==============================================================================
     24 1. Starting the X11 GUI					*gui-x11-start* *E665*
     25 
     26 Then you can run the GUI version of Vim in either of these ways:
     27     gvim [options] [files...]
     28     vim -g [options] [files...]
     29 
     30 So if you call the executable "gvim", or make "gvim" a link to the executable,
     31 then the GUI version will automatically be used.  Additional characters may be
     32 added after "gvim", for example "gvim-5".
     33 
     34 You may also start up the GUI from within the terminal version by using one of
     35 these commands:
     36 	:gui [++opt] [+cmd] [-f|-b] [files...]			*:gu* *:gui*
     37 	:gvim [++opt] [+cmd] [-f|-b] [files...]			*:gv* *:gvim*
     38 The "-f" option runs Vim in the foreground.
     39 The "-b" option runs Vim in the background (this is the default).
     40 Also see |++opt| and |+cmd|.
     41 
     42 							*gui-fork*
     43 When the GUI is started, it does a fork() and exits the current process.
     44 When gvim was started from a shell this makes the shell accept further
     45 commands.  If you don't want this (e.g. when using gvim for a mail program
     46 that waits for gvim to exit), start gvim with "gvim -f", "vim -gf" or use
     47 ":gui -f".  Don't use "vim -fg", because "-fg" specifies the foreground
     48 color.
     49 
     50 When using "vim -f" and then ":gui", Vim will run in the foreground.  The
     51 "-f" argument will be remembered.  To force running Vim in the background use
     52 ":gui -b".
     53 
     54 "gvim --nofork" does the same as "gvim -f".
     55 
     56 When there are running jobs Vim will not fork, because the processes would no
     57 longer be child processes.
     58 								*E851* *E852*
     59 When starting the GUI fails Vim will try to continue running in the terminal.
     60 
     61 If you want the GUI to run in the foreground always, include the 'f'
     62 flag in 'guioptions'.  |-f|.
     63 
     64 ==============================================================================
     65 2. GUI Resources			*gui-resources* *.Xdefaults*
     66 
     67 If using the Motif version of the GUI (not for the KDE, GTK+ or Win32
     68 version), a number of X resources are available.  You should use Vim's class
     69 "Vim" when setting these.  They are as follows:
     70 
     71     Resource name	Meaning		~
     72 
     73     reverseVideo	Boolean: should reverse video be used?
     74     background		Color of background.
     75     foreground		Color of normal text.
     76     scrollBackground	Color of trough portion of scrollbars.
     77     scrollForeground	Color of slider and arrow portions of scrollbars.
     78     menuBackground	Color of menu backgrounds.
     79     menuForeground	Color of menu foregrounds.
     80     tooltipForeground	Color of tooltip and balloon foreground.
     81     tooltipBackground	Color of tooltip and balloon background.
     82 
     83     font		Name of font used for normal text.
     84     boldFont		Name of font used for bold text.
     85     italicFont		Name of font used for italic text.
     86     boldItalicFont	Name of font used for bold, italic text.
     87     menuFont		Name of font used for the menus, used when compiled
     88 			without the |+xfontset| feature
     89     menuFontSet		Name of fontset used for the menus, used when compiled
     90 			with the |+xfontset| feature
     91     tooltipFont		Name of the font used for the tooltip and balloons.
     92 			When compiled with the |+xfontset| feature this is a
     93 			fontset name.
     94 
     95     geometry		Initial geometry to use for gvim's window (default
     96 			is same size as terminal that started it).
     97     scrollbarWidth	Thickness of scrollbars.
     98     borderWidth		Thickness of border around text area.
     99 
    100 A special font for italic, bold, and italic-bold text will only be used if
    101 the user has specified one via a resource.  No attempt is made to guess what
    102 fonts should be used for these based on the normal text font.
    103 
    104 Note that the colors can also be set with the ":highlight" command, using the
    105 "Normal", "Menu", "Tooltip", and "Scrollbar" groups.  Example: >
    106 	:highlight Menu guibg=lightblue
    107 	:highlight Tooltip guibg=yellow
    108 	:highlight Scrollbar guibg=lightblue guifg=blue
    109 	:highlight Normal guibg=grey90
    110 <
    111 							*font-sizes*
    112 Note: All fonts (except for the menu and tooltip) must be of the same size!!!
    113 If you don't do this, text will disappear or mess up the display.  Vim does
    114 not check the font sizes.  It's the size in screen pixels that must be the
    115 same.  Note that some fonts that have the same point size don't have the same
    116 pixel size!  Additionally, the positioning of the fonts must be the same
    117 (ascent and descent).  You can check this with "xlsfonts -l {fontname}".
    118 
    119 If any of these things are also set with Vim commands, e.g. with
    120 ":set guifont=Screen15", then this will override the X resources (currently
    121 'guifont' is the only option that is supported).
    122 
    123 Here is an example of what you might put in your ~/.Xdefaults file: >
    124 
    125 	Vim*useSchemes:			all
    126 	Vim*sgiMode:			true
    127 	Vim*useEnhancedFSB:		true
    128 	Vim.foreground:			Black
    129 	Vim.background:			Wheat
    130 	Vim*fontList:			7x13
    131 
    132 The first three of these are standard resources on Silicon Graphics machines
    133 which make Motif applications look even better, highly recommended!
    134 
    135 The "Vim*fontList" is to set the menu font for Motif.  Example: >
    136 	Vim*menuBar*fontList:	     -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
    137 
    138 NOTE: A more portable, and indeed more correct, way to specify the menu font
    139 in Motif is through the resource: >
    140 	Vim.menuFont:	     -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
    141 Or, when compiled with the |+xfontset| feature: >
    142 	Vim.menuFontSet:     -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
    143 
    144 Don't use "Vim*geometry" in the defaults.  This will break the menus.  Use
    145 "Vim.geometry" instead.
    146 
    147 If you get an error message "Cannot allocate colormap entry for "gray60",
    148 try adding this to your Vim resources (change the colors to your liking): >
    149 
    150 	Vim*scrollBackground:		Black
    151 	Vim*scrollForeground:		Blue
    152 
    153 The resources can also be set with arguments to Vim:
    154 
    155     argument		meaning	~
    156 							*-gui*
    157    -display {display}	Run vim on {display}		*-display*
    158    -iconic		Start vim iconified		*-iconic*
    159    -background {color}	Use {color} for the background	*-background*
    160    -bg {color}		idem				*-bg*
    161    -foreground {color}	Use {color} for normal text	*-foreground*
    162    -fg {color}		idem				*-fg*
    163    -ul {color}		idem				*-ul*
    164    -font {font}		Use {font} for normal text	*-font*
    165    -fn {font}		idem				*-fn*
    166    -boldfont {font}	Use {font} for bold text	*-boldfont*
    167    -italicfont {font}	Use {font} for italic text	*-italicfont*
    168    -menufont {font}	Use {font} for menu items	*-menufont*
    169    -menufontset {fontset} Use {fontset} for menu items	*-menufontset*
    170    -mf {font}		idem				*-mf*
    171    -geometry {geom}	Use {geom} for initial geometry	*-geometry*
    172    -geom {geom}		idem, see |-geometry-example|	*-geom*
    173    -borderwidth {width}	Use a border width of {width}	*-borderwidth*
    174    -bw {width}		idem				*-bw*
    175 							*-scrollbarwidth*
    176    -scrollbarwidth {width}	Use a scrollbar width of {width}
    177    -sw {width}		idem				*-sw*
    178    -menuheight {height}	Use a menu bar height of {height} *-menuheight*
    179    -mh {height}		idem				*-mh*
    180 			NOTE: On Motif the value is ignored, the menu height
    181 			is computed to fit the menus.
    182    -reverse		Use reverse video		*-reverse*
    183    -rv			idem				*-rv*
    184    +reverse		Don't use reverse video		*-+reverse*
    185    +rv			idem				*-+rv*
    186    -xrm {resource}	Set the specified resource	*-xrm*
    187 
    188 Note about reverse video: Vim checks that the result is actually a light text
    189 on a dark background.  The reason is that some X11 versions swap the colors,
    190 and some don't.  These two examples will both give yellow text on a blue
    191 background:
    192     gvim -fg Yellow -bg Blue -reverse
    193     gvim -bg Yellow -fg Blue -reverse
    194 
    195 							*-geometry-example*
    196 An example for the geometry argument: >
    197 	gvim -geometry 80x63+8+100
    198 This creates a window with 80 columns and 63 lines at position 8 pixels from
    199 the left and 100 pixels from the top of the screen.
    200 
    201 ==============================================================================
    202 3. Shell Commands					*gui-pty*
    203 
    204 WARNING: Executing an external command from the GUI will not always work.
    205 "normal" commands like "ls", "grep" and "make" mostly work fine.  Commands
    206 that require an intelligent terminal like "less" and "ispell" won't work.
    207 Some may even hang and need to be killed from another terminal.  So be
    208 careful!
    209 
    210 There are two ways to do the I/O with a shell command: Pipes and a pseudo-tty.
    211 The default is to use a pseudo-tty.  This should work best on most systems.
    212 
    213 Unfortunately, the implementation of the pseudo-tty is different on every Unix
    214 system.  And some systems require root permission.  To avoid running into
    215 problems with a pseudo-tty when you least expect it, test it when not editing
    216 a file.  Be prepared to "kill" the started command or Vim.  Commands like
    217 ":r !cat" may hang!
    218 
    219 If using a pseudo-tty does not work for you, reset the 'guipty' option: >
    220 
    221 	:set noguipty
    222 
    223 Using a pipe should work on any Unix system, but there are disadvantages:
    224 - Some shell commands will notice that a pipe is being used and behave
    225   differently.  E.g., ":!ls" will list the files in one column.
    226 - The ":sh" command won't show a prompt, although it will sort of work.
    227 - When using ":make" it's not possible to interrupt with a CTRL-C.
    228 
    229 Typeahead while the external command is running is often lost.  This happens
    230 both with a pipe and a pseudo-tty.  This is a known problem, but it seems it
    231 can't be fixed (or at least, it's very difficult).
    232 
    233 							*gui-pty-erase*
    234 When your erase character is wrong for an external command, you should fix
    235 this in your "~/.cshrc" file, or whatever file your shell uses for
    236 initializations.  For example, when you want to use backspace to delete
    237 characters, but hitting backspaces produces "^H" instead, try adding this to
    238 your "~/.cshrc": >
    239 	stty erase ^H
    240 The ^H is a real CTRL-H, type it as CTRL-V CTRL-H.
    241 
    242 ==============================================================================
    243 4. Various						*gui-x11-various*
    244 
    245 							*gui-x11-printing*
    246 The "File/Print" menu simply sends the current buffer to "lpr".  No options or
    247 whatever.  If you want something else, you can define your own print command.
    248 For example: >
    249 
    250   :10amenu File.Print :w !lpr -Php3
    251   :10vmenu File.Print :w !lpr -Php3
    252 <
    253 							*X11-icon*
    254 Vim uses a black&white icon by default when compiled with Motif.  A
    255 colored Vim icon is included as $VIMRUNTIME/vim32x32.xpm.  For GTK+, this is
    256 the builtin icon used.  Unfortunately, how you should install it depends on
    257 your window manager.  When you use this, remove the 'i' flag from
    258 'guioptions', to remove the black&white icon: >
    259   :set guioptions-=i
    260 
    261 If you use one of the fvwm* family of window managers simply add this line to
    262 your .fvwm2rc configuration file: >
    263 
    264   Style "vim"		Icon vim32x32.xpm
    265 
    266 Make sure the icon file's location is consistent with the window manager's
    267 ImagePath statement.  Either modify the ImagePath from within your .fvwm2rc or
    268 drop the icon into one the pre-defined directories: >
    269 
    270   ImagePath /usr/X11R6/include/X11/pixmaps:/usr/X11R6/include/X11/bitmaps
    271 
    272 Note: older versions of fvwm use "IconPath" instead of "ImagePath".
    273 
    274 For CDE "dtwm" (a derivative of Motif) add this line in the .Xdefaults: >
    275    Dtwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
    276 
    277 For "mwm" (Motif window manager) the line would be: >
    278    Mwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
    279 
    280 
    281 Mouse Pointers Available in X11 ~
    282 						*X11_mouse_shapes*
    283 By using the 'mouseshape' option, the mouse pointer can be automatically
    284 changed whenever Vim enters one of its various modes (e.g., Insert or
    285 Command).  Currently, the available pointers are:
    286 
    287 	arrow			an arrow pointing northwest
    288 	beam			a I-like vertical bar
    289 	size			an arrow pointing up and down
    290 	busy			a wristwatch
    291 	blank			an invisible pointer
    292 	crosshair		a thin "+" sign
    293 	hand1			a dark hand pointing northeast
    294 	hand2			a light hand pointing northwest
    295 	pencil			a pencil pointing southeast
    296 	question		question_arrow
    297 	right_arrow		an arrow pointing northeast
    298 	up_arrow		an arrow pointing upwards
    299 
    300 Additionally, any of the mouse pointers that are built into X11 may be
    301 used by specifying an integer from the X11/cursorfont.h include file.
    302 
    303 If a name is used that exists on other systems, but not in X11, the default
    304 "arrow" pointer is used.
    305 
    306 ==============================================================================
    307 5. GTK version				*gui-gtk* *GTK+* *GTK* *GTK3* *GTK4*
    308 
    309 The GTK version of the GUI works a little bit different.
    310 
    311 GTK does _not_ use the traditional X resource settings.  Thus items in your
    312 ~/.Xdefaults or app-defaults files are not used.
    313 Many of the traditional X command line arguments are not supported.  (e.g.,
    314 stuff like -bg, -fg, etc).  The ones that are supported are:
    315 
    316     command line argument   resource name	meaning ~
    317     -fn  or  -font	    .font		font name for the text
    318     -geom  or  -geometry    .geometry		size of the gvim window
    319     -rv  or  -reverse	    *reverseVideo	white text on black background
    320     -display					display to be used
    321     -fg -foreground {color}			foreground color
    322     -bg -background {color}			background color
    323 
    324 If using the GTK4 GUI, then only the following are supported:
    325     -fn  or  -font
    326     -geom  or  -geometry    (window positioning is NOT supported)
    327     -fg -foreground {color}
    328     -bg -background {color}
    329 
    330 Command line arguments specific to GTK4:
    331     command line argument   meaning ~
    332     --prg-name {name}	    Argument passed to g_set_prgname(), otherwise
    333 			    "gvim" is used.  On Wayland this will set the app
    334 			    id, which is equivalent to the X11 WM_CLASS
    335 
    336 To set the font, see 'guifont'.  For GTK, there's also a menu option that does
    337 this.
    338 
    339 Additionally, there are these command line arguments, which are handled by GTK
    340 internally (except GTK4, see below).  Look in the GTK documentation for how
    341 they are used:
    342 	--sync
    343 	--gdk-debug
    344 	--gdk-no-debug
    345 	--no-xshm	(not in GTK+ 2)
    346 	--xim-preedit	(not in GTK+ 2)
    347 	--xim-status	(not in GTK+ 2)
    348 	--gtk-debug
    349 	--gtk-no-debug
    350 	--g-fatal-warnings
    351 	--gtk-module
    352 	--display	(GTK+ counterpart of -display; works the same way.)
    353 	--screen	(The screen number; for GTK+ 2.2 multihead support.)
    354 
    355 These arguments are ignored when the |+netbeans_intg| feature is used:
    356 	-xrm
    357 	-mf
    358 
    359 If using the GTK4 GUI, then no GTK specific command line arguments are
    360 supported. Instead configure GTK via environment variables:
    361 https://docs.gtk.org/gtk4/running.html
    362 
    363 As for colors, Vim's color settings (for syntax highlighting) is still
    364 done the traditional Vim way.  See |:highlight| for more help.
    365 
    366 If you want to set the colors of remaining gui components (e.g., the
    367 menubar, scrollbar, whatever), those are GTK specific settings and you
    368 need to set those up in some sort of gtkrc file.  You'll have to refer
    369 to the GTK documentation, however little there is, on how to do this.
    370 See https://www.manpagez.com/html/gtk2/gtk2-2.24.24/gtk2-Resource-Files.php
    371 for more information.
    372 							*gtk3-slow*
    373 If the GTK3 GUI is slow, try: >
    374 
    375     $ GDK_RENDERING=image gvim
    376 
    377 Small font, high resolution, many 'lines' (vertical screen) and UI scaling all
    378 contribute to a slower redraw.
    379 
    380 							*gtk4-slow*
    381 If the GTK4 GUI is slow, freezes, or does not accept keyboard input right
    382 after startup, it may be caused by the OpenGL renderer or GPU driver.  Try
    383 starting gvim with one of the following environment variables.  Setting
    384 $GSK_RENDERER to "cairo" disables the GSK OpenGL renderer.  Setting
    385 $LIBGL_ALWAYS_SOFTWARE to "true" retains the OpenGL renderer but forces Mesa
    386 to use software rendering: >
    387 
    388     $ GSK_RENDERER=cairo gvim
    389     $ LIBGL_ALWAYS_SOFTWARE=true gvim
    390 <
    391 Tooltip Colors ~
    392 							*gtk-tooltip-colors*
    393 Example, which sets the tooltip colors to black on light-yellow: >
    394 
    395 	style "tooltips"
    396 	{
    397 		bg[NORMAL] = "#ffffcc"
    398 		fg[NORMAL] = "#000000"
    399 	}
    400 
    401 	widget "gtk-tooltips*"		style "tooltips"
    402 
    403 Write this in the file ~/.gtkrc and it will be used by GTK+.  For GTK+ 2
    404 you might have to use the file ~/.gtkrc-2.0 instead, depending on your
    405 distribution.
    406 
    407 For GTK+ 3, an effect similar to the above can be obtained by adding the
    408 following snippet of CSS code to $XDG_HOME_DIR/gtk-3.0/gtk.css (see the next
    409 section):
    410 
    411 For GTK+ 3 < 3.20: >
    412 
    413 	.tooltip {
    414 		background-color: #ffffcc;
    415 		color: #000000;
    416 	}
    417 <
    418 For GTK+ 3 >= 3.20: >
    419 
    420 	tooltip {
    421 	    background-color: #ffffcc;
    422 	    text-shadow: none;
    423 	}
    424 
    425 	tooltip label {
    426 	    color: #2e3436;
    427 	}
    428 <
    429 
    430 A Quick Look at GTK+ CSS ~
    431 							*gtk-css*
    432 The contents of this subsection apply to GTK+ 3.20 or later which provides
    433 stable support for GTK+ CSS:
    434 
    435 	https://developer.gnome.org/gtk3/stable/theming.html
    436 
    437 GTK+ uses CSS for styling and layout of widgets.  In this subsection, we'll
    438 have a quick look at GTK+ CSS through simple, illustrative examples.
    439 
    440 You can usually edit the config with: >
    441 	vim $HOME/.config/gtk-3.0/gtk.css
    442 
    443 
    444 Example 1.  Empty Space Adjustment ~
    445 
    446 By default, the toolbar and the tabline of the GTK+ 3 GUI are somewhat larger
    447 than those of the GTK+ 2 GUI.  Some people may want to make them look similar
    448 to the GTK+ 2 GUI in size.
    449 
    450 To do that, we'll try reducing empty space around icons and labels that looks
    451 apparently superfluous.
    452 
    453 Add the following lines to $XDG_HOME_DIR/gtk-3.0/gtk.css (usually,
    454 $HOME/.config/gtk-3.0/gtk.css): >
    455 
    456 	toolbar button {
    457 	    margin-top: -2px;
    458 	    margin-right: 0px;
    459 	    margin-bottom: -2px;
    460 	    margin-left: 0px;
    461 
    462 	    padding-top: 0px;
    463 	    padding-right: 0px;
    464 	    padding-bottom: 0px;
    465 	    padding-left: 0px
    466 	}
    467 
    468 	notebook tab {
    469 	    margin-top: -1px;
    470 	    margin-right: 3px;
    471 	    margin-bottom: -1px;
    472 	    margin-left: 3px;
    473 
    474 	    padding-top: 0px;
    475 	    padding-right: 0px;
    476 	    padding-bottom: 0px;
    477 	    padding-left: 0px
    478 	}
    479 <
    480 Since it's a CSS, they can be rewritten using shorthand: >
    481 
    482 	toolbar button {
    483 	    margin: -2px 0px;
    484 	    padding: 0px;
    485 	}
    486 
    487 	notebook tab {
    488 	    margin: -1px 3px;
    489 	    padding: 0px
    490 	}
    491 <
    492 Note: You might want to use 'toolbariconsize' to adjust the icon size, too.
    493 
    494 Note: Depending on the icon theme and/or the font in use, some extra tweaks
    495 may be needed for a satisfactory result.
    496 
    497 Note: In addition to margin and padding, you can use border.  For details,
    498 refer to the box model of CSS, e.g.,
    499 
    500 	https://www.w3schools.com/css/css_boxmodel.asp
    501 
    502 Example 2.  More Than Just Colors ~
    503 
    504 GTK+ CSS supports gradients as well: >
    505 
    506 	tooltip {
    507 	    background-image: -gtk-gradient(linear,
    508 					    0 0, 0 1,
    509 					    color-stop(0, #344752),
    510 					    color-stop(0.5, #546772),
    511 					    color-stop(1, #243742));
    512 	}
    513 
    514 	tooltip label {
    515 	    color: #f3f3f3;
    516 	}
    517 <
    518 Gradients can be used to make a GUI element visually distinguishable from
    519 others without relying on high contrast. Accordingly, effective use of them is
    520 a useful technique to give a theme a sense of unity in color and luminance.
    521 
    522 Note: Theming can be difficult since it must make every application look
    523 equally good; making a single application more charming often gets others
    524 unexpectedly less attractive or even deteriorates their usability.  Keep this
    525 in mind always when you try improving a theme.
    526 
    527 
    528 Example 3.  border color ~
    529 
    530 To eliminate borders when maximized: >
    531 
    532     @define-color bg_color #1B2B34;
    533     #vim-main-window {
    534 	background-color: @bg_color;
    535     }
    536 
    537 
    538 Using Vim as a GTK+ plugin ~
    539 							*gui-gtk-socketid*
    540 When the GTK+ version of Vim starts up normally, it creates its own top level
    541 window (technically, a 'GtkWindow').  GTK+ provides an embedding facility with
    542 its GtkSocket and GtkPlug widgets.  If one GTK+ application creates a
    543 GtkSocket widget in one of its windows, an entirely different GTK+ application
    544 may embed itself into the first application by creating a top-level GtkPlug
    545 widget using the socket's ID.
    546 
    547 If you pass Vim the command-line option '--socketid' with a decimal or
    548 hexadecimal value, Vim will create a GtkPlug widget using that value instead
    549 of the normal GtkWindow.  This enables Vim to act as a GTK+ plugin.
    550 
    551 This really is a programmer's interface, and is of no use without a supporting
    552 application to spawn the Vim correctly.  For more details on GTK+ sockets, see
    553 https://www.gtk.org/docs/apis/index
    554 
    555 Note that this feature requires the latest GTK version.  GTK 1.2.10 still has
    556 a small problem.  The socket feature has not yet been tested with GTK+ 2 --
    557 feel free to volunteer.
    558 
    559 ==============================================================================
    560 6. GNOME version				*gui-gnome* *Gnome* *GNOME*
    561 
    562 The GNOME GUI works just like the GTK+ version.  See |GTK+| above for how it
    563 works.  It looks a bit different though, and implements one important feature
    564 that's not available in the plain GTK+ GUI:  Interaction with the session
    565 manager. |gui-gnome-session|
    566 
    567 These are the different looks:
    568 - Uses GNOME dialogs (GNOME 1 only).  The GNOME 2 GUI uses the same nice
    569   dialogs as the GTK+ 2 version.
    570 - Uses the GNOME dock, so that the toolbar and menubar can be moved to
    571   different locations other than the top (e.g., the toolbar can be placed on
    572   the left, right, top, or bottom).  The placement of the menubar and
    573   toolbar is only saved in the GNOME 2 version.
    574 - That means the menubar and toolbar handles are back!  Yeah!  And the
    575   resizing grid still works too.
    576 
    577 GNOME is compiled with if it was found by configure and the
    578 --enable-gnome-check argument was used.
    579 
    580 Note: Avoid use of --enable-gnome-check with GTK+ 3 GUI build.  The
    581 functionality mentioned above is consolidated in GTK+ 3.
    582 
    583 
    584 GNOME session support ~
    585 					*gui-gnome-session* *gnome-session*
    586 On logout, Vim shows the well-known exit confirmation dialog if any buffers
    587 are modified.  Clicking [Cancel] will stop the logout process.  Otherwise the
    588 current session is stored to disk by using the |:mksession| command, and
    589 restored the next time you log in.
    590 
    591 The GNOME session support should also work with the KDE session manager.
    592 If you are experiencing any problems please report them as bugs.
    593 
    594 Note: The automatic session save works entirely transparent, in order to
    595 avoid conflicts with your own session files, scripts and autocommands.  That
    596 means in detail:
    597 - The session file is stored to a separate directory (usually $HOME/.gnome2).
    598 - 'sessionoptions' is ignored, and a hardcoded set of appropriate flags is
    599   used instead: >
    600 	blank,curdir,folds,globals,help,options,tabpages,winsize
    601 - The internal variable |v:this_session| is not changed when storing the
    602   session.  Also, it is restored to its old value when logging in again.
    603 
    604 The position and size of the GUI window is not saved by Vim since doing so
    605 is the window manager's job.  But if compiled with GTK+ 2 support, Vim helps
    606 the WM to identify the window by restoring the window role (using the |--role|
    607 command line argument).
    608 
    609 ==============================================================================
    610 7. KDE version					*gui-kde* *kde* *KDE* *KVim*
    611 							*gui-x11-kde*
    612 There is no KDE version of Vim.  There has been some work on a port using the
    613 Qt toolkit, but it never worked properly and it has been abandoned.  Work
    614 continues on Yzis: https://github.com/chrizel/Yzis but it seems also
    615 abandoned.
    616 
    617 ==============================================================================
    618 8. Compiling						*gui-x11-compiling*
    619 
    620 If using X11, Vim's configure will by default first try to find the necessary
    621 GTK+ files on your system.  When both GTK+ 2 and GTK+ 3 are available, GTK+ 2
    622 will be chosen unless --enable-gui=gtk3 is passed explicitly to configure.
    623 
    624 If the GTK+ files cannot be found, then the Motif files will be searched for.
    625 If both fail, the GUI will be disabled.
    626 
    627 For GTK+, Vim's configuration process uses pkg-config(1) to check if the
    628 GTK+ required for a specified build is properly installed and usable.
    629 Accordingly, it is a good idea to make sure before running configure that
    630 your system has a working pkg-config together with the .pc file of the
    631 required GTK+.  For that, say, run the following on the command line to see if
    632 your pkg-config works with your GTK+ 2: >
    633 
    634     $ pkg-config --modversion gtk+-2.0
    635 
    636 Replace gtk+-2.0 with gtk+-3.0 for GTK+ 3.  If you get the correct version
    637 number of your GTK+, you can proceed; if not, you probably need to do some
    638 system administration chores to set up pkg-config and GTK+ correctly.
    639 
    640 The GTK+ 2 GUI is built by default.  Therefore, you usually don't need to pass
    641 any options such as --enable-gui=gtk2 to configure and build that.
    642 
    643 Optionally, the GTK+ 2 GUI can consolidate the GNOME 2 support.  This support
    644 is enabled by passing --enable-gnome-check to configure.
    645 
    646 If you want to build the GTK+ 3 GUI, you have to pass --enable-gui=gtk3
    647 explicitly to configure, and avoid passing --enable-gnome-check to that, as
    648 the functionality of the GNOME 2 support has already been consolidated in
    649 GTK+ 3.
    650 
    651 Otherwise, if you are using Motif, when you have the Motif files in a
    652 directory where configure doesn't look, edit the Makefile to enter the names
    653 of the directories.  Search for "GUI_INC_LOC" for an example to set
    654 the Motif directories.
    655 
    656 							*gui-x11-gtk*
    657 Currently, Vim supports both GTK+ 2 and GTK+ 3.
    658 
    659 The GTK+ 2 GUI requires GTK+ 2.2 or later.
    660 
    661 Although the GTK+ 3 GUI is written in such a way that the source code can be
    662 compiled against all versions of the 3.x series, we recommend GTK+ 3.10 or
    663 later because of its substantial implementation changes in redraw done at
    664 that version.
    665 
    666 							*gui-x11-motif*
    667 For Motif, you need at least Motif version 1.2 and/or X11R5.  Motif 2.0 and
    668 X11R6 are OK.  Motif 1.1 and X11R4 might work, no guarantee (there may be a
    669 few problems, but you might make it compile and run with a bit of work, please
    670 send patches if you do).  The newest releases of LessTif have been reported to
    671 work fine too.
    672 
    673 					    *gui-x11-athena* *gui-x11-neXtaw*
    674 Support for the Athena GUI and neXtaw was removed in patch 8.2.4677.
    675 
    676 							*gui-x11-misc*
    677 In general, do not try to mix files from different GTK+, Motif and X11
    678 versions.  This will cause problems.  For example, using header files for
    679 X11R5 with a library for X11R6 probably doesn't work (although the linking
    680 won't give an error message, Vim will crash later).
    681 
    682 							*gui-wayland*
    683 Support for the Wayland display server protocol has landed in patch 9.1.0064,
    684 for the GTK3 GUI. It is recommended to use the GTK4 GUI if you want a better
    685 Wayland experience however, as the GTK3 GUI is heavily built around X11
    686 specific features and API calls.
    687 
    688 
    689 Note: The Wayland protocol is subject to some restrictions, so the following
    690 functions won't work: |getwinpos()|, |getwinposx()|, |getwinposy()| and the
    691 |v:windowid| variable won't be available.
    692 
    693 ==============================================================================
    694 9. X11 selection mechanism				*x11-selection*
    695 
    696 If using X11, in either the GUI or an xterm with an X11-aware Vim, then Vim
    697 provides varied access to the X11 selection and clipboard.  These are accessed
    698 by using the two selection registers "* and "+.
    699 
    700 X11 provides two basic types of global store, selections and cut-buffers,
    701 which differ in one important aspect: selections are "owned" by an
    702 application, and disappear when that application (e.g., Vim) exits, thus
    703 losing the data, whereas cut-buffers, are stored within the X-server itself
    704 and remain until written over or the X-server exits (e.g., upon logging out).
    705 
    706 The contents of selections are held by the originating application (e.g., upon
    707 a copy), and only passed on to another application when that other application
    708 asks for them (e.g., upon a paste).
    709 
    710 The contents of cut-buffers are immediately written to, and are then
    711 accessible directly from the X-server, without contacting the originating
    712 application.
    713 
    714 							*quoteplus* *quote+*
    715 There are three documented X selections: PRIMARY (which is expected to
    716 represent the current visual selection - as in Vim's Visual mode), SECONDARY
    717 (which is ill-defined) and CLIPBOARD (which is expected to be used for
    718 cut, copy and paste operations).
    719 
    720 Of these three, Vim uses PRIMARY when reading and writing the "* register
    721 (hence when the X11 selections are available, Vim sets a default value for
    722 'clipboard' of "autoselect"), and CLIPBOARD when reading and writing the "+
    723 register.  Vim does not access the SECONDARY selection.
    724 
    725 This applies both to the GUI and the terminal version.  For non-X11 systems
    726 the plus and the star register both use the system clipboard.
    727 
    728 Examples: (assuming the default option values)
    729 - Select a URL in Visual mode in Vim.  Go to your browser and click the
    730   middle mouse button in the URL text field.  The selected text will be
    731   inserted (hopefully!).  Note: in Firefox you can set the
    732   middlemouse.contentLoadURL preference to true in about:config, then the
    733   selected URL will be used when pressing middle mouse button in most places
    734   in the window.
    735 - Select some text in your browser by dragging with the mouse.  Go to Vim and
    736   press the middle mouse button: The selected text is inserted.
    737 - Select some text in Vim and do "+y.  Go to your browser, select some text in
    738   a textfield by dragging with the mouse.  Now use the right mouse button and
    739   select "Paste" from the popup menu.  The selected text is overwritten by the
    740   text from Vim.
    741 Note that the text in the "+ register remains available when making a Visual
    742 selection, which makes other text available in the "* register.  That allows
    743 overwriting selected text.
    744 
    745 								*W23*
    746 When you are yanking into the "* or "+ register and Vim cannot establish a
    747 connection to the X11 selection (or clipboard), it will use register 0 and
    748 output a warning:
    749 
    750   Warning: Clipboard register not available, using register 0 ~
    751 
    752 Note: This also applies to the Wayland clipboard feature as well.
    753 
    754 								*W24*
    755 Vim comes in different flavors, from a tiny build, that just tries to be
    756 compatible to original Vi, to enhanced builds which include many improvements
    757 (like a GUI).  However, on servers and embedded systems, Vim is typically
    758 compiled without clipboard support, since this feature requires X11 libraries
    759 to be present.  Check the ":version" output for the flag |+clipboard| or
    760 -clipboard.  The former means clipboard support is present while the latter
    761 means your Vim does not contain clipboard support.
    762 
    763 In the case when you are trying to access the "* or "+ register and Vim has
    764 no clipboard support, you will see this warning:
    765 
    766   Warning: Clipboard register not available. See :h W24~
    767 
    768 If you have a vim with no clipboard support but would like to use the
    769 clipboard, try to install a more enhanced Vim package like vim-enhanced or
    770 vim-gtk3 (the gui packages usually also come with a terminal Vim that has
    771 clipboard support included).
    772 
    773 							*x11-cut-buffer*
    774 There are, by default, 8 cut-buffers: CUT_BUFFER0 to CUT_BUFFER7.  Vim only
    775 uses CUT_BUFFER0, which is the one that xterm uses by default.
    776 
    777 Whenever Vim is about to become unavailable (either via exiting or becoming
    778 suspended), and thus unable to respond to another application's selection
    779 request, it writes the contents of any owned selection to CUT_BUFFER0.  If the
    780 "+ CLIPBOARD selection is owned by Vim, then this is written in preference,
    781 otherwise if the "* PRIMARY selection is owned by Vim, then that is written.
    782 
    783 Similarly, when Vim tries to paste from "* or "+ (either explicitly, or, in
    784 the case of the "* register, when the middle mouse button is clicked), if the
    785 requested X selection is empty or unavailable, Vim reverts to reading the
    786 current value of the CUT_BUFFER0.
    787 
    788 Note that when text is copied to CUT_BUFFER0 in this way, the type of
    789 selection (character, line or block) is always lost, even if it is a Vim which
    790 later pastes it.
    791 
    792 Xterm, by default, always writes visible selections to both PRIMARY and
    793 CUT_BUFFER0.  When it pastes, it uses PRIMARY if this is available, or else
    794 falls back upon CUT_BUFFER0.  For this reason, when cutting and pasting
    795 between Vim and an xterm, you should use the "* register.  Xterm doesn't use
    796 CLIPBOARD, thus the "+ doesn't work with xterm.
    797 
    798 Most newer applications will provide their current selection via PRIMARY ("*)
    799 and use CLIPBOARD ("+) for cut/copy/paste operations.  You thus have access to
    800 both by choosing to use either of the "* or "+ registers.
    801 
    802 							*gtk4-menu-navigation*
    803 In the GTK 4 GUI, you may also navigate the menu items with these keyboard
    804 mappings:
    805     key			meaning ~
    806     <Tab> <Down>	Go to next item
    807     <S-Tab> <Up>	Go to previous item
    808     <Left>		Go to parent submenu
    809     <Right>		Go to current item's submenu
    810     <C-Left>		Go to next menu bar item
    811     <C-Right>		Go to previous menu bar item
    812 
    813 
    814  vim:tw=78:sw=4:ts=8:noet:ft=help:norl: