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