|
5294
|
1 *usr_42.txt* For Vim version 7.4. 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:
|
