usr_42.txt ForVim version 9.2. Last change: 2026 Feb 14 VIM USER MANUALbyBramMoolenaar Add newmenusBy now you know that Vimis very flexible. This includes themenus used inthe GUI. You can define your own menu entries to make certain commands easilyaccessible. Thisis for mouse-happy users only.42.1 Introduction42.2 Menu commands42.3 Various42.4 Toolbar andpopupmenus Next chapter:usr_43.txt Usingfiletypes Previous chapter:usr_41.txt Writea VimscriptTable of contents:usr_toc.txt==============================================================================42.1 IntroductionThemenus that Vim uses are defined in the file "$VIMRUNTIME/menu.vim". Ifyou want to write your own menus, you might first want to look through thatfile. To definea menu item, use the ":menu" command. The basic form of thiscommandisas follows::menu {menu-item} {keys}The{menu-item} describes where on the menu toput the item.A typical{menu-item}is "File.Save", which represents the item "Save" under the"File" menu.A dotis used to separate the names. Example::menu File.Save :update<CR>The ":update" command writes the file whenit was modified. You can add another level: "Edit.Settings.Shiftwidth" definesa submenu"Settings" under the "Edit" menu, with an item "Shiftwidth". You could useeven deeper levels. Don't use this too much, you need to move the mouse quitea bit to use such an item. The ":menu" commandis very similar to the ":map" command: the left sidespecifies how the itemis triggered and the right hand side defines thecharacters that are executed.{keys} are characters, they are used just likeyou would have typed them. Thus inInsert mode, when{keys}is plain text,that textis inserted.ACCELERATORSThe ampersand character (&)is used to indicate an accelerator. For instance,you can use Alt-F to select "File" andS to select "Save". (The'winaltkeys'option may disable this though!). Therefore, the{menu-item} looks like"&File.&Save". The accelerator characters will be underlined in the menu. Youmust take care that each keyis used only once in each menu. Otherwiseyou will not know which of the two will actually be used. Vim doesn't warnyou for this.PRIORITIESThe actual definition of the File.Save menu itemisas follows::menu 10.340 &File.&Save<Tab>:w :confirm w<CR>The number 10.340is called the priority number. Itis used by the editor todecide whereit places the menu item. The first number (10) indicates theposition on the menu bar. Lower numberedmenus are positioned to the left,higher numbers to the right. These are the priorities used for the standard menus: 1020 40 50 60 709999+------------------------------------------------------------+| FileEdit ToolsSyntax Buffers WindowHelp |+------------------------------------------------------------+Notice that the Help menuis givena very high number, to makeit appear onthe far right. The second number (340) determines the location of the item within thepull-down menu. Lower numbersgo on top, higher number on the bottom. Theseare the priorities in the File menu:+-----------------+ 10.310|Open... | 10.320|Split-Open... | 10.325|New | 10.330|Close | 10.335|---------------- | 10.340|Save | 10.350|Save As... | 10.400|---------------- | 10.410|Split Diff with | 10.420|Split Patched By | 10.500|---------------- | 10.510|Print | 10.600|---------------- | 10.610|Save-Exit | 10.620|Exit |+-----------------+Notice that thereis room in between the numbers. Thisis where you caninsert your own items, if you really want to (it's often better to leave thestandardmenus alone and adda new menu for your own items). When you createa submenu, you can add another ".number" to the priority.Thus each name in{menu-item} has its priority number.SPECIAL CHARACTERSThe{menu-item} in this exampleis "&File.&Save<Tab>:w". This brings up animportant point:{menu-item}must be one word. If you want toputa dot,space or tabs in the name, you either use the<>notation (<Space> and<Tab>,for instance) or use thebackslash (\) escape.:menu 10.305 &File.&Do\ It\.\.\. :exit<CR>In this example, the name of the menu item "Do It..." containsaspace and thecommandis ":exit<CR>".The<Tab> character ina menu nameis used to separate the part that definesthe menu name from the part that givesa hint to the user. The part after the<Tab>is displayed right aligned in the menu. In the File.Save menu the nameusedis "&File.&Save<Tab>:w". Thus the menu nameis "File.Save" and the hintis ":w".SEPARATORSThe separator lines, used to group related menu items together, can be definedby usinga name that starts and ends ina '-'. For example "-sep-". Whenusing several separators the namesmust be different. Otherwise the namesdon't matter. The command froma separator will never be executed, but you have to defineone anyway.A single colon will do. Example::amenu 20.510 Edit.-sep3- :==============================================================================42.2 Menu commandsYou can define menu items that exist for only certain modes. This works justlike the variations on the ":map" command::menuNormal,Visual andOperator-pending mode:nmenuNormal mode:vmenuVisual mode:omenuOperator-pending mode:menu!Insert andCommand-line mode:imenuInsert mode:cmenuCommand-line mode:tlmenuTerminal mode:amenuAll modes (except for Terminal mode)To avoid that the commands ofa menu item are being mapped, use the command":noremenu", ":nnoremenu", ":anoremenu", etc.USING :AMENUThe ":amenu" commandisa bit different. It assumes that the{keys} yougive are to be executed inNormal mode. When Vimis inVisual orInsert modewhen the menuis used, Vim first has togo back toNormal mode. ":amenu"insertsaCTRL-C orCTRL-O for you. For example, if you use this command::amenu 90.100 Mine.Find\ Word *Then the resulting menu commands will be:Normal mode:*Visual mode:CTRL-C *Operator-pending mode:CTRL-C *Insert mode:CTRL-O *Command-line mode:CTRL-C *When inCommand-line mode theCTRL-C willabandon the command typed so far.InVisual andOperator-pending modeCTRL-C will stop the mode. TheCTRL-O inInsert mode will execute the command and then return toInsert mode.CTRL-O only works for one command. If you need to use two or morecommands,put them ina function and call that function. Example::amenu Mine.Next\ File :call <SID>NextFile()<CR>:function <SID>NextFile(): next: 1/^Code:endfunctionThis menu entry goes to the next file in the argumentlist with ":next". Thenit searches for the line that starts with "Code". The<SID> before the function nameis thescript ID. This makes thefunction local to the current Vimscript file. This avoids problems whenafunction with the same nameis defined in anotherscript file. See<SID>.SILENT MENUSThe menu executes the{keys}as if you typed them. Fora ":" command thismeans you will see the command being echoed on the command line. If it'salong command, the hit-Enter prompt will appear. That can be very annoying! To avoid this, make the menu silent. Thisis done with the<silent>argument. For example, take the call to NextFile() in the previous example.When you use this menu, you will see this on the command line::call <SNR>34_NextFile()To avoid this text on the command line,insert "<silent>"as the firstargument::amenu <silent> Mine.Next\ File :call <SID>NextFile()<CR>Don't use "<silent>" too often. Itis not needed for short commands. If youmakea menu for someone else, being able to see the executed command will givehima hint about what he could have typed, instead of using the mouse.LISTING MENUSWhena menu commandis used withouta{keys} part,it lists the alreadydefined menus. You can specifya{menu-item}, or part of it, tolist specificmenus. Example::amenuThis lists all menus. That'sa long list! Better specify the name ofa menuto geta shorter list::amenu EditThis lists only the "Edit" menu items for all modes. Tolist only onespecific menu item forInsert mode::imenu Edit.UndoTake care that you type exactly the right name. Case matters here. But the'&' for accelerators can be omitted. The<Tab> and what comes afterit can beleft outas well.DELETING MENUSTo deletea menu, the same commandis usedas for listing, but with "menu"changed to "unmenu". Thus ":menu" becomes, ":unmenu", ":nmenu" becomes":nunmenu", etc. To delete the "Tools.Make" item forInsert mode::iunmenu Tools.MakeYou can deletea whole menu, with all its items, by using the menu name.Example::aunmenu SyntaxThis deletes theSyntax menu and all the items in it.==============================================================================42.3 VariousYou can change the appearance of themenus with flags in'guioptions'. In thedefault value they are all included, except "M". You can removea flag withacommand like::set guioptions-=mmWhen removed the menubaris not displayed.MWhen added the defaultmenus are not loaded.gWhen removed the inactive menu items are not made greybut are completely removed. (Does not work on allsystems.)tWhen removed the tearoff featureis not enabled.The dotted lineat the top ofa menuis nota separator line. When you selectthis item, the menuis "teared-off": Itis displayed ina separate window.Thisis calleda tearoff menu. Thisis useful when you use the same menuoften.For translating menu items, see:menutrans.Since the mouse has to be used to selecta menu item,itisa good idea to usethe ":browse" command for selectinga file. And ":confirm" to getadialoginstead of an error message, e.g., when the current buffer contains changes.These two can be combined::amenu File.Open :browse confirm edit<CR>The ":browse" makesa file browser appear to select the file to edit. The":confirm" will pop upadialog when the current buffer has changes. You canthen select to save the changes, throw them away or cancel the command. For more complicated items, theconfirm() andinputdialog()functions canbe used. The defaultmenus containa few examples.==============================================================================42.4 Toolbar andpopupmenusThere are two special menus: ToolBar and PopUp. Items that start with thesenamesdo not appear in the normal menu bar.TOOLBARThe toolbar appears only when the "T" flagis included in the'guioptions'option. The toolbar uses icons rather than text to represent the command. Forexample, the{menu-item} named "ToolBar.New" causes the "New" icon to appearon the toolbar. The Vim editor has 28 built-in icons. You can finda table here:builtin-tools. Most of them are used in the default toolbar. You canredefine what these itemsdo (after the defaultmenus are setup). You can add another bitmap fora toolbar item. Or definea new toolbaritem witha bitmap. For example, definea new toolbar item with::tmenu ToolBar.Compile Compile the current file:amenu ToolBar.Compile :!cc %:S -o %:r:S<CR>Now you need to create the icon. ForMS-Windowsitmust be in bitmap format,with the name "Compile.bmp". ForUnix XPM formatis used, the file nameis"Compile.xpm". The sizemust be 18 by 18 pixels. OnMS-Windows other sizescan be usedas well, butit will look ugly. Put the bitmap in the directory "bitmaps" in one of the directories from'runtimepath'. E.g., forUnix "~/.vim/bitmaps/Compile.xpm".You can definetooltips for the items in the toolbar.A tooltipisa shorttext that explains whata toolbar item will do. For example "Open file". Itappears when the mouse pointeris on the item, without moving fora moment.Thisis very useful if the meaning of the picture isn't that obvious.Example::tmenu ToolBar.Make Run make in the current directoryNote:Pay attention to thecase used. "Toolbar" and "toolbar" are differentfrom "ToolBar"!To removea tooltip, use the:tunmenu command.The'toolbar' option can be used to display text instead ofa bitmap, or bothtext anda bitmap. Most people use just the bitmap, since the text takesquitea bit of space.POPUP MENUThepopup menu pops up where the mouse pointer is. OnMS-Windows you activateit by clicking the right mouse button. Then you can select an item with theleft mouse button. OnUnix thepopup menuis used by pressing and holding theright mouse button. Thepopup menu only appears when the'mousemodel' has been set to "popup"or "popup_setpos". The difference between the twois that "popup_setpos"moves the cursor to the mouse pointer position. When clicking insideaselection, the selection will be used unmodified. When thereisa selectionbut you click outside of it, the selectionis removed. Thereisa separatepopup menu for each mode. Thus there are never greyitems like in the normal menus.Whatis the meaning of life, the universe and everything?42Douglas Adams, the only person who knew what this question really was aboutisnow dead, unfortunately. So now you might wonder what the meaning of deathis...==============================================================================Next chapter:usr_43.txt UsingfiletypesCopyright: seemanual-copyright vim:tw=78:ts=8:noet:ft=help:norl: