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: