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