codekingpro/portable-devtools

1*usr_42.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		     VIM USER MANUAL	by Bram Moolenaar5 6 7			      Add new menus8 9 10By now you know that Vim is very flexible.  This includes the menus used in11the GUI.  You can define your own menu entries to make certain commands easily12accessible.  This is for mouse-happy users only.13 14|42.1|	Introduction15|42.2|	Menu commands16|42.3|	Various17|42.4|	Toolbar and popup menus18 19     Next chapter: |usr_43.txt|  Using filetypes20 Previous chapter: |usr_41.txt|  Write a Vim script21Table of contents: |usr_toc.txt|22 23==============================================================================24*42.1*	Introduction25 26The menus that Vim uses are defined in the file "$VIMRUNTIME/menu.vim".  If27you want to write your own menus, you might first want to look through that28file.29   To define a menu item, use the ":menu" command.  The basic form of this30command is as follows: >31 32	:menu {menu-item} {keys}33 34The {menu-item} describes where on the menu to put the item.  A typical35{menu-item} is "File.Save", which represents the item "Save" under the36"File" menu.  A dot is used to separate the names.  Example: >37 38	:menu File.Save  :update<CR>39 40The ":update" command writes the file when it was modified.41   You can add another level: "Edit.Settings.Shiftwidth" defines a submenu42"Settings" under the "Edit" menu, with an item "Shiftwidth".  You could use43even deeper levels.  Don't use this too much, you need to move the mouse quite44a bit to use such an item.45   The ":menu" command is very similar to the ":map" command: the left side46specifies how the item is triggered and the right hand side defines the47characters that are executed.  {keys} are characters, they are used just like48you would have typed them.  Thus in Insert mode, when {keys} is plain text,49that text is inserted.50 51 52ACCELERATORS53 54The ampersand character (&) is used to indicate an accelerator.  For instance,55you can use Alt-F to select "File" and S to select "Save".  (The 'winaltkeys'56option may disable this though!).  Therefore, the {menu-item} looks like57"&File.&Save".  The accelerator characters will be underlined in the menu.58   You must take care that each key is used only once in each menu.  Otherwise59you will not know which of the two will actually be used.  Vim doesn't warn60you for this.61 62 63PRIORITIES64 65The actual definition of the File.Save menu item is as follows: >66 67	:menu 10.340 &File.&Save<Tab>:w  :confirm w<CR>68 69The number 10.340 is called the priority number.  It is used by the editor to70decide where it places the menu item.  The first number (10) indicates the71position on the menu bar.  Lower numbered menus are positioned to the left,72higher numbers to the right.73   These are the priorities used for the standard menus:74 75	  10	20     40     50      60       70		999976 77	+------------------------------------------------------------+78	| File	Edit  Tools  Syntax  Buffers  Window		Help |79	+------------------------------------------------------------+80 81Notice that the Help menu is given a very high number, to make it appear on82the far right.83   The second number (340) determines the location of the item within the84pull-down menu.  Lower numbers go on top, higher number on the bottom.  These85are the priorities in the File menu:86 87			+-----------------+88	    10.310	|Open...	  |89	    10.320	|Split-Open...	  |90	    10.325	|New		  |91	    10.330	|Close		  |92	    10.335	|---------------- |93	    10.340	|Save		  |94	    10.350	|Save As...	  |95	    10.400	|---------------- |96	    10.410	|Split Diff with  |97	    10.420	|Split Patched By |98	    10.500	|---------------- |99	    10.510	|Print		  |100	    10.600	|---------------- |101	    10.610	|Save-Exit	  |102	    10.620	|Exit		  |103			+-----------------+104 105Notice that there is room in between the numbers.  This is where you can106insert your own items, if you really want to (it's often better to leave the107standard menus alone and add a new menu for your own items).108   When you create a submenu, you can add another ".number" to the priority.109Thus each name in {menu-item} has its priority number.110 111 112SPECIAL CHARACTERS113 114The {menu-item} in this example is "&File.&Save<Tab>:w".  This brings up an115important point: {menu-item} must be one word.  If you want to put a dot,116space or tabs in the name, you either use the <> notation (<Space> and <Tab>,117for instance) or use the backslash (\) escape. >118 119	:menu 10.305 &File.&Do\ It\.\.\. :exit<CR>120 121In this example, the name of the menu item "Do It..." contains a space and the122command is ":exit<CR>".123 124The <Tab> character in a menu name is used to separate the part that defines125the menu name from the part that gives a hint to the user.  The part after the126<Tab> is displayed right aligned in the menu.  In the File.Save menu the name127used is "&File.&Save<Tab>:w".  Thus the menu name is "File.Save" and the hint128is ":w".129 130 131SEPARATORS132 133The separator lines, used to group related menu items together, can be defined134by using a name that starts and ends in a '-'.  For example "-sep-".  When135using several separators the names must be different.  Otherwise the names136don't matter.137   The command from a separator will never be executed, but you have to define138one anyway.  A single colon will do.  Example: >139 140	:amenu 20.510 Edit.-sep3- :141 142==============================================================================143*42.2*	Menu commands144 145You can define menu items that exist for only certain modes.  This works just146like the variations on the ":map" command:147 148	:menu		Normal, Visual and Operator-pending mode149	:nmenu		Normal mode150	:vmenu		Visual mode151	:omenu		Operator-pending mode152	:menu!		Insert and Command-line mode153	:imenu		Insert mode154	:cmenu		Command-line mode155	:tlmenu		Terminal mode156	:amenu		All modes (except for Terminal mode)157 158To avoid that the commands of a menu item are being mapped, use the command159":noremenu", ":nnoremenu", ":anoremenu", etc.160 161 162USING :AMENU163 164The ":amenu" command is a bit different.  It assumes that the {keys} you165give are to be executed in Normal mode.  When Vim is in Visual or Insert mode166when the menu is used, Vim first has to go back to Normal mode.  ":amenu"167inserts a CTRL-C or CTRL-O for you.  For example, if you use this command:168>169	:amenu  90.100 Mine.Find\ Word  *170 171Then the resulting menu commands will be:172 173	Normal mode:		*174	Visual mode:		CTRL-C *175	Operator-pending mode:	CTRL-C *176	Insert mode:		CTRL-O *177	Command-line mode:	CTRL-C *178 179When in Command-line mode the CTRL-C will abandon the command typed so far.180In Visual and Operator-pending mode CTRL-C will stop the mode.  The CTRL-O in181Insert mode will execute the command and then return to Insert mode.182   CTRL-O only works for one command.  If you need to use two or more183commands, put them in a function and call that function.  Example: >184 185	:amenu  Mine.Next\ File  :call <SID>NextFile()<CR>186	:function <SID>NextFile()187	:  next188	:  1/^Code189	:endfunction190 191This menu entry goes to the next file in the argument list with ":next".  Then192it searches for the line that starts with "Code".193   The <SID> before the function name is the script ID.  This makes the194function local to the current Vim script file.  This avoids problems when a195function with the same name is defined in another script file.  See |<SID>|.196 197 198SILENT MENUS199 200The menu executes the {keys} as if you typed them.  For a ":" command this201means you will see the command being echoed on the command line.  If it's a202long command, the hit-Enter prompt will appear.  That can be very annoying!203   To avoid this, make the menu silent.  This is done with the <silent>204argument.  For example, take the call to NextFile() in the previous example.205When you use this menu, you will see this on the command line:206 207	:call <SNR>34_NextFile() ~208 209To avoid this text on the command line, insert "<silent>" as the first210argument: >211 212	:amenu <silent> Mine.Next\ File :call <SID>NextFile()<CR>213 214Don't use "<silent>" too often.  It is not needed for short commands.  If you215make a menu for someone else, being able to see the executed command will give216him a hint about what he could have typed, instead of using the mouse.217 218 219LISTING MENUS220 221When a menu command is used without a {keys} part, it lists the already222defined menus.  You can specify a {menu-item}, or part of it, to list specific223menus.  Example: >224 225	:amenu226 227This lists all menus.  That's a long list!  Better specify the name of a menu228to get a shorter list: >229 230	:amenu Edit231 232This lists only the "Edit" menu items for all modes.  To list only one233specific menu item for Insert mode: >234 235	:imenu Edit.Undo236 237Take care that you type exactly the right name.  Case matters here.  But the238'&' for accelerators can be omitted.  The <Tab> and what comes after it can be239left out as well.240 241 242DELETING MENUS243 244To delete a menu, the same command is used as for listing, but with "menu"245changed to "unmenu".  Thus ":menu" becomes, ":unmenu", ":nmenu" becomes246":nunmenu", etc.  To delete the "Tools.Make" item for Insert mode: >247 248	:iunmenu Tools.Make249 250You can delete a whole menu, with all its items, by using the menu name.251Example: >252 253	:aunmenu Syntax254 255This deletes the Syntax menu and all the items in it.256 257==============================================================================258*42.3*	Various259 260You can change the appearance of the menus with flags in 'guioptions'.  In the261default value they are all included, except "M".  You can remove a flag with a262command like: >263 264	:set guioptions-=m265<266	m		When removed the menubar is not displayed.267 268	M		When added the default menus are not loaded.269 270	g		When removed the inactive menu items are not made grey271			but are completely removed.  (Does not work on all272			systems.)273 274	t		When removed the tearoff feature is not enabled.275 276The dotted line at the top of a menu is not a separator line.  When you select277this item, the menu is "teared-off": It is displayed in a separate window.278This is called a tearoff menu.  This is useful when you use the same menu279often.280 281For translating menu items, see |:menutrans|.282 283Since the mouse has to be used to select a menu item, it is a good idea to use284the ":browse" command for selecting a file.  And ":confirm" to get a dialog285instead of an error message, e.g., when the current buffer contains changes.286These two can be combined: >287 288	:amenu File.Open  :browse confirm edit<CR>289 290The ":browse" makes a file browser appear to select the file to edit.  The291":confirm" will pop up a dialog when the current buffer has changes.  You can292then select to save the changes, throw them away or cancel the command.293   For more complicated items, the confirm() and inputdialog() functions can294be used.  The default menus contain a few examples.295 296==============================================================================297*42.4*	Toolbar and popup menus298 299There are two special menus: ToolBar and PopUp.  Items that start with these300names do not appear in the normal menu bar.301 302 303TOOLBAR304 305The toolbar appears only when the "T" flag is included in the 'guioptions'306option.307   The toolbar uses icons rather than text to represent the command.  For308example, the {menu-item} named "ToolBar.New" causes the "New" icon to appear309on the toolbar.310   The Vim editor has 28 built-in icons.  You can find a table here:311|builtin-tools|.  Most of them are used in the default toolbar.  You can312redefine what these items do (after the default menus are setup).313   You can add another bitmap for a toolbar item.  Or define a new toolbar314item with a bitmap.  For example, define a new toolbar item with: >315 316	:tmenu ToolBar.Compile  Compile the current file317	:amenu ToolBar.Compile  :!cc %:S -o %:r:S<CR>318 319Now you need to create the icon.  For MS-Windows it must be in bitmap format,320with the name "Compile.bmp".  For Unix XPM format is used, the file name is321"Compile.xpm".  The size must be 18 by 18 pixels.  On MS-Windows other sizes322can be used as well, but it will look ugly.323   Put the bitmap in the directory "bitmaps" in one of the directories from324'runtimepath'.  E.g., for Unix "~/.vim/bitmaps/Compile.xpm".325 326You can define tooltips for the items in the toolbar.  A tooltip is a short327text that explains what a toolbar item will do.  For example "Open file".  It328appears when the mouse pointer is on the item, without moving for a moment.329This is very useful if the meaning of the picture isn't that obvious.330Example: >331 332	:tmenu ToolBar.Make  Run make in the current directory333<334	Note:335	Pay attention to the case used.  "Toolbar" and "toolbar" are different336	from "ToolBar"!337 338To remove a tooltip, use the |:tunmenu| command.339 340The 'toolbar' option can be used to display text instead of a bitmap, or both341text and a bitmap.  Most people use just the bitmap, since the text takes342quite a bit of space.343 344 345POPUP MENU346 347The popup menu pops up where the mouse pointer is.  On MS-Windows you activate348it by clicking the right mouse button.  Then you can select an item with the349left mouse button.  On Unix the popup menu is used by pressing and holding the350right mouse button.351   The popup menu only appears when the 'mousemodel' has been set to "popup"352or "popup_setpos".  The difference between the two is that "popup_setpos"353moves the cursor to the mouse pointer position.  When clicking inside a354selection, the selection will be used unmodified.  When there is a selection355but you click outside of it, the selection is removed.356   There is a separate popup menu for each mode.  Thus there are never grey357items like in the normal menus.358 359What is the meaning of life, the universe and everything?  *42*360Douglas Adams, the only person who knew what this question really was about is361now dead, unfortunately.  So now you might wonder what the meaning of death362is...363 364==============================================================================365 366Next chapter: |usr_43.txt|  Using filetypes367 368Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl:369