123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855 |
- *gui.txt* Nvim
- VIM REFERENCE MANUAL by Bram Moolenaar
- Nvim Graphical User Interface *gui* *GUI*
- Any client that supports the Nvim |ui-protocol| can be used as a UI for Nvim.
- And multiple UIs can connect to the same Nvim instance! The terms "UI" and
- "GUI" are often used interchangeably because all Nvim UI clients have the same
- potential capabilities; the "TUI" refers to a UI client that outputs to your
- terminal, whereas a "GUI" outputs directly to the OS graphics system.
- Except where noted, this document describes UI capabilities available to both
- TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes
- specific to the terminal UI. Help tags with the "gui-" prefix refer to UI
- features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|.
- ==============================================================================
- Third-party GUIs *third-party-guis* *vscode*
- Nvim provides a builtin "terminal UI" (|TUI|), but also works with many
- (third-party) GUIs which may provide a fresh look or extra features on top of
- Nvim. For example, "vscode-neovim" essentally allows you to use VSCode as
- a Nvim GUI.
- - vscode-neovim (Nvim in VSCode!) https://github.com/vscode-neovim/vscode-neovim
- - Firenvim (Nvim in your web browser!) https://github.com/glacambre/firenvim
- - Neovide https://neovide.dev/
- - Goneovim https://github.com/akiyosi/goneovim
- - Nvy https://github.com/RMichelsen/Nvy
- - Neovim-Qt (Qt5) https://github.com/equalsraf/neovim-qt
- - VimR (macOS) https://github.com/qvacua/vimr
- - Others https://github.com/neovim/neovim/wiki/Related-projects#gui
- Type |gO| to see the table of contents.
- ==============================================================================
- Starting the GUI *gui-config* *gui-start*
- *ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC*
- For GUI-specific configuration Nvim provides the |UIEnter| event. This
- happens after other |initialization|s, or whenever a UI attaches (multiple UIs
- can connect to any Nvim instance).
- Example: this sets "g:gui" to the value of the UI's "rgb" field: >
- :autocmd UIEnter * let g:gui = filter(nvim_list_uis(),{k,v-> v.chan==v:event.chan})[0].rgb
- <
- *:winp* *:winpos* *E188*
- :winp[os]
- Display current position of the top left corner of the GUI vim
- window in pixels. Does not work in all versions.
- Also see |getwinpos()|, |getwinposx()| and |getwinposy()|.
- :winp[os] {X} {Y} *E466*
- Put the GUI vim window at the given {X} and {Y} coordinates.
- The coordinates should specify the position in pixels of the
- top left corner of the window.
- When the GUI window has not been opened yet, the values are
- remembered until the window is opened. The position is
- adjusted to make the window fit on the screen (if possible).
- *:wi* *:win* *:winsize* *E465*
- :win[size] {width} {height}
- Set the window height to {width} by {height} characters.
- Obsolete, use ":set lines=11 columns=22".
- ==============================================================================
- Using the mouse *mouse-using*
- *mouse-mode-table* *mouse-overview*
- Overview of what the mouse buttons do, when 'mousemodel' is "extend":
- *<S-LeftMouse>* *<A-RightMouse>* *<S-RightMouse>* *<RightDrag>*
- *<RightRelease>* *<LeftDrag>*
- Normal Mode: >
- event position selection change action
- cursor window
- ---------------------------------------------------------------------------
- <LeftMouse> yes end yes
- <C-LeftMouse> yes end yes "CTRL-]" (2)
- <S-LeftMouse> yes no change yes "*" (2)
- <LeftDrag> yes start or extend (1) no
- <LeftRelease> yes start or extend (1) no
- <MiddleMouse> yes if not active no put
- <MiddleMouse> yes if active no yank and put
- <RightMouse> yes start or extend yes
- <A-RightMouse> yes start or extend blockw. yes
- <S-RightMouse> yes no change yes "#" (2)
- <C-RightMouse> no no change no "CTRL-T"
- <RightDrag> yes extend no
- <RightRelease> yes extend no
- Insert or Replace Mode: >
- event position selection change action
- cursor window
- ---------------------------------------------------------------------------
- <LeftMouse> yes (cannot be active) yes
- <C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2)
- <S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2)
- <LeftDrag> yes start or extend (1) no like CTRL-O (1)
- <LeftRelease> yes start or extend (1) no like CTRL-O (1)
- <MiddleMouse> no (cannot be active) no put register
- <RightMouse> yes start or extend yes like CTRL-O
- <A-RightMouse> yes start or extend blockw. yes
- <S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2)
- <C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T"
- In a help window: >
- event position selection change action
- cursor window
- ---------------------------------------------------------------------------
- <2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag)
- When 'mousemodel' is "popup", these are different:
- *<A-LeftMouse>*
- Normal Mode: >
- event position selection change action
- cursor window
- ---------------------------------------------------------------------------
- <S-LeftMouse> yes start or extend (1) no
- <A-LeftMouse> yes start/extend blockw no
- <RightMouse> no popup menu no
- Insert or Replace Mode: >
- event position selection change action
- cursor window
- ---------------------------------------------------------------------------
- <S-LeftMouse> yes start or extend (1) no like CTRL-O (1)
- <A-LeftMouse> yes start/extend blockw no
- <RightMouse> no popup menu no
- (1) only if mouse pointer moved since press
- (2) only if click is in same buffer
- Clicking the left mouse button causes the cursor to be positioned. If the
- click is in another window that window is made the active window. When
- editing the command-line the cursor can only be positioned on the
- command-line. When in Insert mode Vim remains in Insert mode. If 'scrolloff'
- is set, and the cursor is positioned within 'scrolloff' lines from the window
- border, the text is scrolled.
- A selection can be started by pressing the left mouse button on the first
- character, moving the mouse to the last character, then releasing the mouse
- button. You will not always see the selection until you release the button,
- only in some versions (GUI, Win32) will the dragging be shown immediately.
- Note that you can make the text scroll by moving the mouse at least one
- character in the first/last line in the window when 'scrolloff' is non-zero.
- In Normal, Visual and Select mode clicking the right mouse button causes the
- Visual area to be extended. When 'mousemodel' is "popup", the left button has
- to be used while keeping the shift key pressed. When clicking in a window
- which is editing another buffer, the Visual or Select mode is stopped.
- In Normal, Visual and Select mode clicking the right mouse button with the alt
- key pressed causes the Visual area to become blockwise. When 'mousemodel' is
- "popup" the left button has to be used with the alt key. Note that this won't
- work on systems where the window manager consumes the mouse events when the
- alt key is pressed (it may move the window).
- *double-click* *<2-LeftMouse>* *<3-LeftMouse>* *<4-LeftMouse>*
- Double, triple and quadruple clicks are supported. For selecting text, extra
- clicks extend the selection: >
- click select
- ---------------------------------
- double word or % match
- triple line
- quadruple rectangular block
- Exception: In a :help window, double-click jumps to help for the word that is
- clicked on.
- Double-click on a word selects that word. 'iskeyword' is used to specify
- which characters are included in a word. Double-click on a character that has
- a match selects until that match (like using "v%"). If the match is an
- #if/#else/#endif block, the selection becomes linewise. The time for
- double-clicking can be set with the 'mousetime' option.
- Example: configure double-click to jump to the tag under the cursor: >vim
- :map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR>
- Dragging the mouse with a double-click (button-down, button-up, button-down
- and then drag) will result in whole words to be selected. This continues
- until the button is released, at which point the selection is per character
- again.
- For scrolling with the mouse see |scroll-mouse-wheel|.
- In Insert mode, when a selection is started, Vim goes into Normal mode
- temporarily. When Visual or Select mode ends, it returns to Insert mode.
- This is like using CTRL-O in Insert mode. Select mode is used when the
- 'selectmode' option contains "mouse".
- *X1Mouse* *X1Drag* *X1Release*
- *X2Mouse* *X2Drag* *X2Release*
- *<MiddleRelease>* *<MiddleDrag>*
- Mouse clicks can be mapped using these |keycodes|: >
- code mouse button normal action
- ---------------------------------------------------------------------------
- <LeftMouse> left pressed set cursor position
- <LeftDrag> left moved while pressed extend selection
- <LeftRelease> left released set selection end
- <MiddleMouse> middle pressed paste text at cursor position
- <MiddleDrag> middle moved while pressed -
- <MiddleRelease> middle released -
- <RightMouse> right pressed extend selection
- <RightDrag> right moved while pressed extend selection
- <RightRelease> right released set selection end
- <X1Mouse> X1 button pressed -
- <X1Drag> X1 moved while pressed -
- <X1Release> X1 button release -
- <X2Mouse> X2 button pressed -
- <X2Drag> X2 moved while pressed -
- <X2Release> X2 button release -
- The X1 and X2 buttons refer to the extra buttons found on some mice (e.g. the
- right thumb).
- Examples: >vim
- :noremap <MiddleMouse> <LeftMouse><MiddleMouse>
- Paste at the position of the middle mouse button click (otherwise the paste
- would be done at the cursor position). >vim
- :noremap <LeftRelease> <LeftRelease>y
- Immediately yank the selection, when using Visual mode.
- Note the use of ":noremap" instead of "map" to avoid a recursive mapping.
- >vim
- :map <X1Mouse> <C-O>
- :map <X2Mouse> <C-I>
- Map the X1 and X2 buttons to go forwards and backwards in the jump list, see
- |CTRL-O| and |CTRL-I|.
- *mouse-swap-buttons*
- To swap the meaning of the left and right mouse buttons: >vim
- :noremap <LeftMouse> <RightMouse>
- :noremap <LeftDrag> <RightDrag>
- :noremap <LeftRelease> <RightRelease>
- :noremap <RightMouse> <LeftMouse>
- :noremap <RightDrag> <LeftDrag>
- :noremap <RightRelease> <LeftRelease>
- :noremap g<LeftMouse> <C-RightMouse>
- :noremap g<RightMouse> <C-LeftMouse>
- :noremap! <LeftMouse> <RightMouse>
- :noremap! <LeftDrag> <RightDrag>
- :noremap! <LeftRelease> <RightRelease>
- :noremap! <RightMouse> <LeftMouse>
- :noremap! <RightDrag> <LeftDrag>
- :noremap! <RightRelease> <LeftRelease>
- <
- ==============================================================================
- Scrollbars *gui-scrollbars*
- There are vertical scrollbars and a horizontal scrollbar. You may
- configure which ones appear with the 'guioptions' option.
- The interface looks like this (with `:set guioptions=mlrb`):
- >
- +------------------------------+ `
- | File Edit Help | <- Menu bar (m) `
- +-+--------------------------+-+ `
- |^| |^| `
- |#| Text area. |#| `
- | | | | `
- |v|__________________________|v| `
- Normal status line -> |-+ File.c 5,2 +-| `
- between Vim windows |^|""""""""""""""""""""""""""|^| `
- | | | | `
- | | Another file buffer. | | `
- | | | | `
- |#| |#| `
- Left scrollbar (l) -> |#| |#| <- Right `
- |#| |#| scrollbar (r) `
- | | | | `
- |v| |v| `
- +-+--------------------------+-+ `
- | |< #### >| | <- Bottom `
- +-+--------------------------+-+ scrollbar (b) `
- <
- Any of the scrollbar or menu components may be turned off by not putting the
- appropriate letter in the 'guioptions' string. The bottom scrollbar is
- only useful when 'nowrap' is set.
- VERTICAL SCROLLBARS *gui-vert-scroll*
- Each Vim window has a scrollbar next to it which may be scrolled up and down
- to move through the text in that buffer. The size of the scrollbar-thumb
- indicates the fraction of the buffer which can be seen in the window.
- When the scrollbar is dragged all the way down, the last line of the file
- will appear in the top of the window.
- If a window is shrunk to zero height (by the growth of another window) its
- scrollbar disappears. It reappears when the window is restored.
- If a window is vertically split, it will get a scrollbar when it is the
- current window and when, taking the middle of the current window and drawing a
- vertical line, this line goes through the window.
- When there are scrollbars on both sides, and the middle of the current window
- is on the left half, the right scrollbar column will contain scrollbars for
- the rightmost windows. The same happens on the other side.
- HORIZONTAL SCROLLBARS *gui-horiz-scroll*
- The horizontal scrollbar (at the bottom of the Vim GUI) may be used to
- scroll text sideways when the 'wrap' option is turned off. The
- scrollbar-thumb size is such that the text of the longest visible line may be
- scrolled as far as possible left and right. The cursor is moved when
- necessary, it must remain on a visible character (unless 'virtualedit' is
- set).
- Computing the length of the longest visible line takes quite a bit of
- computation, and it has to be done every time something changes. If this
- takes too much time or you don't like the cursor jumping to another line,
- include the 'h' flag in 'guioptions'. Then the scrolling is limited by the
- text of the current cursor line.
- ==============================================================================
- Drag and drop *drag-n-drop*
- You can drag and drop one or more files into the Vim window, where they will
- be opened as if a |:drop| command was used.
- If you hold down Shift while doing this, Vim changes to the first dropped
- file's directory. If you hold Ctrl Vim will always split a new window for the
- file. Otherwise it's only done if the current buffer has been changed.
- You can also drop a directory on Vim. This starts the explorer plugin for
- that directory (assuming it was enabled, otherwise you'll get an error
- message). Keep Shift pressed to change to the directory instead.
- If Vim happens to be editing a command line, the names of the dropped files
- and directories will be inserted at the cursor. This allows you to use these
- names with any Ex command. Special characters (space, tab, double quote and
- "|"; backslash on non-MS-Windows systems) will be escaped.
- ==============================================================================
- Menus *menus*
- For an introduction see |usr_42.txt| in the user manual.
- Using Menus *using-menus*
- Basically, menus can be used just like mappings. You can define your own
- menus, as many as you like.
- Long-time Vim users won't use menus much. But the power is in adding your own
- menus and menu items. They are most useful for things that you can't remember
- what the key sequence was.
- For creating menus in a different language, see |:menutrans|.
- *menu.vim*
- The default menus are read from the file "$VIMRUNTIME/menu.vim". See
- |$VIMRUNTIME| for where the path comes from. You can set up your own menus.
- Starting off with the default set is a good idea. You can add more items, or,
- if you don't like the defaults at all, start with removing all menus
- |:unmenu-all|. You can also avoid the default menus being loaded by adding
- this line to your vimrc file (NOT your gvimrc file!): >
- :let did_install_default_menus = 1
- If you also want to avoid the Syntax menu: >
- :let did_install_syntax_menu = 1
- The first item in the Syntax menu can be used to show all available filetypes
- in the menu (which can take a bit of time to load). If you want to have all
- filetypes already present at startup, add: >
- :let do_syntax_sel_menu = 1
- Note that the menu.vim is sourced when `:syntax on` or `:filetype on` is
- executed or after your .vimrc file is sourced. This means that the 'encoding'
- option and the language of messages (`:language messages`) must be set before
- that (if you want to change them).
- *console-menus*
- Although this documentation is in the GUI section, you can actually use menus
- in console mode too. You will have to load |menu.vim| explicitly then, it is
- not done by default. You can use the |:emenu| command and command-line
- completion with 'wildmenu' to access the menu entries almost like a real menu
- system. To do this, put these commands in your vimrc file: >
- :source $VIMRUNTIME/menu.vim
- :set wildmenu
- :set cpo-=<
- :set wcm=<C-Z>
- :map <F4> :emenu <C-Z>
- Pressing <F4> will start the menu. You can now use the cursor keys to select
- a menu entry. Hit <Enter> to execute it. Hit <Esc> if you want to cancel.
- Creating New Menus *creating-menus*
- *:me* *:menu* *:noreme* *:noremenu*
- *E330* *E327* *E331* *E336* *E333*
- *E328* *E329* *E337* *E792*
- To create a new menu item, use the ":menu" commands. They are mostly like
- the ":map" set of commands (see |map-modes|), but the first argument is a menu
- item name, given as a path of menus and submenus with a '.' between them,
- e.g.: >
- :menu File.Save :w<CR>
- :inoremenu File.Save <C-O>:w<CR>
- :menu Edit.Big\ Changes.Delete\ All\ Spaces :%s/[ ^I]//g<CR>
- This last one will create a new item in the menu bar called "Edit", holding
- the mouse button down on this will pop up a menu containing the item
- "Big Changes", which is a sub-menu containing the item "Delete All Spaces",
- which when selected, performs the operation.
- To create a menu for terminal mode, use |:tlmenu| instead of |:tmenu| unlike
- key mapping (|:tmap|). This is because |:tmenu| is already used for defining
- tooltips for menus. See |terminal-input|.
- Special characters in a menu name:
- *menu-shortcut*
- - & The next character is the shortcut key. Make sure each shortcut key is
- only used once in a (sub)menu. If you want to insert a literal "&" in the
- menu name use "&&".
- *menu-text*
- - <Tab> Separates the menu name from right-aligned text. This can be used to
- show the equivalent typed command. The text "<Tab>" can be used here for
- convenience. If you are using a real tab, don't forget to put a backslash
- before it!
- Example: >
- :amenu &File.&Open<Tab>:e :browse e<CR>
- [typed literally]
- With the shortcut "F" (while keeping the <Alt> key pressed), and then "O",
- this menu can be used. The second part is shown as "Open :e". The ":e"
- is right aligned, and the "O" is underlined, to indicate it is the shortcut.
- *:am* *:amenu* *:an* *:anoremenu*
- The ":amenu" command can be used to define menu entries for all modes at once,
- except for Terminal mode. To make the command work correctly, a character is
- automatically inserted for some modes: >
- mode inserted appended
- Normal nothing nothing
- Visual <C-C> <C-\><C-G>
- Insert <C-\><C-O>
- Cmdline <C-C> <C-\><C-G>
- Op-pending <C-C> <C-\><C-G>
- <
- Example: >
- :amenu File.Next :next^M
- is equal to: >
- :nmenu File.Next :next^M
- :vmenu File.Next ^C:next^M^\^G
- :imenu File.Next ^\^O:next^M
- :cmenu File.Next ^C:next^M^\^G
- :omenu File.Next ^C:next^M^\^G
- Careful: In Insert mode this only works for a SINGLE Normal mode command,
- because of the CTRL-O. If you have two or more commands, you will need to use
- the ":imenu" command. For inserting text in any mode, you can use the
- expression register: >
- :amenu Insert.foobar "='foobar'<CR>P
- The special text <Cmd> begins a "command menu", it executes the command
- directly without changing modes. Where you might use ":...<CR>" you can
- instead use "<Cmd>...<CR>". See |<Cmd>| for more info. Example: >
- anoremenu File.Next <Cmd>next<CR>
- Note that <Esc> in Cmdline mode executes the command, like in a mapping. This
- is Vi compatible. Use CTRL-C to quit Cmdline mode.
- *:nme* *:nmenu* *:nnoreme* *:nnoremenu* *:nunme* *:nunmenu*
- Menu commands starting with "n" work in Normal mode. |mapmode-n|
- *:ome* *:omenu* *:onoreme* *:onoremenu* *:ounme* *:ounmenu*
- Menu commands starting with "o" work in Operator-pending mode. |mapmode-o|
- *:vme* *:vmenu* *:vnoreme* *:vnoremenu* *:vunme* *:vunmenu*
- Menu commands starting with "v" work in Visual mode. |mapmode-v|
- *:xme* *:xmenu* *:xnoreme* *:xnoremenu* *:xunme* *:xunmenu*
- Menu commands starting with "x" work in Visual and Select mode. |mapmode-x|
- *:sme* *:smenu* *:snoreme* *:snoremenu* *:sunme* *:sunmenu*
- Menu commands starting with "s" work in Select mode. |mapmode-s|
- *:ime* *:imenu* *:inoreme* *:inoremenu* *:iunme* *:iunmenu*
- Menu commands starting with "i" work in Insert mode. |mapmode-i|
- *:cme* *:cmenu* *:cnoreme* *:cnoremenu* *:cunme* *:cunmenu*
- Menu commands starting with "c" work in Cmdline mode. |mapmode-c|
- *:tlm* *:tlmenu* *:tln* *:tlnoremenu* *:tlu* *:tlunmenu*
- Menu commands starting with "tl" work in Terminal mode. |mapmode-t|
- *:menu-<silent>* *:menu-silent*
- To define a menu which will not be echoed on the command line, add
- "<silent>" as the first argument. Example: >
- :menu <silent> Settings.Ignore\ case :set ic<CR>
- The ":set ic" will not be echoed when using this menu. Messages from the
- executed command are still given though. To shut them up too, add a ":silent"
- in the executed command: >
- :menu <silent> Search.Header :exe ":silent normal /Header\r"<CR>
- "<silent>" may also appear just after "<script>".
- *:menu-<script>* *:menu-script*
- The "to" part of the menu will be inspected for mappings. If you don't want
- this, use the ":noremenu" command (or the similar one for a specific mode).
- If you do want to use script-local mappings, add "<script>" as the very first
- argument to the ":menu" command or just after "<silent>".
- *menu-priority*
- You can give a priority to a menu. Menus with a higher priority go more to
- the right. The priority is given as a number before the ":menu" command.
- Example: >
- :80menu Buffer.next :bn<CR>
- The default menus have these priorities: >
- File 10
- Edit 20
- Tools 40
- Syntax 50
- Buffers 60
- Window 70
- Help 9999
- <
- When no or zero priority is given, 500 is used.
- The priority for the PopUp menu is not used.
- You can use a priority higher than 9999, to make it go after the Help menu,
- but that is non-standard and is discouraged. The highest possible priority is
- about 32000. The lowest is 1.
- *sub-menu-priority*
- The same mechanism can be used to position a sub-menu. The priority is then
- given as a dot-separated list of priorities, before the menu name: >
- :menu 80.500 Buffer.next :bn<CR>
- Giving the sub-menu priority is only needed when the item is not to be put
- in a normal position. For example, to put a sub-menu before the other items: >
- :menu 80.100 Buffer.first :brew<CR>
- Or to put a sub-menu after the other items, and further items with default
- priority will be put before it: >
- :menu 80.900 Buffer.last :blast<CR>
- When a number is missing, the default value 500 will be used: >
- :menu .900 myMenu.test :echo "text"<CR>
- The menu priority is only used when creating a new menu. When it already
- existed, e.g., in another mode, the priority will not change. Thus, the
- priority only needs to be given the first time a menu is used.
- An exception is the PopUp menu. There is a separate menu for each mode
- (Normal, Op-pending, Visual, Insert, Cmdline). The order in each of these
- menus can be different. This is different from menu-bar menus, which have
- the same order for all modes.
- NOTE: sub-menu priorities currently don't work for all versions of the GUI.
- *menu-separator* *E332*
- Menu items can be separated by a special item that inserts some space between
- items. Depending on the system this is displayed as a line or a dotted line.
- These items must start with a '-' and end in a '-'. The part in between is
- used to give it a unique name. Priorities can be used as with normal items.
- Example: >
- :menu Example.item1 :do something
- :menu Example.-Sep- :
- :menu Example.item2 :do something different
- Note that the separator also requires a rhs. It doesn't matter what it is,
- because the item will never be selected. Use a single colon to keep it
- simple.
- *gui-toolbar*
- The default toolbar is setup in menu.vim. The display of the toolbar is
- controlled by the 'guioptions' letter 'T'. You can thus have menu & toolbar
- together, or either on its own, or neither. The appearance is controlled by
- the 'toolbar' option. You can choose between an image, text or both.
- *toolbar-icon*
- The toolbar is defined as a special menu called ToolBar, which only has one
- level. Vim interprets the items in this menu as follows:
- - 1 If an "icon=" argument was specified, the file with this name is used.
- The file can either be specified with the full path or with the base name.
- In the last case it is searched for in the "bitmaps" directory in
- 'runtimepath', like in point 3. Examples: >
- :amenu icon=/usr/local/pixmaps/foo_icon.xpm ToolBar.Foo :echo "Foo"<CR>
- :amenu icon=FooIcon ToolBar.Foo :echo "Foo"<CR>
- < Note that in the first case the extension is included, while in the second
- case it is omitted.
- If the file cannot be opened the next points are tried.
- A space in the file name must be escaped with a backslash.
- A menu priority must come _after_ the icon argument: >
- :amenu icon=foo 1.42 ToolBar.Foo :echo "42!"<CR>
- - 2 An item called 'BuiltIn##', where ## is a number, is taken as number ## of
- the built-in bitmaps available in Vim. Currently there are 31 numbered
- from 0 to 30 which cover most common editing operations |builtin-tools|. >
- :amenu ToolBar.BuiltIn22 :call SearchNext("back")<CR>
- - 3 An item with another name is first searched for in the directory
- "bitmaps" in 'runtimepath'. If found, the bitmap file is used as the
- toolbar button image. Note that the exact filename is OS-specific: For
- example, under Win32 the command >
- :amenu ToolBar.Hello :echo "hello"<CR>
- < would find the file 'hello.bmp'. Under X11 it is 'Hello.xpm'.
- For MS-Windows and the bitmap is scaled to fit the button. For
- MS-Windows a size of 18 by 18 pixels works best.
- For MS-Windows the bitmap should have 16 colors with the standard palette.
- The light grey pixels will be changed to the Window frame color and the
- dark grey pixels to the window shadow color. More colors might also work,
- depending on your system.
- - 4 If the bitmap is still not found, Vim checks for a match against its list
- of built-in names. Each built-in button image has a name.
- So the command >
- :amenu ToolBar.Open :e
- < will show the built-in "open a file" button image if no open.bmp exists.
- All the built-in names can be seen used in menu.vim.
- - 5 If all else fails, a blank, but functioning, button is displayed.
- *builtin-tools*
- >
- nr Name Normal action
- 00 New open new window
- 01 Open browse for file to open in current window
- 02 Save write buffer to file
- 03 Undo undo last change
- 04 Redo redo last undone change
- 05 Cut delete selected text to clipboard
- 06 Copy copy selected text to clipboard
- 07 Paste paste text from clipboard
- 08 Print print current buffer
- 09 Help open a buffer on Vim's builtin help
- 10 Find start a search command
- 11 SaveAll write all modified buffers to file
- 12 SaveSesn write session file for current situation
- 13 NewSesn write new session file
- 14 LoadSesn load session file
- 15 RunScript browse for file to run as a Vim script
- 16 Replace prompt for substitute command
- 17 WinClose close current window
- 18 WinMax make current window use many lines
- 19 WinMin make current window use few lines
- 20 WinSplit split current window
- 21 Shell start a shell
- 22 FindPrev search again, backward
- 23 FindNext search again, forward
- 24 FindHelp prompt for word to search help for
- 25 Make run make and jump to first error
- 26 TagJump jump to tag under the cursor
- 27 RunCtags build tags for files in current directory
- 28 WinVSplit split current window vertically
- 29 WinMaxWidth make current window use many columns
- 30 WinMinWidth make current window use few columns
- <
- *hidden-menus* *win32-hidden-menus*
- In the Win32 GUI, starting a menu name with ']' excludes that menu from the
- main menu bar. You must then use the |:popup| command to display it.
- When splitting the window the window toolbar is not copied to the new window.
- *popup-menu*
- You can define the special menu "PopUp". This is the menu that is displayed
- when the right mouse button is pressed, if 'mousemodel' is set to popup or
- popup_setpos.
- The default "PopUp" menu is: >vim
- anoremenu PopUp.Go\ to\ definition <Cmd>lua vim.lsp.buf.definition()<CR>
- amenu PopUp.Open\ in\ web\ browser gx
- anoremenu PopUp.Inspect <Cmd>Inspect<CR>
- anoremenu PopUp.-1- <Nop>
- vnoremenu PopUp.Cut "+x
- vnoremenu PopUp.Copy "+y
- anoremenu PopUp.Paste "+gP
- vnoremenu PopUp.Paste "+P
- vnoremenu PopUp.Delete "_x
- nnoremenu PopUp.Select\ All ggVG
- vnoremenu PopUp.Select\ All gg0oG$
- inoremenu PopUp.Select\ All <C-Home><C-O>VG
- anoremenu PopUp.-2- <Nop>
- anoremenu PopUp.How-to\ disable\ mouse <Cmd>help disable-mouse<CR>
- <
- Showing What Menus Are Mapped To *showing-menus*
- To see what an existing menu is mapped to, use just one argument after the
- menu commands (just like you would with the ":map" commands). If the menu
- specified is a submenu, then all menus under that hierarchy will be shown.
- If no argument is given after :menu at all, then ALL menu items are shown
- for the appropriate mode (e.g., Command-line mode for :cmenu).
- Special characters in the list, just before the rhs:
- • * Menu was defined with "nore" to disallow remapping.
- • & Menu was defined with "<script>" to allow remapping script-local mappings.
- • s Menu was defined with "<silent>" to avoid showing what it is mapped to
- when triggered.
- • - Menu was disabled.
- Note that hitting <Tab> while entering a menu name after a menu command may
- be used to complete the name of the menu item.
- Executing Menus *execute-menus*
- *:em* *:emenu* *E334* *E335*
- :[range]em[enu] {menu} Execute {menu} from the command line.
- The default is to execute the Normal mode
- menu. If a range is specified, it executes
- the Visual mode menu.
- If used from <c-o>, it executes the
- insert-mode menu Eg: >
- :emenu File.Exit
- :[range]em[enu] {mode} {menu} Like above, but execute the menu for {mode}:
- - 'n': |:nmenu| Normal mode
- - 'v': |:vmenu| Visual mode
- - 's': |:smenu| Select mode
- - 'o': |:omenu| Operator-pending mode
- - 't': |:tlmenu| Terminal mode
- - 'i': |:imenu| Insert mode
- - 'c': |:cmenu| Cmdline mode
- You can use :emenu to access useful menu items you may have got used to from
- GUI mode. See 'wildmenu' for an option that works well with this. See
- |console-menus| for an example.
- When using a range, if the lines match with '<,'>, then the menu is executed
- using the last visual selection.
- Deleting Menus *delete-menus*
- *:unme* *:unmenu*
- *:aun* *:aunmenu*
- To delete a menu item or a whole submenu, use the unmenu commands, which are
- analogous to the unmap commands. Eg: >
- :unmenu! Edit.Paste
- This will remove the Paste item from the Edit menu for Insert and
- Command-line modes.
- Note that hitting <Tab> while entering a menu name after an umenu command
- may be used to complete the name of the menu item for the appropriate mode.
- To remove all menus use: *:unmenu-all* >
- :unmenu * " remove all menus in Normal and visual mode
- :unmenu! * " remove all menus in Insert and Command-line mode
- :aunmenu * " remove all menus in all modes, except for Terminal
- " mode
- :tlunmenu * " remove all menus in Terminal mode
- If you want to get rid of the menu bar: >
- :set guioptions-=m
- Disabling Menus *disable-menus*
- *:menu-disable* *:menu-enable*
- If you do not want to remove a menu, but disable it for a moment, this can be
- done by adding the "enable" or "disable" keyword to a ":menu" command.
- Examples: >
- :menu disable &File.&Open\.\.\.
- :amenu enable *
- :amenu disable &Tools.*
- The command applies to the modes as used with all menu commands. Note that
- characters like "&" need to be included for translated names to be found.
- When the argument is "*", all menus are affected. Otherwise the given menu
- name and all existing submenus below it are affected.
- Examples for Menus *menu-examples*
- Here is an example on how to add menu items with menus! You can add a menu
- item for the keyword under the cursor. The register "z" is used. >
- :nmenu Words.Add\ Var wb"zye:menu! Words.<C-R>z <C-R>z<CR>
- :nmenu Words.Remove\ Var wb"zye:unmenu! Words.<C-R>z<CR>
- :vmenu Words.Add\ Var "zy:menu! Words.<C-R>z <C-R>z <CR>
- :vmenu Words.Remove\ Var "zy:unmenu! Words.<C-R>z<CR>
- :imenu Words.Add\ Var <Esc>wb"zye:menu! Words.<C-R>z <C-R>z<CR>a
- :imenu Words.Remove\ Var <Esc>wb"zye:unmenu! Words.<C-R>z<CR>a
- (the rhs is in <> notation, you can copy/paste this text to try out the
- mappings, or put these lines in your gvimrc; "<C-R>" is CTRL-R, "<CR>" is
- the <CR> key. |<>|)
- *tooltips* *menu-tips*
- Tooltips & Menu tips
- See section |42.4| in the user manual.
- *:tmenu*
- :tm[enu] {menupath} {rhs} Define a tip for a menu or tool. (only in
- X11 and Win32 GUI)
- :tm[enu] [menupath] List menu tips. (only in X11 and Win32 GUI)
- *:tunmenu*
- :tu[nmenu] {menupath} Remove a tip for a menu or tool.
- (only in X11 and Win32 GUI)
- Note: To create menus for terminal mode, use |:tlmenu| instead.
- When a tip is defined for a menu item, it appears in the command-line area
- when the mouse is over that item, much like a standard Windows menu hint in
- the status bar. (Except when Vim is in Command-line mode, when of course
- nothing is displayed.)
- When a tip is defined for a ToolBar item, it appears as a tooltip when the
- mouse pauses over that button, in the usual fashion. Use the |hl-Tooltip|
- highlight group to change its colors.
- A "tip" can be defined for each menu item. For example, when defining a menu
- item like this: >
- :amenu MyMenu.Hello :echo "Hello"<CR>
- The tip is defined like this: >
- :tmenu MyMenu.Hello Displays a greeting.
- And delete it with: >
- :tunmenu MyMenu.Hello
- Tooltips are currently only supported for the X11 and Win32 GUI. However, they
- should appear for the other gui platforms in the not too distant future.
- The ":tmenu" command works just like other menu commands, it uses the same
- arguments. ":tunmenu" deletes an existing menu tip, in the same way as the
- other unmenu commands.
- If a menu item becomes invalid (i.e. its actions in all modes are deleted) Vim
- deletes the menu tip (and the item) for you. This means that :aunmenu deletes
- a menu item - you don't need to do a :tunmenu as well.
- 5.9 Popup Menus
- You can cause a menu to popup at the cursor. This behaves similarly to the
- PopUp menus except that any menu tree can be popped up.
- *:popup* *:popu*
- :popu[p] {name} Popup the menu {name}. The menu named must
- have at least one subentry, but need not
- appear on the menu-bar (see |hidden-menus|).
- :popu[p]! {name} Like above, but use the position of the mouse
- pointer instead of the cursor.
- Example: >
- :popup File
- will make the "File" menu (if there is one) appear at the text cursor (mouse
- pointer if ! was used). >
- :amenu ]Toolbar.Make :make<CR>
- :popup ]Toolbar
- This creates a popup menu that doesn't exist on the main menu-bar.
- Note that a menu that starts with ']' will not be displayed.
- vim:tw=78:sw=4:ts=8:et:ft=help:norl:
|