| *usr_42.txt* For Vim version 7.0. Last change: 2006 Apr 24 |
| |
| VIM USER MANUAL - by Bram Moolenaar |
| |
| Add new menus |
| |
| |
| By now you know that Vim is very flexible. This includes the menus used in |
| the GUI. You can define your own menu entries to make certain commands easily |
| accessible. This is for mouse-happy users only. |
| |
| |42.1| Introduction |
| |42.2| Menu commands |
| |42.3| Various |
| |42.4| Toolbar and popup menus |
| |
| Next chapter: |usr_43.txt| Using filetypes |
| Previous chapter: |usr_41.txt| Write a Vim script |
| Table of contents: |usr_toc.txt| |
| |
| ============================================================================== |
| *42.1* Introduction |
| |
| The menus that Vim uses are defined in the file "$VIMRUNTIME/menu.vim". If |
| you want to write your own menus, you might first want to look through that |
| file. |
| To define a menu item, use the ":menu" command. The basic form of this |
| command is as follows: > |
| |
| :menu {menu-item} {keys} |
| |
| The {menu-item} describes where on the menu to put the item. A typical |
| {menu-item} is "File.Save", which represents the item "Save" under the |
| "File" menu. A dot is used to separate the names. Example: > |
| |
| :menu File.Save :update<CR> |
| |
| The ":update" command writes the file when it was modified. |
| You can add another level: "Edit.Settings.Shiftwidth" defines a submenu |
| "Settings" under the "Edit" menu, with an item "Shiftwidth". You could use |
| even deeper levels. Don't use this too much, you need to move the mouse quite |
| a bit to use such an item. |
| The ":menu" command is very similar to the ":map" command: the left side |
| specifies how the item is triggered and the right hand side defines the |
| characters that are executed. {keys} are characters, they are used just like |
| you would have typed them. Thus in Insert mode, when {keys} is plain text, |
| that text is inserted. |
| |
| |
| ACCELERATORS |
| |
| The ampersand character (&) is used to indicate an accelerator. For instance, |
| you can use Alt-F to select "File" and S 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. |
| You must take care that each key is used only once in each menu. Otherwise |
| you will not know which of the two will actually be used. Vim doesn't warn |
| you for this. |
| |
| |
| PRIORITIES |
| |
| The actual definition of the File.Save menu item is as follows: > |
| |
| :menu 10.340 &File.&Save<Tab>:w :confirm w<CR> |
| |
| The number 10.340 is called the priority number. It is used by the editor to |
| decide where it places the menu item. The first number (10) indicates the |
| position on the menu bar. Lower numbered menus are positioned to the left, |
| higher numbers to the right. |
| These are the priorities used for the standard menus: |
| |
| 10 20 40 50 60 70 9999 |
| |
| +------------------------------------------------------------+ |
| | File Edit Tools Syntax Buffers Window Help | |
| +------------------------------------------------------------+ |
| |
| Notice that the Help menu is given a very high number, to make it appear on |
| the far right. |
| The second number (340) determines the location of the item within the |
| pull-down menu. Lower numbers go on top, higher number on the bottom. These |
| are 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 there is room in between the numbers. This is where you can |
| insert your own items, if you really want to (it's often better to leave the |
| standard menus alone and add a new menu for your own items). |
| When you create a submenu, you can add another ".number" to the priority. |
| Thus each name in {menu-item} has its priority number. |
| |
| |
| SPECIAL CHARACTERS |
| |
| The {menu-item} in this example is "&File.&Save<Tab>:w". This brings up an |
| important point: {menu-item} must be one word. If you want to put a dot, |
| space or tabs in the name, you either use the <> notation (<Space> and <Tab>, |
| for instance) or use the backslash (\) escape. > |
| |
| :menu 10.305 &File.&Do\ It\.\.\. :exit<CR> |
| |
| In this example, the name of the menu item "Do It..." contains a space and the |
| command is ":exit<CR>". |
| |
| The <Tab> character in a menu name is used to separate the part that defines |
| the menu name from the part that gives a hint to the user. The part after the |
| <Tab> is displayed right aligned in the menu. In the File.Save menu the name |
| used is "&File.&Save<Tab>:w". Thus the menu name is "File.Save" and the hint |
| is ":w". |
| |
| |
| SEPARATORS |
| |
| The separator lines, used to group related menu items together, can be defined |
| by using a name that starts and ends in a '-'. For example "-sep-". When |
| using several separators the names must be different. Otherwise the names |
| don't matter. |
| The command from a separator will never be executed, but you have to define |
| one anyway. A single colon will do. Example: > |
| |
| :amenu 20.510 Edit.-sep3- : |
| |
| ============================================================================== |
| *42.2* Menu commands |
| |
| You can define menu items that exist for only certain modes. This works just |
| like the variations on the ":map" command: |
| |
| :menu Normal, Visual and Operator-pending mode |
| :nmenu Normal mode |
| :vmenu Visual mode |
| :omenu Operator-pending mode |
| :menu! Insert and Command-line mode |
| :imenu Insert mode |
| :cmenu Command-line mode |
| :amenu All modes |
| |
| To avoid that the commands of a menu item are being mapped, use the command |
| ":noremenu", ":nnoremenu", ":anoremenu", etc. |
| |
| |
| USING :AMENU |
| |
| The ":amenu" command is a bit different. It assumes that the {keys} you |
| give are to be executed in Normal mode. When Vim is in Visual or Insert mode |
| when the menu is used, Vim first has to go back to Normal mode. ":amenu" |
| inserts a CTRL-C or CTRL-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 in Command-line mode the CTRL-C will abandon the command typed so far. |
| In Visual and Operator-pending mode CTRL-C will stop the mode. The CTRL-O in |
| Insert mode will execute the command and then return to Insert mode. |
| CTRL-O only works for one command. If you need to use two or more |
| commands, put them in a function and call that function. Example: > |
| |
| :amenu Mine.Next\ File :call <SID>NextFile()<CR> |
| :function <SID>NextFile() |
| : next |
| : 1/^Code |
| :endfunction |
| |
| This menu entry goes to the next file in the argument list with ":next". Then |
| it searches for the line that starts with "Code". |
| The <SID> before the function name is the script ID. This makes the |
| function local to the current Vim script file. This avoids problems when a |
| function with the same name is defined in another script file. See |<SID>|. |
| |
| |
| SILENT MENUS |
| |
| The menu executes the {keys} as if you typed them. For a ":" command this |
| means you will see the command being echoed on the command line. If it's a |
| long command, the hit-Enter prompt will appear. That can be very annoying! |
| To avoid this, make the menu silent. This is 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 first |
| argument: > |
| |
| :amenu <silent> Mine.Next\ File :call <SID>NextFile()<CR> |
| |
| Don't use "<silent>" too often. It is not needed for short commands. If you |
| make a menu for someone else, being able the see the executed command will |
| give him a hint about what he could have typed, instead of using the mouse. |
| |
| |
| LISTING MENUS |
| |
| When a menu command is used without a {keys} part, it lists the already |
| defined menus. You can specify a {menu-item}, or part of it, to list specific |
| menus. Example: > |
| |
| :amenu |
| |
| This lists all menus. That's a long list! Better specify the name of a menu |
| to get a shorter list: > |
| |
| :amenu Edit |
| |
| This lists only the "Edit" menu items for all modes. To list only one |
| specific menu item for Insert mode: > |
| |
| :imenu Edit.Undo |
| |
| Take care that you type exactly the right name. Case matters here. But the |
| '&' for accelerators can be omitted. The <Tab> and what comes after it can be |
| left out as well. |
| |
| |
| DELETING MENUS |
| |
| To delete a menu, the same command is used as for listing, but with "menu" |
| changed to "unmenu". Thus ":menu" becomes, ":unmenu", ":nmenu" becomes |
| ":nunmenu", etc. To delete the "Tools.Make" item for Insert mode: > |
| |
| :iunmenu Tools.Make |
| |
| You can delete a whole menu, with all its items, by using the menu name. |
| Example: > |
| |
| :aunmenu Syntax |
| |
| This deletes the Syntax menu and all the items in it. |
| |
| ============================================================================== |
| *42.3* Various |
| |
| You can change the appearance of the menus with flags in 'guioptions'. In the |
| default value they are all included. You can remove a flag with a command |
| like: > |
| |
| :set guioptions-=m |
| < |
| m When removed the menubar is not displayed. |
| |
| M When removed the default menus are not loaded. |
| |
| g When removed the inactive menu items are not made grey |
| but are completely removed. (Does not work on all |
| systems.) |
| |
| t When removed the tearoff feature is not enabled. |
| |
| The dotted line at the top of a menu is not a separator line. When you select |
| this item, the menu is "teared-off": It is displayed in a separate window. |
| This is called a tearoff menu. This is useful when you use the same menu |
| often. |
| |
| For translating menu items, see |:menutrans|. |
| |
| Since the mouse has to be used to select a menu item, it is a good idea to use |
| the ":browse" command for selecting a file. And ":confirm" to get a dialog |
| instead 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" makes a file browser appear to select the file to edit. The |
| ":confirm" will pop up a dialog when the current buffer has changes. You can |
| then select to save the changes, throw them away or cancel the command. |
| For more complicated items, the confirm() and inputdialog() functions can |
| be used. The default menus contain a few examples. |
| |
| ============================================================================== |
| *42.4* Toolbar and popup menus |
| |
| There are two special menus: ToolBar and PopUp. Items that start with these |
| names do not appear in the normal menu bar. |
| |
| |
| TOOLBAR |
| |
| The toolbar appears only when the "T" flag is included in the 'guioptions' |
| option. |
| The toolbar uses icons rather than text to represent the command. For |
| example, the {menu-item} named "ToolBar.New" causes the "New" icon to appear |
| on the toolbar. |
| The Vim editor has 28 built-in icons. You can find a table here: |
| |builtin-tools|. Most of them are used in the default toolbar. You can |
| redefine what these items do (after the default menus are setup). |
| You can add another bitmap for a toolbar item. Or define a new toolbar |
| item with a bitmap. For example, define a new toolbar item with: > |
| |
| :tmenu ToolBar.Compile Compile the current file |
| :amenu ToolBar.Compile :!cc % -o %:r<CR> |
| |
| Now you need to create the icon. For MS-Windows it must be in bitmap format, |
| with the name "Compile.bmp". For Unix XPM format is used, the file name is |
| "Compile.xpm". The size must be 18 by 18 pixels. On MS-Windows other sizes |
| can be used as well, but it will look ugly. |
| Put the bitmap in the directory "bitmaps" in one of the directories from |
| 'runtimepath'. E.g., for Unix "~/.vim/bitmaps/Compile.xpm". |
| |
| You can define tooltips for the items in the toolbar. A tooltip is a short |
| text that explains what a toolbar item will do. For example "Open file". It |
| appears when the mouse pointer is on the item, without moving for a moment. |
| This is very useful if the meaning of the picture isn't that obvious. |
| Example: > |
| |
| :tmenu ToolBar.Make Run make in the current directory |
| < |
| Note: |
| Pay attention to the case used. "Toolbar" and "toolbar" are different |
| from "ToolBar"! |
| |
| To remove a tooltip, use the |:tunmenu| command. |
| |
| The 'toolbar' option can be used to display text instead of a bitmap, or both |
| text and a bitmap. Most people use just the bitmap, since the text takes |
| quite a bit of space. |
| |
| |
| POPUP MENU |
| |
| The popup menu pops up where the mouse pointer is. On MS-Windows you activate |
| it by clicking the right mouse button. Then you can select an item with the |
| left mouse button. On Unix the popup menu is used by pressing and holding the |
| right mouse button. |
| The popup menu only appears when the 'mousemodel' has been set to "popup" |
| or "popup_setpos". The difference between the two is that "popup_setpos" |
| moves the cursor to the mouse pointer position. When clicking inside a |
| selection, the selection will be used unmodified. When there is a selection |
| but you click outside of it, the selection is removed. |
| There is a separate popup menu for each mode. Thus there are never grey |
| items like in the normal menus. |
| |
| What is the meaning of life, the universe and everything? *42* |
| Douglas Adams, the only person who knew what this question really was about is |
| now dead, unfortunately. So now you might wonder what the meaning of death |
| is... |
| |
| ============================================================================== |
| |
| Next chapter: |usr_43.txt| Using filetypes |
| |
| Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: |