1*usr_42.txt* For Vim version 7.3. Last change: 2008 May 05 2 3 VIM USER MANUAL - by Bram Moolenaar 4 5 Add new menus 6 7 8By now you know that Vim is very flexible. This includes the menus used in 9the GUI. You can define your own menu entries to make certain commands easily 10accessible. This is for mouse-happy users only. 11 12|42.1| Introduction 13|42.2| Menu commands 14|42.3| Various 15|42.4| Toolbar and popup menus 16 17 Next chapter: |usr_43.txt| Using filetypes 18 Previous chapter: |usr_41.txt| Write a Vim script 19Table of contents: |usr_toc.txt| 20 21============================================================================== 22*42.1* Introduction 23 24The menus that Vim uses are defined in the file "$VIMRUNTIME/menu.vim". If 25you want to write your own menus, you might first want to look through that 26file. 27 To define a menu item, use the ":menu" command. The basic form of this 28command is as follows: > 29 30 :menu {menu-item} {keys} 31 32The {menu-item} describes where on the menu to put the item. A typical 33{menu-item} is "File.Save", which represents the item "Save" under the 34"File" menu. A dot is used to separate the names. Example: > 35 36 :menu File.Save :update<CR> 37 38The ":update" command writes the file when it was modified. 39 You can add another level: "Edit.Settings.Shiftwidth" defines a submenu 40"Settings" under the "Edit" menu, with an item "Shiftwidth". You could use 41even deeper levels. Don't use this too much, you need to move the mouse quite 42a bit to use such an item. 43 The ":menu" command is very similar to the ":map" command: the left side 44specifies how the item is triggered and the right hand side defines the 45characters that are executed. {keys} are characters, they are used just like 46you would have typed them. Thus in Insert mode, when {keys} is plain text, 47that text is inserted. 48 49 50ACCELERATORS 51 52The ampersand character (&) is used to indicate an accelerator. For instance, 53you can use Alt-F to select "File" and S to select "Save". (The 'winaltkeys' 54option may disable this though!). Therefore, the {menu-item} looks like 55"&File.&Save". The accelerator characters will be underlined in the menu. 56 You must take care that each key is used only once in each menu. Otherwise 57you will not know which of the two will actually be used. Vim doesn't warn 58you for this. 59 60 61PRIORITIES 62 63The actual definition of the File.Save menu item is as follows: > 64 65 :menu 10.340 &File.&Save<Tab>:w :confirm w<CR> 66 67The number 10.340 is called the priority number. It is used by the editor to 68decide where it places the menu item. The first number (10) indicates the 69position on the menu bar. Lower numbered menus are positioned to the left, 70higher numbers to the right. 71 These are the priorities used for the standard menus: 72 73 10 20 40 50 60 70 9999 74 75 +------------------------------------------------------------+ 76 | File Edit Tools Syntax Buffers Window Help | 77 +------------------------------------------------------------+ 78 79Notice that the Help menu is given a very high number, to make it appear on 80the far right. 81 The second number (340) determines the location of the item within the 82pull-down menu. Lower numbers go on top, higher number on the bottom. These 83are the priorities in the File menu: 84 85 +-----------------+ 86 10.310 |Open... | 87 10.320 |Split-Open... | 88 10.325 |New | 89 10.330 |Close | 90 10.335 |---------------- | 91 10.340 |Save | 92 10.350 |Save As... | 93 10.400 |---------------- | 94 10.410 |Split Diff with | 95 10.420 |Split Patched By | 96 10.500 |---------------- | 97 10.510 |Print | 98 10.600 |---------------- | 99 10.610 |Save-Exit | 100 10.620 |Exit | 101 +-----------------+ 102 103Notice that there is room in between the numbers. This is where you can 104insert your own items, if you really want to (it's often better to leave the 105standard menus alone and add a new menu for your own items). 106 When you create a submenu, you can add another ".number" to the priority. 107Thus each name in {menu-item} has its priority number. 108 109 110SPECIAL CHARACTERS 111 112The {menu-item} in this example is "&File.&Save<Tab>:w". This brings up an 113important point: {menu-item} must be one word. If you want to put a dot, 114space or tabs in the name, you either use the <> notation (<Space> and <Tab>, 115for instance) or use the backslash (\) escape. > 116 117 :menu 10.305 &File.&Do\ It\.\.\. :exit<CR> 118 119In this example, the name of the menu item "Do It..." contains a space and the 120command is ":exit<CR>". 121 122The <Tab> character in a menu name is used to separate the part that defines 123the menu name from the part that gives a hint to the user. The part after the 124<Tab> is displayed right aligned in the menu. In the File.Save menu the name 125used is "&File.&Save<Tab>:w". Thus the menu name is "File.Save" and the hint 126is ":w". 127 128 129SEPARATORS 130 131The separator lines, used to group related menu items together, can be defined 132by using a name that starts and ends in a '-'. For example "-sep-". When 133using several separators the names must be different. Otherwise the names 134don't matter. 135 The command from a separator will never be executed, but you have to define 136one anyway. A single colon will do. Example: > 137 138 :amenu 20.510 Edit.-sep3- : 139 140============================================================================== 141*42.2* Menu commands 142 143You can define menu items that exist for only certain modes. This works just 144like the variations on the ":map" command: 145 146 :menu Normal, Visual and Operator-pending mode 147 :nmenu Normal mode 148 :vmenu Visual mode 149 :omenu Operator-pending mode 150 :menu! Insert and Command-line mode 151 :imenu Insert mode 152 :cmenu Command-line mode 153 :amenu All modes 154 155To avoid that the commands of a menu item are being mapped, use the command 156":noremenu", ":nnoremenu", ":anoremenu", etc. 157 158 159USING :AMENU 160 161The ":amenu" command is a bit different. It assumes that the {keys} you 162give are to be executed in Normal mode. When Vim is in Visual or Insert mode 163when the menu is used, Vim first has to go back to Normal mode. ":amenu" 164inserts a CTRL-C or CTRL-O for you. For example, if you use this command: 165> 166 :amenu 90.100 Mine.Find\ Word * 167 168Then the resulting menu commands will be: 169 170 Normal mode: * 171 Visual mode: CTRL-C * 172 Operator-pending mode: CTRL-C * 173 Insert mode: CTRL-O * 174 Command-line mode: CTRL-C * 175 176When in Command-line mode the CTRL-C will abandon the command typed so far. 177In Visual and Operator-pending mode CTRL-C will stop the mode. The CTRL-O in 178Insert mode will execute the command and then return to Insert mode. 179 CTRL-O only works for one command. If you need to use two or more 180commands, put them in a function and call that function. Example: > 181 182 :amenu Mine.Next\ File :call <SID>NextFile()<CR> 183 :function <SID>NextFile() 184 : next 185 : 1/^Code 186 :endfunction 187 188This menu entry goes to the next file in the argument list with ":next". Then 189it searches for the line that starts with "Code". 190 The <SID> before the function name is the script ID. This makes the 191function local to the current Vim script file. This avoids problems when a 192function with the same name is defined in another script file. See |<SID>|. 193 194 195SILENT MENUS 196 197The menu executes the {keys} as if you typed them. For a ":" command this 198means you will see the command being echoed on the command line. If it's a 199long command, the hit-Enter prompt will appear. That can be very annoying! 200 To avoid this, make the menu silent. This is done with the <silent> 201argument. For example, take the call to NextFile() in the previous example. 202When you use this menu, you will see this on the command line: 203 204 :call <SNR>34_NextFile() ~ 205 206To avoid this text on the command line, insert "<silent>" as the first 207argument: > 208 209 :amenu <silent> Mine.Next\ File :call <SID>NextFile()<CR> 210 211Don't use "<silent>" too often. It is not needed for short commands. If you 212make a menu for someone else, being able the see the executed command will 213give him a hint about what he could have typed, instead of using the mouse. 214 215 216LISTING MENUS 217 218When a menu command is used without a {keys} part, it lists the already 219defined menus. You can specify a {menu-item}, or part of it, to list specific 220menus. Example: > 221 222 :amenu 223 224This lists all menus. That's a long list! Better specify the name of a menu 225to get a shorter list: > 226 227 :amenu Edit 228 229This lists only the "Edit" menu items for all modes. To list only one 230specific menu item for Insert mode: > 231 232 :imenu Edit.Undo 233 234Take care that you type exactly the right name. Case matters here. But the 235'&' for accelerators can be omitted. The <Tab> and what comes after it can be 236left out as well. 237 238 239DELETING MENUS 240 241To delete a menu, the same command is used as for listing, but with "menu" 242changed to "unmenu". Thus ":menu" becomes, ":unmenu", ":nmenu" becomes 243":nunmenu", etc. To delete the "Tools.Make" item for Insert mode: > 244 245 :iunmenu Tools.Make 246 247You can delete a whole menu, with all its items, by using the menu name. 248Example: > 249 250 :aunmenu Syntax 251 252This deletes the Syntax menu and all the items in it. 253 254============================================================================== 255*42.3* Various 256 257You can change the appearance of the menus with flags in 'guioptions'. In the 258default value they are all included, except "M". You can remove a flag with a 259command like: > 260 261 :set guioptions-=m 262< 263 m When removed the menubar is not displayed. 264 265 M When added the default menus are not loaded. 266 267 g When removed the inactive menu items are not made grey 268 but are completely removed. (Does not work on all 269 systems.) 270 271 t When removed the tearoff feature is not enabled. 272 273The dotted line at the top of a menu is not a separator line. When you select 274this item, the menu is "teared-off": It is displayed in a separate window. 275This is called a tearoff menu. This is useful when you use the same menu 276often. 277 278For translating menu items, see |:menutrans|. 279 280Since the mouse has to be used to select a menu item, it is a good idea to use 281the ":browse" command for selecting a file. And ":confirm" to get a dialog 282instead of an error message, e.g., when the current buffer contains changes. 283These two can be combined: > 284 285 :amenu File.Open :browse confirm edit<CR> 286 287The ":browse" makes a file browser appear to select the file to edit. The 288":confirm" will pop up a dialog when the current buffer has changes. You can 289then select to save the changes, throw them away or cancel the command. 290 For more complicated items, the confirm() and inputdialog() functions can 291be used. The default menus contain a few examples. 292 293============================================================================== 294*42.4* Toolbar and popup menus 295 296There are two special menus: ToolBar and PopUp. Items that start with these 297names do not appear in the normal menu bar. 298 299 300TOOLBAR 301 302The toolbar appears only when the "T" flag is included in the 'guioptions' 303option. 304 The toolbar uses icons rather than text to represent the command. For 305example, the {menu-item} named "ToolBar.New" causes the "New" icon to appear 306on the toolbar. 307 The Vim editor has 28 built-in icons. You can find a table here: 308|builtin-tools|. Most of them are used in the default toolbar. You can 309redefine what these items do (after the default menus are setup). 310 You can add another bitmap for a toolbar item. Or define a new toolbar 311item with a bitmap. For example, define a new toolbar item with: > 312 313 :tmenu ToolBar.Compile Compile the current file 314 :amenu ToolBar.Compile :!cc % -o %:r<CR> 315 316Now you need to create the icon. For MS-Windows it must be in bitmap format, 317with the name "Compile.bmp". For Unix XPM format is used, the file name is 318"Compile.xpm". The size must be 18 by 18 pixels. On MS-Windows other sizes 319can be used as well, but it will look ugly. 320 Put the bitmap in the directory "bitmaps" in one of the directories from 321'runtimepath'. E.g., for Unix "~/.vim/bitmaps/Compile.xpm". 322 323You can define tooltips for the items in the toolbar. A tooltip is a short 324text that explains what a toolbar item will do. For example "Open file". It 325appears when the mouse pointer is on the item, without moving for a moment. 326This is very useful if the meaning of the picture isn't that obvious. 327Example: > 328 329 :tmenu ToolBar.Make Run make in the current directory 330< 331 Note: 332 Pay attention to the case used. "Toolbar" and "toolbar" are different 333 from "ToolBar"! 334 335To remove a tooltip, use the |:tunmenu| command. 336 337The 'toolbar' option can be used to display text instead of a bitmap, or both 338text and a bitmap. Most people use just the bitmap, since the text takes 339quite a bit of space. 340 341 342POPUP MENU 343 344The popup menu pops up where the mouse pointer is. On MS-Windows you activate 345it by clicking the right mouse button. Then you can select an item with the 346left mouse button. On Unix the popup menu is used by pressing and holding the 347right mouse button. 348 The popup menu only appears when the 'mousemodel' has been set to "popup" 349or "popup_setpos". The difference between the two is that "popup_setpos" 350moves the cursor to the mouse pointer position. When clicking inside a 351selection, the selection will be used unmodified. When there is a selection 352but you click outside of it, the selection is removed. 353 There is a separate popup menu for each mode. Thus there are never grey 354items like in the normal menus. 355 356What is the meaning of life, the universe and everything? *42* 357Douglas Adams, the only person who knew what this question really was about is 358now dead, unfortunately. So now you might wonder what the meaning of death 359is... 360 361============================================================================== 362 363Next chapter: |usr_43.txt| Using filetypes 364 365Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: 366
