vim: runtime/doc/gui.txt comparison

comparison runtime/doc/gui.txt @ 7:3fc0f57ecb91 v7.0001

updated for version 7.0001

author	vimboss
date	Sun, 13 Jun 2004 20:20:40 +0000
parents
children	7edf9b6e4c36

comparison

equal deleted inserted replaced

-:c2daee826b8f
+:3fc0f57ecb91
+*gui.txt*       For Vim version 7.0aa.  Last change: 2004 Jun 02
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+Vim's Graphical User Interface				*gui* *GUI*
+1. Starting the GUI		|gui-start|
+2. Scrollbars			|gui-scrollbars|
+3. Mouse Control		|gui-mouse|
+4. Making GUI Selections	|gui-selections|
+5. Menus			|menus|
+6. Extras			|gui-extras|
+7. Shell Commands		|gui-shell|
+Other GUI documentation:
+|gui_x11.txt|	For specific items of the X11 GUI.
+|gui_w32.txt|	For specific items of the Win32 GUI.
+{Vi does not have any of these commands}
+==============================================================================
+1. Starting the GUI				*gui-start* *E229* *E233*
+First you must make sure you actually have a version of Vim with the GUI code
+included.  You can check this with the ":version" command, it should include
+"+GUI_Athena", "+GUI_BeOS", "+GUI_GTK", "+GUI_Motif" or "MS-Windows ... bit
+GUI version".
+How to start the GUI depends on the system used.  Mostly you can run the
+GUI version of Vim with:
+gvim [options] [files...]
+The X11 version of Vim can run both in GUI and in non-GUI mode.  See
+|gui-x11-start|.
+					*gui-init* *gvimrc* *.gvimrc* *_gvimrc*
+When the GUI starts up initializations are carried out, in this order:
+- The termcap options are reset to their default value for the GUI.
+- If the system menu file exists, it is sourced.  The name of this file is
+normally "$VIMRUNTIME/menu.vim".  You can check this with ":version".  Also
+see |$VIMRUNTIME|.  To skip loading the system menu include 'M' in
+'guioptions'.				*buffers-menu* *no_buffers_menu*
+The system menu file includes a "Buffers" menu.  If you don't want this, set
+the "no_buffers_menu" variable in your .vimrc (not .gvimrc!): >
+	:let no_buffers_menu = 1
+< NOTE: Switching on syntax highlighting also loads the menu file, thus
+disabling the Buffers menu must be done before ":syntax on".
+The path names are truncated to 35 characters.  You can truncate them at a
+different length, for example 50, like this: >
+	:let bmenu_max_pathlen = 50
+- If the "-U {gvimrc}" command-line option has been used when starting Vim,
+the {gvimrc} file will be read for initializations.  The following
+initializations are skipped.
+- For Unix and MS-Windows, if the system gvimrc exists, it is sourced.  The
+name of this file is normally "$VIM/gvimrc".  You can check this with
+":version".  Also see |$VIM|.
+- The following are tried, and only the first one that exists is used:
+- If the GVIMINIT environment variable exists and is not empty, it is
+executed as an Ex command.
+- If the user gvimrc file exists, it is sourced.  The name of this file is
+normally "$HOME/.gvimrc".  You can check this with ":version".
+- For Win32, when $HOME is not set, "$VIM\_gvimrc" is used.
+- When a "_gvimrc" file is not found, ".gvimrc" is tried too.  And vice
+versa.
+- If the 'exrc' option is set (which is NOT the default) the file ./.gvimrc
+is sourced, if it exists and isn't the same file as the system or user
+gvimrc file.  If this file is not owned by you, some security restrictions
+apply.  When ".gvimrc" is not found, "_gvimrc" is tried too.  For Macintosh
+and DOS/Win32 "_gvimrc" is tried first.
+NOTE: All but the first one are not carried out if Vim was started with
+"-u NONE" and no "-U" argument was given, or when started with "-U NONE".
+All this happens AFTER the normal Vim initializations, like reading your
+.vimrc file.  See |initialization|.
+But the GUI window is only opened after all the initializations have been
+carried out.  If you want some commands to be executed just after opening the
+GUI window, use the |GUIEnter| autocommand event.  Example: >
+	:autocommand GUIEnter * winpos 100 50
+You can use the gvimrc files to set up your own customized menus (see |:menu|)
+and initialize other things that you may want to set up differently from the
+terminal version.
+Recommended place for your personal GUI initializations:
+	Unix		    $HOME/.gvimrc
+	OS/2		    $HOME/.gvimrc or $VIM/.gvimrc
+	MS-DOS and Win32    $HOME/_gvimrc or $VIM/_gvimrc
+	Amiga		    s:.gvimrc or $VIM/.gvimrc
+There are a number of options which only have meaning in the GUI version of
+Vim.  These are 'guicursor', 'guifont', 'guipty' and 'guioptions'.  They are
+documented in |options.txt| with all the other options.
+If using the Motif or Athena version of the GUI (but not for the GTK+ or Win32
+version), a number of X resources are available.  See |gui-resources|.
+Another way to set the colors for different occasions is with highlight
+groups.  The "Normal" group is used to set the background and foreground
+colors.  Example (which looks nice): >
+	:highlight Normal guibg=grey90
+The "guibg" and "guifg" settings override the normal background and
+foreground settings.  The other settings for the Normal highlight group are
+not used.  Use the 'guifont' option to set the font.
+Also check out the 'guicursor' option, to set the colors for the cursor in
+various modes.
+Vim tries to make the window fit on the screen when it starts up.  This avoids
+that you can't see part of it.  On the X Window System this requires a bit of
+guesswork.  You can change the height that is used for the window title and a
+task bar with the 'guiheadroom' option.
+						*:winp* *:winpos* *E188*
+:winp[os]
+		Display current position of the top left corner of the GUI vim
+		window in pixels.  Does not work in all versions.
+:winp[os] {X} {Y}							*E466*
+		Put the GUI vim window at the given {X} and {Y} coordinates.
+		The coordinates should specify the position in pixels of the
+		top left corner of the window.  Does not work in all versions.
+		Does work in an (new) xterm |xterm-color|.
+		When the GUI window has not been opened yet, the values are
+		remembered until the window is opened.  The position is
+		adjusted to make the window fit on the screen (if possible).
+						    *:win* *:winsize* *E465*
+:win[size] {width} {height}
+		Set the window height to {width} by {height} characters.
+		Obsolete, use ":set lines=11 columns=22".
+		If you get less lines than expected, check the 'guiheadroom'
+		option.
+If you are running the X Window System, you can get information about the
+window Vim is running in with this command: >
+	:!xwininfo -id $WINDOWID
+==============================================================================
+2. Scrollbars						*gui-scrollbars*
+There are vertical scrollbars and a horizontal scrollbars.  You may
+configure which ones appear with the 'guioptions' option.
+The interface looks like this (with ":set guioptions=mlrb"):
+		       +------------------------------+
+		       | File  Edit		 Help | <- Menu bar (m)
+		       +-+--------------------------+-+
+		       |^|			    |^|
+		       |#| Text area.		    |#|
+		       | |			    | |
+		       |v|__________________________|v|
+Normal status line -> |-+ File.c	       5,2  +-|
+between Vim windows   |^|""""""""""""""""""""""""""|^|
+		       | |			    | |
+		       | | Another file buffer.     | |
+		       | |			    | |
+		       |#|			    |#|
+Left scrollbar (l) -> |#|			    |#| <- Right
+		       |#|			    |#|    scrollbar (r)
+		       | |			    | |
+		       |v|			    |v|
+		       +-+--------------------------+-+
+		       | |< ####		   >| | <- Bottom
+		       +-+--------------------------+-+    scrollbar (b)
+Any of the scrollbar or menu components may be turned off by not putting the
+appropriate letter in the 'guioptions' string.  The bottom scrollbar is
+only useful when 'nowrap' is set.
+VERTICAL SCROLLBARS					*gui-vert-scroll*
+Each Vim window has a scrollbar next to it which may be scrolled up and down
+to move through the text in that buffer.  The size of the scrollbar-thumb
+indicates the fraction of the buffer which can be seen in the window.
+When the scrollbar is dragged all the way down, the last line of the file
+will appear in the top of the window.
+If a window is shrunk to zero height (by the growth of another window) its
+scrollbar disappears. It reappears when the window is restored.
+If a window is vertically split, it will get a scrollbar when it is the
+current window and when, taking the middle of the current window and drawing a
+vertical line, this line goes through the window.
+When there are scrollbars on both sides, and the middle of the current window
+is on the left half, the right scrollbar column will contain scrollbars for
+the rightmost windows.  The same happens on the other side.
+HORIZONTAL SCROLLBARS					*gui-horiz-scroll*
+The horizontal scrollbar (at the bottom of the Vim GUI) may be used to
+scroll text sideways when the 'wrap' option is turned off.  The
+scrollbar-thumb size is such that the text of the longest visible line may be
+scrolled as far as possible left and right.  The cursor is moved when
+necessary, it must remain on a visible character (unless 'virtualedit' is
+set).
+Computing the length of the longest visible takes quite a bit of computation,
+and it has to be done every time something changes.  If this takes too much
+time or you don't like the cursor jumping to another line, include the 'h'
+flag in 'guioptions'.  Then the scrolling is limited by the text of the
+current cursor line.
+							*athena-intellimouse*
+If you have an Intellimouse and an X server that supports using the wheel,
+then you can use the wheel to scroll the text up and down in gvim.  This works
+with XFree86 4.0 and later, and with some older versions when you add patches.
+See |scroll-mouse-wheel|.
+For older versions of XFree86 you must patch your X server.  The following
+page has a bit of information about using the Intellimouse on Linux as well as
+links to the patches and X server binaries (may not have the one you need
+though):
+http://www.inria.fr/koala/colas/mouse-wheel-scroll/
+==============================================================================
+3. Mouse Control					*gui-mouse*
+The mouse only works if the appropriate flag in the 'mouse' option is set.
+When the GUI is switched on, and 'mouse' wasn't set yet, the 'mouse' option is
+automatically set to "a", enabling it for all modes except for the
+|hit-enter| prompt.  If you don't want this, a good place to change the
+'mouse' option is the "gvimrc" file.
+Other options that are relevant:
+'mousefocus'	window focus follows mouse pointer |gui-mouse-focus|
+'mousemodel'	what mouse button does which action
+'mousehide'	hide mouse pointer while typing text
+'selectmode'	whether to start Select mode or Visual mode
+A quick way to set these is with the ":behave" command.
+							*:behave* *:be*
+:be[have] {model}	Set behavior for mouse and selection.  Valid
+			arguments are:
+			   mswin	MS-Windows behavior
+			   xterm	Xterm behavior
+			Using ":behave" changes these options:
+			option		mswin			xterm	~
+			'selectmode'	"mouse,key"		""
+			'mousemodel'	"popup"			"extend"
+			'keymodel'	"startsel,stopsel"	""
+			'selection'	"exclusive"		"inclusive"
+In the $VIMRUNTIME directory, there is a script called |mswin.vim|, which will
+also map a few keys to the MS-Windows cut/copy/paste commands.  This is NOT
+compatible, since it uses the CTRL-V, CTRL-X and CTRL-C keys.  If you don't
+mind, use this command: >
+	:so $VIMRUNTIME/mswin.vim
+For scrolling with a wheel on a mouse, see |scroll-mouse-wheel|.
+3.1 Moving Cursor with Mouse				*gui-mouse-move*
+Click the left mouse button somewhere in a text buffer where you want the
+cursor to go, and it does!
+This works in	    when 'mouse' contains ~
+Normal mode	    'n' or 'a'
+Visual mode	    'v' or 'a'
+Insert mode	    'i' or 'a'
+Select mode is handled like Visual mode.
+You may use this with an operator such as 'd' to delete text from the current
+cursor position to the position you point to with the mouse.  That is, you hit
+'d' and then click the mouse somewhere.
+							*gui-mouse-focus*
+The 'mousefocus' option can be set to make the keyboard focus follow the
+mouse pointer.  This means that the window where the mouse pointer is, is the
+active window.  Warning: this doesn't work very well when using a menu,
+because the menu command will always be applied to the top window.
+If you are on the ':' line (or '/' or '?'), then clicking the left or right
+mouse button will position the cursor on the ':' line (if 'mouse' contains
+'c', 'a' or 'A').
+In any situation the middle mouse button may be clicked to paste the current
+selection.
+3.2 Selection with Mouse				*gui-mouse-select*
+The mouse can be used to start a selection.  How depends on the 'mousemodel'
+option:
+'mousemodel' is "extend": use the right mouse button
+'mousemodel' is "popup":  use the left mouse button, while keeping the Shift
+key pressed.
+If there was no selection yet, this starts a selection from the old cursor
+position to the position pointed to with the mouse.  If there already is a
+selection then the closest end will be extended.
+If 'selectmode' contains "mouse", then the selection will be in Select mode.
+This means that typing normal text will replace the selection.  See
+|Select-mode|.  Otherwise, the selection will be in Visual mode.
+Double clicking may be done to make the selection word-wise, triple clicking
+makes it line-wise, and quadruple clicking makes it rectangular block-wise.
+See |gui-selections| on how the selection is used.
+3.3 Other Text Selection with Mouse		*gui-mouse-modeless*
+						*modeless-selection*
+A different kind of selection is used when:
+- in Command-line mode
+- in the Command-line window and pointing in another window
+- at the |hit-enter| prompt
+- whenever the current mode is not in the 'mouse' option
+- when holding the CTRL and SHIFT keys in the GUI
+Since Vim continues like the selection isn't there, and there is no mode
+associated with the selection, this is called modeless selection.  Any text in
+the Vim window can be selected.  Select the text by pressing the left mouse
+button at the start, drag to the end and release.  To extend the selection,
+use the right mouse button when 'mousemodel' is "extend", or the left mouse
+button with the shift key pressed when 'mousemodel' is "popup".
+The middle mouse button pastes the text.
+The selection is removed when the selected text is scrolled or changed.
+On the command line CTRL-Y can be used to copy the selection into the
+clipboard.  To do this from Insert mode, use CTRL-O : CTRL-Y <CR>.
+3.4 Using Mouse on Status Lines				*gui-mouse-status*
+Clicking the left or right mouse button on the status line below a Vim
+window makes that window the current window.  This actually happens on button
+release (to be able to distinguish a click from a drag action).
+With the left mouse button a status line can be dragged up and down, thus
+resizing the windows above and below it.  This does not change window focus.
+The same can be used on the vertical separator: click to give the window left
+of it focus, drag left and right to make windows wider and narrower.
+3.5 Various Mouse Clicks				*gui-mouse-various*
+<S-LeftMouse>	Search forward for the word under the mouse click.
+			When 'mousemodel' is "popup" this starts or extends a
+			selection.
+<S-RightMouse>	Search backward for the word under the mouse click.
+<C-LeftMouse>	Jump to the tag name under the mouse click.
+<C-RightMouse>	Jump back to position before the previous tag jump
+			(same as "CTRL-T")
+3.6 Mouse Mappings					*gui-mouse-mapping*
+The mouse events, complete with modifiers, may be mapped.  Eg: >
+:map <S-LeftMouse>     <RightMouse>
+:map <S-LeftDrag>      <RightDrag>
+:map <S-LeftRelease>   <RightRelease>
+:map <2-S-LeftMouse>   <2-RightMouse>
+:map <2-S-LeftDrag>    <2-RightDrag>
+:map <2-S-LeftRelease> <2-RightRelease>
+:map <3-S-LeftMouse>   <3-RightMouse>
+:map <3-S-LeftDrag>    <3-RightDrag>
+:map <3-S-LeftRelease> <3-RightRelease>
+:map <4-S-LeftMouse>   <4-RightMouse>
+:map <4-S-LeftDrag>    <4-RightDrag>
+:map <4-S-LeftRelease> <4-RightRelease>
+These mappings make selection work the way it probably should in a Motif
+application, with shift-left mouse allowing for extending the visual area
+rather than the right mouse button.
+Mouse mapping with modifiers does not work for modeless selection.
+3.7 Drag and drop						*drag-n-drop*
+You can drag and drop one or more files into the Vim window, where they will
+be opened as if a |:drop| command was used.
+If you hold down Shift while doing this, Vim changes to the first dropped
+file's directory.  If you hold Ctrl Vim will always split a new window for the
+file.  Otherwise it's only done if the current buffer has been changed.
+You can also drop a directory on Vim.  This starts the explorer plugin for
+that directory (assuming it was enabled, otherwise you'll get an error
+message).  Keep Shift pressed to change to the directory instead.
+If Vim happens to be editing a command line, the names of the dropped files
+and directories will be inserted at the cursor.  This allows you to use these
+names with any Ex command.  Special characters (space, tab, double quote and
+'|'; backslash on non-MS-Windows systems) will be escaped.
+==============================================================================
+4. Making GUI Selections				*gui-selections*
+							*quotestar*
+You may make selections with the mouse (see |gui-mouse-select|), or by using
+Vim's Visual mode (see |v|).  If 'a' is present in 'guioptions', then
+whenever a selection is started (Visual or Select mode), or when the selection
+is changed, Vim becomes the owner of the windowing system's primary selection
+(on MS-Windows the |gui-clipboard| is used; under X11, the |x11-selection| is
+used - you should read whichever of these is appropriate now).
+							*clipboard*
+There is a special register for storing this selection, it is the "*
+register.  Nothing is put in here unless the information about what text is
+selected is about to change (eg with a left mouse click somewhere), or when
+another application wants to paste the selected text.  Then the text is put
+in the "* register.  For example, to cut a line and make it the current
+selection/put it on the clipboard: >
+	"*dd
+Similarly, when you want to paste a selection from another application, e.g.,
+by clicking the middle mouse button, the selection is put in the "* register
+first, and then 'put' like any other register.  For example, to put the
+selection (contents of the clipboard): >
+	"*p
+When using this register under X11, also see |x11-selection|.  This also
+explains the related "+ register.
+Note that when pasting text from one Vim into another separate Vim, the type
+of selection (character, line, or block) will also be copied.  For other
+applications the type is always character.  However, if the text gets
+transferred via the |x11-cut-buffer|, the selection type is ALWAYS lost.
+When the "unnamed" string is included in the 'clipboard' option, the unnamed
+register is the same as the "* register.  Thus you can yank to and paste the
+selection without prepending "* to commands.
+==============================================================================
+5. Menus						*menus*
+For an introduction see |usr_42.txt| in the user manual.
+5.1 Using Menus						*using-menus*
+Basically, menus can be used just like mappings.  You can define your own
+menus, as many as you like.
+Long-time Vim users won't use menus much.  But the power is in adding your own
+menus and menu items.  They are most useful for things that you can't remember
+what the key sequence was.
+For creating menus in a different language, see |:menutrans|.
+							*menu.vim*
+The default menus are read from the file "$VIMRUNTIME/menu.vim".  See
+|$VIMRUNTIME| for where the path comes from.  You can set up your own menus.
+Starting off with the default set is a good idea.  You can add more items, or,
+if you don't like the defaults at all, start with removing all menus
+|:unmenu-all|.  You can also avoid the default menus being loaded by adding
+this line to your .vimrc file (NOT your .gvimrc file!): >
+	:let did_install_default_menus = 1
+If you also want to avoid the Syntax menu: >
+	:let did_install_syntax_menu = 1
+If you do want the Syntax menu but not all the entries for each available
+syntax file (which take quite a bit of time to load): >
+	:let skip_syntax_sel_menu = 1
+<
+							*console-menus*
+Although this documentation is in the GUI section, you can actually use menus
+in console mode too.  You will have to load |menu.vim| explicitly then, it is
+not done by default.  You can use the |:emenu| command and command-line
+completion with 'wildmenu' to access the menu entries almost like a real menu
+system.  To do this, put these commands in your .vimrc file: >
+	:source $VIMRUNTIME/menu.vim
+	:set wildmenu
+	:set cpo-=<
+	:set wcm=<C-Z>
+	:map <F4> :emenu <C-Z>
+Pressing <F4> will start the menu.  You can now use the cursor keys to select
+a menu entry.  Hit <Enter> to execute it.  Hit <Esc> if you want to cancel.
+This does require the |+menu| feature enabled at compile time.
+							*tear-off-menus*
+GTK+ and Motif support Tear-off menus.  These are sort of sticky menus or
+pop-up menus that are present all the time.  If the resizing does not work
+correctly, this may be caused by using something like "Vim*geometry" in the
+defaults.  Use "Vim.geometry" instead.
+The Win32 GUI version emulates Motif's tear-off menus.  Actually, a Motif user
+will spot the differences easily, but hopefully they're just as useful.  You
+can also use the |:tearoff| command together with |hidden-menus| to create
+floating menus that do not appear on the main menu bar.
+5.2 Creating New Menus					*creating-menus*
+				*:me*  *:menu*  *:noreme*  *:noremenu*
+				*:am*  *:amenu* *:an*      *:anoremenu*
+				*:nme* *:nmenu* *:nnoreme* *:nnoremenu*
+				*:ome* *:omenu* *:onoreme* *:onoremenu*
+				*:vme* *:vmenu* *:vnoreme* *:vnoremenu*
+				*:ime* *:imenu* *:inoreme* *:inoremenu*
+				*:cme* *:cmenu* *:cnoreme* *:cnoremenu*
+				*E330* *E327* *E331* *E336* *E333*
+				*E328* *E329* *E337*
+To create a new menu item, use the ":menu" commands.  They are mostly like
+the ":map" set of commands but the first argument is a menu item name, given
+as a path of menus and submenus with a '.' between them. eg: >
+:menu File.Save  :w<CR>
+:inoremenu File.Save  <C-O>:w<CR>
+:menu Edit.Big\ Changes.Delete\ All\ Spaces  :%s/[ ^I]//g<CR>
+This last one will create a new item in the menu bar called "Edit", holding
+the mouse button down on this will pop up a menu containing the item
+"Big Changes", which is a sub-menu containing the item "Delete All Spaces",
+which when selected, performs the operation.
+Special characters in a menu name:
+	&	The next character is the shortcut key.  Make sure each
+		shortcut key is only used once in a (sub)menu.  If you want to
+		insert a literal "&" in the menu name use "&&".
+	<Tab>	Separates the menu name from right-aligned text.  This can be
+		used to show the equivalent typed command.  The text "<Tab>"
+		can be used here for convenience.  If you are using a real
+		Tab, don't forget to put a backslash before it!
+Example: >
+:amenu &File.&Open<Tab>:e  :browse e<CR>
+[typed literally]
+With the shortcut "F" (while keeping the <Alt> key pressed), and then "O",
+this menu can be used.  The second part is shown as "Open     :e".  The ":e"
+is right aligned, and the "O" is underlined, to indicate it is the shortcut.
+The ":amenu" command can be used to define menu entries for all modes at once.
+To make the command work correctly, a character is automatically inserted for
+some modes:
+	mode		inserted	appended	~
+	Normal		nothing		nothing
+	Visual		<C-C>		<C-\><C-G>
+	Insert		<C-O>
+	Cmdline		<C-C>		<C-\><C-G>
+	Op-pending	<C-C>		<C-\><C-G>
+Appending CTRL-\ CTRL-G is for going back to insert mode when 'insertmode' is
+set. |CTRL-\_CTRL-G|
+Example: >
+:amenu File.Next	:next^M
+is equal to: >
+:nmenu File.Next	:next^M
+:vmenu File.Next	^C:next^M^\^G
+:imenu File.Next	^O:next^M
+:cmenu File.Next	^C:next^M^\^G
+:omenu File.Next	^C:next^M^\^G
+Careful: In Insert mode this only works for a SINGLE Normal mode command,
+because of the CTRL-O.  If you have two or more commands, you will need to use
+the ":imenu" command.  For inserting text in any mode, you can use the
+expression register: >
+:amenu Insert.foobar   "='foobar'<CR>P
+Note that the '<' and 'k' flags in 'cpoptions' also apply here (when
+included they make the <> form and raw key codes not being recognized).
+Note that <Esc> in Cmdline mode executes the command, like in a mapping.  This
+is Vi compatible.  Use CTRL-C to quit Cmdline mode.
+						*:menu-<silent>* *:menu-silent*
+To define a menu which will not be echoed on the command line, add
+"<silent>" as the first argument.  Example: >
+	:menu <silent> Settings.Ignore\ case  :set ic<CR>
+The ":set ic" will not be echoed when using this menu.  Messages from the
+executed command are still given though.  To shut them up too, add a ":silent"
+in the executed command: >
+	:menu <silent> Search.Header :exe ":silent normal /Header\r"<CR>
+<
+						*:menu-<script>* *:menu-script*
+The "to" part of the menu will be inspected for mappings.  If you don't want
+this, use the ":noremenu" command (or the similar one for a specific mode).
+If you do want to use script-local mappings, add "<script>" as the very first
+argument to the ":menu" command or after "<silent>".
+							*menu-priority*
+You can give a priority to a menu.  Menus with a higher priority go more to
+the right.  The priority is given as a number before the ":menu" command.
+Example: >
+	:80menu Buffer.next :bn<CR>
+The default menus have these priorities:
+	File		10
+	Edit		20
+	Tools		40
+	Syntax		50
+	Buffers		60
+	Window		70
+	Help		9999
+When no or zero priority is given, 500 is used.
+The priority for the PopUp menu is not used.
+The Help menu will be placed on the far right side of the menu bar on systems
+which support this (Motif and GTK+).  For GTK+ 2, this is not done anymore
+because right-aligning the Help menu is now discouraged UI design.
+You can use a priority higher than 9999, to make it go after the Help menu,
+but that is non-standard and is discouraged.  The highest possible priority is
+about 32000.  The lowest is 1.
+							*sub-menu-priority*
+The same mechanism can be used to position a sub-menu.  The priority is then
+given as a dot-separated list of priorities, before the menu name: >
+	:menu 80.500 Buffer.next :bn<CR>
+Giving the sub-menu priority is only needed when the item is not to be put
+in a normal position.  For example, to put a sub-menu before the other items: >
+	:menu 80.100 Buffer.first :brew<CR>
+Or to put a sub-menu after the other items, and further items with default
+priority will be put before it: >
+	:menu 80.900 Buffer.last :blast<CR>
+When a number is missing, the default value 500 will be used: >
+	:menu .900 myMenu.test :echo "text"<CR>
+The menu priority is only used when creating a new menu.  When it already
+existed, e.g., in another mode, the priority will not change.  Thus, the
+priority only needs to be given the first time a menu is used.
+An exception is the PopUp menu.  There is a separate menu for each mode
+(Normal, Op-pending, Visual, Insert, Cmdline).  The order in each of these
+menus can be different.  This is different from menu-bar menus, which have
+the same order for all modes.
+NOTE: sub-menu priorities currently don't work for all versions of the GUI.
+							*menu-separator* *E332*
+Menu items can be separated by a special item that inserts some space between
+items.  Depending on the system this is displayed as a line or a dotted line.
+These items must start with a '-' and end in a '-'.  The part in between is
+used to give it a unique name.  Priorities can be used as with normal items.
+Example: >
+	:menu Example.item1	:do something
+	:menu Example.-Sep-	:
+	:menu Example.item2	:do something different
+Note that the separator also requires a rhs.  It doesn't matter what it is,
+because the item will never be selected.  Use a single colon to keep it
+simple.
+							*gui-toolbar*
+The toolbar is currently available in the Win32, Athena, Motif, GTK+ (X11) and
+Photon GUI.  It should turn up in other GUIs in due course.  The default
+toolbar is setup in menu.vim.
+The display of the toolbar is controlled by the 'guioptions' letter 'T'. You
+can thus have menu & toolbar together, or either on its own, or neither.
+The appearance is controlled by the 'toolbar' option.  You can chose between
+an image, text or both.
+							*toolbar-icon*
+The toolbar is defined as a special menu called ToolBar, which only has one
+level.  Vim interprets the items in this menu as follows:
+1)  If an "icon=" argument was specified, the file with this name is used.
+The file can either be specified with the full path or with the base name.
+In the last case it is searched for in the "bitmaps" directory in
+'runtimepath', like in point 3).  Examples: >
+	:amenu icon=/usr/local/pixmaps/foo_icon.xpm ToolBar.Foo :echo "Foo"<CR>
+	:amenu icon=FooIcon ToolBar.Foo :echo "Foo"<CR>
+<   Note that in the first case the extension is included, while in the second
+case it is omitted.
+If the file cannot be opened the next points are tried.
+A space in the file name must be escaped with a backslash.
+A menu priority must come _after_ the icon argument: >
+	:amenu icon=foo 1.42 ToolBar.Foo :echo "42!"<CR>
+2)  An item called 'BuiltIn##', where ## is a number, is taken as number ## of
+the built-in bitmaps available in Vim. Currently there are 31 numbered
+from 0 to 30 which cover most common editing operations |builtin-tools|. >
+	:amenu ToolBar.BuiltIn22 :call SearchNext("back")<CR>
+3)  An item with another name is first searched for in the directory
+"bitmaps" in 'runtimepath'.  If found, the bitmap file is used as the
+toolbar button image.  Note that the exact filename is OS-specific: For
+example, under Win32 the command >
+	:amenu ToolBar.Hello :echo "hello"<CR>
+<   would find the file 'hello.bmp'.  Under GTK+/X11 it is 'Hello.xpm'.  With
+GTK+ 2 the files 'Hello.png', 'Hello.xpm' and 'Hello.bmp' are checked for
+existence, and the first one found would be used.
+For MS-Windows and GTK+ 2 the bitmap is scaled to fit the button.  For
+MS-Windows a size of 18 by 18 pixels works best.
+For MS-Windows the bitmap should have 16 colors with the standard palette.
+The light grey pixels will be changed to the Window frame color and the
+dark grey pixels to the window shadow color.  More colors might also work,
+depending on your system.
+4)  If the bitmap is still not found, Vim checks for a match against its list
+of built-in names.  Each built-in button image has a name.
+So the command >
+	:amenu ToolBar.Open :e
+<   will show the built-in "open a file" button image if no open.bmp exists.
+All the built-in names can be seen used in menu.vim.
+5)  If all else fails, a blank, but functioning, button is displayed.
+							*builtin-tools*
+nr  Name		Normal action  ~
+00  New			open new window
+01  Open		browse for file to open in current window
+02  Save		write buffer to file
+03  Undo		undo last change
+04  Redo		redo last undone change
+05  Cut			delete selected text to clipboard
+06  Copy		copy selected text to clipboard
+07  Paste		paste text from clipboard
+08  Print		print current buffer
+09  Help		open a buffer on Vim's builtin help
+10  Find		start a search command
+11  SaveAll		write all modified buffers to file
+12  SaveSesn		write session file for current situation
+13  NewSesn		write new session file
+14  LoadSesn		load session file
+15  RunScript		browse for file to run as a Vim script
+16  Replace		prompt for substitute command
+17  WinClose		close current window
+18  WinMax		make current window use many lines
+19  WinMin		make current window use few lines
+20  WinSplit		split current window
+21  Shell		start a shell
+22  FindPrev		search again, backward
+23  FindNext		search again, forward
+24  FindHelp		prompt for word to search help for
+25  Make		run make and jump to first error
+26  TagJump		jump to tag under the cursor
+27  RunCtags		build tags for files in current directory
+28  WinVSplit		split current window vertically
+29  WinMaxWidth		make current window use many columns
+30  WinMinWidth		make current window use few columns
+					*hidden-menus* *win32-hidden-menus*
+In the Win32 and GTK+ GUI, starting a menu name with ']' excludes that menu
+from the main menu bar.  You must then use the |:popup| or |:tearoff| command
+to display it.
+							*popup-menu*
+In the Win32, GTK+, Motif, Athena and Photon GUI, you can define the special
+menu "PopUp".  This is the menu that is displayed when the right mouse button
+is pressed, if 'mousemodel' is set to popup or popup_setpos.
+5.3 Showing What Menus Are Mapped To			*showing-menus*
+To see what an existing menu is mapped to, use just one argument after the
+menu commands (just like you would with the ":map" commands).  If the menu
+specified is a submenu, then all menus under that hierarchy will be shown.
+If no argument is given after :menu at all, then ALL menu items are shown
+for the appropriate mode (eg, Command-line mode for :cmenu).
+Special characters in the list, just before the rhs:
+*	The menu was defined with "nore" to disallow remapping.
+&	The menu was defined with "<script>" to allow remapping script-local
+	mappings only.
+-	The menu was disabled.
+Note that hitting <Tab> while entering a menu name after a menu command may
+be used to complete the name of the menu item.
+5.4 Executing Menus					*execute-menus*
+						*:em*  *:emenu* *E334* *E335*
+:[range]em[enu] {menu}		Execute {menu} from the command line.
+				The default is to execute the Normal mode
+				menu.  If a range is specified, it executes
+				the Visual mode menu.
+				If used from <c-o>, it executes the
+				insert-mode menu Eg: >
+	:emenu File.Exit
+If the console-mode vim has been compiled with WANT_MENU defined, you can
+use :emenu to access useful menu items you may have got used to from GUI
+mode.  See 'wildmenu' for an option that works well with this.  See
+|console-menus| for an example.
+When using a range, if the lines match with '<,'>, then the menu is executed
+using the last visual selection.
+5.5 Deleting Menus					*delete-menus*
+						*:unme*  *:unmenu*
+						*:aun*   *:aunmenu*
+						*:nunme* *:nunmenu*
+						*:ounme* *:ounmenu*
+						*:vunme* *:vunmenu*
+						*:iunme* *:iunmenu*
+						*:cunme* *:cunmenu*
+To delete a menu item or a whole submenu, use the unmenu commands, which are
+analogous to the unmap commands.  Eg: >
+:unmenu! Edit.Paste
+This will remove the Paste item from the Edit menu for Insert and
+Command-line modes.
+Note that hitting <Tab> while entering a menu name after an umenu command
+may be used to complete the name of the menu item for the appropriate mode.
+To remove all menus use:			*:unmenu-all*  >
+	:unmenu *	" remove all menus in Normal and visual mode
+	:unmenu! *	" remove all menus in Insert and Command-line mode
+	:aunmenu *	" remove all menus in all modes
+If you want to get rid of the menu bar: >
+	:set guioptions-=m
+5.6 Disabling Menus					*disable-menus*
+						*:menu-disable* *:menu-enable*
+If you do not want to remove a menu, but disable it for a moment, this can be
+done by adding the "enable" or "disable" keyword to a ":menu" command.
+Examples: >
+	:menu disable &File.&Open\.\.\.
+	:amenu enable *
+	:amenu disable &Tools.*
+The command applies to the modes as used with all menu commands.  Note that
+characters like "&" need to be included for translated names to be found.
+When the argument is "*", all menus are affected.  Otherwise the given menu
+name and all existing submenus below it are affected.
+5.7 Examples for Menus					*menu-examples*
+Here is an example on how to add menu items with menu's!  You can add a menu
+item for the keyword under the cursor.  The register "z" is used. >
+:nmenu Words.Add\ Var		wb"zye:menu! Words.<C-R>z <C-R>z<CR>
+:nmenu Words.Remove\ Var	wb"zye:unmenu! Words.<C-R>z<CR>
+:vmenu Words.Add\ Var		"zy:menu! Words.<C-R>z <C-R>z <CR>
+:vmenu Words.Remove\ Var	"zy:unmenu! Words.<C-R>z<CR>
+:imenu Words.Add\ Var		<Esc>wb"zye:menu! Words.<C-R>z <C-R>z<CR>a
+:imenu Words.Remove\ Var	<Esc>wb"zye:unmenu! Words.<C-R>z<CR>a
+(the rhs is in <> notation, you can copy/paste this text to try out the
+mappings, or put these lines in your gvimrc; "<C-R>" is CTRL-R, "<CR>" is
+the <CR> key.  |<>|)
+5.8 Tooltips & Menu tips
+See section |42.4| in the user manual.
+							*:tmenu* *:tm*
+:tm[enu] {menupath} {rhs}	Define a tip for a menu or tool.  {only in
+				X11 and Win32 GUI}
+:tm[enu] [menupath]		List menu tips. {only in X11 and Win32 GUI}
+							*:tunmenu* *:tu*
+:tu[nmenu] {menupath}		Remove a tip for a menu or tool.
+				{only in X11 and Win32 GUI}
+When a tip is defined for a menu item, it appears in the command-line area
+when the mouse is over that item, much like a standard Windows menu hint in
+the status bar. (Except when Vim is in Command-line mode, when of course
+nothing is displayed.)
+When a tip is defined for a ToolBar item, it appears as a tooltip when the
+mouse pauses over that button, in the usual fashion.  Use the |hl-Tooltip|
+highlight group to change its colors.
+A "tip" can be defined for each menu item.  For example, when defining a menu
+item like this: >
+	:amenu MyMenu.Hello :echo "Hello"<CR>
+The tip is defined like this: >
+	:tmenu MyMenu.Hello Displays a greeting.
+And delete it with: >
+	:tunmenu MyMenu.Hello
+Tooltips are currently only supported for the X11 and Win32 GUI. However, they
+should appear for the other gui platforms in the not too distant future.
+The ":tmenu" command works just like other menu commands, it uses the same
+arguments.  ":tunmenu" deletes an existing menu tip, in the same way as the
+other unmenu commands.
+If a menu item becomes invalid (i.e. its actions in all modes are deleted) Vim
+deletes the menu tip (and the item) for you.  This means that :aunmenu deletes
+a menu item - you don't need to do a :tunmenu as well.
+5.9 Popup Menus
+In the Win32 and GTK+ GUI, you can cause a menu to popup at the cursor.
+This behaves similarly to the PopUp menus except that any menu tree can
+be popped up.
+This command is for backwards compatibility, using it is discouraged, because
+it behaves in a strange way.
+							*:popup* *:popu*
+:popu[p] {name}			Popup the menu {name}.  The menu named must
+				have at least one subentry, but need not
+				appear on the menu-bar (see |hidden-menus|).
+				{only available for Win32 and GTK GUI}
+Example: >
+	:popup File
+will make the "File" menu (if there is one) appear at the text cursor. >
+	:amenu ]Toolbar.Make	:make<CR>
+	:popup ]Toolbar
+This creates a popup menu that doesn't exist on the main menu-bar.
+Note that a menu that starts with ']' will not be displayed.
+==============================================================================
+6. Extras						*gui-extras*
+This section describes other features which are related to the GUI.
+- With the GUI, there is no wait for one second after hitting escape, because
+the key codes don't start with <Esc>.
+- Typing ^V followed by a special key in the GUI will insert "<Key>", since
+the internal string used is meaningless.  Modifiers may also be held down to
+get "<Modifiers-Key>".
+- In the GUI, the modifiers SHIFT, CTRL, and ALT (or META) may be used within
+mappings of special keys and mouse events.  eg: :map <M-LeftDrag> <LeftDrag>
+- In the GUI, several normal keys may have modifiers in mappings etc, these
+are <Space>, <Tab>, <NL>, <CR>, <Esc>.
+- To check in a Vim script if the GUI is being used, you can use something
+like this: >
+	if has("gui_running")
+	   echo "yes, we have a GUI"
+	else
+	   echo "Boring old console"
+	endif
+==============================================================================
+7. Shell Commands					*gui-shell*
+For the X11 GUI the external commands are executed inside the gvim window.
+See |gui-pty|.
+WARNING: Executing an external command from the X11 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!
+For the Win32 GUI the external commands are executed in a separate window.
+See |gui-shell-win32|.
+vim:tw=78:sw=4:ts=8:ft=help:norl:

Mercurial > vim

comparison runtime/doc/gui.txt @ 7:3fc0f57ecb91 v7.0001