| blob | 48fc926d884c20a30616543533de4894f3bf6b96 |
1 *visual.txt* For Vim version 5.8. Last change: 2000 Jan 05
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 1. Using Visual mode |visual-use|
13 2. Starting and stopping Visual mode |visual-start|
14 3. Changing the Visual area |visual-change|
15 4. Operating on the Visual area |visual-operators|
16 5. Blockwise operators |blockwise-operators|
17 6. Repeating |visual-repeat|
18 7. Examples |visual-examples|
19 8. Select mode |Select-mode|
21 {Vi has no Visual mode, the name "visual" is used for Normal mode, to
22 distinguish it from Ex mode}
24 ==============================================================================
25 1. Using Visual mode *visual-use*
27 Using Visual mode consists of three parts:
28 1. Mark the start of the text with "v", "V" or CTRL-V.
29 The character under the cursor will be used as the start.
30 2. Move to the end of the text.
31 The text from the start of the Visual mode up to and including the
32 character under the cursor is highlighted.
33 3. Hit an operator.
34 The highlighted characters will be operated upon.
36 The 'highlight' option can be used to set the display mode to use for
37 highlighting in Visual mode.
39 The highlighted text includes the character under the cursor. On terminals
40 where it is possible to make the cursor invisible the cursor position is
41 also highlighted. On terminals where this is not possible the cursor is
42 displayed normally. If your cursor cannot be made invisible and you want Vim
43 to highlight the character under the cursor anyway, you could set the 't_cv'
44 and 't_ci' options to something harmless, for example:
45 > :set t_cv=^[^[ t_ci=^[^[
47 With "v" the text before the start position and after the end position will
48 not be highlighted. However, All uppercase and non-alpha operators, except
49 "~", will work on whole lines anyway. See the list of operators below.
51 *visual-block*
52 With CTRL-V (blockwise Visual mode) the highlighted text will be a rectangle
53 between start position and the cursor. However, some operators work on whole
54 lines anyway (see the list below). The change and substitute operators will
55 delete the highlighted text and then start insertion at the top left
56 position.
58 ==============================================================================
59 2. Starting and stopping Visual mode *visual-start*
61 *v* *characterwise-visual*
62 v start Visual mode per character.
64 *V* *linewise-visual*
65 V start Visual mode linewise.
67 *CTRL-V* *blockwise-visual*
68 CTRL-V start Visual mode blockwise. Note: Under Windows
69 CTRL-V could be mapped to paste text, it doesn't work
70 to start Visual mode then, see |CTRL-V-alternative|.
72 If you use <Esc>, click the left mouse button or use any command that
73 does a jump to another buffer while in Visual mode, the highlighting stops
74 and no text is affected. Also when you hit "v" in characterwise Visual mode,
75 "CTRL-V" in blockwise Visual mode or "V" in linewise Visual mode. If you hit
76 CTRL-Z the highlighting stops and the editor is suspended or a new shell is
77 started |CTRL-Z|.
79 new mode after typing: *v_v* *v_CTRL-V* *v_V*
80 old mode "v" "CTRL-V" "V" ~
82 Normal Visual blockwise Visual linewise Visual
83 Visual Normal blockwise Visual linewise Visual
84 blockwise Visual Visual Normal linewise Visual
85 linewise Visual Visual blockwise Visual Normal
87 *gv* *v_gv*
88 gv Start Visual mode with the same area as the previous
89 area and the same mode. In Visual mode the current and
90 the previous Visual area are exchanged.
92 *<LeftMouse>*
93 <LeftMouse> Set the current cursor position. If Visual mode is
94 active it is stopped. Only when 'mouse' option is
95 contains 'n' or 'a'. If the position is within 'so'
96 lines from the last line on the screen the text is
97 scrolled up. If the position is within 'so' lines from
98 the first line on the screen the text is scrolled
99 down.
101 *<RightMouse>*
102 <RightMouse> Start Visual mode if it is not active. The text from
103 the cursor position to the position of the click is
104 highlighted. If Visual mode was already active move
105 the start or end of the highlighted text, which ever
106 is closest, to the position of the click. Only when
107 'mouse' option contains 'n' or 'a'.
109 Note: when 'mousemodel' is set to "popup",
110 <S-LeftMouse> has to be used instead of <RightMouse>.
112 *<LeftRelease>*
113 <LeftRelease> This works like a <LeftMouse>, if it is not a
114 the same position as <LeftMouse>. In an xterm you
115 won't see the selected area until the button is
116 released, unless there is access to the display where
117 the xterm is running (via the DISPLAY environment
118 variable or the -display argument). Only when 'mouse'
119 option contains 'n' or 'a'.
121 If Visual mode is not active and the "v", "V" or CTRL-V is preceded with a
122 count, the size of the previously highlighted area is used for a start. You
123 can then move the end of the highlighted area and give an operator. The type
124 of the old area is used (character, line or blockwise).
125 - Linewise Visual mode: The number of lines is multiplied with the count.
126 - Blockwise Visual mode: The number of lines and columns is multiplied with
127 the count.
128 - Normal Visual mode within one line: The number of characters is multiplied
129 with the count.
130 - Normal Visual mode with several lines: The number of lines is multiplied
131 with the count, in the last line the same number of characters is used as
132 in the last line in the previously highlighted area.
133 The start of the text is the Cursor position. If the "$" command was used as
134 one of the last commands to extend the highlighted text, the area will be
135 extended to the rightmost column of the longest line.
137 If you want to highlight exactly the same area as the last time, you can use
138 "gv" |gv| |v_gv|.
140 *v_CTRL-C*
141 CTRL-C In Visual mode: Stop Visual mode. When insert mode is
142 pending (the mode message shows
143 "-- (insert) VISUAL --"), it is also stopped.
145 ==============================================================================
146 3. Changing the Visual area *visual-change*
148 *v_o*
149 o Go to Other end of highlighted text: The current
150 cursor position becomes the start of the highlighted
151 text and the cursor is moved to the other end of the
152 highlighted text. The highlighted area remains the
153 same.
155 *v_O*
156 O Go to Other end of highlighted text. This is like
157 "o", but in Visual block mode the cursor moves to the
158 other corner in the same line. When the corner is at
159 a character that occupies more than one position on
160 the screen (e.g., a <Tab>), the highlighted text may
161 change.
163 *v_$*
164 When the "$" command is used with blockwise Visual mode, the right end of the
165 highlighted text will be determined by the longest highlighted line. This
166 stops when a motion command is used that does not move straight up or down.
168 For moving the end of the block many commands can be used, but you cannot
169 use Ex commands, commands that make changes or abandon the file. Commands
170 (starting with) ".pPiIaAO&", CTRL-^, "Z", CTRL-], CTRL-T, CTRL-R, CTRL-I
171 and CTRL-O cause a beep and Visual mode continues.
174 ==============================================================================
175 4. Operating on the Visual area *visual-operators*
177 The operators that can be used are:
178 ~ switch case |v_~|
179 d delete |v_d|
180 c change (4) |v_c|
181 y yank |v_y|
182 > shift right (4) |v_>|
183 < shift left (4) |v_<|
184 ! filter through external command (1) |v_!|
185 = filter through 'equalprg' option command (1) |v_=|
186 gq format lines to 'textwidth' length (1) |v_gq|
188 The objects that can be used are:
189 aw a word (with white space) |v_aw|
190 iw inner word |v_iw|
191 aW a WORD (with white space) |v_aW|
192 iW inner WORD |v_iW|
193 as a sentence (with white space) |v_as|
194 is inner sentence |v_is|
195 ap a paragraph (with white space) |v_ap|
196 ip inner paragraph |v_ip|
197 ab a () block (with braces) |v_ab|
198 ib inner () block |v_ib|
199 aB a {} block (with brackets) |v_aB|
200 iB inner {} block |v_iB|
202 Additionally the following commands can be used:
203 : start ex command for highlighted lines (1) |v_:|
204 r change (4) |v_r|
205 s change |v_s|
206 C change (2)(4) |v_C|
207 S change (2) |v_S|
208 R change (2) |v_R|
209 x delete |v_x|
210 D delete (3) |v_D|
211 X delete (2) |v_X|
212 Y yank (2) |v_Y|
213 J join (1) |v_J|
214 U make uppercase |v_U|
215 u make lowercase |v_u|
216 ^] find tag |v_CTRL-]|
217 I block insert |v_b_I|
218 A block append |v_b_A|
220 (1): Always whole lines, see |:visual_example|.
221 (2): Whole lines when not using CTRL-V.
222 (3): Whole lines when not using CTRL-V, delete until the end of the line when
223 using CTRL-V.
224 (4): When using CTRL-V operates on the block only.
226 Note that the ":vmap" command can be used to specifically map keys in Visual
227 mode. For example, if you would like the "/" command not to extend the Visual
228 area, but instead take the highlighted text and search for that:
229 > :vmap / y/<C-R>"<CR>
230 (In the <> notation |<>|, when typing it you should type it literally; you
231 need to remove the 'B' and '<' flags from 'cpoptions')
233 If you want to give a register name using the """ command, do this just before
234 typing the operator character: "v{move-around}"xd".
236 If you want to give a count to the command, do this just before typing the
237 operator character: "v{move-around}3>" (move lines 3 indents to the right).
239 *{move-around}*
240 The {move-around} is any sequence of movement commands. Note the difference
241 with {motion}, which is only ONE movement command.
243 ==============================================================================
244 5. Blockwise operators *blockwise-operators*
246 {not available when compiled without the |+visualextra| feature}
248 Visual-block Insert *v_b_I*
249 With a blockwise selection, Istring<ESC> will insert string at the start of
250 block on every line of the block, provided that the line extends into the
251 block. TABs are split to retain visual columns.
252 See |v_b_I_example|.
254 Visual-block Append *v_b_A*
255 With a blockwise selection, Astring<ESC> will append string to the end of
256 block on every line of the block. There is some differing behavior where the
257 block RHS is not straight, due to different line lengths.
259 a. Block was created with <C-v>$
260 In this case the string is appended to the end of each line.
261 b. Block was created with <C-v>{move-around}
262 In this case the string is appended to the end of the block on each
263 line which extends into the block, and whitespace is inserted to pad to
264 the end-of-block column.
265 Note: Padding is buggy (vim 5.4c).
266 See |v_b_A_example|.
268 Visual-block change *v_b_c*
269 All selected text in the block will be replaced by the same text string. When
270 using "c" the selected text is deleted and Insert mode started. You can then
271 enter text (without a line break). When you hit <Esc>, the same string is
272 inserted in all previously selected lines.
274 Visual-block Change *v_b_C*
275 Like using "c", but the selection is extended until the end of the line for
276 all lines.
278 *v_b_<*
279 Visual-block Shift *v_b_>*
280 The block is shifted by 'shiftwidth'. The RHS of the block is irrelevant. The
281 LHS of the block determines the point from which to apply a right shift, and
282 padding includes TABs optimally according to 'ts' and 'et'. The LHS of the
283 block determines the point upto which to shift left.
284 Note: v_< padding is buggy if the Visual Block starts and ends in the same
285 TAB. (Vim 5.4c).
286 See |v_b_>_example|.
287 See |v_b_<_example|.
289 Visual-block Replace *v_b_r*
290 Every screen char in the highlighted region is replaced with the same char, ie
291 TABs are split and the virtual whitespace is replaced, maintaining screen
292 layout.
293 See |v_b_r_example|.
296 ==============================================================================
297 6. Repeating *visual-repeat*
299 When repeating a Visual mode operator, the operator will be applied to the
300 same amount of text as the last time:
301 - Linewise Visual mode: The same number of lines.
302 - Blockwise Visual mode: The same number of lines and columns.
303 - Normal Visual mode within one line: The same number of characters.
304 - Normal Visual mode with several lines: The same number of lines, in the
305 last line the same number of characters as in the last line the last time.
306 The start of the text is the Cursor position. If the "$" command was used as
307 one of the last commands to extend the highlighted text, the repeating will
308 be applied up to the rightmost column of the longest line.
311 ==============================================================================
312 7. Examples *visual-examples*
314 *:visual_example*
315 Currently the ":" command works on whole lines only. When you select part of
316 a line, doing something like ":!date" will replace the whole line. If you
317 want only part of the line to be replaced you will have to make a mapping for
318 it. In a future release ":" may work on partial lines.
320 Here is an example, to replace the selected text with the output of "date":
321 > :vmap _a <Esc>`>a<CR><Esc>`<i<CR><Esc>!!date<CR>kJJ
323 (In the <> notation |<>|, when typing it you should type it literally; you
324 need to remove the 'B' and '<' flags from 'cpoptions')
326 What this does is:
327 <Esc> stop Visual mode
328 `> go to the end of the Visual area
329 a<CR><Esc> break the line after the Visual area
330 `< jump to the start of the Visual area
331 i<CR><Esc> break the line before the Visual area
332 !!date<CR> filter the Visual text through date
333 kJJ Join the lines back together
335 *visual-search*
336 Here is an idea for a mapping that makes it possible to do a search for the
337 selected text:
338 > :vmap X y/<C-R>"<CR>
340 (In the <> notation |<>|, when typing it you should type it literally; you
341 need to remove the 'B' and '<' flags from 'cpoptions')
343 Note that special characters (like '.' and '*') will cause problems.
345 Visual-block Examples *blockwise-examples*
346 With the following text, I will indicate the commands to produce the block and
347 the results below. In all cases, the cursor begins on the 'a' in the first
348 line if the test text.
349 The following modeline settings are assumed :ts=8:sw=4:
351 It will be helpful to
352 :set hls
353 /<TAB>
354 where <TAB> ia a real TAB. This helps visualise the operations.
356 The test text is:
358 abcdefghijklmnopqrstuvwxyz
359 abc defghijklmnopqrstuvwxyz
360 abcdef ghi jklmnopqrstuvwxyz
361 abcdefghijklmnopqrstuvwxyz
363 1. fo<C-v>3jISTRING<ESC> *v_b_I_example*
365 abcdefghijklmnSTRINGopqrstuvwxyz
366 abc STRING defghijklmnopqrstuvwxyz
367 abcdef ghi STRING jklmnopqrstuvwxyz
368 abcdefghijklmnSTRINGopqrstuvwxyz
370 2. fo<C-v>3j$ASTRING<ESC> *v_b_A_example*
372 abcdefghijklmnopqrstuvwxyzSTRING
373 abc defghijklmnopqrstuvwxyzSTRING
374 abcdef ghi jklmnopqrstuvwxyzSTRING
375 abcdefghijklmnopqrstuvwxyzSTRING
377 3. fo<C-v>3j3l<.. *v_b_<_example*
379 abcdefghijklmnopqrstuvwxyz
380 abc defghijklmnopqrstuvwxyz
381 abcdef ghi jklmnopqrstuvwxyz
382 abcdefghijklmnopqrstuvwxyz
384 4. fo\x163j>.. *v_b_>_example*
386 abcdefghijklmn opqrstuvwxyz
387 abc defghijklmnopqrstuvwxyz
388 abcdef ghi jklmnopqrstuvwxyz
389 abcdefghijklmn opqrstuvwxyz
391 5. fo\x165l3jrX *v_b_r_example*
393 abcdefghijklmnXXXXXXuvwxyz
394 abc XXXXXXhijklmnopqrstuvwxyz
395 abcdef ghi XXXXXX jklmnopqrstuvwxyz
396 abcdefghijklmnXXXXXXuvwxyz
398 ==============================================================================
399 8. Select mode *Select* *Select-mode*
401 Select mode looks like Visual mode, but the commands accepted are quite
402 different. This resembles the selection mode in Microsoft Windows.
403 When the 'showmode' option is set, "-- SELECT --" is shown in the last line.
405 Entering Select mode:
406 - Using the mouse to select an area, and 'selectmode' contains "mouse".
407 'mouse' must also contain a flag for the current mode.
408 - Using a non-printable movement command, with the Shift key pressed, and
409 'selectmode' contains "key". For example: <S-Left> and <S-End>. 'keymodel'
410 must also contain "startsel".
411 - Using "v", "V" or CTRL-V command, and 'selectmode' contains "cmd".
412 - Using "gh", "gH" or "g_CTRL-H" command in Normal mode.
413 - From Visual mode, press CTRL-G. *v_CTRL-G*
415 Commands in Select mode:
416 - Printable characters, <NL> and <CR> cause the selection to be deleted, and
417 Vim enters Insert mode. The typed character is inserted.
418 - Non-printable movement commands, with the Shift key pressed, extend the
419 selection. 'keymodel' must include "startsel".
420 - Non-printable movement commands, with the Shift key NOT pressed, stop Select
421 mode. 'keymodel' must include "stopsel".
422 - ESC stops Select mode.
423 - CTRL-O switches to Visual mode for the duration of one command. *v_CTRL-O*
424 - CTRL-G switches to Visual mode.
426 Otherwise, typed characters are handled as in Visual mode.
428 When using an operator in Select mode, and the selection is linewise, the
429 selected lines are operated upon, but like in characterwise selection. For
430 example, when a whole line is deleted, it can later be pasted halfway a line.
433 Mappings and menus in Select mode. *Select-mode-mapping*
435 In Select mode the mappings and menus of Visual mode are used. Before it is
436 executed, Vim automatically switches to Visual mode, so that the same
437 behavior as in Visual mode is effective.
439 After the mapping or menu finishes, the selection is enabled again and Select
440 mode entered, unless the selected area was deleted, another buffer became
441 the current one or the window layout was changed.
443 *gV* *v_gV*
444 gV Avoid the automatic reselection of the Visual area
445 after a Select mode mapping or menu has finished.
446 Put this just before the end of the mapping or menu.
447 At least it should be after any operations on the
448 selection.
450 *gh*
451 gh Start Select mode, characterwise. This is like "v",
452 but starts Select mode instead of Visual mode.
453 Mnemonic: "get highlighted".
455 *gH*
456 gH Start Select mode, linewise. This is like "V",
457 but starts Select mode instead of Visual mode.
458 Mnemonic: "get Highlighted".
460 *g_CTRL-H*
461 g CTRL-H Start Select mode, blockwise. This is like CTRL-V,
462 but starts Select mode instead of Visual mode.
463 Mnemonic: "get Highlighted".
465 vim:tw=78:ts=8:sw=8: