Quick links: help overview · MacVim reference · quick reference · commands index · user manual · reference manual
visual.txt    For Vim version 9.1.  Last change: 2023 Sep 19


		  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.
			On MS-Windows, you may need to press CTRL-Break
			dos-CTRL-Break.

==============================================================================
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:


Quick links: help overview · MacVim reference · quick reference · commands index · user manual · reference manual