diff options
Diffstat (limited to 'runtime/doc/usr_42.txt')
| -rw-r--r-- | runtime/doc/usr_42.txt | 366 |
1 files changed, 366 insertions, 0 deletions
diff --git a/runtime/doc/usr_42.txt b/runtime/doc/usr_42.txt new file mode 100644 index 0000000..2901913 --- /dev/null +++ b/runtime/doc/usr_42.txt @@ -0,0 +1,366 @@ +*usr_42.txt* For Vim version 8.1. Last change: 2008 May 05 + + 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 + :tlmenu Terminal mode + :amenu All modes (except for Terminal mode) + +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, except "M". You can remove a flag with a +command like: > + + :set guioptions-=m +< + m When removed the menubar is not displayed. + + M When added 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 %:S -o %:r:S<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:noet:ft=help:norl: |