1 *gui_x11.txt* For Vim version 7.3. Last change: 2010 Jul 20
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Vim's Graphical User Interface *gui-x11* *GUI-X11*
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|
19 Other relevant documentation:
20 |gui.txt| For generic items of the GUI.
22 {Vi does not have any of these commands}
24 ==============================================================================
25 1. Starting the X11 GUI *gui-x11-start* *E665*
27 Then you can run the GUI version of Vim in either of these ways:
28 gvim [options] [files...]
29 vim -g [options] [files...]
31 So if you call the executable "gvim", or make "gvim" a link to the executable,
32 then the GUI version will automatically be used. Additional characters may be
33 added after "gvim", for example "gvim-5".
35 You may also start up the GUI from within the terminal version by using one of
37 :gui [++opt] [+cmd] [-f|-b] [files...] *:gu* *:gui*
38 :gvim [++opt] [+cmd] [-f|-b] [files...] *:gv* *:gvim*
39 The "-f" option runs Vim in the foreground.
40 The "-b" option runs Vim in the background (this is the default).
41 Also see |++opt| and |+cmd|.
44 When the GUI is started, it does a fork() and exits the current process.
45 When gvim was started from a shell this makes the shell accept further
46 commands. If you don't want this (e.g. when using gvim for a mail program
47 that waits for gvim to exit), start gvim with "gvim -f", "vim -gf" or use
48 ":gui -f". Don't use "vim -fg", because "-fg" specifies the foreground
51 When using "gvim -f" and then ":gui", Vim will run in the foreground. The
52 "-f" argument will be remembered. To force running Vim in the background use
55 "gvim --nofork" does the same as "gvim -f".
57 If you want the GUI to run in the foreground always, include the 'f'
58 flag in 'guioptions'. |-f|.
60 ==============================================================================
61 2. GUI Resources *gui-resources* *.Xdefaults*
63 If using the Motif or Athena version of the GUI (not for the KDE, GTK+ or Win32
64 version), a number of X resources are available. You should use Vim's class
65 "Vim" when setting these. They are as follows:
67 Resource name Meaning ~
69 reverseVideo Boolean: should reverse video be used?
70 background Color of background.
71 foreground Color of normal text.
72 scrollBackground Color of trough portion of scrollbars.
73 scrollForeground Color of slider and arrow portions of scrollbars.
74 menuBackground Color of menu backgrounds.
75 menuForeground Color of menu foregrounds.
76 tooltipForeground Color of tooltip and balloon foreground.
77 tooltipBackground Color of tooltip and balloon background.
79 font Name of font used for normal text.
80 boldFont Name of font used for bold text.
81 italicFont Name of font used for italic text.
82 boldItalicFont Name of font used for bold, italic text.
83 menuFont Name of font used for the menus, used when compiled
84 without the |+xfontset| feature
85 menuFontSet Name of fontset used for the menus, used when compiled
86 with the |+xfontset| feature
87 tooltipFont Name of the font used for the tooltip and balloons.
88 When compiled with the |+xfontset| feature this is a
91 geometry Initial geometry to use for gvim's window (default
92 is same size as terminal that started it).
93 scrollbarWidth Thickness of scrollbars.
94 borderWidth Thickness of border around text area.
95 menuHeight Height of the menu bar (only for Athena).
97 A special font for italic, bold, and italic-bold text will only be used if
98 the user has specified one via a resource. No attempt is made to guess what
99 fonts should be used for these based on the normal text font.
101 Note that the colors can also be set with the ":highlight" command, using the
102 "Normal", "Menu", "Tooltip", and "Scrollbar" groups. Example: >
103 :highlight Menu guibg=lightblue
104 :highlight Tooltip guibg=yellow
105 :highlight Scrollbar guibg=lightblue guifg=blue
106 :highlight Normal guibg=grey90
109 Note: All fonts (except for the menu and tooltip) must be of the same size!!!
110 If you don't do this, text will disappear or mess up the display. Vim does
111 not check the font sizes. It's the size in screen pixels that must be the
112 same. Note that some fonts that have the same point size don't have the same
113 pixel size! Additionally, the positioning of the fonts must be the same
114 (ascent and descent). You can check this with "xlsfonts -l {fontname}".
116 If any of these things are also set with Vim commands, e.g. with
117 ":set guifont=Screen15", then this will override the X resources (currently
118 'guifont' is the only option that is supported).
120 Here is an example of what you might put in your ~/.Xdefaults file: >
124 Vim*useEnhancedFSB: true
125 Vim.foreground: Black
126 Vim.background: Wheat
129 The first three of these are standard resources on Silicon Graphics machines
130 which make Motif applications look even better, highly recommended!
132 The "Vim*fontList" is to set the menu font for Motif. Example: >
133 Vim*menuBar*fontList: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
135 Vim*menuBar*SmeBSB*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
136 Vim*menuBar*MenuButton*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
138 NOTE: A more portable, and indeed more correct, way to specify the menu font
139 in either Motif or Athena 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-*-*-*-*-*-*-*
144 Don't use "Vim*geometry" in the defaults. This will break the menus. Use
145 "Vim.geometry" instead.
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): >
150 Vim*scrollBackground: Black
151 Vim*scrollForeground: Blue
153 The resources can also be set with arguments to Vim:
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*
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*
184 +reverse Don't use reverse video *-+reverse*
186 -xrm {resource} Set the specified resource *-xrm*
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
192 gvim -fg Yellow -bg Blue -reverse
193 gvim -bg Yellow -fg Blue -reverse
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.
201 ==============================================================================
202 3. Shell Commands *gui-pty*
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
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.
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
219 If using a pseudo-tty does not work for you, reset the 'guipty' option: >
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.
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).
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
240 The ^H is a real CTRL-H, type it as CTRL-V CTRL-H.
242 ==============================================================================
243 4. Various *gui-x11-various*
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.
250 :10amenu File.Print :w !lpr -Php3
251 :10vmenu File.Print :w !lpr -Php3
254 Vim uses a black&white icon by default when compiled with Motif or Athena. 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: >
261 If you use one of the fvwm* family of window managers simply add this line to
262 your .fvwm2rc configuration file: >
264 Style "vim" Icon vim32x32.xpm
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: >
270 ImagePath /usr/X11R6/include/X11/pixmaps:/usr/X11R6/include/X11/bitmaps
272 Note: older versions of fvwm use "IconPath" instead of "ImagePath".
274 For CDE "dtwm" (a derivative of Motif) add this line in the .Xdefaults: >
275 Dtwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
277 For "mwm" (Motif window manager) the line would be: >
278 Mwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
280 Mouse Pointers Available in X11 *X11_mouse_shapes*
282 By using the |'mouseshape'| option, the mouse pointer can be automatically
283 changed whenever Vim enters one of its various modes (e.g., Insert or
284 Command). Currently, the available pointers are:
286 arrow an arrow pointing northwest
287 beam a I-like vertical bar
288 size an arrow pointing up and down
290 blank an invisible pointer
291 crosshair a thin "+" sign
292 hand1 a dark hand pointing northeast
293 hand2 a light hand pointing northwest
294 pencil a pencil pointing southeast
295 question question_arrow
296 right_arrow an arrow pointing northeast
297 up_arrow an arrow pointing upwards
299 Additionally, any of the mouse pointers that are built into X11 may be
300 used by specifying an integer from the X11/cursorfont.h include file.
302 If a name is used that exists on other systems, but not in X11, the default
303 "arrow" pointer is used.
305 ==============================================================================
306 5. GTK version *gui-gtk* *GTK+* *GTK*
308 The GTK version of the GUI works a little bit different.
310 GTK does _not_ use the traditional X resource settings. Thus items in your
311 ~/.Xdefaults or app-defaults files are not used.
312 Many of the traditional X command line arguments are not supported. (e.g.,
313 stuff like -bg, -fg, etc). The ones that are supported are:
315 command line argument resource name meaning ~
316 -fn or -font .font font name for the text
317 -geom or -geometry .geometry size of the gvim window
318 -rv or -reverse *reverseVideo white text on black background
319 -display display to be used
320 -fg -foreground {color} foreground color
321 -bg -background {color} background color
323 To set the font, see |'guifont'|. For GTK, there's also a menu option that
326 Additionally, there are these command line arguments, which are handled by GTK
327 internally. Look in the GTK documentation for how they are used:
331 --no-xshm (not in GTK+ 2)
332 --xim-preedit (not in GTK+ 2)
333 --xim-status (not in GTK+ 2)
338 --display (GTK+ counterpart of -display; works the same way.)
339 --screen (The screen number; for GTK+ 2.2 multihead support.)
341 These arguments are ignored when the |+netbeans_intg| feature is used:
345 As for colors, Vim's color settings (for syntax highlighting) is still
346 done the traditional Vim way. See |:highlight| for more help.
348 If you want to set the colors of remaining gui components (e.g., the
349 menubar, scrollbar, whatever), those are GTK specific settings and you
350 need to set those up in some sort of gtkrc file. You'll have to refer
351 to the GTK documentation, however little there is, on how to do this.
352 See http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html
353 for more information.
356 Example, which sets the tooltip colors to black on light-yellow: >
360 bg[NORMAL] = "#ffffcc"
361 fg[NORMAL] = "#000000"
364 widget "gtk-tooltips*" style "tooltips"
366 Write this in the file ~/.gtkrc and it will be used by GTK+. For GTK+ 2
367 you might have to use the file ~/.gtkrc-2.0 instead, depending on your
370 Using Vim as a GTK+ plugin *gui-gtk-socketid*
372 When the GTK+ version of Vim starts up normally, it creates its own top level
373 window (technically, a 'GtkWindow'). GTK+ provides an embedding facility with
374 its GtkSocket and GtkPlug widgets. If one GTK+ application creates a
375 GtkSocket widget in one of its windows, an entirely different GTK+ application
376 may embed itself into the first application by creating a top-level GtkPlug
377 widget using the socket's ID.
379 If you pass Vim the command-line option '--socketid' with a decimal or
380 hexadecimal value, Vim will create a GtkPlug widget using that value instead
381 of the normal GtkWindow. This enables Vim to act as a GTK+ plugin.
383 This really is a programmer's interface, and is of no use without a supporting
384 application to spawn the Vim correctly. For more details on GTK+ sockets, see
385 http://www.gtk.org/api/
387 Note that this feature requires the latest GTK version. GTK 1.2.10 still has
388 a small problem. The socket feature has not yet been tested with GTK+ 2 --
389 feel free to volunteer.
391 ==============================================================================
392 6. GNOME version *gui-gnome* *Gnome* *GNOME*
394 The GNOME GUI works just like the GTK+ version. See |GTK+| above for how it
395 works. It looks a bit different though, and implements one important feature
396 that's not available in the plain GTK+ GUI: Interaction with the session
397 manager. |gui-gnome-session|
399 These are the different looks:
400 - Uses GNOME dialogs (GNOME 1 only). The GNOME 2 GUI uses the same nice
401 dialogs as the GTK+ 2 version.
402 - Uses the GNOME dock, so that the toolbar and menubar can be moved to
403 different locations other than the top (e.g., the toolbar can be placed on
404 the left, right, top, or bottom). The placement of the menubar and
405 toolbar is only saved in the GNOME 2 version.
406 - That means the menubar and toolbar handles are back! Yeah! And the
407 resizing grid still works too.
409 GNOME is compiled with if it was found by configure and the
410 --enable-gnome-check argument was used.
413 GNOME session support *gui-gnome-session* *gnome-session*
415 On logout, Vim shows the well-known exit confirmation dialog if any buffers
416 are modified. Clicking [Cancel] will stop the logout process. Otherwise the
417 current session is stored to disk by using the |:mksession| command, and
418 restored the next time you log in.
420 The GNOME session support should also work with the KDE session manager.
421 If you are experiencing any problems please report them as bugs.
423 Note: The automatic session save works entirely transparent, in order to
424 avoid conflicts with your own session files, scripts and autocommands. That
426 - The session file is stored to a separate directory (usually $HOME/.gnome2).
427 - 'sessionoptions' is ignored, and a hardcoded set of appropriate flags is
429 blank,curdir,folds,globals,help,options,tabpages,winsize
430 - The internal variable |v:this_session| is not changed when storing the
431 session. Also, it is restored to its old value when logging in again.
433 The position and size of the GUI window is not saved by Vim since doing so
434 is the window manager's job. But if compiled with GTK+ 2 support, Vim helps
435 the WM to identify the window by restoring the window role (using the |--role|
436 command line argument).
438 ==============================================================================
439 7. KDE version *gui-kde* *kde* *KDE* *KVim*
441 There is no KDE version of Vim. There has been some work on a port using the
442 Qt toolkit, but it never worked properly and it has been abandoned. Work
443 continues on Yzis: www.yzis.org.
445 ==============================================================================
446 8. Compiling *gui-x11-compiling*
448 If using X11, Vim's Makefile will by default first try to find the necessary
449 GTK+ files on your system. If the GTK+ files cannot be found, then the Motif
450 files will be searched for. Finally, if this fails, the Athena files will be
451 searched for. If all three fail, the GUI will be disabled.
453 For GTK+, Vim's configuration process requires that GTK+ be properly
454 installed. That is, the shell script 'gtk-config' must be in your PATH, and
455 you can already successful compile, build, and execute a GTK+ program. The
456 reason for this is that the compiler flags (CFLAGS) and link flags (LDFLAGS)
457 are obtained through the 'gtk-config' shell script.
459 If you want to build with GTK+ 2 support pass the --enable-gtk2-check argument
460 to ./configure. Optionally, support for GNOME 2 will be compiled if the
461 --enable-gnome-check option is also given.
463 Otherwise, if you are using Motif or Athena, when you have the Motif or Athena
464 files in a directory where configure doesn't look, edit the Makefile to enter
465 the names of the directories. Search for "GUI_INC_LOC" for an example to set
466 the Motif directories, "CONF_OPT_X" for Athena.
469 At the time of this writing, GTK+ version 1.0.6 and 1.2 are outdated. It
470 is suggested that you use GTK 2. The GTK 1 support will most likely be
473 For the GTK+ 2 GUI, using the latest release of the GTK+ 2.0 or GTK+ 2.2
474 series is recommended.
476 Lastly, although GTK+ has supposedly been ported to the Win32 platform, this
477 has not been tested with Vim and is also unsupported. Also, it's unlikely to
478 even compile since GTK+ GUI uses parts of the generic X11 code. This might
479 change in distant future; particularly because getting rid of the X11 centric
480 code parts is also required for GTK+ framebuffer support.
483 For Motif, you need at least Motif version 1.2 and/or X11R5. Motif 2.0 and
484 X11R6 are OK. Motif 1.1 and X11R4 might work, no guarantee (there may be a
485 few problems, but you might make it compile and run with a bit of work, please
486 send me the patches if you do). The newest releases of LessTif have been
487 reported to work fine too.
490 The Athena version uses the Xaw widget set by default. If you have the 3D
491 version, you might want to link with Xaw3d instead. This will make the
492 menus look a bit better. Edit the Makefile and look for "XAW_LIB". The
493 scrollbars will remain the same, because Vim has its own, which are already
494 3D (in fact, they look more like Motif).
497 The neXtaw version is mostly like Athena, but uses different widgets.
500 In general, do not try to mix files from different GTK+, Motif, Athena and X11
501 versions. This will cause problems. For example, using header files for
502 X11R5 with a library for X11R6 probably doesn't work (although the linking
503 won't give an error message, Vim will crash later).
505 ==============================================================================
506 9. X11 selection mechanism *x11-selection*
508 If using X11, in either the GUI or an xterm with an X11-aware Vim, then Vim
509 provides varied access to the X11 selection and clipboard. These are accessed
510 by using the two selection registers "* and "+.
512 X11 provides two basic types of global store, selections and cut-buffers,
513 which differ in one important aspect: selections are "owned" by an
514 application, and disappear when that application (e.g., Vim) exits, thus
515 losing the data, whereas cut-buffers, are stored within the X-server itself
516 and remain until written over or the X-server exits (e.g., upon logging out).
518 The contents of selections are held by the originating application (e.g., upon
519 a copy), and only passed on to another application when that other application
520 asks for them (e.g., upon a paste).
522 The contents of cut-buffers are immediately written to, and are then
523 accessible directly from the X-server, without contacting the originating
527 There are three documented X selections: PRIMARY (which is expected to
528 represent the current visual selection - as in Vim's Visual mode), SECONDARY
529 (which is ill-defined) and CLIPBOARD (which is expected to be used for
530 cut, copy and paste operations).
532 Of these three, Vim uses PRIMARY when reading and writing the "* register
533 (hence when the X11 selections are available, Vim sets a default value for
534 |'clipboard'| of "autoselect"), and CLIPBOARD when reading and writing the "+
535 register. Vim does not access the SECONDARY selection.
537 Examples: (assuming the default option values)
538 - Select an URL in Visual mode in Vim. Go to your browser and click the
539 middle mouse button in the URL text field. The selected text will be
540 inserted (hopefully!). Note: in Firefox you can set the
541 middlemouse.contentLoadURL preference to true in about:config, then the
542 selected URL will be used when pressing middle mouse button in most places
544 - Select some text in your browser by dragging with the mouse. Go to Vim and
545 press the middle mouse button: The selected text is inserted.
546 - Select some text in Vim and do "+y. Go to your browser, select some text in
547 a textfield by dragging with the mouse. Now use the right mouse button and
548 select "Paste" from the popup menu. The selected text is overwritten by the
550 Note that the text in the "+ register remains available when making a Visual
551 selection, which makes other text available in the "* register. That allows
552 overwriting selected text.
554 There are, by default, 8 cut-buffers: CUT_BUFFER0 to CUT_BUFFER7. Vim only
555 uses CUT_BUFFER0, which is the one that xterm uses by default.
557 Whenever Vim is about to become unavailable (either via exiting or becoming
558 suspended), and thus unable to respond to another application's selection
559 request, it writes the contents of any owned selection to CUT_BUFFER0. If the
560 "+ CLIPBOARD selection is owned by Vim, then this is written in preference,
561 otherwise if the "* PRIMARY selection is owned by Vim, then that is written.
563 Similarly, when Vim tries to paste from "* or "+ (either explicitly, or, in
564 the case of the "* register, when the middle mouse button is clicked), if the
565 requested X selection is empty or unavailable, Vim reverts to reading the
566 current value of the CUT_BUFFER0.
568 Note that when text is copied to CUT_BUFFER0 in this way, the type of
569 selection (character, line or block) is always lost, even if it is a Vim which
572 Xterm, by default, always writes visible selections to both PRIMARY and
573 CUT_BUFFER0. When it pastes, it uses PRIMARY if this is available, or else
574 falls back upon CUT_BUFFER0. For this reason, when cutting and pasting
575 between Vim and an xterm, you should use the "* register. Xterm doesn't use
576 CLIPBOARD, thus the "+ doesn't work with xterm.
578 Most newer applications will provide their current selection via PRIMARY ("*)
579 and use CLIPBOARD ("+) for cut/copy/paste operations. You thus have access to
580 both by choosing to use either of the "* or "+ registers.
583 vim:tw=78:sw=4:ts=8:ft=help:norl: