diff options
Diffstat (limited to 'runtime/doc/visual.txt')
| -rw-r--r-- | runtime/doc/visual.txt | 559 |
1 files changed, 559 insertions, 0 deletions
diff --git a/runtime/doc/visual.txt b/runtime/doc/visual.txt new file mode 100644 index 0000000..540d5c5 --- /dev/null +++ b/runtime/doc/visual.txt @@ -0,0 +1,559 @@ +*visual.txt* For Vim version 9.0. Last change: 2022 Dec 04 + + + 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| + +{Since Vim 7.4.200 the |+visual| feature is always included} + +============================================================================== +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* +[count]v Start Visual mode per character. + With [count] select the same number of characters or + lines as used for the last Visual operation, but at + the current cursor position, multiplied by [count]. + When the previous Visual operation was on a block both + the width and height of the block are multiplied by + [count]. + When there was no previous Visual operation [count] + characters are selected. This is like moving the + cursor right N * [count] characters. One less when + 'selection' is not "exclusive". + + *V* *linewise-visual* +[count]V Start Visual mode linewise. + With [count] select the same number of lines as used + for the last Visual operation, but at the current + cursor position, multiplied by [count]. When there + was no previous Visual operation [count] lines are + selected. + + *CTRL-V* *blockwise-visual* +[count]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|. + [count] is used as with `v` above. + +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. + + *gn* *v_gn* +gn Search forward for the last used search pattern, like + with `n`, and start Visual mode to select the match. + If the cursor is on the match, visually selects it. + If an operator is pending, operates on the match. + E.g., "dgn" deletes the text of the next match. + If Visual mode is active, extends the selection + until the end of the next match. + 'wrapscan' applies. + Note: Unlike `n` the search direction does not depend + on the previous search command. + + *gN* *v_gN* +gN Like |gn| but searches backward, like with `N`. + + *<LeftMouse>* +<LeftMouse> Set the current cursor position. If Visual mode is + active it is stopped. Only when 'mouse' option + 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, whichever + 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'. + +<LeftMouseNM> Internal mouse code, used for clicking on the status +<LeftReleaseNM> line to focus a window. NM stands for non-mappable. + You cannot use these, but they might show up in some + places. + +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 parentheses) |v_ab| + ib inner () block |v_ib| + aB a {} block (with braces) |v_aB| + iB inner {} block |v_iB| + at a <tag> </tag> block (with tags) |v_at| + it inner <tag> </tag> block |v_it| + a< a <> block (with <>) |v_a<| + i< inner <> block |v_i<| + a[ a [] block (with []) |v_a[| + i[ inner [] block |v_i[| + a" a double quoted string (with quotes) |v_aquote| + i" inner double quoted string |v_iquote| + a' a single quoted string (with quotes) |v_a'| + i' inner simple quoted string |v_i'| + a` a string in backticks (with backticks) |v_a`| + i` inner string in backticks |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| + P put without overwriting registers |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(/#/g + +Note that the "'<,'>" will appear automatically when you press ":" in Visual +mode. + +============================================================================== +5. Blockwise operators *blockwise-operators* + +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. Works only for adding text to a line, not for +deletions. 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. +Works only for adding text to a line, not for deletions. + +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 up to which to shift left. +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. Any count passed +to the `.` command is not used. + + +============================================================================== +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. +- CTRL-R {register} selects the register to be used for the text that is + deleted when typing text. *v_CTRL-R* + Unless you specify the "_" (black hole) register, the unnamed register is + also overwritten. + + +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|. + +One particular edge case: > + :vnoremap <C-K> <Esc> +This ends Visual mode when in Visual mode, but in Select mode it does not +work, because Select mode is restored after executing the mapped keys. You +need to use: > + :snoremap <C-K> <Esc> +< +Users will expect printable characters to replace the selected area. +Therefore avoid mapping printable characters in Select mode. Or use +|:sunmap| after |:map| and |:vmap| to remove it for Select mode. + +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:noet:ft=help:norl: |