Mercurial > vim

comparison runtime/doc/map.txt @ 22862:6d50182e7e24 v8.2.1978

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.2.1978: making a mapping work in all modes is complicated Commit: https://github.com/vim/vim/commit/957cf67d50516ba98716f59c9e1cb6412ec1535d Author: Bram Moolenaar <Bram@vim.org> Date: Thu Nov 12 14:21:06 2020 +0100 patch 8.2.1978: making a mapping work in all modes is complicated Problem: Making a mapping work in all modes is complicated. Solution: Add the <Cmd> special key. (Yegappan Lakshmanan, closes https://github.com/vim/vim/issues/7282, closes 4784, based on patch by Bjorn Linse)
author Bram Moolenaar <Bram@vim.org>
date Thu, 12 Nov 2020 14:30:04 +0100
parents 17c4178f26ea
children e7c125224b1a
comparison
equal deleted inserted replaced
22861:459c4d8b3a34 22862:6d50182e7e24
1 *map.txt* For Vim version 8.2. Last change: 2020 Oct 07 1 *map.txt* For Vim version 8.2. Last change: 2020 Nov 12
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
269 - Changing the buffer text |textlock|. 269 - Changing the buffer text |textlock|.
270 - Editing another buffer. 270 - Editing another buffer.
271 - The |:normal| command. 271 - The |:normal| command.
272 - Moving the cursor is allowed, but it is restored afterwards. 272 - Moving the cursor is allowed, but it is restored afterwards.
273 If you want the mapping to do any of these let the returned characters do 273 If you want the mapping to do any of these let the returned characters do
274 that. 274 that, or use a |<Cmd>| mapping instead.
275 275
276 You can use getchar(), it consumes typeahead if there is any. E.g., if you 276 You can use getchar(), it consumes typeahead if there is any. E.g., if you
277 have these mappings: > 277 have these mappings: >
278 inoremap <expr> <C-L> nr2char(getchar()) 278 inoremap <expr> <C-L> nr2char(getchar())
279 inoremap <expr> <C-L>x "foo" 279 inoremap <expr> <C-L>x "foo"
300 CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an 300 CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an
301 empty string, so that nothing is inserted. 301 empty string, so that nothing is inserted.
302 302
303 Note that using 0x80 as a single byte before other text does not work, it will 303 Note that using 0x80 as a single byte before other text does not work, it will
304 be seen as a special key. 304 be seen as a special key.
305
306 *<Cmd>* *:map-cmd*
307 The special text <Cmd> begins a "command mapping", it executes the command
308 directly without changing modes. Where you might use ":...<CR>" in the
309 {rhs} of a mapping, you can instead use "<Cmd>...<CR>".
310 Example: >
311 noremap x <Cmd>echo mode(1)<CR>
312 <
313 This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or
314 `<C-O>:` in Insert mode, because the commands are executed directly in the
315 current mode, instead of always going to Normal mode. Visual mode is
316 preserved, so tricks with |gv| are not needed. Commands can be invoked
317 directly in Command-line mode (which would otherwise require timer hacks).
318 Example of using <Cmd> halfway Insert mode: >
319 nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc>
320
321 Unlike <expr> mappings, there are no special restrictions on the <Cmd>
322 command: it is executed as if an (unrestricted) |autocmd| was invoked.
323
324 Note:
325 - Because <Cmd> avoids mode-changes it does not trigger |CmdlineEnter| and
326 |CmdlineLeave| events, because no user interaction is expected.
327 - For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain,
328 unmapped keys.
329 - In Select mode, |:map| and |:vmap| command mappings are executed in
330 Visual mode. Use |:smap| to handle Select mode differently.
331
332 *E1135* *E1136*
333 <Cmd> commands must terminate, that is, they must be followed by <CR> in the
334 {rhs} of the mapping definition. |Command-line| mode is never entered.
335
336 *E1137*
337 <Cmd> commands can have only normal characters and cannot contain special
338 characters like function keys.
305 339
306 340
307 1.3 MAPPING AND MODES *:map-modes* 341 1.3 MAPPING AND MODES *:map-modes*
308 *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* 342 *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o*
309 343