summaryrefslogtreecommitdiffstats
path: root/runtime/doc/visual.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/visual.txt')
-rw-r--r--runtime/doc/visual.txt559
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: