diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/doc/autocmd.txt | 7 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 1 | ||||
| -rw-r--r-- | runtime/doc/map.txt | 38 |
3 files changed, 42 insertions, 4 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index a5407046a..0a668c195 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -551,12 +551,15 @@ CmdlineChanged After a change was made to the text in the *CmdlineEnter* CmdlineEnter After moving the cursor to the command line, where the user can type a command or search - string. + string; including non-interactive use of ":" + in a mapping, but not when using |<Cmd>|. <afile> is set to a single character, indicating the type of command-line. |cmdwin-char| *CmdlineLeave* -CmdlineLeave Before leaving the command line. +CmdlineLeave Before leaving the command line; including + non-interactive use of ":" in a mapping, but + not when using |<Cmd>|. Also when abandoning the command line, after typing CTRL-C or <Esc>. When the commands result in an error the diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index c08b75bb8..3303cab3a 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -8660,6 +8660,7 @@ screencol() *screencol()* the following mappings: > nnoremap <expr> GG ":echom ".screencol()."\n" nnoremap <silent> GG :echom screencol()<CR> + nnoremap GG <Cmd>echom screencol()<CR> < screenpos({winid}, {lnum}, {col}) *screenpos()* The result is a Dict with the screen position of the text diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 276ab5050..83a5428ce 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -1,4 +1,4 @@ -*map.txt* For Vim version 8.2. Last change: 2020 Oct 07 +*map.txt* For Vim version 8.2. Last change: 2020 Nov 12 VIM REFERENCE MANUAL by Bram Moolenaar @@ -271,7 +271,7 @@ For this reason the following is blocked: - The |:normal| command. - Moving the cursor is allowed, but it is restored afterwards. If you want the mapping to do any of these let the returned characters do -that. +that, or use a |<Cmd>| mapping instead. You can use getchar(), it consumes typeahead if there is any. E.g., if you have these mappings: > @@ -303,6 +303,40 @@ empty string, so that nothing is inserted. Note that using 0x80 as a single byte before other text does not work, it will be seen as a special key. + *<Cmd>* *:map-cmd* +The special text <Cmd> begins a "command mapping", it executes the command +directly without changing modes. Where you might use ":...<CR>" in the +{rhs} of a mapping, you can instead use "<Cmd>...<CR>". +Example: > + noremap x <Cmd>echo mode(1)<CR> +< +This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or +`<C-O>:` in Insert mode, because the commands are executed directly in the +current mode, instead of always going to Normal mode. Visual mode is +preserved, so tricks with |gv| are not needed. Commands can be invoked +directly in Command-line mode (which would otherwise require timer hacks). +Example of using <Cmd> halfway Insert mode: > + nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc> + +Unlike <expr> mappings, there are no special restrictions on the <Cmd> +command: it is executed as if an (unrestricted) |autocmd| was invoked. + +Note: +- Because <Cmd> avoids mode-changes it does not trigger |CmdlineEnter| and + |CmdlineLeave| events, because no user interaction is expected. +- For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain, + unmapped keys. +- In Select mode, |:map| and |:vmap| command mappings are executed in + Visual mode. Use |:smap| to handle Select mode differently. + + *E1135* *E1136* +<Cmd> commands must terminate, that is, they must be followed by <CR> in the +{rhs} of the mapping definition. |Command-line| mode is never entered. + + *E1137* +<Cmd> commands can have only normal characters and cannot contain special +characters like function keys. + 1.3 MAPPING AND MODES *:map-modes* *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* |