Mercurial > vim
annotate runtime/doc/usr_42.txt @ 10885:310834b0256a v8.0.0332
patch 8.0.0332: GUI test fails on some systems
commit https://github.com/vim/vim/commit/4e9dbc74df24dc22d0eeda3741c3fb0e0e7373bf
Author: Bram Moolenaar <Bram@vim.org>
Date: Fri Feb 17 13:44:48 2017 +0100
patch 8.0.0332: GUI test fails on some systems
Problem: GUI test fails on some systems.
Solution: Try different language settings. (Kazunobu Kuriyama)
| author | Christian Brabandt <cb@256bit.org> |
|---|---|
| date | Fri, 17 Feb 2017 13:45:04 +0100 |
| parents | 9f48eab77d62 |
| children | 1174611ad715 |
| rev | line source |
|---|---|
|
10198
9f48eab77d62
commit https://github.com/vim/vim/commit/bb76f24af2010943387ce696a7092175b4ecccf2
Christian Brabandt <cb@256bit.org>
parents:
5690
diff
changeset
|
1 *usr_42.txt* For Vim version 8.0. 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 | |
| 153 :amenu All modes | |
| 154 | |
| 155 To avoid that the commands of a menu item are being mapped, use the command | |
| 156 ":noremenu", ":nnoremenu", ":anoremenu", etc. | |
| 157 | |
| 158 | |
| 159 USING :AMENU | |
| 160 | |
| 161 The ":amenu" command is a bit different. It assumes that the {keys} you | |
| 162 give are to be executed in Normal mode. When Vim is in Visual or Insert mode | |
| 163 when the menu is used, Vim first has to go back to Normal mode. ":amenu" | |
| 164 inserts a CTRL-C or CTRL-O for you. For example, if you use this command: | |
| 165 > | |
| 166 :amenu 90.100 Mine.Find\ Word * | |
| 167 | |
| 168 Then 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 | |
| 176 When in Command-line mode the CTRL-C will abandon the command typed so far. | |
| 177 In Visual and Operator-pending mode CTRL-C will stop the mode. The CTRL-O in | |
| 178 Insert 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 | |
| 180 commands, 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 | |
| 188 This menu entry goes to the next file in the argument list with ":next". Then | |
| 189 it searches for the line that starts with "Code". | |
| 190 The <SID> before the function name is the script ID. This makes the | |
| 191 function local to the current Vim script file. This avoids problems when a | |
| 192 function with the same name is defined in another script file. See |<SID>|. | |
| 193 | |
| 194 | |
| 195 SILENT MENUS | |
| 196 | |
| 197 The menu executes the {keys} as if you typed them. For a ":" command this | |
| 198 means you will see the command being echoed on the command line. If it's a | |
| 199 long 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> | |
| 201 argument. For example, take the call to NextFile() in the previous example. | |
| 202 When you use this menu, you will see this on the command line: | |
| 203 | |
| 204 :call <SNR>34_NextFile() ~ | |
| 205 | |
| 206 To avoid this text on the command line, insert "<silent>" as the first | |
| 207 argument: > | |
| 208 | |
| 209 :amenu <silent> Mine.Next\ File :call <SID>NextFile()<CR> | |
| 210 | |
| 211 Don't use "<silent>" too often. It is not needed for short commands. If you | |
| 212 make a menu for someone else, being able the see the executed command will | |
| 213 give him a hint about what he could have typed, instead of using the mouse. | |
| 214 | |
| 215 | |
| 216 LISTING MENUS | |
| 217 | |
| 218 When a menu command is used without a {keys} part, it lists the already | |
| 219 defined menus. You can specify a {menu-item}, or part of it, to list specific | |
| 220 menus. Example: > | |
| 221 | |
| 222 :amenu | |
| 223 | |
| 224 This lists all menus. That's a long list! Better specify the name of a menu | |
| 225 to get a shorter list: > | |
| 226 | |
| 227 :amenu Edit | |
| 228 | |
| 229 This lists only the "Edit" menu items for all modes. To list only one | |
| 230 specific menu item for Insert mode: > | |
| 231 | |
| 232 :imenu Edit.Undo | |
| 233 | |
| 234 Take 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 | |
| 236 left out as well. | |
| 237 | |
| 238 | |
| 239 DELETING MENUS | |
| 240 | |
| 241 To delete a menu, the same command is used as for listing, but with "menu" | |
| 242 changed 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 | |
| 247 You can delete a whole menu, with all its items, by using the menu name. | |
| 248 Example: > | |
| 249 | |
| 250 :aunmenu Syntax | |
| 251 | |
| 252 This deletes the Syntax menu and all the items in it. | |
| 253 | |
| 254 ============================================================================== | |
| 255 *42.3* Various | |
| 256 | |
| 257 You can change the appearance of the menus with flags in 'guioptions'. In the | |
| 1620 | 258 default value they are all included, except "M". You can remove a flag with a |
| 259 command like: > | |
| 7 | 260 |
| 261 :set guioptions-=m | |
| 262 < | |
| 263 m When removed the menubar is not displayed. | |
| 264 | |
| 1620 | 265 M When added the default menus are not loaded. |
| 7 | 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 | |
| 273 The dotted line at the top of a menu is not a separator line. When you select | |
| 274 this item, the menu is "teared-off": It is displayed in a separate window. | |
| 275 This is called a tearoff menu. This is useful when you use the same menu | |
| 276 often. | |
| 277 | |
| 278 For translating menu items, see |:menutrans|. | |
| 279 | |
| 280 Since the mouse has to be used to select a menu item, it is a good idea to use | |
| 281 the ":browse" command for selecting a file. And ":confirm" to get a dialog | |
| 282 instead of an error message, e.g., when the current buffer contains changes. | |
| 283 These two can be combined: > | |
| 284 | |
| 285 :amenu File.Open :browse confirm edit<CR> | |
| 286 | |
| 287 The ":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 | |
| 289 then select to save the changes, throw them away or cancel the command. | |
| 290 For more complicated items, the confirm() and inputdialog() functions can | |
| 291 be used. The default menus contain a few examples. | |
| 292 | |
| 293 ============================================================================== | |
| 294 *42.4* Toolbar and popup menus | |
| 295 | |
| 296 There are two special menus: ToolBar and PopUp. Items that start with these | |
| 297 names do not appear in the normal menu bar. | |
| 298 | |
| 299 | |
| 300 TOOLBAR | |
| 301 | |
| 302 The toolbar appears only when the "T" flag is included in the 'guioptions' | |
| 303 option. | |
| 304 The toolbar uses icons rather than text to represent the command. For | |
| 305 example, the {menu-item} named "ToolBar.New" causes the "New" icon to appear | |
| 306 on 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 | |
| 309 redefine 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 | |
| 311 item with a bitmap. For example, define a new toolbar item with: > | |
| 312 | |
| 313 :tmenu ToolBar.Compile Compile the current file | |
| 5690 | 314 :amenu ToolBar.Compile :!cc %:S -o %:r:S<CR> |
| 7 | 315 |
| 316 Now you need to create the icon. For MS-Windows it must be in bitmap format, | |
| 317 with 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 | |
| 319 can 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 | |
| 323 You can define tooltips for the items in the toolbar. A tooltip is a short | |
| 324 text that explains what a toolbar item will do. For example "Open file". It | |
| 325 appears when the mouse pointer is on the item, without moving for a moment. | |
| 326 This is very useful if the meaning of the picture isn't that obvious. | |
| 327 Example: > | |
| 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 | |
| 335 To remove a tooltip, use the |:tunmenu| command. | |
| 336 | |
| 337 The 'toolbar' option can be used to display text instead of a bitmap, or both | |
| 338 text and a bitmap. Most people use just the bitmap, since the text takes | |
| 339 quite a bit of space. | |
| 340 | |
| 341 | |
| 342 POPUP MENU | |
| 343 | |
| 344 The popup menu pops up where the mouse pointer is. On MS-Windows you activate | |
| 345 it by clicking the right mouse button. Then you can select an item with the | |
| 346 left mouse button. On Unix the popup menu is used by pressing and holding the | |
| 347 right mouse button. | |
| 348 The popup menu only appears when the 'mousemodel' has been set to "popup" | |
| 349 or "popup_setpos". The difference between the two is that "popup_setpos" | |
| 350 moves the cursor to the mouse pointer position. When clicking inside a | |
| 351 selection, the selection will be used unmodified. When there is a selection | |
| 352 but you click outside of it, the selection is removed. | |
| 353 There is a separate popup menu for each mode. Thus there are never grey | |
| 354 items like in the normal menus. | |
| 355 | |
| 356 What is the meaning of life, the universe and everything? *42* | |
| 357 Douglas Adams, the only person who knew what this question really was about is | |
| 358 now dead, unfortunately. So now you might wonder what the meaning of death | |
| 359 is... | |
| 360 | |
| 361 ============================================================================== | |
| 362 | |
| 363 Next chapter: |usr_43.txt| Using filetypes | |
| 364 | |
| 365 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: |