blob: f57384521316f5e68a8bd3c71e7c9598e5389ac8 [file] [log] [blame]
Bram Moolenaarc8734422012-06-01 22:38:45 +02001*visual.txt* For Vim version 7.3. Last change: 2012 May 25
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Visual mode *Visual* *Visual-mode* *visual-mode*
8
9Visual mode is a flexible and easy way to select a piece of text for an
10operator. It is the only way to select a block of text.
11
12This is introduced in section |04.4| of the user manual.
13
141. Using Visual mode |visual-use|
152. Starting and stopping Visual mode |visual-start|
163. Changing the Visual area |visual-change|
174. Operating on the Visual area |visual-operators|
185. Blockwise operators |blockwise-operators|
196. Repeating |visual-repeat|
207. Examples |visual-examples|
218. Select mode |Select-mode|
22
23{Vi has no Visual mode, the name "visual" is used for Normal mode, to
24distinguish it from Ex mode}
25{not available when the |+visual| feature was disabled when compiling}
26
27==============================================================================
281. Using Visual mode *visual-use*
29
30Using Visual mode consists of three parts:
311. Mark the start of the text with "v", "V" or CTRL-V.
32 The character under the cursor will be used as the start.
332. Move to the end of the text.
34 The text from the start of the Visual mode up to and including the
35 character under the cursor is highlighted.
363. Type an operator command.
37 The highlighted characters will be operated upon.
38
39The 'highlight' option can be used to set the display mode to use for
40highlighting in Visual mode.
41The 'virtualedit' option can be used to allow positioning the cursor to
42positions where there is no actual character.
43
44The highlighted text normally includes the character under the cursor.
45However, when the 'selection' option is set to "exclusive" and the cursor is
46after the Visual area, the character under the cursor is not included.
47
48With "v" the text before the start position and after the end position will
Bram Moolenaar81695252004-12-29 20:58:21 +000049not be highlighted. However, all uppercase and non-alpha operators, except
Bram Moolenaar071d4272004-06-13 20:20:40 +000050"~" and "U", will work on whole lines anyway. See the list of operators
51below.
52
53 *visual-block*
54With CTRL-V (blockwise Visual mode) the highlighted text will be a rectangle
55between start position and the cursor. However, some operators work on whole
56lines anyway (see the list below). The change and substitute operators will
57delete the highlighted text and then start insertion at the top left
58position.
59
60==============================================================================
612. Starting and stopping Visual mode *visual-start*
62
63 *v* *characterwise-visual*
Bram Moolenaarc8734422012-06-01 22:38:45 +020064[count]v Start Visual mode per character.
65 With [count] select that many characters, like moving
66 the cursor right [count] characters. One less when
67 'selection' is not "exclusive".
Bram Moolenaar071d4272004-06-13 20:20:40 +000068
69 *V* *linewise-visual*
Bram Moolenaarc8734422012-06-01 22:38:45 +020070[count]V Start Visual mode linewise.
71 With [count] select that many lines.
Bram Moolenaar071d4272004-06-13 20:20:40 +000072
73 *CTRL-V* *blockwise-visual*
Bram Moolenaarc8734422012-06-01 22:38:45 +020074[count]CTRL-V Start Visual mode blockwise. Note: Under Windows
Bram Moolenaar071d4272004-06-13 20:20:40 +000075 CTRL-V could be mapped to paste text, it doesn't work
76 to start Visual mode then, see |CTRL-V-alternative|.
Bram Moolenaarc8734422012-06-01 22:38:45 +020077 [count] is used as with `v` above.
Bram Moolenaar071d4272004-06-13 20:20:40 +000078
79If you use <Esc>, click the left mouse button or use any command that
80does a jump to another buffer while in Visual mode, the highlighting stops
81and no text is affected. Also when you hit "v" in characterwise Visual mode,
82"CTRL-V" in blockwise Visual mode or "V" in linewise Visual mode. If you hit
83CTRL-Z the highlighting stops and the editor is suspended or a new shell is
84started |CTRL-Z|.
85
86 new mode after typing: *v_v* *v_CTRL-V* *v_V*
87old mode "v" "CTRL-V" "V" ~
88
89Normal Visual blockwise Visual linewise Visual
90Visual Normal blockwise Visual linewise Visual
91blockwise Visual Visual Normal linewise Visual
92linewise Visual Visual blockwise Visual Normal
93
Bram Moolenaard5cdbeb2005-10-10 20:59:28 +000094 *gv* *v_gv* *reselect-Visual*
Bram Moolenaar071d4272004-06-13 20:20:40 +000095gv Start Visual mode with the same area as the previous
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000096 area and the same mode.
97 In Visual mode the current and the previous Visual
98 area are exchanged.
99 After using "p" or "P" in Visual mode the text that
100 was put will be selected.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000101
102 *<LeftMouse>*
103<LeftMouse> Set the current cursor position. If Visual mode is
104 active it is stopped. Only when 'mouse' option is
105 contains 'n' or 'a'. If the position is within 'so'
106 lines from the last line on the screen the text is
107 scrolled up. If the position is within 'so' lines from
108 the first line on the screen the text is scrolled
109 down.
110
111 *<RightMouse>*
112<RightMouse> Start Visual mode if it is not active. The text from
113 the cursor position to the position of the click is
114 highlighted. If Visual mode was already active move
115 the start or end of the highlighted text, which ever
116 is closest, to the position of the click. Only when
117 'mouse' option contains 'n' or 'a'.
118
119 Note: when 'mousemodel' is set to "popup",
120 <S-LeftMouse> has to be used instead of <RightMouse>.
121
122 *<LeftRelease>*
123<LeftRelease> This works like a <LeftMouse>, if it is not at
124 the same position as <LeftMouse>. In an older version
125 of xterm you won't see the selected area until the
126 button is released, unless there is access to the
127 display where the xterm is running (via the DISPLAY
128 environment variable or the -display argument). Only
129 when 'mouse' option contains 'n' or 'a'.
130
131If Visual mode is not active and the "v", "V" or CTRL-V is preceded with a
132count, the size of the previously highlighted area is used for a start. You
133can then move the end of the highlighted area and give an operator. The type
134of the old area is used (character, line or blockwise).
135- Linewise Visual mode: The number of lines is multiplied with the count.
136- Blockwise Visual mode: The number of lines and columns is multiplied with
137 the count.
138- Normal Visual mode within one line: The number of characters is multiplied
139 with the count.
140- Normal Visual mode with several lines: The number of lines is multiplied
141 with the count, in the last line the same number of characters is used as
142 in the last line in the previously highlighted area.
143The start of the text is the Cursor position. If the "$" command was used as
144one of the last commands to extend the highlighted text, the area will be
145extended to the rightmost column of the longest line.
146
147If you want to highlight exactly the same area as the last time, you can use
148"gv" |gv| |v_gv|.
149
Bram Moolenaar81695252004-12-29 20:58:21 +0000150 *v_<Esc>*
151<Esc> In Visual mode: Stop Visual mode.
152
Bram Moolenaar071d4272004-06-13 20:20:40 +0000153 *v_CTRL-C*
154CTRL-C In Visual mode: Stop Visual mode. When insert mode is
155 pending (the mode message shows
156 "-- (insert) VISUAL --"), it is also stopped.
157
158==============================================================================
1593. Changing the Visual area *visual-change*
160
161 *v_o*
162o Go to Other end of highlighted text: The current
163 cursor position becomes the start of the highlighted
164 text and the cursor is moved to the other end of the
165 highlighted text. The highlighted area remains the
166 same.
167
168 *v_O*
169O Go to Other end of highlighted text. This is like
170 "o", but in Visual block mode the cursor moves to the
171 other corner in the same line. When the corner is at
172 a character that occupies more than one position on
173 the screen (e.g., a <Tab>), the highlighted text may
174 change.
175
176 *v_$*
177When the "$" command is used with blockwise Visual mode, the right end of the
178highlighted text will be determined by the longest highlighted line. This
179stops when a motion command is used that does not move straight up or down.
180
181For moving the end of the block many commands can be used, but you cannot
182use Ex commands, commands that make changes or abandon the file. Commands
Bram Moolenaar9964e462007-05-05 17:54:07 +0000183(starting with) ".", "&", CTRL-^, "Z", CTRL-], CTRL-T, CTRL-R, CTRL-I
Bram Moolenaar071d4272004-06-13 20:20:40 +0000184and CTRL-O cause a beep and Visual mode continues.
185
186When switching to another window on the same buffer, the cursor position in
187that window is adjusted, so that the same Visual area is still selected. This
188is especially useful to view the start of the Visual area in one window, and
189the end in another. You can then use <RightMouse> (or <S-LeftMouse> when
Bram Moolenaar81695252004-12-29 20:58:21 +0000190'mousemodel' is "popup") to drag either end of the Visual area.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000191
192==============================================================================
1934. Operating on the Visual area *visual-operators*
194
195The operators that can be used are:
196 ~ switch case |v_~|
197 d delete |v_d|
198 c change (4) |v_c|
199 y yank |v_y|
200 > shift right (4) |v_>|
201 < shift left (4) |v_<|
202 ! filter through external command (1) |v_!|
203 = filter through 'equalprg' option command (1) |v_=|
204 gq format lines to 'textwidth' length (1) |v_gq|
205
206The objects that can be used are:
207 aw a word (with white space) |v_aw|
208 iw inner word |v_iw|
209 aW a WORD (with white space) |v_aW|
210 iW inner WORD |v_iW|
211 as a sentence (with white space) |v_as|
212 is inner sentence |v_is|
213 ap a paragraph (with white space) |v_ap|
214 ip inner paragraph |v_ip|
215 ab a () block (with parenthesis) |v_ab|
216 ib inner () block |v_ib|
217 aB a {} block (with braces) |v_aB|
218 iB inner {} block |v_iB|
Bram Moolenaar5e3dae82010-03-02 16:19:40 +0100219 at a <tag> </tag> block (with tags) |v_at|
220 it inner <tag> </tag> block |v_it|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000221 a< a <> block (with <>) |v_a<|
222 i< inner <> block |v_i<|
223 a[ a [] block (with []) |v_a[|
224 i[ inner [] block |v_i[|
Bram Moolenaar5e3dae82010-03-02 16:19:40 +0100225 a" a double quoted string (with quotes) |v_aquote|
226 i" inner double quoted string |v_iquote|
227 a' a single quoted string (with quotes) |v_a'|
228 i' inner simple quoted string |v_i'|
229 a` a string in backticks (with backticks) |v_a`|
230 i` inner string in backticks |v_i`|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000231
232Additionally the following commands can be used:
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100233 : start Ex command for highlighted lines (1) |v_:|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000234 r change (4) |v_r|
235 s change |v_s|
236 C change (2)(4) |v_C|
237 S change (2) |v_S|
238 R change (2) |v_R|
239 x delete |v_x|
240 D delete (3) |v_D|
241 X delete (2) |v_X|
242 Y yank (2) |v_Y|
243 p put |v_p|
244 J join (1) |v_J|
245 U make uppercase |v_U|
246 u make lowercase |v_u|
247 ^] find tag |v_CTRL-]|
248 I block insert |v_b_I|
249 A block append |v_b_A|
250
251(1): Always whole lines, see |:visual_example|.
252(2): Whole lines when not using CTRL-V.
253(3): Whole lines when not using CTRL-V, delete until the end of the line when
254 using CTRL-V.
255(4): When using CTRL-V operates on the block only.
256
257Note that the ":vmap" command can be used to specifically map keys in Visual
258mode. For example, if you would like the "/" command not to extend the Visual
259area, but instead take the highlighted text and search for that: >
260 :vmap / y/<C-R>"<CR>
261(In the <> notation |<>|, when typing it you should type it literally; you
262need to remove the 'B' and '<' flags from 'cpoptions'.)
263
264If you want to give a register name using the """ command, do this just before
265typing the operator character: "v{move-around}"xd".
266
267If you want to give a count to the command, do this just before typing the
268operator character: "v{move-around}3>" (move lines 3 indents to the right).
269
270 *{move-around}*
271The {move-around} is any sequence of movement commands. Note the difference
272with {motion}, which is only ONE movement command.
273
Bram Moolenaar66fa2712006-01-22 23:22:22 +0000274Another way to operate on the Visual area is using the |/\%V| item in a
275pattern. For example, to replace all '(' in the Visual area with '#': >
276
277 :%s/\%V(/X/g
278
Bram Moolenaar071d4272004-06-13 20:20:40 +0000279==============================================================================
2805. Blockwise operators *blockwise-operators*
281
282{not available when compiled without the |+visualextra| feature}
283
284Reminder: Use 'virtualedit' to be able to select blocks that start or end
285after the end of a line or halfway a tab.
286
287Visual-block Insert *v_b_I*
288With a blockwise selection, I{string}<ESC> will insert {string} at the start
289of block on every line of the block, provided that the line extends into the
290block. Thus lines that are short will remain unmodified. TABs are split to
291retain visual columns.
292See |v_b_I_example|.
293
294Visual-block Append *v_b_A*
295With a blockwise selection, A{string}<ESC> will append {string} to the end of
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000296block on every line of the block. There is some differing behavior where the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000297block RHS is not straight, due to different line lengths:
298
2991. Block was created with <C-v>$
300 In this case the string is appended to the end of each line.
3012. Block was created with <C-v>{move-around}
302 In this case the string is appended to the end of the block on each line,
303 and whitespace is inserted to pad to the end-of-block column.
304See |v_b_A_example|.
305Note: "I" and "A" behave differently for lines that don't extend into the
306selected block. This was done intentionally, so that you can do it the way
307you want.
308
309Visual-block change *v_b_c*
310All selected text in the block will be replaced by the same text string. When
311using "c" the selected text is deleted and Insert mode started. You can then
312enter text (without a line break). When you hit <Esc>, the same string is
313inserted in all previously selected lines.
314
315Visual-block Change *v_b_C*
316Like using "c", but the selection is extended until the end of the line for
317all lines.
318
319 *v_b_<*
320Visual-block Shift *v_b_>*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000321The block is shifted by 'shiftwidth'. The RHS of the block is irrelevant. The
Bram Moolenaar071d4272004-06-13 20:20:40 +0000322LHS of the block determines the point from which to apply a right shift, and
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000323padding includes TABs optimally according to 'ts' and 'et'. The LHS of the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000324block determines the point upto which to shift left.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000325See |v_b_>_example|.
326See |v_b_<_example|.
327
328Visual-block Replace *v_b_r*
329Every screen char in the highlighted region is replaced with the same char, ie
330TABs are split and the virtual whitespace is replaced, maintaining screen
331layout.
332See |v_b_r_example|.
333
334
335==============================================================================
3366. Repeating *visual-repeat*
337
338When repeating a Visual mode operator, the operator will be applied to the
339same amount of text as the last time:
340- Linewise Visual mode: The same number of lines.
341- Blockwise Visual mode: The same number of lines and columns.
342- Normal Visual mode within one line: The same number of characters.
343- Normal Visual mode with several lines: The same number of lines, in the
344 last line the same number of characters as in the last line the last time.
345The start of the text is the Cursor position. If the "$" command was used as
346one of the last commands to extend the highlighted text, the repeating will
347be applied up to the rightmost column of the longest line.
348
349
350==============================================================================
3517. Examples *visual-examples*
352
353 *:visual_example*
354Currently the ":" command works on whole lines only. When you select part of
355a line, doing something like ":!date" will replace the whole line. If you
356want only part of the line to be replaced you will have to make a mapping for
357it. In a future release ":" may work on partial lines.
358
359Here is an example, to replace the selected text with the output of "date": >
360 :vmap _a <Esc>`>a<CR><Esc>`<i<CR><Esc>!!date<CR>kJJ
361
362(In the <> notation |<>|, when typing it you should type it literally; you
363need to remove the 'B' and '<' flags from 'cpoptions')
364
365What this does is:
366<Esc> stop Visual mode
367`> go to the end of the Visual area
368a<CR><Esc> break the line after the Visual area
369`< jump to the start of the Visual area
370i<CR><Esc> break the line before the Visual area
371!!date<CR> filter the Visual text through date
372kJJ Join the lines back together
373
374 *visual-search*
375Here is an idea for a mapping that makes it possible to do a search for the
376selected text: >
377 :vmap X y/<C-R>"<CR>
378
379(In the <> notation |<>|, when typing it you should type it literally; you
380need to remove the 'B' and '<' flags from 'cpoptions')
381
382Note that special characters (like '.' and '*') will cause problems.
383
384Visual-block Examples *blockwise-examples*
385With the following text, I will indicate the commands to produce the block and
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000386the results below. In all cases, the cursor begins on the 'a' in the first
Bram Moolenaar81695252004-12-29 20:58:21 +0000387line of the test text.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000388The following modeline settings are assumed ":ts=8:sw=4:".
389
390It will be helpful to
391:set hls
392/<TAB>
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000393where <TAB> is a real TAB. This helps visualise the operations.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000394
395The test text is:
396
397abcdefghijklmnopqrstuvwxyz
398abc defghijklmnopqrstuvwxyz
399abcdef ghi jklmnopqrstuvwxyz
400abcdefghijklmnopqrstuvwxyz
401
4021. fo<C-v>3jISTRING<ESC> *v_b_I_example*
403
404abcdefghijklmnSTRINGopqrstuvwxyz
405abc STRING defghijklmnopqrstuvwxyz
406abcdef ghi STRING jklmnopqrstuvwxyz
407abcdefghijklmnSTRINGopqrstuvwxyz
408
4092. fo<C-v>3j$ASTRING<ESC> *v_b_A_example*
410
411abcdefghijklmnopqrstuvwxyzSTRING
412abc defghijklmnopqrstuvwxyzSTRING
413abcdef ghi jklmnopqrstuvwxyzSTRING
414abcdefghijklmnopqrstuvwxyzSTRING
415
4163. fo<C-v>3j3l<.. *v_b_<_example*
417
418abcdefghijklmnopqrstuvwxyz
419abc defghijklmnopqrstuvwxyz
420abcdef ghi jklmnopqrstuvwxyz
421abcdefghijklmnopqrstuvwxyz
422
4234. fo<C-v>3j>.. *v_b_>_example*
424
425abcdefghijklmn opqrstuvwxyz
426abc defghijklmnopqrstuvwxyz
427abcdef ghi jklmnopqrstuvwxyz
428abcdefghijklmn opqrstuvwxyz
429
4305. fo<C-v>5l3jrX *v_b_r_example*
431
432abcdefghijklmnXXXXXXuvwxyz
433abc XXXXXXhijklmnopqrstuvwxyz
434abcdef ghi XXXXXX jklmnopqrstuvwxyz
435abcdefghijklmnXXXXXXuvwxyz
436
437==============================================================================
4388. Select mode *Select* *Select-mode*
439
440Select mode looks like Visual mode, but the commands accepted are quite
441different. This resembles the selection mode in Microsoft Windows.
442When the 'showmode' option is set, "-- SELECT --" is shown in the last line.
443
444Entering Select mode:
445- Using the mouse to select an area, and 'selectmode' contains "mouse".
446 'mouse' must also contain a flag for the current mode.
447- Using a non-printable movement command, with the Shift key pressed, and
448 'selectmode' contains "key". For example: <S-Left> and <S-End>. 'keymodel'
449 must also contain "startsel".
450- Using "v", "V" or CTRL-V command, and 'selectmode' contains "cmd".
451- Using "gh", "gH" or "g_CTRL-H" command in Normal mode.
452- From Visual mode, press CTRL-G. *v_CTRL-G*
453
454Commands in Select mode:
455- Printable characters, <NL> and <CR> cause the selection to be deleted, and
456 Vim enters Insert mode. The typed character is inserted.
457- Non-printable movement commands, with the Shift key pressed, extend the
458 selection. 'keymodel' must include "startsel".
459- Non-printable movement commands, with the Shift key NOT pressed, stop Select
460 mode. 'keymodel' must include "stopsel".
461- ESC stops Select mode.
462- CTRL-O switches to Visual mode for the duration of one command. *v_CTRL-O*
463- CTRL-G switches to Visual mode.
464
465Otherwise, typed characters are handled as in Visual mode.
466
467When using an operator in Select mode, and the selection is linewise, the
468selected lines are operated upon, but like in characterwise selection. For
469example, when a whole line is deleted, it can later be pasted halfway a line.
470
471
472Mappings and menus in Select mode. *Select-mode-mapping*
473
Bram Moolenaar371d5402006-03-20 21:47:49 +0000474When mappings and menus are defined with the |:vmap| or |:vmenu| command they
475work both in Visual mode and in Select mode. When these are used in Select
476mode Vim automatically switches to Visual mode, so that the same behavior as
477in Visual mode is effective. If you don't want this use |:xmap| or |:smap|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000478
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100479Users will expect printable characters to replace the selected area.
480Therefore avoid mapping printable characters in Select mode. Or use
481|:sunmap| after |:map| and |:vmap| to remove it for Select mode.
482
Bram Moolenaar071d4272004-06-13 20:20:40 +0000483After the mapping or menu finishes, the selection is enabled again and Select
484mode entered, unless the selected area was deleted, another buffer became
485the current one or the window layout was changed.
486
487When a character was typed that causes the selection to be deleted and Insert
488mode started, Insert mode mappings are applied to this character. This may
489cause some confusion, because it means Insert mode mappings apply to a
490character typed in Select mode. Language mappings apply as well.
491
492 *gV* *v_gV*
493gV Avoid the automatic reselection of the Visual area
494 after a Select mode mapping or menu has finished.
495 Put this just before the end of the mapping or menu.
496 At least it should be after any operations on the
497 selection.
498
499 *gh*
500gh Start Select mode, characterwise. This is like "v",
501 but starts Select mode instead of Visual mode.
502 Mnemonic: "get highlighted".
503
504 *gH*
505gH Start Select mode, linewise. This is like "V",
506 but starts Select mode instead of Visual mode.
507 Mnemonic: "get Highlighted".
508
509 *g_CTRL-H*
510g CTRL-H Start Select mode, blockwise. This is like CTRL-V,
511 but starts Select mode instead of Visual mode.
512 Mnemonic: "get Highlighted".
513
514 vim:tw=78:ts=8:ft=help:norl: