*gui_x11.txt*   For Vim version 7.1.  Last change: 2006 Jul 12


		  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, e.g. with
":set guifont=Screen15", then this will override the X resources (currently
'guifont' is the only option that is supported).

Here is an example of what you might put in your ~/.Xdefaults file: >

	Vim*useSchemes:			all
	Vim*sgiMode:			true
	Vim*useEnhancedFSB:		true
	Vim.foreground:			Black
	Vim.background:			Wheat
	Vim*fontList:			7x13

The first three of these are standard resources on Silicon Graphics machines
which make Motif applications look even better, highly recommended!

The "Vim*fontList" is to set the menu font for Motif.  Example: >
	Vim*menuBar*fontList:	     -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
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-gtk11-co:
	"	is a special double quote
	\"	is a literal double quote
	\\"	is a literal backslash and a special double quote
	\\\"	is a literal backslash and a literal double quote
	\\\\"	is 2 literal backslashes and a special double quote
	\\\\\"	is 2 literal backslashes and a literal double quote
	etc.

Example: >
	gvim "C:\My Music\freude" +"set ignorecase" +/"\"foo\\" +\"bar\\\"

opens "C:\My Music\freude" and executes the line mode commands: >
	set ignorecase; /"foo\ and /bar\"

==============================================================================
8. Various						*gui-w32-various*

							*gui-w32-printing*
The "File/Print" menu prints the text with syntax highlighting, see
|:hardcopy|.  If you just want to print the raw text and have a default
printer installed this should also work: >
	:w >>prn

Vim supports a number of standard MS Windows features.  Some of these are
detailed elsewhere: see |'mouse'|, |win32-hidden-menus|.

							*drag-n-drop-win32*
You can drag and drop one or more files into the Vim window, where they will
be opened as normal.  See |drag-n-drop|.

							*:simalt* *:si*
:sim[alt] {key}		simulate pressing {key} while holding Alt pressed.
			{not in Vi} {only for Win32 versions}

Normally, Vim takes control of all Alt-<Key> combinations, to increase the
number of possible mappings.  This clashes with the standard use of Alt as the
key for accessing menus.
The quick way of getting standard behavior is to set the 'winaltkeys' option
to "yes".  This however prevents you from mapping Alt keys at all.
Another way is to set 'winaltkeys' to "menu".  Menu shortcut keys are then
handled by windows, other ALT keys can be mapped.  This doesn't allow a
dependency on the current state though.
To get round this, the :simalt command allows Vim (when 'winaltkeys' is not
"yes") to fake a Windows-style Alt keypress.  You can use this to map Alt key
combinations (or anything else for that matter) to produce standard Windows
actions.  Here are some examples: >

	:map <M-f> :simalt f<CR>
This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by
simulating the keystrokes Alt, F. >
	:map <M-Space> :simalt ~<CR>
This maps Alt-Space to pop down the system menu for the Vim window.  Note that
~ is used by simalt to represent the <Space> character. >
	:map <C-n> :simalt ~n<CR>
Maps Control-N to produce the keys Alt-Space followed by N.  This minimizes the
Vim window via the system menu.

Note that the key changes depending on the language you are using.

						*intellimouse-wheel-problems*
When using the Intellimouse mouse wheel causes Vim to stop accepting input, go
to:
	ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions

And add gvim to the list of applications.  This problem only appears to happen
with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on.

 vim:tw=78:sw=4:ts=8:ft=help:norl:
                                                                                                                                                                                                                                                                     ./usr/share/vim/vim71/doc/gui_x11.txt                                                               0000644 0000000 0000000 00000062477 11112325261 016157  0                                                                                                    ustar   root                            root                                                                                                                                                                                                                   *gui_x11.txt*   For Vim version 7.1.  Last change: 2006 Jul 12


		  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, e.g. with
":set guifont=Screen15", then this will override the X resources (currently
'guifont' is the only option that is supported).

Here is an example of what you might put in your ~/.Xdefaults file: >

	Vim*useSchemes:			all
	Vim*sgiMode:			true
	Vim*useEnhancedFSB:		true
	Vim.foreground:			Black
	Vim.background:			Wheat
	Vim*fontList:			7x13

The first three of these are standard resources on Silicon Graphics machines
which make Motif applications look even better, highly recommended!

The "Vim*fontList" is to set the menu font for Motif.  Example: >
	Vim*menuBar*fontList:	     -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
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 ":m