gui.txt ForVim version 9.1. Last change: 2024 Nov 17VIM REFERENCE MANUAL by Bram MoolenaarVim's GraphicalUserInterfaceguiGUI1. Starting theGUIgui-start2. Scrollbarsgui-scrollbars3. Mouse Controlgui-mouse4. MakingGUI Selectionsgui-selections5. Menusmenus6. Fontgui-font7. Extrasgui-extras8. Shell Commandsgui-shellOtherGUI documentation:gui_x11.txt For specific items of theX11 GUI.gui_w32.txt For specific items of theWin32 GUI.==============================================================================1. Starting theGUIgui-startE229E233First youmust make sure you actually havea version of Vim with theGUI codeincluded. You can check this with the ":version" command,it says "with xxxGUI", where "xxx"is X11-Motif, Photon, GTK2, GTK3, etc., or"MS-Windows 32 bitGUI version".How to start theGUI depends on the system used. Mostly you can run theGUI version of Vim with:gvim[options] [files...]TheX11 version of Vim can run both inGUI and in non-GUI mode. Seegui-x11-start.gui-initgvimrc.gvimrc_gvimrc$MYGVIMRCThegvimrc fileis where GUI-specificstartup commands should be placed. Itis always sourced after thevimrc file. If you have one then the$MYGVIMRCenvironment variable has its name.When theGUI starts up initializations are carried out, in this order:- The'term' optionis set to "builtin_gui" andterminaloptions are reset to their default value for theGUIterminal-options.- If the system menu file exists,itis sourced. The name of this fileis normally "$VIMRUNTIME/menu.vim". You can check this with ":version". Also see$VIMRUNTIME. To skip loading the system menu include 'M' in'guioptions'.buffers-menuno_buffers_menu The system menu file includesa "Buffers" menu. If you don't want this, set the "no_buffers_menu" variable in your.vimrc (not .gvimrc!)::let no_buffers_menu = 1NOTE: Switching onsyntax highlighting also loads the menu file, thus disabling the Buffers menumust be done before ":syntax on". The path names are truncated to 35 characters. You can truncate themata different length, for example 50, like this::let bmenu_max_pathlen = 50- If the "-U{gvimrc}" command-line option has been used whenstarting Vim, the{gvimrc} file will be read for initializations. The following initializations are skipped. When{gvimrc}is "NONE" no file will be read for initializations.- ForUnix and MS-Windows, if the systemgvimrc exists,itis sourced. The name of this fileis normally "$VIM/gvimrc". You can check this with ":version". Also see$VIM.- The following are tried, and only the first one that existsis used:- If the GVIMINIT environment variable exists andis not empty,itis executedas anEx command.- If the usergvimrc file exists,itis sourced. The name of this fileis normally "$HOME/.gvimrc". You can check this with ":version".- For Win32,$HOMEis set by Vim if needed, see$HOME-windows.- Whena "_gvimrc" fileis not found, ".gvimrc"is tried too. And vice versa.- On Unix, if "~/.config/vim/gvimrc" or "$XDG_CONFIG_HOME/vim/gvimrc" exists,itis sourced. You can check this with ":version". The name of the first file foundis stored in $MYGVIMRC, unlessit was already set.- If the'exrc' optionis set (whichis NOT the default) the file ./.gvimrcis sourced, ifit exists and isn't the same fileas the system or usergvimrc file. If this fileis not owned by you, some security restrictions apply. When ".gvimrc"is not found, "_gvimrc"is tried too. ForMacintosh and DOS/Win32 "_gvimrc"is tried first.NOTE: All but the first one are not carried out if Vim was started with"-u NONE" or "-u DEFAULTS" and no "-U" argument was given, or when startedwith "-U NONE".All this happens AFTER the normal Vim initializations, like reading your.vimrc file. Seeinitialization.But theGUIwindowis only opened after all the initializations have beencarried out. If you want some commands to be executed just after opening theGUI window, use theGUIEnterautocommand event. Example::autocmd GUIEnter * winpos 100 50You can use thegvimrc files to set up your own customizedmenus (see:menu)and initialize other things that you may want to set up differently from theterminal version.Recommended place for your personalGUI initializations:Unix $HOME/.gvimrc or $HOME/.vim/gvimrcWin32 $HOME/_gvimrc, $HOME/vimfiles/gvimrc or $VIM/_gvimrcAmiga s:.gvimrc, home:.gvimrc, home:vimfiles:gvimrc or $VIM/.gvimrcHaiku $HOME/config/settings/vim/gvimrcThe personalinitialization files are searched in the order specified aboveand only the first one thatis foundis read.There area number ofoptions which only have meaning in theGUI version ofVim. These are'guicursor','guifont','guipty' and'guioptions'. They aredocumented inoptions.txt with all the other options.If using theMotif version of theGUI (but not for theGTK+ orWin32 version),a number ofX resources are available. Seegui-resources.Another way to set the colors for different occasionsis with highlightgroups. The "Normal" groupis used to set the background and foregroundcolors. Example (which looks nice)::highlight Normal guibg=grey90The "guibg" and "guifg" settings override the normal background andforeground settings. The other settings for theNormal highlight group arenot used. Use the'guifont' option to set the font.Also check out the'guicursor' option, to set the colors for the cursor invarious modes.Vim tries to make thewindow fit on the screen whenit starts up. This avoidsthat you can't see part of it. On theX Window System this requiresa bit ofguesswork. You can change the height thatis used for thewindow title andataskbar with the'guiheadroom' option.:winp:winposE188:winp[os]Display current position of the top left corner of theGUI vimwindow in pixels. Does not work in all versions.Also seegetwinpos(),getwinposx() andgetwinposy().:winp[os]{X}{Y}E466Put theGUI vimwindowat the given{X} and{Y} coordinates.The coordinates should specify the position in pixels of thetop left corner of the window. Does not work in all versions.Does work in an (new) xtermxterm-color.When theGUIwindow has not been opened yet, the values areremembered until thewindowis opened. The positionisadjusted to make thewindow fit on the screen (if possible).:wi:win:winsizeE465:win[size]{width}{height}Set thewindow height to{width} by{height} characters.Itis recommended to use `:set lines=11 columns=22` instead,since it'seasy to see what the numbers mean.If you getless lines than expected, check the'guiheadroom'option.If you are running theX Window System, you can get information about thewindow Vimis running in with these commands::!xwininfo -id $WINDOWID:!xprop -id $WINDOWID:execute '!xwininfo -id ' .. v:windowid:execute '!xprop -id ' .. v:windowidgui-IMEiBusInput methods for international characters inX that rely on theXIMframework, most notably iBus, have been known to produce undesirable resultsin gvim. These may include an inability to enter spaces, or long delaysbetween typinga character andit being recognized by the application.One workaround that has been successful, for unknown reasons,is to preventgvim from forking into the background bystartingit with the-f argument.==============================================================================2. Scrollbarsgui-scrollbarsThere are vertical scrollbars anda horizontal scrollbar. You mayconfigure 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 theappropriateletter in the'guioptions' string. The bottom scrollbarisonly useful when'nowrap'is set.VERTICAL SCROLLBARSgui-vert-scrollEach Vimwindow hasa scrollbar next toit which may be scrolled up and downto move through the text in that buffer. The size of the scrollbar-thumbindicates the fraction of the buffer which can be seen in the window.When the scrollbaris dragged all the way down, the last line of the filewill appear in the top of the window.Ifawindowis shrunk to zero height (by the growth of another window) itsscrollbar disappears. It reappears when thewindowis restored.Ifawindowis vertically split,it will geta scrollbar whenitis thecurrentwindow and when, taking the middle of the currentwindow and drawingavertical line, this line goes through the window.When there are scrollbars on both sides, and the middle of the currentwindowis on the left half, the right scrollbar column will contain scrollbars forthe rightmost windows. The same happens on the other side.HORIZONTAL SCROLLBARSgui-horiz-scrollThe horizontal scrollbar (at the bottom of the Vim GUI) may be used toscroll text sideways when the'wrap' optionis turned off. Thescrollbar-thumb sizeis such that the text of the longest visible line may bescrolledas faras possible left and right. The cursoris moved whennecessary,itmust remain ona visible character (unless'virtualedit'isset).Computing the length of the longest visible line takes quitea bit ofcomputation, andit has to be done every time something changes. If thistakes too much time or you don't like the cursor jumping to another line,include the 'h' flag in'guioptions'. Then thescrollingis limited by thetext of the current cursor line.motif-intellimouseIf you have an Intellimouse and anX server that supports using the wheel,then you can use the wheel to scroll the text up and down in gvim. This workswith XFree86 4.0 and later, and with some older versions when you add patches.Seescroll-mouse-wheel.For older versions of XFree86 youmust patch yourX server. The followingpage hasa bit of information about using the Intellimouse on Linuxas wellaslinks to the patches andX server binaries (may not have the one you needthough):http://www.inria.fr/koala/colas/mouse-wheel-scroll/==============================================================================3. Mouse Controlgui-mouseThe mouse only works if the appropriate flag in the'mouse' optionis set.When theGUIis switched on, and'mouse' wasn't set yet, the'mouse' optionisautomatically set to "a", enablingit for all modes except for thehit-enter prompt. If you don't want this,a good place to change the'mouse' optionis the "gvimrc" file.Otheroptions that are relevant:'mousefocus'window focus follows mouse pointergui-mouse-focus'mousemodel'what mouse button does which action'mousehide'hide mouse pointer while typing text'mousemoveevent' enable mouse move events so that<MouseMove> can be mapped'selectmode'whether to startSelect mode orVisual modeA quick way to set theseis with the ":behave" command.:behave:be:be[have]{model}Set behavior for mouse and selection. Validarguments are: mswinMS-Windows behavior xtermXterm behaviorUsing ":behave" changes these options:optionmswinxterm'selectmode'"mouse,key"""'mousemodel'"popup""extend"'keymodel'"startsel,stopsel"""'selection'"exclusive""inclusive"In the$VIMRUNTIME directory, thereisascript calledmswin.vim, which willalso mapa few keys to theMS-Windows cut/copy/paste commands. Thisis NOTcompatible, sinceit uses theCTRL-V,CTRL-X andCTRL-C keys. If you don'tmind, use this command::so $VIMRUNTIME/mswin.vimForscrolling witha wheel ona mouse, seescroll-mouse-wheel.3.1 Moving Cursor with Mousegui-mouse-moveClick the left mouse button somewhere ina text buffer where you want thecursor to go, andit does!This works in when 'mouse' containsNormal mode 'n' or 'a'Visual mode 'v' or 'a'Insert mode 'i' or 'a'Select modeis handled likeVisual mode.You may use this with anoperator suchas 'd' to delete text from the currentcursor position to the position you point to with the mouse. That is, you hit'd' and then click the mouse somewhere.gui-mouse-focusThe'mousefocus' option can be set to make the keyboard focus follow themouse pointer. This means that thewindow where the mouse pointer is,is theactive window. Warning: this doesn't work very well when usinga 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 rightmouse button will position the cursor on the ':' line (if'mouse' contains'c' or 'a').In any situation the middle mouse button may be clicked to paste the currentselection.3.2 Selection with Mousegui-mouse-selectThe mouse can be used to starta 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 Shiftkey pressed.If there was no selection yet, this startsa selection from the old cursorposition to the position pointed to with the mouse. If there alreadyisaselection then the closestend will be extended.If'selectmode' contains "mouse", then the selection will be inSelect mode.This means that typing normal text will replace the selection. SeeSelect-mode. Otherwise, the selection will be inVisual mode.Double clicking may be done to make the selection word-wise, triple clickingmakesit line-wise, and quadruple clicking makesit rectangular block-wise.Seegui-selections on how the selectionis used.3.3 Other Text Selection with Mousegui-mouse-modelessmodeless-selectionA different kind of selectionis used when:- inCommand-line mode- in theCommand-linewindow and pointing in anotherwindow-at thehit-enter prompt- whenever the current modeis not in the'mouse' option- when holding the CTRL and SHIFT keys in theGUISince Vim continues like the selection isn't there, and thereis no modeassociated with the selection, thisis called modeless selection. Any text inthe Vimwindow can be selected.Select the text by pressing the left mousebuttonat the start, drag to theend and release. To extend the selection,use the right mouse button when'mousemodel'is "extend", or the left mousebutton with theshift key pressed when'mousemodel'is "popup".The selectionis removed when the selected textis scrolled or changed.On the command lineCTRL-Y can be used to copy the selection into theclipboard. Todo this fromInsert mode, useCTRL-O:CTRL-Y<CR>. When'guioptions' containsa orA (default on X11), the selectionis automaticallycopied to the "* register.The middle mouse button can then paste the text. On non-X11 systems, you canuseCTRL-R +.3.4 Using Mouse on Status Linesgui-mouse-statusClicking the left or right mouse button on the status line belowa Vimwindow makes thatwindow the current window. This actually happens on buttonrelease (to be able to distinguisha click froma drag action).With the left mouse buttona status line can be dragged up and down, thusresizing thewindows above and below it. This does not changewindow focus.The same can be used on the vertical separator: click to give thewindow leftofit focus, drag left and right to makewindows wider and narrower.3.5 Various Mouse Clicksgui-mouse-various<S-LeftMouse>Search forward for theword under the mouse click.When'mousemodel'is "popup" this starts orextendsaselection.<S-RightMouse>Search backward for theword under the mouse click.<C-LeftMouse>Jump to thetag name under the mouse click.<C-RightMouse>Jump back to position before the previoustag jump(sameas "CTRL-T")3.6 Mouse Mappingsgui-mouse-mappingThe 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 wayit probably should inaMotifapplication, with shift-left mouse allowing for extending the visual arearather than the right mouse button.<MouseMove> may be mapped, but'mousemoveevent'must be enabled to use themapping.Mousemapping with modifiers does not work for modeless selection.3.7 Drag and dropdrag-n-dropYou can drag and drop one or more files into the Vim window, where they willbe openedas ifa:drop command was used. You can check if thisissupported with thedrop_file feature:has('drop_file').If you hold down Shift while doing this, Vim changes to the first droppedfile's directory. If you hold Ctrl Vim will always splita newwindow for thefile. Otherwise it's only done if the current buffer has been changed.You can also dropa directory on Vim. This starts the explorerplugin forthat directory (assumingit was enabled, otherwise you'll get an errormessage). Keep Shift pressed to change to the directory instead.If Vim happens to be editinga command line, the names of the dropped filesand directories will be insertedat the cursor. This allows you to use thesenames with anyEx command.Special characters (space, tab, doublequote and'|';backslash on non-MS-Windows systems) will be escaped.==============================================================================4. MakingGUI Selectionsgui-selectionsquotestarYou may make selections with the mouse (seegui-mouse-select), or by usingVim'sVisual mode (seev). If 'a'is present in'guioptions', thenwhenevera selectionis started (Visual orSelect mode), or when the selectionis changed, Vim becomes the owner of the windowing system's primary selection(onMS-Windows thegui-clipboardis used; under X11, thex11-selectionisused- you should read whichever of theseis appropriate now).clipboardThereisa specialregister for storing this selection,itis the "*register. Nothingisput in here unless the information about what textisselectedis about to change (e.g. witha left mouse click somewhere), or whenanother application wants to paste the selected text. Then the textisputin the "* register. For example, to cuta line and makeit the currentselection/putit on the clipboard:"*ddSimilarly, when you want to pastea selection from another application, e.g.,by clicking the middle mouse button, the selectionisput in the "*registerfirst, and then'put' like any other register. For example, toput theselection (contents of the clipboard):"*pWhen using thisregister under X11, also seex11-selection. This alsoexplains the related "+ register.Note that when pasting text from one Vim into another separate Vim, the typeof selection (character, line, or block) will also be copied. For otherapplications the typeis always character. However, if the text getstransferred via thex11-cut-buffer, the selection typeis ALWAYS lost.When the "unnamed"stringis included in the'clipboard' option, the unnamedregisteris the sameas the "* register. Thus you canyank to and paste theselection without prepending "* to commands.See alsoW23 andW24.==============================================================================5. MenusmenusFor an introduction seeusr_42.txt in the user manual.5.1 Using Menususing-menusBasically,menus can be used just like mappings. You can define your ownmenus,as manyas you like.Long-time Vim users won't usemenus much. But the poweris in adding your ownmenus and menu items. They are most useful for things that you can't rememberwhat the key sequence was.For creatingmenus ina different language, see:menutrans.If you don't want to usemenusat all, see'go-M'.menu.vimThe defaultmenus 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 setisa good idea. You can add more items, or,if you don't like the defaultsat all, start with removing allmenus:unmenu-all. You can also avoid the defaultmenus being loaded by addingthis line to your.vimrc file (NOT your.gvimrc file!)::let g:did_install_default_menus = 1If you also want to avoid theSyntax menu::let g:did_install_syntax_menu = 1The first item in theSyntax menu can be used to show all availablefiletypesin the menu (which can takea bit of time to load). If you want to have allfiletypes already presentat startup, add::let g:do_syntax_sel_menu = 1menu-lazyloadg:do_no_lazyload_menusThe following menuitems show all available color schemes, keymaps and compilersettings:Edit > Color SchemeEdit > KeymapTools > Set CompilerHowever, they can also takea bit of time to load, because they search allrelated files from the directories in'runtimepath'. Therefore they areloaded lazily (by theCursorHold event), or you can also load them manually.If you want to have all these items already presentat startup, add::let g:do_no_lazyload_menus = 1Note that themenu.vimis sourced when `:syntax on` or `:filetype on`isexecuted or after your.vimrc fileis sourced. This means that the'encoding'option and the language ofmessages (`:language messages`)must be set beforethat (if you want to change them).console-menusAlthough this documentationis in theGUI section, you can actually usemenusin console mode too. You will have to loadmenu.vim explicitly then,itisnot done by default. You can use the:emenu command and command-linecompletion with'wildmenu' to access the menu entries almost likea real menusystem. Todo 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 selecta menu entry. Hit<Enter> to execute it. Hit<Esc> if you want to cancel.This does require the+menu feature enabledat compile time.tear-off-menusGTK+ 2 andMotif support Tear-off menus. These are sort of stickymenus orpop-upmenus that are present all the time. If the resizing does not workcorrectly, this may be caused by using something like "Vim*geometry" in thedefaults. Use "Vim.geometry" instead.As toGTK+ 3, tear-offmenus have been deprecated sinceGTK+ 3.4.Accordingly, they are disabled ifgvimis linked againstGTK+ 3.4 or later.TheWin32GUI version emulates Motif's tear-off menus. Actually,aMotif userwill spot the differences easily, but hopefully they're justas useful. Youcan also use the:tearoff command together withhidden-menus to createfloatingmenus thatdo not appear on the main menu bar.5.2 Creating New Menuscreating-menus:me:menu:noreme:noremenuE330E327E331E336E333E328E329E337E792To createa new menu item, use the ":menu" commands. They are mostly likethe ":map" set of commands (seemap-modes), but the first argumentisa menuitem name, givenasa path ofmenus and submenus witha '.' between them,e.g.: :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 createa new item in the menubar called "Edit", holdingthe mouse button down on this will pop upa menu containing the item"Big Changes", whichisa sub-menu containing the item "Delete All Spaces",which when selected, performs the operation.To createa menu forterminal mode, use:tlmenu instead of:tmenu unlikekeymapping(:tmap). Thisis because:tmenuis already used for definingtooltips for menus. Seeterminal-typing.Special characters ina menu name:menu-shortcut&The next characteris the shortcut key. Make sure eachshortcut keyis only used once ina (sub)menu. If you want toinserta literal "&" in the menu name use "&&".menu-text<Tab>Separates the menu name from right-aligned text. This can beused to show the equivalent typed command. The text "<Tab>"can be used here for convenience. If you are usinga realtab, don't forget toputabackslash 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 partis shownas "Open:e". The ":e"is right aligned, and the "O"is underlined, to indicateitis the shortcut.:am:amenu:an:anoremenuThe ":amenu" command can be used to define menu entries for all modesat once,except for Terminal mode. To make the command work correctly,a characterisautomatically inserted for some modes:modeinsertedappendedNormalnothingnothingVisual<C-C><C-\><C-G>Insert<C-\><C-O>Cmdline<C-C><C-\><C-G>Op-pending<C-C><C-\><C-G>AppendingCTRL-\CTRL-Gis for going back toinsert mode when'insertmode'isset.CTRL-\_CTRL-GExample: :amenu File.Next:next^Mis 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^\^GCareful: InInsert mode this only works fora SINGLENormal mode command,because of theCTRL-O. If you have two or more commands, you will need to usethe ":imenu" command. Forinserting text in any mode, you can use theexpression register: :amenu Insert.foobar "='foobar'<CR>PThe special text<Cmd> beginsa "command menu",it executes the commanddirectly withoutchanging modes. Where you might use ":...<CR>" you caninstead use "<Cmd>...<CR>". See<Cmd> for more info. Example:anoremenu File.Next <Cmd>next<CR>Note that the '<' and 'k' flags in'cpoptions' also apply here (whenincluded they make the<> form and raw key codes not being recognized).Note that<Esc> inCmdline mode executes the command, like ina mapping. ThisisVi compatible. UseCTRL-C to quitCmdline mode.:nme:nmenu:nnoreme:nnoremenu:nunme:nunmenuMenu commandsstarting with "n" work inNormal mode.mapmode-n:ome:omenu:onoreme:onoremenu:ounme:ounmenuMenu commandsstarting with "o" work inOperator-pending mode.mapmode-o:vme:vmenu:vnoreme:vnoremenu:vunme:vunmenuMenu commandsstarting with "v" work inVisual mode.mapmode-v:xme:xmenu:xnoreme:xnoremenu:xunme:xunmenuMenu commandsstarting with "x" work inVisual andSelect mode.mapmode-x:sme:smenu:snoreme:snoremenu:sunme:sunmenuMenu commandsstarting with "s" work inSelect mode.mapmode-s:ime:imenu:inoreme:inoremenu:iunme:iunmenuMenu commandsstarting with "i" work inInsert mode.mapmode-i:cme:cmenu:cnoreme:cnoremenu:cunme:cunmenuMenu commandsstarting with "c" work inCmdline mode.mapmode-c:tlm:tlmenu:tln:tlnoremenu:tlu:tlunmenuMenu commandsstarting with "tl" work in Terminal mode.mapmode-t:menu-<silent>:menu-silentTo definea 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 theexecuted command are still given though. To shut them up too, adda ":silent"in the executed command::menu <silent> Search.Header :exe ":silent normal /Header\r"<CR>"<silent>" may also appear just after "<special>" or "<script>".:menu-<special>:menu-specialDefinea menu with<>notation for special keys, even though the "<" flagmay appear in'cpoptions'. Thisis useful if the side effect of setting'cpoptions'is not desired. Example::menu <special> Search.Header /Header<CR>"<special>"must appearas the very first argument to the ":menu" command orjust after "<silent>" or "<script>".:menu-<script>:menu-scriptThe "to" part of the menu will be inspected for mappings. If you don't wantthis, use the ":noremenu" command (or the similar one fora specific mode).If youdo want to usescript-local mappings, add "<script>"as the very firstargument to the ":menu" command or just after "<silent>" or "<special>".menu-priorityYou can givea priority toa menu. Menus witha higher prioritygo more tothe right. The priorityis givenasa number before the ":menu" command.Example::80menu Buffer.next :bn<CR>The defaultmenus have these priorities:File10Edit20Tools40Syntax50Buffers60Window70Help9999When no or zero priorityis given, 500is used.The priority for the PopUp menuis not used.The Help menu will be placed on the far right side of the menubar on systemswhich support this (Motif and GTK+). ForGTK+ 2 and 3, thisis not doneanymore because right-aligning the Help menuis now discouraged UI design.You can usea priority higher than 9999, to makeitgo after the Help menu,but thatis non-standard andis discouraged. The highest possible priorityisabout 32000. The lowestis 1.sub-menu-priorityThe same mechanism can be used to positiona sub-menu. The priorityis thengivenasa dot-separatedlist of priorities, before the menu name::menu 80.500 Buffer.next :bn<CR>Giving the sub-menu priorityis only needed when the itemis not to beputina normal position. For example, toputa sub-menu before the other items::menu 80.100 Buffer.first :brew<CR>Or toputa sub-menu after the other items, and further items with defaultpriority will beput before it::menu 80.900 Buffer.last :blast<CR>Whena numberis missing, the default value 500 will be used::menu .900 myMenu.test :echo "text"<CR>The menu priorityis only used when creatinga new menu. Whenit alreadyexisted, e.g., in another mode, the priority will not change. Thus, thepriority only needs to be given the first timea menuis used.An exceptionis the PopUp menu. Thereisa separate menu for each mode(Normal, Op-pending, Visual, Insert, Cmdline). The order in each of thesemenus can be different. Thisis different from menu-bar menus, which havethe same order for all modes.NOTE: sub-menu priorities currently don't work for all versions of the GUI.menu-separatorE332Menu items can be separated bya special item that inserts somespace betweenitems. Depending on the system thisis displayedasa line ora dotted line.These itemsmust start witha '-' andend ina '-'. The part in betweenisused to giveita unique name. Priorities can be usedas with normal items.Example::menu Example.item1:do something:menu Example.-Sep-::menu Example.item2:do something differentNote that the separator also requiresa rhs. It doesn't matter whatit is,because the item will never be selected. Usea single colon to keepitsimple.gui-toolbarThe toolbaris currently available in the Win32, Motif,GTK+ (X11),and Photon GUI. It should turn up in other GUIs in due course. Thedefault toolbaris setup in menu.vim.The display of the toolbaris controlled by the'guioptions'letter 'T'. Youcan thus have menu& toolbar together, or either on its own, or neither.The appearanceis controlled by the'toolbar' option. You can choose betweenan image, text or both.toolbar-iconThe toolbaris definedasa special menu called ToolBar, which only has onelevel. Vim interprets the items in this menuas follows:1) If an "icon=" argument was specified, the file with this nameis used. The file can either be specified with the full path or with the base name. In the lastcaseitis 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 firstcase the extensionis included, while in the secondcaseitis omitted. If the file cannot be opened the next points are tried.Aspace in the file namemust be escaped witha backslash.A menu prioritymust come _after_ the icon argument::amenu icon=foo 1.42 ToolBar.Foo :echo "42!"<CR>2) An item called 'BuiltIn##', where ##isa number,is takenas number ## of the built-in bitmaps available in Vim. Currently there are 31 numbered from0 to 30 which cover most common editing operationsbuiltin-tools.:amenu ToolBar.BuiltIn22 :call SearchNext("back")<CR>3) An item with another nameis first searched for in the directory "bitmaps" in'runtimepath'. If found, the bitmap fileis usedas the toolbar button image.Note that the exact filenameis OS-specific: For example, underWin32 the command:amenu ToolBar.Hello :echo "hello"<CR> would find the file 'hello.bmp'. Under GTK+/X11itis 'Hello.xpm'. WithGTK+ 2 the files 'Hello.png', 'Hello.xpm' and 'Hello.bmp' are checked for existence, and the first one found would be used. ForMS-Windows andGTK+ 2 the bitmapis scaled to fit the button. ForMS-Windowsa size of 18 by 18 pixels works best. ForMS-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 thewindow shadow color. More colors might also work, depending on your system.4) If the bitmapis still not found, Vim checks fora match against itslist of built-in names. Each built-in button image hasa name. So the command:amenu ToolBar.Open :e will show the built-in "opena 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, buttonis displayed.builtin-toolsnr NameNormal action00 Newopen newwindow01 Openbrowse for file to open in currentwindow02 Savewrite buffer to file03 Undoundo last change04 Redoredo last undone change05 Cutdelete selected text toclipboard06 Copycopy selected text toclipboard07 Pastepaste text fromclipboard08 Printprint current buffer09 Helpopena buffer on Vim's builtinhelp10 Findstarta search command11 SaveAllwrite all modifiedbuffers to file12 SaveSesnwrite session file for current situation13 NewSesnwrite new session file14 LoadSesnload session file15 RunScriptbrowse for file to runasa Vimscript16Replaceprompt for substitute command17 WinCloseclose currentwindow18 WinMaxmake currentwindow use many lines19 WinMinmake currentwindow use few lines20 WinSplitsplit currentwindow21 Shellstarta shell22 FindPrevsearch again, backward23 FindNextsearch again, forward24 FindHelpprompt forword to searchhelp for25 Makerun make and jump to first error26 TagJumpjump totag under the cursor27 RunCtagsbuildtags for files in current directory28 WinVSplitsplit currentwindow vertically29 WinMaxWidthmake currentwindow use many columns30 WinMinWidthmake currentwindow use few columnshidden-menuswin32-hidden-menusIn theWin32 andGTK+ GUI,startinga menu name with ']' excludes that menufrom the main menu bar. Youmust then use the:popup or:tearoff commandto display it.window-toolbarWinBarEachwindow can havea local toolbar. This uses the first line of the window,thus reduces thespace for the text by one line. The items in the toolbarmust start with "WinBar".Only text can be used. When using Unicode, special characters can be used tomake the items look like icons.If the itemsdo not fit then the last ones cannot be used. The toolbar doesnot wrap.Note that Vim may be in any mode when executing these commands. The menushould be defined forNormal mode and will be executed withoutchanging thecurrent mode. Thus if the currentwindowis inVisual mode and the menucommand does not intentionally change the mode, Vim will remain inVisualmode. Bestis to use:nnoremenu to avoid side effects.Example for debugger tools:nnoremenu 1.10 WinBar.Step :Step<CR>nnoremenu 1.20 WinBar.Next :Next<CR>nnoremenu 1.30 WinBar.Finish :Finish<CR>nnoremenu 1.40 WinBar.Cont :Continue<CR>hl-ToolbarLinehl-ToolbarButtonThewindow toolbar uses the ToolbarLine and ToolbarButton highlight groups.When splitting thewindow thewindow toolbaris not copied to the new window.popup-menuIn the Win32, GTK+,Motif and Photon GUI, you can define thespecial menu "PopUp". Thisis the menu thatis displayed when the right mousebuttonis pressed, if'mousemodel'is set topopup or popup_setpos.Example: nnoremenu 1.40 PopUp.&Paste"+gP menu PopUp5.3 Showing What Menus Are Mapped Toshowing-menusTo see what an existing menuis mapped to, use just one argument after themenu commands (just like you would with the ":map" commands). If the menuspecifiedisa submenu, then allmenus under that hierarchy will be shown.If no argumentis given after:menuat all, then ALL menu items are shownfor the appropriate mode (e.g.,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 remappingscript-localmappings only.sThe menu was defined with "<silent>" to avoid showing whatitismapped to when triggered.-The menu was disabled.Note that hitting<Tab> while enteringa menu name aftera menu command maybe used to complete the name of the menu item.Itis not allowed to changemenus while listing them.E1310This doesn't normally happen, only when, for example, you would haveatimercallback definea menu and the user listsmenus ina wayit showsmore-prompt.5.4 Executing Menusexecute-menus:em:emenuE334E335:[range]em[enu]{menu}Execute{menu} from the command line.The defaultis to execute theNormal modemenu. Ifa rangeis specified,it executestheVisual mode menu.If used from<c-o>,it executes theinsert-mode menu Eg::emenu File.Exit:[range]em[enu]{mode}{menu}Like above, but execute the menu for{mode}: 'n'::nmenuNormal mode 'v'::vmenuVisual mode 's'::smenuSelect mode 'o'::omenuOperator-pending mode 't'::tlmenu Terminal mode 'i'::imenuInsert mode 'c'::cmenuCmdline modeIf the console-mode vim has been compiled with WANT_MENU defined, you canuse:emenu to access useful menu items you may have got used to fromGUImode. See'wildmenu' for an option that works well with this. Seeconsole-menus for an example.When usinga range, if the lines match with '<,'>, then the menuis executedusing the last visual selection.5.5 Deleting Menusdelete-menus:unme:unmenu:aun:aunmenuTo deletea menu item ora whole submenu, use the unmenu commands, which areanalogous to the unmap commands. Eg: :unmenu! Edit.PasteThis will remove the Paste item from the Edit menu forInsert andCommand-line modes.Note that hitting<Tab> while enteringa menu name after an umenu commandmay be used to complete the name of the menu item for the appropriate mode.To remove allmenus 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, except for Terminal" mode:tlunmenu *" remove all menus in Terminal modeIf you want to get rid of the menu bar::set guioptions-=m5.6 Disabling Menusdisable-menus:menu-disable:menu-enableIf youdo not want to removea menu, but disableit fora moment, this can bedone by adding the "enable" or "disable" keyword toa ":menu" command.Examples::menu disable &File.&Open\.\.\.:amenu enable *:amenu disable &Tools.*The command applies to the modesas used with all menu commands.Note thatcharacters like "&" need to be included for translated names to be found.When the argumentis "*", allmenus are affected. Otherwise the given menuname and all existing submenus belowit are affected.5.7 Examples for Menusmenu-examplesHereis an example on how to add menu items with menus. You can adda menuitem for the keyword under the cursor. Theregister "z"is used. :nmenu Words.Add\ Varwb"zye:menu! Words.<C-R>z <C-R>z<CR> :nmenu Words.Remove\ Varwb"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 rhsis in<> notation, you can copy/paste this text to try out themappings, orput these lines in your gvimrc; "<C-R>"isCTRL-R, "<CR>"isthe<CR> key.<>)tooltipsmenu-tips5.8 Tooltips& MenutipsSeesection42.4 in the user manual.:tmenu:tm:tm[enu]{menupath}{rhs}Definea tip fora menu or tool. {only inX11 andWin32 GUI}:tm[enu][menupath]List menu tips.{only in X11 and Win32 GUI}:tunmenu:tu:tu[nmenu]{menupath}Removea tip fora menu or tool.{only in X11 and Win32 GUI}Note: To createmenus forterminal mode, use:tlmenu instead.Whena tipis defined fora menu item,it appears in the command-line areawhen the mouseis over that item, much likea standard Windows menu hint inthe status bar. (Except when Vimis inCommand-line mode, when of coursenothingis displayed.)Whena tipis defined fora ToolBar item,it appearsasa tooltip when themouse pauses over that button, in the usual fashion. Use thehl-Tooltiphighlight group to change its colors.A "tip" can be defined for each menu item. For example, when defininga menuitem like this::amenu MyMenu.Hello :echo "Hello"<CR>The tipis defined like this::tmenu MyMenu.Hello Displays a greeting.And deleteit with::tunmenu MyMenu.HelloTooltips are currently only supported for theX11 andWin32 GUI. However, theyshould appear for the othergui platforms in the not too distant future.The ":tmenu" command works just like other menu commands,it uses the samearguments. ":tunmenu" deletes an existing menu tip, in the same wayas theother unmenu commands.Ifa menu item becomes invalid (i.e. its actions in all modes are deleted) Vimdeletes the menu tip (and the item) for you. This means that:aunmenu deletesa menu item- you don't need todoa:tunmenuas well.5.9 Popup MenusIn theWin32 andGTK+ GUI, you can causea menu topopupat the cursor.This behaves similarly to the PopUpmenus except that any menu tree canbe popped up.This commandis for backwards compatibility, usingitis discouraged, becauseit behaves ina strange way.:popup:popu:popu[p]{name}Popup the menu{name}. The menu namedmusthaveat least one subentry, but need notappear on the menu-bar (seehidden-menus).{only available forWin32 andGTKGUI or inthe terminal}:popu[p]!{name}Like above, but use the position of the mousepointer instead of the cursor.In theterminal thisis the last knownposition, whichis usuallyat the last clickor release (mousemovementis irrelevant).Example::popup Filewill make the "File" menu (if thereis one) appearat the text cursor (mousepointer if! was used).:amenu ]Toolbar.Make:make<CR>:popup ]ToolbarThis createsapopup menu that doesn't exist on the main menu-bar.Note that in theGUI the:popup command will return immediately, beforeaselection has been made. In theterminal the commands waits for the user tomakea selection.Note thata menu that starts with ']' will not be displayed.==============================================================================6. FontThissection describes font related options.GUIFONTgui-font'guifont'is the option that tells Vim what font to use. In its simplest formthe valueis just one font name. It can also bealist of font namesseparated with commas. The first valid fontis used. When no valid font canbe found you will get an error message.On systems where'guifontset'is supported (X11) and'guifontset'is notempty, then'guifont'is not used. Seexfontset.Note: As to theGTK GUIs, no erroris given against any invalid names, and thefirst element of thelistis always picked up and made use of. Thisisbecause, instead of identifyinga given name witha font, theGTK GUIs useitto constructapattern and try to look upa font which best matches thepattern among available fonts, and this way, the matching never fails. Aninvalid name doesn't matter becausea number of font properties other thanname willdo to get the matching done.Spaces aftera comma are ignored. To includea comma ina font name precedeit witha backslash. Setting an option requires an extrabackslash beforeaspace anda backslash. See alsooption-backslash. For example: :set guifont=Screen15,\ 7x13,font\\,with\\,commaswill make Vim try to use the font "Screen15" first, and ifit failsit willtry to use "7x13" and then "font,with,commas" instead.If none of the fonts can be loaded, Vim will keep the current setting. If anempty fontlistis given, Vim will try using other resource settings (for X,it will use the Vim.font resource), and finallyit will try some builtindefault which should always be there("7x13" in thecase of X). The fontnames given should be "normal" fonts. Vim will try to find the relatedboldanditalic fonts.For Win32, GTK, Motif,Mac OS and Photon: :set guifont=*will bring upa font requester, where you can pick the font you want.The font name depends on theGUI used. Seesetting-guifont fora way to set'guifont' forvarious systems.For theGTK+ 2 and 3 GUIs, the font name looks like this: :set guifont=Andale\ Mono\ 11That's all. XLFDs are not used. ForChinese thisis reported to work well: if has("gui_gtk2") set guifont=Bitstream\ Vera\ Sans\ Mono\ 12,Fixed\ 12 set guifontwide=Microsoft\ Yahei\ 12,WenQuanYi\ Zen\ Hei\ 12 endif(Replace gui_gtk2 with gui_gtk3 for theGTK+ 3 GUI)ForMac OSX you can use something like this: :set guifont=Monaco:h10Mono-spaced fontsE236Note that the fontsmust be mono-spaced (all characters have the same width).An exceptionis GTK: all fonts are accepted, but mono-spaced fonts look best.To previewa font on X11, you might be able to use the "xfontsel" program.The "xlsfonts" program givesalist of all available fonts.For theWin32GUIE244E245- Takes theseoptions in the font name (usea ':' to separate the options):hXX- heightis XX (points, can be floating-point)wXX- widthis XX (points, can be floating-point)WXX- weightis XX (seeNote on Weights below)b- bold. Thisis equivalent to setting the weight to 700.i-italicu-underlines- strikeoutcXX- character set XX. Valid charsets are: ANSI, ARABIC, BALTIC, CHINESEBIG5, DEFAULT, EASTEUROPE, GB2312, GREEK, HANGEUL, HEBREW, JOHAB, MAC, OEM, RUSSIAN, SHIFTJIS, SYMBOL, THAI, TURKISH and VIETNAMESE. Normally you would use "cDEFAULT".qXX- quality XX. Valid quality names are: PROOF, DRAFT, ANTIALIASED, NONANTIALIASED, CLEARTYPE and DEFAULT. Normally you would use "qDEFAULT". Some quality values are not supported in legacy OSs.-A '_' can be used in the place ofa space, so you don't need to use backslashes toescape the spaces.Examples: :set guifont=courier_new:h12:w5:b:cRUSSIAN :set guifont=Andale_Mono:h7.5:w4.5See alsofont-sizes.Note on Weights: Fonts often come witha variety of weights. "Normal" weightsin Windows havea value of 400 and, left unspecified, thisis the value thatwill be used when attempting to find fonts. Windows will often match fontsbased on their weight with higher priority than the font name which meansaBook or Medium variant ofa font might be used despite specifyinga Light orExtraLight variant. If you are experiencing heavier weight substitution, thenexplicitly settinga lower weight value may mitigate against this unwantedsubstitution.GUIFONTWIDEgui-fontwideWhen not empty,'guifontwide'specifiesa comma-separatedlist of fonts to beused for double-width characters. The first font that can be loadedis used.Note: The size of these fontsmust be exactly twiceas wideas the onespecified with'guifont' and the same height. If thereisa mismatch then thetext will not be drawn correctly.AllGUI versions but GTK+:'guifontwide'is only used when'encoding'is set to "utf-8" and'guifontset'is empty or invalid.When'guifont'is set anda valid fontis found init and'guifontwide'isempty Vim will attempt to finda matching double-width font and set'guifontwide' to it.GTK+GUI only:guifontwide_gtkIf set and valid,'guifontwide'is always used for double width characters,even if'encoding'is not set to "utf-8".Vim does not attempt to find an appropriate value for'guifontwide'automatically. If'guifontwide'is empty Pango/Xft will choose the font forcharacters not available in'guifont'. Thus youdo not need to set'guifontwide'at all unless you want to override the choice made by Pango/Xft.Windows +multibyte only:guifontwide_win_mbyteIf set and valid,'guifontwide'is used forIME instead of'guifont'.==============================================================================7. Extrasgui-extrasThissection describes other features which are related to the GUI.- With the GUI, thereis no wait for one second after hitting escape, because the key codes don't start with<Esc>.- Typing ^V followed bya special key in theGUI willinsert "<Key>", since the internalstring usedis 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. E.g.::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 ina Vimscript if theGUIis being used, you can use something like this:if has("gui_running") echo "yes, we have a GUI"else echo "Boring old console"endifsetting-guifont- When you use the samevimrc file onvarious systems, you can use something like this to setoptions specifically for each type of GUI:if has("gui_running") if has("gui_gtk"):set guifont=Luxi\ Mono\ 12 elseif has("x11"):set guifont=*-lucidatypewriter-medium-r-normal-*-*-180-*-*-m-*-* elseif has("gui_win32"):set guifont=Luxi_Mono:h12:cANSI endifendifA recommendedJapanese fontis MS Mincho. You can find info here:https://learn.microsoft.com/en-us/typography/font-list/ms-minchoIt should be distributed with Windows.==============================================================================8. Shell Commandsgui-shellFor theX11GUI the external commands are executed inside thegvim window.Seegui-pty.WARNING: Executing an external command from theX11GUI will not always work."normal" commands like "ls", "grep" and "make" mostly work fine.Commands that require an intelligentterminal like "less" and "ispell" won'twork. Some may even hang and need to be killed from another terminal. So becareful!For theWin32GUI the external commands are executed ina separate window.Seegui-shell-win32. vim:tw=78:sw=4:ts=8:noet:ft=help:norl: