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