mirror of
https://github.com/amix/vimrc
synced 2025-07-22 20:44:59 +08:00
shenwenjie
365
doc/usr_42.txt
Normal file
365
doc/usr_42.txt
Normal file
@ -0,0 +1,365 @@
|
||||
*usr_42.txt* For Vim version 7.4. 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
|
||||
: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, 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 % -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:
|
||||
Reference in New Issue
Block a user