diff options
Diffstat (limited to 'runtime/doc/gui_x11.txt')
| -rw-r--r-- | runtime/doc/gui_x11.txt | 528 |
1 files changed, 0 insertions, 528 deletions
diff --git a/runtime/doc/gui_x11.txt b/runtime/doc/gui_x11.txt deleted file mode 100644 index 7f60ae2e10..0000000000 --- a/runtime/doc/gui_x11.txt +++ /dev/null @@ -1,528 +0,0 @@ -*gui_x11.txt* For Vim version 7.4. Last change: 2014 Mar 08 - - - 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. - -============================================================================== -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|. - -============================================================================== -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 -< -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.) - -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 compiled with if it was found by configure and the ---enable-gnome-check argument was used. - - -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,tabpages,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. - -============================================================================== -7. KDE version *gui-kde* *kde* *KDE* *KVim* - *gui-x11-kde* -There is no KDE version of Vim. There has been some work on a port using the -Qt toolkit, but it never worked properly and it has been abandoned. Work -continues on Yzis: https://github.com/chrizel/Yzis. - -============================================================================== -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 that 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. - -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, GTK+ version 1.0.6 and 1.2 are outdated. It -is suggested that you use GTK 2. The GTK 1 support will most likely be -dropped soon. - -For the GTK+ 2 GUI, using the latest release of the GTK+ 2.0 or GTK+ 2.2 -series is recommended. - -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-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 your browser and click the - middle mouse button in the URL text field. The selected text will be - inserted (hopefully!). Note: in Firefox you can set the - middlemouse.contentLoadURL preference to true in about:config, then the - selected URL will be used when pressing middle mouse button in most places - in the window. -- Select some text in your browser 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 your browser, 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: |