# Vim documentation: gui_x11

main help file

    *gui_x11.txt*   For Vim version 6.0aq.  Last change: 2001 Jul 31

    		  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. Compiling			|gui-x11-compiling|
    8. X11 selection mechanism	|x11-selection|
    9. X11 command server		|x11-command-server|

    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*

    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".

    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 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.
        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
        geometry		Initial geometry to use for gvim's window (default
    			is same size as terminal that started it).
        scrollbarWidth	Thickness of scrollbars.
        menuHeight		Height of the menu bar.
        borderWidth		Thickness of border around text area.

    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 at the moment.

    Note that the colors can also be set with the ":highlight" command, using the
    "Normal", "Menu" and "Scrollbar" groups.  Example:
    	:highlight Menu guibg=lightblue
    	:highlight Scrollbar guibg=lightblue guifg=blue
    	:highlight Normal guibg=grey90

    							*font-sizes*
    Note: All fonts 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-*-*-*-*-*-*-*

    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*

       -mf {font}		idem				*-mf*

       -geometry {geom}	Use {geom} for initial geometry	*-geometry*

       -geom {geom}		idem				*-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*

       -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

    ==============================================================================

    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
    IconPath statement.  Either modify the IconPath from within your .fvwm2rc or
    drop the icon into one the pre-defined directories:

      IconPath /usr/X11R6/include/X11/pixmaps:/usr/X11R6/include/X11/bitmaps

    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_ obey many of the traditional X resource settings (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

    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
    	--xim-preedit
    	--xim-status
    	--gtk-debug
    	--gtk-no-debug
    	--g-fatal-warnings
    	--gtk-module
    	--display	(GTK+ counterpart of -display; works the same way.)

    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.

    						*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.  Don't forget to
    remove the ">" characters from the first column.

    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.

    ==============================================================================

    6. GNOME version				*gui-gnome* *Gnome* *GNOME*

    The Gnome GUI works just like the GTK version.  It only looks a bit different.
    See |GTK| above for how it works.

    These are the different looks:
    - Uses GNOME dialogs.
    - 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 positioning of the menubar and
      toolbar isn't saved right now; I think that's for GNOME session management
      which isn't supported (yet).
    - 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.

    ==============================================================================

    7. 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.

    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.

    Lastly, although GTK+ has supposedly been ported to the Win32 platform, this
    has not been tested with Vim and is also unsupported.

    							*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-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).

    ==============================================================================

    8. 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.

    ==============================================================================

    9. X11 command server			    *x11-xcmdsrv* *x11-command-server*

    						*E247* *E248* *E249* *E251*
    When compiled with the |+xcmdsrv| option, Vim can act as a command server.
    Somewhat like what is available with the |ole-interface| on the windows
    platform.

    By default, a GUI Vim will register a name on the X-server by which it can be
    addressed for subsequent execution of injected strings.  Vim can also act as
    a client and send strings to other instances of Vim on the same X11 display.

    The following command line arguments are available:

        argument			meaning

       --remote [+{cmd}] {file} ...					*--remote*
       				Open the file list in a remote
    				Vim. The rest of the command line
    				is taken as the file list.  Thus any
    				non-file arguments must come before this.

       --remote-wait [+{cmd}] {file} ...				*--remote-wait*
       				As above, but wait for files to
    				complete (unload) in remote Vim.

       --servername {name}		Send to or become the server	*--servername*
    				{name}

       --serversend {keys}		Send {keys} to server and exit.	*--serversend*

       --serverexpr {expr}		Evaluate {expr} in server and	*--serverexpr*
    				print the result on stdout.

       --serverlist			Output a list of server names.	*--serverlist*

    When an X11 GUI Vim (gvim) is started, it will try to register a send-server
    name on the 'VimRegistry' property on the root window.  By default it will try
    to register the name under which it was invoked (gvim, egvim ...).  This can
    be overridden with the --servername argument.  If the specified name is not
    available, a 3 digit postfix is applied until a free name is encountered, ie.
    gvim-001 for the second invocation of gvim on a particular X-server.  The
    resulting name is available in the servername builtin variable
    |v:servername|.

    A non GUI Vim with access to the X11 display (|xterm-clipboard| enabled), can
    also act as a command server if a server name is explicitly given with the
    --servername argument.

    An empty --servername argument will cause the command server to be disabled.

    When Vim is invoked with --serversend it will try to locate the server name
    determined by the invocation name and --servername argument as described
    above.  If an exact match is not available, the first server with the 3 digit
    postfix will be used.  If no server can be located, Vim will start up
    according to the rest of the command line and execute the kestrokes by itself.
    This way it is not necessary to know whether gvim is already started when
    sending command to it.  if a name with the 3 digit postfix is specified with
    the --servername argument, it must match exactly.

    The --remote argument will cause a |:drop| command to be constructed from the
    rest of the command line and sent as described above.
    The --remote-wait argument does the same thing and additionally sets up to
    wait for earch of the files to have been edited.  This uses the BufUnload
    event, thus as soon as a file has been unloaded, Vim assumes you are done
    editing it.
    Note that the --remote and --remote-wait arguments will consume the rest of
    the command line.  Ie. all remaining arguments will be regarded as filenames.
    You can not put options there!

    The --serverlist argument will cause Vim to print a list of registered command
    servers on the standard output (stdout) and exit.

    Functions
    There are a number of VimL functions for scripting the command server.  See
    the description in |eval.txt| or use CTRL-] on the function name to jump to
    the full explanation.

        synopsis				     explanation
        serversend(server, string, type, idvar)  send key sequence or expression
        servernames()			     get a list of available servers
        serverreply_peek(serverid, retvar)	     check for reply string
        serverreply_read(serverid)		     read reply string
        serverreply_send(serverid, string)	     send reply string

    See also the explanation of |CTRL-\_CTRL-N|.  Very useful as a leading key
    sequence.
    The {serverid} for serverreply_send() can be obtained with expand("<client>")

    top - main help file