vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

usr_42.txt (13853B)


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