1*visual.txt* For Vim version 7.3. Last change: 2010 Feb 17 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{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 49not be highlighted. However, all uppercase and non-alpha operators, except 50"~" 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* 64v start Visual mode per character. 65 66 *V* *linewise-visual* 67V start Visual mode linewise. 68 69 *CTRL-V* *blockwise-visual* 70CTRL-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|. 73 74If you use <Esc>, click the left mouse button or use any command that 75does a jump to another buffer while in Visual mode, the highlighting stops 76and 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 78CTRL-Z the highlighting stops and the editor is suspended or a new shell is 79started |CTRL-Z|. 80 81 new mode after typing: *v_v* *v_CTRL-V* *v_V* 82old mode "v" "CTRL-V" "V" ~ 83 84Normal Visual blockwise Visual linewise Visual 85Visual Normal blockwise Visual linewise Visual 86blockwise Visual Visual Normal linewise Visual 87linewise Visual Visual blockwise Visual Normal 88 89 *gv* *v_gv* *reselect-Visual* 90gv 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. 96 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. 105 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'. 113 114 Note: when 'mousemodel' is set to "popup", 115 <S-LeftMouse> has to be used instead of <RightMouse>. 116 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'. 125 126If Visual mode is not active and the "v", "V" or CTRL-V is preceded with a 127count, the size of the previously highlighted area is used for a start. You 128can then move the end of the highlighted area and give an operator. The type 129of 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. 138The start of the text is the Cursor position. If the "$" command was used as 139one of the last commands to extend the highlighted text, the area will be 140extended to the rightmost column of the longest line. 141 142If you want to highlight exactly the same area as the last time, you can use 143"gv" |gv| |v_gv|. 144 145 *v_<Esc>* 146<Esc> In Visual mode: Stop Visual mode. 147 148 *v_CTRL-C* 149CTRL-C In Visual mode: Stop Visual mode. When insert mode is 150 pending (the mode message shows 151 "-- (insert) VISUAL --"), it is also stopped. 152 153============================================================================== 1543. Changing the Visual area *visual-change* 155 156 *v_o* 157o 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. 162 163 *v_O* 164O 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. 170 171 *v_$* 172When the "$" command is used with blockwise Visual mode, the right end of the 173highlighted text will be determined by the longest highlighted line. This 174stops when a motion command is used that does not move straight up or down. 175 176For moving the end of the block many commands can be used, but you cannot 177use Ex commands, commands that make changes or abandon the file. Commands 178(starting with) ".", "&", CTRL-^, "Z", CTRL-], CTRL-T, CTRL-R, CTRL-I 179and CTRL-O cause a beep and Visual mode continues. 180 181When switching to another window on the same buffer, the cursor position in 182that window is adjusted, so that the same Visual area is still selected. This 183is especially useful to view the start of the Visual area in one window, and 184the end in another. You can then use <RightMouse> (or <S-LeftMouse> when 185'mousemodel' is "popup") to drag either end of the Visual area. 186 187============================================================================== 1884. Operating on the Visual area *visual-operators* 189 190The 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| 200 201The 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`| 226 227Additionally 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| 245 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. 251 252Note that the ":vmap" command can be used to specifically map keys in Visual 253mode. For example, if you would like the "/" command not to extend the Visual 254area, 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 257need to remove the 'B' and '<' flags from 'cpoptions'.) 258 259If you want to give a register name using the """ command, do this just before 260typing the operator character: "v{move-around}"xd". 261 262If you want to give a count to the command, do this just before typing the 263operator character: "v{move-around}3>" (move lines 3 indents to the right). 264 265 *{move-around}* 266The {move-around} is any sequence of movement commands. Note the difference 267with {motion}, which is only ONE movement command. 268 269Another way to operate on the Visual area is using the |/\%V| item in a 270pattern. For example, to replace all '(' in the Visual area with '#': > 271 272 :%s/\%V(/X/g 273 274============================================================================== 2755. Blockwise operators *blockwise-operators* 276 277{not available when compiled without the |+visualextra| feature} 278 279Reminder: Use 'virtualedit' to be able to select blocks that start or end 280after the end of a line or halfway a tab. 281 282Visual-block Insert *v_b_I* 283With a blockwise selection, I{string}<ESC> will insert {string} at the start 284of block on every line of the block, provided that the line extends into the 285block. Thus lines that are short will remain unmodified. TABs are split to 286retain visual columns. 287See |v_b_I_example|. 288 289Visual-block Append *v_b_A* 290With a blockwise selection, A{string}<ESC> will append {string} to the end of 291block on every line of the block. There is some differing behavior where the 292block RHS is not straight, due to different line lengths: 293 2941. Block was created with <C-v>$ 295 In this case the string is appended to the end of each line. 2962. 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. 299See |v_b_A_example|. 300Note: "I" and "A" behave differently for lines that don't extend into the 301selected block. This was done intentionally, so that you can do it the way 302you want. 303 304Visual-block change *v_b_c* 305All selected text in the block will be replaced by the same text string. When 306using "c" the selected text is deleted and Insert mode started. You can then 307enter text (without a line break). When you hit <Esc>, the same string is 308inserted in all previously selected lines. 309 310Visual-block Change *v_b_C* 311Like using "c", but the selection is extended until the end of the line for 312all lines. 313 314 *v_b_<* 315Visual-block Shift *v_b_>* 316The block is shifted by 'shiftwidth'. The RHS of the block is irrelevant. The 317LHS of the block determines the point from which to apply a right shift, and 318padding includes TABs optimally according to 'ts' and 'et'. The LHS of the 319block determines the point upto which to shift left. 320See |v_b_>_example|. 321See |v_b_<_example|. 322 323Visual-block Replace *v_b_r* 324Every screen char in the highlighted region is replaced with the same char, ie 325TABs are split and the virtual whitespace is replaced, maintaining screen 326layout. 327See |v_b_r_example|. 328 329 330============================================================================== 3316. Repeating *visual-repeat* 332 333When repeating a Visual mode operator, the operator will be applied to the 334same 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. 340The start of the text is the Cursor position. If the "$" command was used as 341one of the last commands to extend the highlighted text, the repeating will 342be applied up to the rightmost column of the longest line. 343 344 345============================================================================== 3467. Examples *visual-examples* 347 348 *:visual_example* 349Currently the ":" command works on whole lines only. When you select part of 350a line, doing something like ":!date" will replace the whole line. If you 351want only part of the line to be replaced you will have to make a mapping for 352it. In a future release ":" may work on partial lines. 353 354Here 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 356 357(In the <> notation |<>|, when typing it you should type it literally; you 358need to remove the 'B' and '<' flags from 'cpoptions') 359 360What this does is: 361<Esc> stop Visual mode 362`> go to the end of the Visual area 363a<CR><Esc> break the line after the Visual area 364`< jump to the start of the Visual area 365i<CR><Esc> break the line before the Visual area 366!!date<CR> filter the Visual text through date 367kJJ Join the lines back together 368 369 *visual-search* 370Here is an idea for a mapping that makes it possible to do a search for the 371selected text: > 372 :vmap X y/<C-R>"<CR> 373 374(In the <> notation |<>|, when typing it you should type it literally; you 375need to remove the 'B' and '<' flags from 'cpoptions') 376 377Note that special characters (like '.' and '*') will cause problems. 378 379Visual-block Examples *blockwise-examples* 380With the following text, I will indicate the commands to produce the block and 381the results below. In all cases, the cursor begins on the 'a' in the first 382line of the test text. 383The following modeline settings are assumed ":ts=8:sw=4:". 384 385It will be helpful to 386:set hls 387/<TAB> 388where <TAB> is a real TAB. This helps visualise the operations. 389 390The test text is: 391 392abcdefghijklmnopqrstuvwxyz 393abc defghijklmnopqrstuvwxyz 394abcdef ghi jklmnopqrstuvwxyz 395abcdefghijklmnopqrstuvwxyz 396 3971. fo<C-v>3jISTRING<ESC> *v_b_I_example* 398 399abcdefghijklmnSTRINGopqrstuvwxyz 400abc STRING defghijklmnopqrstuvwxyz 401abcdef ghi STRING jklmnopqrstuvwxyz 402abcdefghijklmnSTRINGopqrstuvwxyz 403 4042. fo<C-v>3j$ASTRING<ESC> *v_b_A_example* 405 406abcdefghijklmnopqrstuvwxyzSTRING 407abc defghijklmnopqrstuvwxyzSTRING 408abcdef ghi jklmnopqrstuvwxyzSTRING 409abcdefghijklmnopqrstuvwxyzSTRING 410 4113. fo<C-v>3j3l<.. *v_b_<_example* 412 413abcdefghijklmnopqrstuvwxyz 414abc defghijklmnopqrstuvwxyz 415abcdef ghi jklmnopqrstuvwxyz 416abcdefghijklmnopqrstuvwxyz 417 4184. fo<C-v>3j>.. *v_b_>_example* 419 420abcdefghijklmn opqrstuvwxyz 421abc defghijklmnopqrstuvwxyz 422abcdef ghi jklmnopqrstuvwxyz 423abcdefghijklmn opqrstuvwxyz 424 4255. fo<C-v>5l3jrX *v_b_r_example* 426 427abcdefghijklmnXXXXXXuvwxyz 428abc XXXXXXhijklmnopqrstuvwxyz 429abcdef ghi XXXXXX jklmnopqrstuvwxyz 430abcdefghijklmnXXXXXXuvwxyz 431 432============================================================================== 4338. Select mode *Select* *Select-mode* 434 435Select mode looks like Visual mode, but the commands accepted are quite 436different. This resembles the selection mode in Microsoft Windows. 437When the 'showmode' option is set, "-- SELECT --" is shown in the last line. 438 439Entering 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* 448 449Commands 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. 459 460Otherwise, typed characters are handled as in Visual mode. 461 462When using an operator in Select mode, and the selection is linewise, the 463selected lines are operated upon, but like in characterwise selection. For 464example, when a whole line is deleted, it can later be pasted halfway a line. 465 466 467Mappings and menus in Select mode. *Select-mode-mapping* 468 469When mappings and menus are defined with the |:vmap| or |:vmenu| command they 470work both in Visual mode and in Select mode. When these are used in Select 471mode Vim automatically switches to Visual mode, so that the same behavior as 472in Visual mode is effective. If you don't want this use |:xmap| or |:smap|. 473 474Users will expect printable characters to replace the selected area. 475Therefore avoid mapping printable characters in Select mode. Or use 476|:sunmap| after |:map| and |:vmap| to remove it for Select mode. 477 478After the mapping or menu finishes, the selection is enabled again and Select 479mode entered, unless the selected area was deleted, another buffer became 480the current one or the window layout was changed. 481 482When a character was typed that causes the selection to be deleted and Insert 483mode started, Insert mode mappings are applied to this character. This may 484cause some confusion, because it means Insert mode mappings apply to a 485character typed in Select mode. Language mappings apply as well. 486 487 *gV* *v_gV* 488gV 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. 493 494 *gh* 495gh Start Select mode, characterwise. This is like "v", 496 but starts Select mode instead of Visual mode. 497 Mnemonic: "get highlighted". 498 499 *gH* 500gH Start Select mode, linewise. This is like "V", 501 but starts Select mode instead of Visual mode. 502 Mnemonic: "get Highlighted". 503 504 *g_CTRL-H* 505g CTRL-H Start Select mode, blockwise. This is like CTRL-V, 506 but starts Select mode instead of Visual mode. 507 Mnemonic: "get Highlighted". 508 509 vim:tw=78:ts=8:ft=help:norl: 510