1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
|
*gui_x11.txt* For Vim version 7.0aa. Last change: 2004 Dec 29
VIM REFERENCE MANUAL by Bram Moolenaar
Vim's Graphical User Interface *gui-x11* *GUI-X11*
*Athena* *Motif*
1. Starting the X11 GUI |gui-x11-start|
2. GUI Resources |gui-resources|
3. Shell Commands |gui-pty|
4. Various |gui-x11-various|
5. GTK version |gui-gtk|
6. GNOME version |gui-gnome|
7. KDE version |gui-kde|
8. Compiling |gui-x11-compiling|
9. X11 selection mechanism |x11-selection|
Other relevant documentation:
|gui.txt| For generic items of the GUI.
{Vi does not have any of these commands}
==============================================================================
1. Starting the X11 GUI *gui-x11-start* *E665*
Then you can run the GUI version of Vim in either of these ways:
gvim [options] [files...]
vim -g [options] [files...]
So if you call the executable "gvim", or make "gvim" a link to the executable,
then the GUI version will automatically be used. Additional characters may be
added after "gvim", for example "gvim-5".
You may also start up the GUI from within the terminal version by using one of
these commands:
:gui [++opt] [+cmd] [-f|-b] [files...] *:gu* *:gui*
:gvim [++opt] [+cmd] [-f|-b] [files...] *:gv* *:gvim*
The "-f" option runs Vim in the foreground.
The "-b" option runs Vim in the background (this is the default).
Also see |++opt| and |+cmd|.
*gui-fork*
When the GUI is started, it does a fork() and exits the current process.
When gvim was started from a shell this makes the shell accept further
commands. If you don't want this (e.g. when using gvim for a mail program
that waits for gvim to exit), start gvim with "gvim -f", "vim -gf" or use
":gui -f". Don't use "vim -fg", because "-fg" specifies the foreground
color.
When using "gvim -f" and then ":gui", Vim will run in the foreground. The
"-f" argument will be remembered. To force running Vim in the background use
":gui -b".
"gvim --nofork" does the same as "gvim -f".
If you want the GUI to run in the foreground always, include the 'f'
flag in 'guioptions'. |-f|.
==============================================================================
2. GUI Resources *gui-resources* *.Xdefaults*
If using the Motif or Athena version of the GUI (not for the KDE, GTK+ or Win32
version), a number of X resources are available. You should use Vim's class
"Vim" when setting these. They are as follows:
Resource name Meaning ~
reverseVideo Boolean: should reverse video be used?
background Color of background.
foreground Color of normal text.
scrollBackground Color of trough portion of scrollbars.
scrollForeground Color of slider and arrow portions of scrollbars.
menuBackground Color of menu backgrounds.
menuForeground Color of menu foregrounds.
tooltipForeground Color of tooltip and balloon foreground.
tooltipBackground Color of tooltip and balloon background.
font Name of font used for normal text.
boldFont Name of font used for bold text.
italicFont Name of font used for italic text.
boldItalicFont Name of font used for bold, italic text.
menuFont Name of font used for the menus, used when compiled
without the |+xfontset| feature
menuFontSet Name of fontset used for the menus, used when compiled
with the |+xfontset| feature
tooltipFont Name of the font used for the tooltip and balloons.
When compiled with the |+xfontset| feature this is a
fontset name.
geometry Initial geometry to use for gvim's window (default
is same size as terminal that started it).
scrollbarWidth Thickness of scrollbars.
borderWidth Thickness of border around text area.
menuHeight Height of the menu bar (only for Athena).
A special font for italic, bold, and italic-bold text will only be used if
the user has specified one via a resource. No attempt is made to guess what
fonts should be used for these based on the normal text font.
Note that the colors can also be set with the ":highlight" command, using the
"Normal", "Menu", "Tooltip", and "Scrollbar" groups. Example: >
:highlight Menu guibg=lightblue
:highlight Tooltip guibg=yellow
:highlight Scrollbar guibg=lightblue guifg=blue
:highlight Normal guibg=grey90
<
*font-sizes*
Note: All fonts (except for the menu and tooltip) must be of the same size!!!
If you don't do this, text will disappear or mess up the display. Vim does
not check the font sizes. It's the size in screen pixels that must be the
same. Note that some fonts that have the same point size don't have the same
pixel size! Additionally, the positioning of the fonts must be the same
(ascent and descent). You can check this with "xlsfonts -l {fontname}".
If any of these things are also set with Vim commands, eg with
":set guifont=Screen15", then this will override the X resources (currently
'guifont' is the only option that is supported).
Here is an example of what you might put in your ~/.Xdefaults file: >
Vim*useSchemes: all
Vim*sgiMode: true
Vim*useEnhancedFSB: true
Vim.foreground: Black
Vim.background: Wheat
Vim*fontList: 7x13
The first three of these are standard resources on Silicon Graphics machines
which make Motif applications look even better, highly recommended!
The "Vim*fontList" is to set the menu font for Motif. Example: >
Vim*menuBar*fontList: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
With Athena: >
Vim*menuBar*SmeBSB*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
Vim*menuBar*MenuButton*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
NOTE: A more portable, and indeed more correct, way to specify the menu font
in either Motif or Athena is through the resource: >
Vim.menuFont: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
Or, when compiled with the |+xfontset| feature: >
Vim.menuFontSet: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
Don't use "Vim*geometry" in the defaults. This will break the menus. Use
"Vim.geometry" instead.
If you get an error message "Cannot allocate colormap entry for "gray60",
try adding this to your Vim resources (change the colors to your liking): >
Vim*scrollBackground: Black
Vim*scrollForeground: Blue
The resources can also be set with arguments to Vim:
argument meaning ~
*-gui*
-display {display} Run vim on {display} *-display*
-iconic Start vim iconified *-iconic*
-background {color} Use {color} for the background *-background*
-bg {color} idem *-bg*
-foreground {color} Use {color} for normal text *-foreground*
-fg {color} idem *-fg*
-ul {color} idem *-ul*
-font {font} Use {font} for normal text *-font*
-fn {font} idem *-fn*
-boldfont {font} Use {font} for bold text *-boldfont*
-italicfont {font} Use {font} for italic text *-italicfont*
-menufont {font} Use {font} for menu items *-menufont*
-menufontset {fontset} Use {fontset} for menu items *-menufontset*
-mf {font} idem *-mf*
-geometry {geom} Use {geom} for initial geometry *-geometry*
-geom {geom} idem, see |-geometry-example| *-geom*
-borderwidth {width} Use a border width of {width} *-borderwidth*
-bw {width} idem *-bw*
*-scrollbarwidth*
-scrollbarwidth {width} Use a scrollbar width of {width}
-sw {width} idem *-sw*
-menuheight {height} Use a menu bar height of {height} *-menuheight*
-mh {height} idem *-mh*
NOTE: On Motif the value is ignored, the menu height
is computed to fit the menus.
-reverse Use reverse video *-reverse*
-rv idem *-rv*
+reverse Don't use reverse video *-+reverse*
+rv idem *-+rv*
-xrm {resource} Set the specified resource *-xrm*
Note about reverse video: Vim checks that the result is actually a light text
on a dark background. The reason is that some X11 versions swap the colors,
and some don't. These two examples will both give yellow text on a blue
background:
gvim -fg Yellow -bg Blue -reverse
gvim -bg Yellow -fg Blue -reverse
*-geometry-example*
An example for the geometry argument: >
gvim -geometry 80x63+8+100
This creates a window with 80 columns and 63 lines at position 8 pixels from
the left and 100 pixels from the top of the screen.
==============================================================================
3. Shell Commands *gui-pty*
WARNING: Executing an external command from the GUI will not always work.
"normal" commands like "ls", "grep" and "make" mostly work fine. Commands
that require an intelligent terminal like "less" and "ispell" won't work.
Some may even hang and need to be killed from another terminal. So be
careful!
There are two ways to do the I/O with a shell command: Pipes and a pseudo-tty.
The default is to use a pseudo-tty. This should work best on most systems.
Unfortunately, the implementation of the pseudo-tty is different on every Unix
system. And some systems require root permission. To avoid running into
problems with a pseudo-tty when you least expect it, test it when not editing
a file. Be prepared to "kill" the started command or Vim. Commands like
":r !cat" may hang!
If using a pseudo-tty does not work for you, reset the 'guipty' option: >
:set noguipty
Using a pipe should work on any Unix system, but there are disadvantages:
- Some shell commands will notice that a pipe is being used and behave
differently. E.g., ":!ls" will list the files in one column.
- The ":sh" command won't show a prompt, although it will sort of work.
- When using ":make" it's not possible to interrupt with a CTRL-C.
Typeahead while the external command is running is often lost. This happens
both with a pipe and a pseudo-tty. This is a known problem, but it seems it
can't be fixed (or at least, it's very difficult).
*gui-pty-erase*
When your erase character is wrong for an external command, you should fix
this in your "~/.cshrc" file, or whatever file your shell uses for
initializations. For example, when you want to use backspace to delete
characters, but hitting backspaces produces "^H" instead, try adding this to
your "~/.cshrc": >
stty erase ^H
The ^H is a real CTRL-H, type it as CTRL-V CTRL-H.
==============================================================================
4. Various *gui-x11-various*
*gui-x11-printing*
The "File/Print" menu simply sends the current buffer to "lpr". No options or
whatever. If you want something else, you can define your own print command.
For example: >
:10amenu File.Print :w !lpr -Php3
:10vmenu File.Print :w !lpr -Php3
<
*X11-icon*
Vim uses a black&white icon by default when compiled with Motif or Athena. A
colored Vim icon is included as $VIMRUNTIME/vim32x32.xpm. For GTK+, this is
the builtin icon used. Unfortunately, how you should install it depends on
your window manager. When you use this, remove the 'i' flag from
'guioptions', to remove the black&white icon: >
:set guioptions-=i
If you use one of the fvwm* family of window managers simply add this line to
your .fvwm2rc configuration file: >
Style "vim" Icon vim32x32.xpm
Make sure the icon file's location is consistent with the window manager's
ImagePath statement. Either modify the ImagePath from within your .fvwm2rc or
drop the icon into one the pre-defined directories: >
ImagePath /usr/X11R6/include/X11/pixmaps:/usr/X11R6/include/X11/bitmaps
Note: older versions of fvwm use "IconPath" instead of "ImagePath".
For CDE "dtwm" (a derivative of Motif) add this line in the .Xdefaults: >
Dtwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
For "mwm" (Motif window manager) the line would be: >
Mwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
Mouse Pointers Available in X11 *X11_mouse_shapes*
By using the |'mouseshape'| option, the mouse pointer can be automatically
changed whenever Vim enters one of its various modes (e.g., Insert or
Command). Currently, the available pointers are:
arrow an arrow pointing northwest
beam a I-like vertical bar
size an arrow pointing up and down
busy a wristwatch
blank an invisible pointer
crosshair a thin "+" sign
hand1 a dark hand pointing northeast
hand2 a light hand pointing northwest
pencil a pencil pointing southeast
question question_arrow
right_arrow an arrow pointing northeast
up_arrow an arrow pointing upwards
Additionally, any of the mouse pointers that are built into X11 may be
used by specifying an integer from the X11/cursorfont.h include file.
If a name is used that exists on other systems, but not in X11, the default
"arrow" pointer is used.
==============================================================================
5. GTK version *gui-gtk* *GTK+* *GTK*
The GTK version of the GUI works a little bit different.
GTK does _not_ use the traditional X resource settings. Thus items in your
~/.Xdefaults or app-defaults files are not used.
Many of the traditional X command line arguments are not supported. (e.g.,
stuff like -bg, -fg, etc). The ones that are supported are:
command line argument resource name meaning ~
-fn or -font .font font name for the text
-geom or -geometry .geometry size of the gvim window
-rv or -reverse *reverseVideo white text on black background
-display display to be used
-fg -foreground {color} foreground color
-bg -background {color} background color
To set the font, see |'guifont'|. For GTK, there's also a menu option that
does this.
Additionally, there are these command line arguments, which are handled by GTK
internally. Look in the GTK documentation for how they are used:
--sync
--gdk-debug
--gdk-no-debug
--no-xshm (not in GTK+ 2)
--xim-preedit (not in GTK+ 2)
--xim-status (not in GTK+ 2)
--gtk-debug
--gtk-no-debug
--g-fatal-warnings
--gtk-module
--display (GTK+ counterpart of -display; works the same way.)
--screen (The screen number; for GTK+ 2.2 multihead support.)
These arguments are ignored when the |+netbeans_intg| feature is used:
-xrm
-mf
As for colors, Vim's color settings (for syntax highlighting) is still
done the traditional Vim way. See |:highlight| for more help.
If you want to set the colors of remaining gui components (e.g., the
menubar, scrollbar, whatever), those are GTK specific settings and you
need to set those up in some sort of gtkrc file. You'll have to refer
to the GTK documentation, however little there is, on how to do this.
See http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html
for more information.
*gtk-tooltip-colors*
Example, which sets the tooltip colors to black on light-yellow: >
style "tooltips"
{
bg[NORMAL] = "#ffffcc"
fg[NORMAL] = "#000000"
}
widget "gtk-tooltips*" style "tooltips"
Write this in the file ~/.gtkrc and it will be used by GTK+. For GTK+ 2
you might have to use the file ~/.gtkrc-2.0 instead, depending on your
distribution.
Using Vim as a GTK+ plugin *gui-gtk-socketid*
When the GTK+ version of Vim starts up normally, it creates its own top level
window (technically, a 'GtkWindow'). GTK+ provides an embedding facility with
its GtkSocket and GtkPlug widgets. If one GTK+ application creates a
GtkSocket widget in one of its windows, an entirely different GTK+ application
may embed itself into the first application by creating a top-level GtkPlug
widget using the socket's ID.
If you pass Vim the command-line option '--socketid' with a decimal or
hexadecimal value, Vim will create a GtkPlug widget using that value instead
of the normal GtkWindow. This enables Vim to act as a GTK+ plugin.
This really is a programmer's interface, and is of no use without a supporting
application to spawn the Vim correctly. For more details on GTK+ sockets, see
http://www.gtk.org/api/
Note that this feature requires the latest GTK version. GTK 1.2.10 still has
a small problem. The socket feature has not yet been tested with GTK+ 2 --
feel free to volunteer.
==============================================================================
6. GNOME version *gui-gnome* *Gnome* *GNOME*
The GNOME GUI works just like the GTK+ version. See |GTK+| above for how it
works. It looks a bit different though, and implements one important feature
that's not available in the plain GTK+ GUI: Interaction with the session
manager. |gui-gnome-session|
These are the different looks:
- Uses GNOME dialogs (GNOME 1 only). The GNOME 2 GUI uses the same nice
dialogs as the GTK+ 2 version.
- Uses the GNOME dock, so that the toolbar and menubar can be moved to
different locations other than the top (e.g., the toolbar can be placed on
the left, right, top, or bottom). The placement of the menubar and
toolbar is only saved in the GNOME 2 version.
- That means the menubar and toolbar handles are back! Yeah! And the
resizing grid still works too.
GNOME is automatically compiled with if it was found by configure.
(FIXME: Is this still true? Use --enable-gnome-check to force it to.)
GNOME session support *gui-gnome-session* *gnome-session*
On logout, Vim shows the well-known exit confirmation dialog if any buffers
are modified. Clicking [Cancel] will stop the logout process. Otherwise the
current session is stored to disk by using the |:mksession| command, and
restored the next time you log in.
The GNOME session support should also work with the KDE session manager.
If you are experiencing any problems please report them as bugs.
Note: The automatic session save works entirely transparent, in order to
avoid conflicts with your own session files, scripts and autocommands. That
means in detail:
- The session file is stored to a separate directory (usually $HOME/.gnome2).
- 'sessionoptions' is ignored, and a hardcoded set of appropriate flags is
used instead: >
blank,curdir,folds,globals,help,options,winsize
- The internal variable |v:this_session| is not changed when storing the
session. Also, it is restored to its old value when logging in again.
The position and size of the GUI window is not saved by Vim since doing so
is the window manager's job. But if compiled with GTK+ 2 support, Vim helps
the WM to identify the window by restoring the window role (using the |--role|
command line argument).
==============================================================================
7. KDE version *gui-kde* *kde* *KDE* *KVim*
NOTE: The KDE version is still under development. It is not recommended for
daily work.
The KDE version of Vim works with KDE 2.x and KDE 3.x.
KVim (name code for gui-kde) does not use traditional X settings for its
configuration.
Most important difference is the font handling, KVim uses QFont to display the
text. To set your font use the following syntax :
>
:set guifont=Fixed\ [Misc]/10/-1/5/50/0/0/0/1/0
<
the '10' value is the font size, other settings concerns more specific Qt
options which you should not need to care with.
The suggested way to choose your font is through the font selection dialog
available with the command :
:set guifont=*
Note: X Font names are not supported any more, so if you use GVim too, you'll
have to set something like this in your ~/.gvimrc : >
if has("gui_kde")
:set guifont=Fixed\ [Misc]/10/-1/5/50/0/0/0/1/0
else if has("gui_gtk")
:set guifont=-misc-fixed-medium-r-normal-*-*-100-*-*-c-*-iso10646-1
endif
<
*antialias*
KVim uses antialias for its font, so that the text looks better, to disable
this you have to refer to Qt's documentation (export QT_XFT=0 for QT 2.x).
KDE provides some other features, like being able to move the menubar and the
toolbar wherever you want around the text area.
*kde-toolbar*
KVim can be used with a KDE-look toolbar instead of Vim's default toolbar. To
enable this feature you have to run the configure script with the
--enable-kde-toolbar switch. It may be moved to a runtime option in the
future.
*DCOP*
Since Vim 6.0, the new ClientServer feature has been added, it works fine in
KVim too. KVim also provides its own communication scheme based on DCOP. This
is mainly used by the |vimpart| but can freely be used by other applications
or manually through KDE's DCOP tools. The DCOP servername is synchronized with
the X11 servername so that it's easier to identify the same KVim through the
two communication systems.
*vimpart* *vim-kpart*
KVim developers are also working on a component to allow embedding of Vim into
KDE's applications. As of this writing, the component is working and can be
used in different KDE applications. New KDE applications should support it
soon. To get more information about this component, refer to
http://freehackers.org/kvim or to the KDE project.
==============================================================================
8. Compiling *gui-x11-compiling*
If using X11, Vim's Makefile will by default first try to find the necessary
GTK+ files on your system. If the GTK+ files cannot be found, then the Motif
files will be searched for. Finally, if this fails, the Athena files will be
searched for. If all three fail, the GUI will be disabled.
For GTK+, Vim's configuration process requires that GTK+ be properly
installed. That is, the shell script 'gtk-config' must be in your PATH, and
you can already successful compile, build, and execute a GTK+ program. The
reason for this is because the compiler flags (CFLAGS) and link flags
(LDFLAGS) are obtained through the 'gtk-config' shell script.
If you want to build with GTK+ 2 support pass the --enable-gtk2-check argument
to ./configure. Optionally, support for GNOME 2 will be compiled if the
--enable-gnome-check option is also given. Note that the support for GTK+ 2
is still experimental. However, many people have reported that it works just
fine for them.
Otherwise, if you are using Motif or Athena, when you have the Motif or Athena
files in a directory where configure doesn't look, edit the Makefile to enter
the names of the directories. Search for "GUI_INC_LOC" for an example to set
the Motif directories, "CONF_OPT_X" for Athena.
*gui-x11-gtk*
At the time of this writing, you may use either GTK+ version 1.0.6 or 1.2. It
is suggested that you use v1.2 since not all of Vim's GUI features are present
if using v1.0.6. For instance, there are no tearoff menus present in v1.0.6.
Using a version from GTK+'s CVS tree may or may not work, and is therefore not
supported and not recommended.
For the experimental GTK+ 2 GUI, using the latest release of the GTK+ 2.0 or
GTK+ 2.2 series is recommended. CVS HEAD seems to work fine most of time as
well.
Lastly, although GTK+ has supposedly been ported to the Win32 platform, this
has not been tested with Vim and is also unsupported. Also, it's unlikely to
even compile since GTK+ GUI uses parts of the generic X11 code. This might
change in distant future; particularly because getting rid of the X11 centric
code parts is also required for GTK+ framebuffer support.
*gui-x11-motif*
For Motif, you need at least Motif version 1.2 and/or X11R5. Motif 2.0 and
X11R6 are OK. Motif 1.1 and X11R4 might work, no guarantee (there may be a
few problems, but you might make it compile and run with a bit of work, please
send me the patches if you do). The newest releases of LessTif have been
reported to work fine too.
*gui-x11-athena*
The Athena version uses the Xaw widget set by default. If you have the 3D
version, you might want to link with Xaw3d instead. This will make the
menus look a bit better. Edit the Makefile and look for "XAW_LIB". The
scrollbars will remain the same, because Vim has its own, which are already
3D (in fact, they look more like Motif).
*gui-x11-kde*
For Vim-KDE, you need at least Qt(>=2.x) and the corresponding kdelibs.
To compile, you must use the --with-qt-dir configure flag because QTDIR is not
automatically detected yet. Giving KDE's directories to the configure script
may also help in some cases.
*gui-x11-neXtaw*
The neXtaw version is mostly like Athena, but uses different widgets.
*gui-x11-misc*
In general, do not try to mix files from different GTK+, Motif, Athena and X11
versions. This will cause problems. For example, using header files for
X11R5 with a library for X11R6 probably doesn't work (although the linking
won't give an error message, Vim will crash later).
==============================================================================
9. X11 selection mechanism *x11-selection*
If using X11, in either the GUI or an xterm with an X11-aware Vim, then Vim
provides varied access to the X11 selection and clipboard. These are accessed
by using the two selection registers "* and "+.
X11 provides two basic types of global store, selections and cut-buffers,
which differ in one important aspect: selections are "owned" by an
application, and disappear when that application (e.g., Vim) exits, thus
losing the data, whereas cut-buffers, are stored within the X-server itself
and remain until written over or the X-server exits (e.g., upon logging out).
The contents of selections are held by the originating application (e.g., upon
a copy), and only passed on to another application when that other application
asks for them (e.g., upon a paste).
The contents of cut-buffers are immediately written to, and are then
accessible directly from the X-server, without contacting the originating
application.
*quoteplus* *quote+*
There are three documented X selections: PRIMARY (which is expected to
represent the current visual selection - as in Vim's Visual mode), SECONDARY
(which is ill-defined) and CLIPBOARD (which is expected to be used for
cut, copy and paste operations).
Of these three, Vim uses PRIMARY when reading and writing the "* register
(hence when the X11 selections are available, Vim sets a default value for
|'clipboard'| of "autoselect"), and CLIPBOARD when reading and writing the "+
register. Vim does not access the SECONDARY selection.
Examples: (assuming the default option values)
- Select an URL in Visual mode in Vim. Go to a text field in Netscape and
click the middle mouse button. The selected text will be inserted
(hopefully!).
- Select some text in Netscape by dragging with the mouse. Go to Vim and
press the middle mouse button: The selected text is inserted.
- Select some text in Vim and do "+y. Go to Netscape, select some text in a
textfield by dragging with the mouse. Now use the right mouse button and
select "Paste" from the popup menu. The selected text is overwritten by the
text from Vim.
Note that the text in the "+ register remains available when making a Visual
selection, which makes other text available in the "* register. That allows
overwriting selected text.
*x11-cut-buffer*
There are, by default, 8 cut-buffers: CUT_BUFFER0 to CUT_BUFFER7. Vim only
uses CUT_BUFFER0, which is the one that xterm uses by default.
Whenever Vim is about to become unavailable (either via exiting or becoming
suspended), and thus unable to respond to another application's selection
request, it writes the contents of any owned selection to CUT_BUFFER0. If the
"+ CLIPBOARD selection is owned by Vim, then this is written in preference,
otherwise if the "* PRIMARY selection is owned by Vim, then that is written.
Similarly, when Vim tries to paste from "* or "+ (either explicitly, or, in
the case of the "* register, when the middle mouse button is clicked), if the
requested X selection is empty or unavailable, Vim reverts to reading the
current value of the CUT_BUFFER0.
Note that when text is copied to CUT_BUFFER0 in this way, the type of
selection (character, line or block) is always lost, even if it is a Vim which
later pastes it.
Xterm, by default, always writes visible selections to both PRIMARY and
CUT_BUFFER0. When it pastes, it uses PRIMARY if this is available, or else
falls back upon CUT_BUFFER0. For this reason, when cutting and pasting
between Vim and an xterm, you should use the "* register. Xterm doesn't use
CLIPBOARD, thus the "+ doesn't work with xterm.
Most newer applications will provide their current selection via PRIMARY ("*)
and use CLIPBOARD ("+) for cut/copy/paste operations. You thus have access to
both by choosing to use either of the "* or "+ registers.
vim:tw=78:sw=4:ts=8:ft=help:norl:
|