| *visual.txt* For Vim version 7.1. Last change: 2006 Sep 26 |
| |
| |
| VIM REFERENCE MANUAL by Bram Moolenaar |
| |
| |
| Visual mode *Visual* *Visual-mode* *visual-mode* |
| |
| Visual mode is a flexible and easy way to select a piece of text for an |
| operator. It is the only way to select a block of text. |
| |
| This is introduced in section |04.4| of the user manual. |
| |
| 1. Using Visual mode |visual-use| |
| 2. Starting and stopping Visual mode |visual-start| |
| 3. Changing the Visual area |visual-change| |
| 4. Operating on the Visual area |visual-operators| |
| 5. Blockwise operators |blockwise-operators| |
| 6. Repeating |visual-repeat| |
| 7. Examples |visual-examples| |
| 8. Select mode |Select-mode| |
| |
| {Vi has no Visual mode, the name "visual" is used for Normal mode, to |
| distinguish it from Ex mode} |
| {not available when the |+visual| feature was disabled when compiling} |
| |
| ============================================================================== |
| 1. Using Visual mode *visual-use* |
| |
| Using Visual mode consists of three parts: |
| 1. Mark the start of the text with "v", "V" or CTRL-V. |
| The character under the cursor will be used as the start. |
| 2. Move to the end of the text. |
| The text from the start of the Visual mode up to and including the |
| character under the cursor is highlighted. |
| 3. Type an operator command. |
| The highlighted characters will be operated upon. |
| |
| The 'highlight' option can be used to set the display mode to use for |
| highlighting in Visual mode. |
| The 'virtualedit' option can be used to allow positioning the cursor to |
| positions where there is no actual character. |
| |
| The highlighted text normally includes the character under the cursor. |
| However, when the 'selection' option is set to "exclusive" and the cursor is |
| after the Visual area, the character under the cursor is not included. |
| |
| With "v" the text before the start position and after the end position will |
| not be highlighted. However, all uppercase and non-alpha operators, except |
| "~" and "U", will work on whole lines anyway. See the list of operators |
| below. |
| |
| *visual-block* |
| With CTRL-V (blockwise Visual mode) the highlighted text will be a rectangle |
| between start position and the cursor. However, some operators work on whole |
| lines anyway (see the list below). The change and substitute operators will |
| delete the highlighted text and then start insertion at the top left |
| position. |
| |
| ============================================================================== |
| 2. Starting and stopping Visual mode *visual-start* |
| |
| *v* *characterwise-visual* |
| v start Visual mode per character. |
| |
| *V* *linewise-visual* |
| V start Visual mode linewise. |
| |
| *CTRL-V* *blockwise-visual* |
| CTRL-V start Visual mode blockwise. Note: Under Windows |
| CTRL-V could be mapped to paste text, it doesn't work |
| to start Visual mode then, see |CTRL-V-alternative|. |
| |
| If you use <Esc>, click the left mouse button or use any command that |
| does a jump to another buffer while in Visual mode, the highlighting stops |
| and no text is affected. Also when you hit "v" in characterwise Visual mode, |
| "CTRL-V" in blockwise Visual mode or "V" in linewise Visual mode. If you hit |
| CTRL-Z the highlighting stops and the editor is suspended or a new shell is |
| started |CTRL-Z|. |
| |
| new mode after typing: *v_v* *v_CTRL-V* *v_V* |
| old mode "v" "CTRL-V" "V" ~ |
| |
| Normal Visual blockwise Visual linewise Visual |
| Visual Normal blockwise Visual linewise Visual |
| blockwise Visual Visual Normal linewise Visual |
| linewise Visual Visual blockwise Visual Normal |
| |
| *gv* *v_gv* *reselect-Visual* |
| gv Start Visual mode with the same area as the previous |
| area and the same mode. |
| In Visual mode the current and the previous Visual |
| area are exchanged. |
| After using "p" or "P" in Visual mode the text that |
| was put will be selected. |
| |
| *<LeftMouse>* |
| <LeftMouse> Set the current cursor position. If Visual mode is |
| active it is stopped. Only when 'mouse' option is |
| contains 'n' or 'a'. If the position is within 'so' |
| lines from the last line on the screen the text is |
| scrolled up. If the position is within 'so' lines from |
| the first line on the screen the text is scrolled |
| down. |
| |
| *<RightMouse>* |
| <RightMouse> Start Visual mode if it is not active. The text from |
| the cursor position to the position of the click is |
| highlighted. If Visual mode was already active move |
| the start or end of the highlighted text, which ever |
| is closest, to the position of the click. Only when |
| 'mouse' option contains 'n' or 'a'. |
| |
| Note: when 'mousemodel' is set to "popup", |
| <S-LeftMouse> has to be used instead of <RightMouse>. |
| |
| *<LeftRelease>* |
| <LeftRelease> This works like a <LeftMouse>, if it is not at |
| the same position as <LeftMouse>. In an older version |
| of xterm you won't see the selected area until the |
| button is released, unless there is access to the |
| display where the xterm is running (via the DISPLAY |
| environment variable or the -display argument). Only |
| when 'mouse' option contains 'n' or 'a'. |
| |
| If Visual mode is not active and the "v", "V" or CTRL-V is preceded with a |
| count, the size of the previously highlighted area is used for a start. You |
| can then move the end of the highlighted area and give an operator. The type |
| of the old area is used (character, line or blockwise). |
| - Linewise Visual mode: The number of lines is multiplied with the count. |
| - Blockwise Visual mode: The number of lines and columns is multiplied with |
| the count. |
| - Normal Visual mode within one line: The number of characters is multiplied |
| with the count. |
| - Normal Visual mode with several lines: The number of lines is multiplied |
| with the count, in the last line the same number of characters is used as |
| in the last line in the previously highlighted area. |
| The start of the text is the Cursor position. If the "$" command was used as |
| one of the last commands to extend the highlighted text, the area will be |
| extended to the rightmost column of the longest line. |
| |
| If you want to highlight exactly the same area as the last time, you can use |
| "gv" |gv| |v_gv|. |
| |
| *v_<Esc>* |
| <Esc> In Visual mode: Stop Visual mode. |
| |
| *v_CTRL-C* |
| CTRL-C In Visual mode: Stop Visual mode. When insert mode is |
| pending (the mode message shows |
| "-- (insert) VISUAL --"), it is also stopped. |
| |
| ============================================================================== |
| 3. Changing the Visual area *visual-change* |
| |
| *v_o* |
| o Go to Other end of highlighted text: The current |
| cursor position becomes the start of the highlighted |
| text and the cursor is moved to the other end of the |
| highlighted text. The highlighted area remains the |
| same. |
| |
| *v_O* |
| O Go to Other end of highlighted text. This is like |
| "o", but in Visual block mode the cursor moves to the |
| other corner in the same line. When the corner is at |
| a character that occupies more than one position on |
| the screen (e.g., a <Tab>), the highlighted text may |
| change. |
| |
| *v_$* |
| When the "$" command is used with blockwise Visual mode, the right end of the |
| highlighted text will be determined by the longest highlighted line. This |
| stops when a motion command is used that does not move straight up or down. |
| |
| For moving the end of the block many commands can be used, but you cannot |
| use Ex commands, commands that make changes or abandon the file. Commands |
| (starting with) ".", "&", CTRL-^, "Z", CTRL-], CTRL-T, CTRL-R, CTRL-I |
| and CTRL-O cause a beep and Visual mode continues. |
| |
| When switching to another window on the same buffer, the cursor position in |
| that window is adjusted, so that the same Visual area is still selected. This |
| is especially useful to view the start of the Visual area in one window, and |
| the end in another. You can then use <RightMouse> (or <S-LeftMouse> when |
| 'mousemodel' is "popup") to drag either end of the Visual area. |
| |
| ============================================================================== |
| 4. Operating on the Visual area *visual-operators* |
| |
| The operators that can be used are: |
| ~ switch case |v_~| |
| d delete |v_d| |
| c change (4) |v_c| |
| y yank |v_y| |
| > shift right (4) |v_>| |
| < shift left (4) |v_<| |
| ! filter through external command (1) |v_!| |
| = filter through 'equalprg' option command (1) |v_=| |
| gq format lines to 'textwidth' length (1) |v_gq| |
| |
| The objects that can be used are: |
| aw a word (with white space) |v_aw| |
| iw inner word |v_iw| |
| aW a WORD (with white space) |v_aW| |
| iW inner WORD |v_iW| |
| as a sentence (with white space) |v_as| |
| is inner sentence |v_is| |
| ap a paragraph (with white space) |v_ap| |
| ip inner paragraph |v_ip| |
| ab a () block (with parenthesis) |v_ab| |
| ib inner () block |v_ib| |
| aB a {} block (with braces) |v_aB| |
| iB inner {} block |v_iB| |
| a< a <> block (with <>) |v_a<| |
| i< inner <> block |v_i<| |
| a[ a [] block (with []) |v_a[| |
| i[ inner [] block |v_i[| |
| |
| Additionally the following commands can be used: |
| : start ex command for highlighted lines (1) |v_:| |
| r change (4) |v_r| |
| s change |v_s| |
| C change (2)(4) |v_C| |
| S change (2) |v_S| |
| R change (2) |v_R| |
| x delete |v_x| |
| D delete (3) |v_D| |
| X delete (2) |v_X| |
| Y yank (2) |v_Y| |
| p put |v_p| |
| J join (1) |v_J| |
| U make uppercase |v_U| |
| u make lowercase |v_u| |
| ^] find tag |v_CTRL-]| |
| I block insert |v_b_I| |
| A block append |v_b_A| |
| |
| (1): Always whole lines, see |:visual_example|. |
| (2): Whole lines when not using CTRL-V. |
| (3): Whole lines when not using CTRL-V, delete until the end of the line when |
| using CTRL-V. |
| (4): When using CTRL-V operates on the block only. |
| |
| Note that the ":vmap" command can be used to specifically map keys in Visual |
| mode. For example, if you would like the "/" command not to extend the Visual |
| area, but instead take the highlighted text and search for that: > |
| :vmap / y/<C-R>"<CR> |
| (In the <> notation |<>|, when typing it you should type it literally; you |
| need to remove the 'B' and '<' flags from 'cpoptions'.) |
| |
| If you want to give a register name using the """ command, do this just before |
| typing the operator character: "v{move-around}"xd". |
| |
| If you want to give a count to the command, do this just before typing the |
| operator character: "v{move-around}3>" (move lines 3 indents to the right). |
| |
| *{move-around}* |
| The {move-around} is any sequence of movement commands. Note the difference |
| with {motion}, which is only ONE movement command. |
| |
| Another way to operate on the Visual area is using the |/\%V| item in a |
| pattern. For example, to replace all '(' in the Visual area with '#': > |
| |
| :%s/\%V(/X/g |
| |
| ============================================================================== |
| 5. Blockwise operators *blockwise-operators* |
| |
| {not available when compiled without the |+visualextra| feature} |
| |
| Reminder: Use 'virtualedit' to be able to select blocks that start or end |
| after the end of a line or halfway a tab. |
| |
| Visual-block Insert *v_b_I* |
| With a blockwise selection, I{string}<ESC> will insert {string} at the start |
| of block on every line of the block, provided that the line extends into the |
| block. Thus lines that are short will remain unmodified. TABs are split to |
| retain visual columns. |
| See |v_b_I_example|. |
| |
| Visual-block Append *v_b_A* |
| With a blockwise selection, A{string}<ESC> will append {string} to the end of |
| block on every line of the block. There is some differing behavior where the |
| block RHS is not straight, due to different line lengths: |
| |
| 1. Block was created with <C-v>$ |
| In this case the string is appended to the end of each line. |
| 2. Block was created with <C-v>{move-around} |
| In this case the string is appended to the end of the block on each line, |
| and whitespace is inserted to pad to the end-of-block column. |
| See |v_b_A_example|. |
| Note: "I" and "A" behave differently for lines that don't extend into the |
| selected block. This was done intentionally, so that you can do it the way |
| you want. |
| |
| Visual-block change *v_b_c* |
| All selected text in the block will be replaced by the same text string. When |
| using "c" the selected text is deleted and Insert mode started. You can then |
| enter text (without a line break). When you hit <Esc>, the same string is |
| inserted in all previously selected lines. |
| |
| Visual-block Change *v_b_C* |
| Like using "c", but the selection is extended until the end of the line for |
| all lines. |
| |
| *v_b_<* |
| Visual-block Shift *v_b_>* |
| The block is shifted by 'shiftwidth'. The RHS of the block is irrelevant. The |
| LHS of the block determines the point from which to apply a right shift, and |
| padding includes TABs optimally according to 'ts' and 'et'. The LHS of the |
| block determines the point upto which to shift left. |
| Note: v_< padding is buggy if the Visual Block starts and ends in the same |
| TAB. (Vim 5.4c) |
| See |v_b_>_example|. |
| See |v_b_<_example|. |
| |
| Visual-block Replace *v_b_r* |
| Every screen char in the highlighted region is replaced with the same char, ie |
| TABs are split and the virtual whitespace is replaced, maintaining screen |
| layout. |
| See |v_b_r_example|. |
| |
| |
| ============================================================================== |
| 6. Repeating *visual-repeat* |
| |
| When repeating a Visual mode operator, the operator will be applied to the |
| same amount of text as the last time: |
| - Linewise Visual mode: The same number of lines. |
| - Blockwise Visual mode: The same number of lines and columns. |
| - Normal Visual mode within one line: The same number of characters. |
| - Normal Visual mode with several lines: The same number of lines, in the |
| last line the same number of characters as in the last line the last time. |
| The start of the text is the Cursor position. If the "$" command was used as |
| one of the last commands to extend the highlighted text, the repeating will |
| be applied up to the rightmost column of the longest line. |
| |
| |
| ============================================================================== |
| 7. Examples *visual-examples* |
| |
| *:visual_example* |
| Currently the ":" command works on whole lines only. When you select part of |
| a line, doing something like ":!date" will replace the whole line. If you |
| want only part of the line to be replaced you will have to make a mapping for |
| it. In a future release ":" may work on partial lines. |
| |
| Here is an example, to replace the selected text with the output of "date": > |
| :vmap _a <Esc>`>a<CR><Esc>`<i<CR><Esc>!!date<CR>kJJ |
| |
| (In the <> notation |<>|, when typing it you should type it literally; you |
| need to remove the 'B' and '<' flags from 'cpoptions') |
| |
| What this does is: |
| <Esc> stop Visual mode |
| `> go to the end of the Visual area |
| a<CR><Esc> break the line after the Visual area |
| `< jump to the start of the Visual area |
| i<CR><Esc> break the line before the Visual area |
| !!date<CR> filter the Visual text through date |
| kJJ Join the lines back together |
| |
| *visual-search* |
| Here is an idea for a mapping that makes it possible to do a search for the |
| selected text: > |
| :vmap X y/<C-R>"<CR> |
| |
| (In the <> notation |<>|, when typing it you should type it literally; you |
| need to remove the 'B' and '<' flags from 'cpoptions') |
| |
| Note that special characters (like '.' and '*') will cause problems. |
| |
| Visual-block Examples *blockwise-examples* |
| With the following text, I will indicate the commands to produce the block and |
| the results below. In all cases, the cursor begins on the 'a' in the first |
| line of the test text. |
| The following modeline settings are assumed ":ts=8:sw=4:". |
| |
| It will be helpful to |
| :set hls |
| /<TAB> |
| where <TAB> is a real TAB. This helps visualise the operations. |
| |
| The test text is: |
| |
| abcdefghijklmnopqrstuvwxyz |
| abc defghijklmnopqrstuvwxyz |
| abcdef ghi jklmnopqrstuvwxyz |
| abcdefghijklmnopqrstuvwxyz |
| |
| 1. fo<C-v>3jISTRING<ESC> *v_b_I_example* |
| |
| abcdefghijklmnSTRINGopqrstuvwxyz |
| abc STRING defghijklmnopqrstuvwxyz |
| abcdef ghi STRING jklmnopqrstuvwxyz |
| abcdefghijklmnSTRINGopqrstuvwxyz |
| |
| 2. fo<C-v>3j$ASTRING<ESC> *v_b_A_example* |
| |
| abcdefghijklmnopqrstuvwxyzSTRING |
| abc defghijklmnopqrstuvwxyzSTRING |
| abcdef ghi jklmnopqrstuvwxyzSTRING |
| abcdefghijklmnopqrstuvwxyzSTRING |
| |
| 3. fo<C-v>3j3l<.. *v_b_<_example* |
| |
| abcdefghijklmnopqrstuvwxyz |
| abc defghijklmnopqrstuvwxyz |
| abcdef ghi jklmnopqrstuvwxyz |
| abcdefghijklmnopqrstuvwxyz |
| |
| 4. fo<C-v>3j>.. *v_b_>_example* |
| |
| abcdefghijklmn opqrstuvwxyz |
| abc defghijklmnopqrstuvwxyz |
| abcdef ghi jklmnopqrstuvwxyz |
| abcdefghijklmn opqrstuvwxyz |
| |
| 5. fo<C-v>5l3jrX *v_b_r_example* |
| |
| abcdefghijklmnXXXXXXuvwxyz |
| abc XXXXXXhijklmnopqrstuvwxyz |
| abcdef ghi XXXXXX jklmnopqrstuvwxyz |
| abcdefghijklmnXXXXXXuvwxyz |
| |
| ============================================================================== |
| 8. Select mode *Select* *Select-mode* |
| |
| Select mode looks like Visual mode, but the commands accepted are quite |
| different. This resembles the selection mode in Microsoft Windows. |
| When the 'showmode' option is set, "-- SELECT --" is shown in the last line. |
| |
| Entering Select mode: |
| - Using the mouse to select an area, and 'selectmode' contains "mouse". |
| 'mouse' must also contain a flag for the current mode. |
| - Using a non-printable movement command, with the Shift key pressed, and |
| 'selectmode' contains "key". For example: <S-Left> and <S-End>. 'keymodel' |
| must also contain "startsel". |
| - Using "v", "V" or CTRL-V command, and 'selectmode' contains "cmd". |
| - Using "gh", "gH" or "g_CTRL-H" command in Normal mode. |
| - From Visual mode, press CTRL-G. *v_CTRL-G* |
| |
| Commands in Select mode: |
| - Printable characters, <NL> and <CR> cause the selection to be deleted, and |
| Vim enters Insert mode. The typed character is inserted. |
| - Non-printable movement commands, with the Shift key pressed, extend the |
| selection. 'keymodel' must include "startsel". |
| - Non-printable movement commands, with the Shift key NOT pressed, stop Select |
| mode. 'keymodel' must include "stopsel". |
| - ESC stops Select mode. |
| - CTRL-O switches to Visual mode for the duration of one command. *v_CTRL-O* |
| - CTRL-G switches to Visual mode. |
| |
| Otherwise, typed characters are handled as in Visual mode. |
| |
| When using an operator in Select mode, and the selection is linewise, the |
| selected lines are operated upon, but like in characterwise selection. For |
| example, when a whole line is deleted, it can later be pasted halfway a line. |
| |
| |
| Mappings and menus in Select mode. *Select-mode-mapping* |
| |
| When mappings and menus are defined with the |:vmap| or |:vmenu| command they |
| work both in Visual mode and in Select mode. When these are used in Select |
| mode Vim automatically switches to Visual mode, so that the same behavior as |
| in Visual mode is effective. If you don't want this use |:xmap| or |:smap|. |
| |
| After the mapping or menu finishes, the selection is enabled again and Select |
| mode entered, unless the selected area was deleted, another buffer became |
| the current one or the window layout was changed. |
| |
| When a character was typed that causes the selection to be deleted and Insert |
| mode started, Insert mode mappings are applied to this character. This may |
| cause some confusion, because it means Insert mode mappings apply to a |
| character typed in Select mode. Language mappings apply as well. |
| |
| *gV* *v_gV* |
| gV Avoid the automatic reselection of the Visual area |
| after a Select mode mapping or menu has finished. |
| Put this just before the end of the mapping or menu. |
| At least it should be after any operations on the |
| selection. |
| |
| *gh* |
| gh Start Select mode, characterwise. This is like "v", |
| but starts Select mode instead of Visual mode. |
| Mnemonic: "get highlighted". |
| |
| *gH* |
| gH Start Select mode, linewise. This is like "V", |
| but starts Select mode instead of Visual mode. |
| Mnemonic: "get Highlighted". |
| |
| *g_CTRL-H* |
| g CTRL-H Start Select mode, blockwise. This is like CTRL-V, |
| but starts Select mode instead of Visual mode. |
| Mnemonic: "get Highlighted". |
| |
| vim:tw=78:ts=8:ft=help:norl: |