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