codekingpro/portable-devtools

1*visual.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		  VIM REFERENCE MANUAL	  by Bram Moolenaar5 6 7Visual mode				*Visual* *Visual-mode* *visual-mode*8 9Visual mode is a flexible and easy way to select a piece of text for an10operator.  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{Since Vim 7.4.200 the |+visual| feature is always included}24 25==============================================================================261. Using Visual mode					*visual-use*27 28Using Visual mode consists of three parts:291. Mark the start of the text with "v", "V" or CTRL-V.30   The character under the cursor will be used as the start.312. Move to the end of the text.32   The text from the start of the Visual mode up to and including the33   character under the cursor is highlighted.343. Type an operator command.35   The highlighted characters will be operated upon.36 37The 'highlight' option can be used to set the display mode to use for38highlighting in Visual mode.39The 'virtualedit' option can be used to allow positioning the cursor to40positions where there is no actual character.41 42The highlighted text normally includes the character under the cursor.43However, when the 'selection' option is set to "exclusive" and the cursor is44after the Visual area, the character under the cursor is not included.45 46With "v" the text before the start position and after the end position will47not be highlighted.  However, all uppercase and non-alpha operators, except48"~" and "U", will work on whole lines anyway.  See the list of operators49below.50 51							*visual-block*52With CTRL-V (blockwise Visual mode) the highlighted text will be a rectangle53between start position and the cursor.  However, some operators work on whole54lines anyway (see the list below).  The change and substitute operators will55delete the highlighted text and then start insertion at the top left56position.57 58==============================================================================592. Starting and stopping Visual mode			*visual-start*60 61						*v* *characterwise-visual*62[count]v		Start Visual mode per character.63			With [count] select the same number of characters or64			lines as used for the last Visual operation, but at65			the current cursor position, multiplied by [count].66			When the previous Visual operation was on a block both67			the width and height of the block are multiplied by68			[count].69			When there was no previous Visual operation [count]70			characters are selected.  This is like moving the71			cursor right N * [count] characters.  One less when72			'selection' is not "exclusive".73 74						*V* *linewise-visual*75[count]V		Start Visual mode linewise.76			With [count] select the same number of lines as used77			for the last Visual operation, but at the current78			cursor position, multiplied by [count].  When there79			was no previous Visual operation [count] lines are80			selected.81 82						*CTRL-V* *blockwise-visual*83[count]CTRL-V		Start Visual mode blockwise.  Note: Under Windows84			CTRL-V could be mapped to paste text, it doesn't work85			to start Visual mode then, see |CTRL-V-alternative|.86			[count] is used as with `v` above.87 88If you use <Esc>, click the left mouse button or use any command that89does a jump to another buffer while in Visual mode, the highlighting stops90and no text is affected.  Also when you hit "v" in characterwise Visual mode,91"CTRL-V" in blockwise Visual mode or "V" in linewise Visual mode.  If you hit92CTRL-Z the highlighting stops and the editor is suspended or a new shell is93started |CTRL-Z|.94 95	      new mode after typing:		*v_v* *v_CTRL-V* *v_V*96old mode	     "v"	      "CTRL-V"		     "V"	~97 98Normal		    Visual	   blockwise Visual	  linewise Visual99Visual		    Normal	   blockwise Visual	  linewise Visual100blockwise Visual    Visual	   Normal		  linewise Visual101linewise Visual     Visual	   blockwise Visual	  Normal102 103						*gv* *v_gv* *reselect-Visual*104gv			Start Visual mode with the same area as the previous105			area and the same mode.106			In Visual mode the current and the previous Visual107			area are exchanged.108			After using "p" or "P" in Visual mode the text that109			was put will be selected.110 111								*gn* *v_gn*112gn			Search forward for the last used search pattern, like113			with `n`, and start Visual mode to select the match.114			If the cursor is on the match, visually selects it.115			If an operator is pending, operates on the match.116			E.g., "dgn" deletes the text of the next match.117			If Visual mode is active, extends the selection118			until the end of the next match.119			'wrapscan' applies.120			Note: Unlike `n` the search direction does not depend121			on the previous search command.122 123								*gN* *v_gN*124gN			Like |gn| but searches backward, like with `N`.125 126							*<LeftMouse>*127<LeftMouse>		Set the current cursor position.  If Visual mode is128			active it is stopped.  Only when 'mouse' option129			contains 'n' or 'a'.  If the position is within 'so'130			lines from the last line on the screen the text is131			scrolled up.  If the position is within 'so' lines132			from the first line on the screen the text is scrolled133			down.134 135							*<RightMouse>*136<RightMouse>		Start Visual mode if it is not active.  The text from137			the cursor position to the position of the click is138			highlighted.  If Visual mode was already active move139			the start or end of the highlighted text, whichever140			is closest, to the position of the click.  Only when141			'mouse' option contains 'n' or 'a'.142 143			Note: when 'mousemodel' is set to "popup",144			<S-LeftMouse> has to be used instead of <RightMouse>.145 146							*<LeftRelease>*147<LeftRelease>		This works like a <LeftMouse>, if it is not at148			the same position as <LeftMouse>.  In an older version149			of xterm you won't see the selected area until the150			button is released, unless there is access to the151			display where the xterm is running (via the DISPLAY152			environment variable or the -display argument).  Only153			when 'mouse' option contains 'n' or 'a'.154 155<LeftMouseNM>		Internal mouse code, used for clicking on the status156<LeftReleaseNM>		line to focus a window.  NM stands for non-mappable.157			You cannot use these, but they might show up in some158			places.159 160If Visual mode is not active and the "v", "V" or CTRL-V is preceded with a161count, the size of the previously highlighted area is used for a start.  You162can then move the end of the highlighted area and give an operator.  The type163of the old area is used (character, line or blockwise).164- Linewise Visual mode: The number of lines is multiplied with the count.165- Blockwise Visual mode: The number of lines and columns is multiplied with166  the count.167- Normal Visual mode within one line: The number of characters is multiplied168  with the count.169- Normal Visual mode with several lines: The number of lines is multiplied170  with the count, in the last line the same number of characters is used as171  in the last line in the previously highlighted area.172The start of the text is the Cursor position.  If the "$" command was used as173one of the last commands to extend the highlighted text, the area will be174extended to the rightmost column of the longest line.175 176If you want to highlight exactly the same area as the last time, you can use177"gv" |gv| |v_gv|.178 179							*v_<Esc>*180<Esc>			In Visual mode: Stop Visual mode.181 182							*v_CTRL-C*183CTRL-C			In Visual mode: Stop Visual mode.  When insert mode is184			pending (the mode message shows185			"-- (insert) VISUAL --"), it is also stopped.186			On MS-Windows, you may need to press CTRL-Break187			|dos-CTRL-Break|.188 189==============================================================================1903. Changing the Visual area				*visual-change*191 192							*v_o*193o			Go to Other end of highlighted text: The current194			cursor position becomes the start of the highlighted195			text and the cursor is moved to the other end of the196			highlighted text.  The highlighted area remains the197			same.198 199							*v_O*200O			Go to Other end of highlighted text.  This is like201			"o", but in Visual block mode the cursor moves to the202			other corner in the same line.  When the corner is at203			a character that occupies more than one position on204			the screen (e.g., a <Tab>), the highlighted text may205			change.206 207							*v_$*208When the "$" command is used with blockwise Visual mode, the right end of the209highlighted text will be determined by the longest highlighted line.  This210stops when a motion command is used that does not move straight up or down.211 212For moving the end of the block many commands can be used, but you cannot213use Ex commands, commands that make changes or abandon the file.  Commands214(starting with) ".", "&", CTRL-^, "Z", CTRL-], CTRL-T, CTRL-R, CTRL-I215and CTRL-O cause a beep and Visual mode continues.216 217When switching to another window on the same buffer, the cursor position in218that window is adjusted, so that the same Visual area is still selected.  This219is especially useful to view the start of the Visual area in one window, and220the end in another.  You can then use <RightMouse> (or <S-LeftMouse> when221'mousemodel' is "popup") to drag either end of the Visual area.222 223==============================================================================2244. Operating on the Visual area				*visual-operators*225 226The operators that can be used are:227	~	switch case					|v_~|228	d	delete						|v_d|229	c	change (4)					|v_c|230	y	yank						|v_y|231	>	shift right (4)					|v_>|232	<	shift left (4)					|v_<|233	!	filter through external command (1)		|v_!|234	=	filter through 'equalprg' option command (1)	|v_=|235	gq	format lines to 'textwidth' length (1)		|v_gq|236 237The objects that can be used are:238	aw	a word (with white space)			|v_aw|239	iw	inner word					|v_iw|240	aW	a WORD (with white space)			|v_aW|241	iW	inner WORD					|v_iW|242	as	a sentence (with white space)			|v_as|243	is	inner sentence					|v_is|244	ap	a paragraph (with white space)			|v_ap|245	ip	inner paragraph					|v_ip|246	ab	a () block (with parentheses)			|v_ab|247	ib	inner () block					|v_ib|248	aB	a {} block (with braces)			|v_aB|249	iB	inner {} block					|v_iB|250	at	a <tag> </tag> block (with tags)		|v_at|251	it	inner <tag> </tag> block			|v_it|252	a<	a <> block (with <>)				|v_a<|253	i<	inner <> block					|v_i<|254	a[	a [] block (with [])				|v_a[|255	i[	inner [] block					|v_i[|256	a"	a double quoted string (with quotes)		|v_aquote|257	i"	inner double quoted string			|v_iquote|258	a'	a single quoted string (with quotes)		|v_a'|259	i'	inner simple quoted string			|v_i'|260	a`	a string in backticks (with backticks)		|v_a`|261	i`	inner string in backticks			|v_i`|262 263Additionally the following commands can be used:264	:	start Ex command for highlighted lines (1)	|v_:|265	r	change (4)					|v_r|266	s	change						|v_s|267	C	change (2)(4)					|v_C|268	S	change (2)					|v_S|269	R	change (2)					|v_R|270	x	delete						|v_x|271	D	delete (3)					|v_D|272	X	delete (2)					|v_X|273	Y	yank (2)					|v_Y|274	p	put						|v_p|275	P	put without overwriting registers		|v_P|276	J	join (1)					|v_J|277	U	make uppercase					|v_U|278	u	make lowercase					|v_u|279	^]	find tag					|v_CTRL-]|280	I	block insert					|v_b_I|281	A	block append					|v_b_A|282 283(1): Always whole lines, see |:visual_example|.284(2): Whole lines when not using CTRL-V.285(3): Whole lines when not using CTRL-V, delete until the end of the line when286     using CTRL-V.287(4): When using CTRL-V operates on the block only.288 289Note that the ":vmap" command can be used to specifically map keys in Visual290mode.  For example, if you would like the "/" command not to extend the Visual291area, but instead take the highlighted text and search for that: >292	:vmap / y/<C-R>"<CR>293(In the <> notation |<>|, when typing it you should type it literally; you294need to remove the 'B' and '<' flags from 'cpoptions'.)295 296If you want to give a register name using the """ command, do this just before297typing the operator character: "v{move-around}"xd".298 299If you want to give a count to the command, do this just before typing the300operator character: "v{move-around}3>" (move lines 3 indents to the right).301 302							*{move-around}*303The {move-around} is any sequence of movement commands.  Note the difference304with {motion}, which is only ONE movement command.305 306Another way to operate on the Visual area is using the |/\%V| item in a307pattern.  For example, to replace all '(' in the Visual area with '#': >308 309	:'<,'>s/\%V(/#/g310 311Note that the "'<,'>" will appear automatically when you press ":" in Visual312mode.313 314==============================================================================3155. Blockwise operators					*blockwise-operators*316 317Reminder: Use 'virtualedit' to be able to select blocks that start or end318after the end of a line or halfway a tab.319 320Visual-block Insert						*v_b_I*321With a blockwise selection, I{string}<ESC> will insert {string} at the start322of block on every line of the block, provided that the line extends into the323block.  Thus lines that are short will remain unmodified.  TABs are split to324retain visual columns.  Works only for adding text to a line, not for325deletions.  See |v_b_I_example|.326 327Visual-block Append						*v_b_A*328With a blockwise selection, A{string}<ESC> will append {string} to the end of329block on every line of the block.  There is some differing behavior where the330block RHS is not straight, due to different line lengths:331 3321. Block was created with <C-v>$333    In this case the string is appended to the end of each line.3342. Block was created with <C-v>{move-around}335    In this case the string is appended to the end of the block on each line,336    and whitespace is inserted to pad to the end-of-block column.337See |v_b_A_example|.338Note: "I" and "A" behave differently for lines that don't extend into the339selected block.  This was done intentionally, so that you can do it the way340you want.341Works only for adding text to a line, not for deletions.342 343Visual-block change						*v_b_c*344All selected text in the block will be replaced by the same text string.  When345using "c" the selected text is deleted and Insert mode started.  You can then346enter text (without a line break).  When you hit <Esc>, the same string is347inserted in all previously selected lines.348 349Visual-block Change						*v_b_C*350Like using "c", but the selection is extended until the end of the line for351all lines.352 353								*v_b_<*354Visual-block Shift						*v_b_>*355The block is shifted by 'shiftwidth'.  The RHS of the block is irrelevant.356The LHS of the block determines the point from which to apply a right shift,357and padding includes TABs optimally according to 'ts' and 'et'.  The LHS of358the block determines the point up to which to shift left.359See |v_b_>_example|.360See |v_b_<_example|.361 362Visual-block Replace						*v_b_r*363Every screen char in the highlighted region is replaced with the same char, ie364TABs are split and the virtual whitespace is replaced, maintaining screen365layout.366See |v_b_r_example|.367 368 369==============================================================================3706. Repeating						*visual-repeat*371 372When repeating a Visual mode operator, the operator will be applied to the373same amount of text as the last time:374- Linewise Visual mode: The same number of lines.375- Blockwise Visual mode: The same number of lines and columns.376- Normal Visual mode within one line: The same number of characters.377- Normal Visual mode with several lines: The same number of lines, in the378  last line the same number of characters as in the last line the last time.379The start of the text is the Cursor position.  If the "$" command was used as380one of the last commands to extend the highlighted text, the repeating will381be applied up to the rightmost column of the longest line.  Any count passed382to the `.` command is not used.383 384 385==============================================================================3867. Examples						*visual-examples*387 388							*:visual_example*389Currently the ":" command works on whole lines only.  When you select part of390a line, doing something like ":!date" will replace the whole line.  If you391want only part of the line to be replaced you will have to make a mapping for392it.  In a future release ":" may work on partial lines.393 394Here is an example, to replace the selected text with the output of "date": >395	:vmap _a <Esc>`>a<CR><Esc>`<i<CR><Esc>!!date<CR>kgJgJ396 397(In the <> notation |<>|, when typing it you should type it literally; you398need to remove the 'B' and '<' flags from 'cpoptions')399 400What this does is:401<Esc>		stop Visual mode402`>		go to the end of the Visual area403a<CR><Esc>	break the line after the Visual area404`<		jump to the start of the Visual area405i<CR><Esc>	break the line before the Visual area406!!date<CR>	filter the Visual text through date407kJJ		Join the lines back together408 409							*visual-search*410Here is an idea for a mapping that makes it possible to do a search for the411selected text: >412	:vmap X y/<C-R>"<CR>413 414(In the <> notation |<>|, when typing it you should type it literally; you415need to remove the 'B' and '<' flags from 'cpoptions')416 417Note that special characters (like '.' and '*') will cause problems.418 419Visual-block Examples					*blockwise-examples*420With the following text, I will indicate the commands to produce the block and421the results below.  In all cases, the cursor begins on the 'a' in the first422line of the test text.423The following modeline settings are assumed ":ts=8:sw=4:".424 425It will be helpful to426:set hls427/<TAB>428where <TAB> is a real TAB.  This helps visualise the operations.429 430The test text is:431 432abcdefghijklmnopqrstuvwxyz433abc		defghijklmnopqrstuvwxyz434abcdef  ghi		jklmnopqrstuvwxyz435abcdefghijklmnopqrstuvwxyz436 4371. fo<C-v>3jISTRING<ESC>					*v_b_I_example*438 439abcdefghijklmnSTRINGopqrstuvwxyz440abc	      STRING  defghijklmnopqrstuvwxyz441abcdef  ghi   STRING  	jklmnopqrstuvwxyz442abcdefghijklmnSTRINGopqrstuvwxyz443 4442. fo<C-v>3j$ASTRING<ESC>					*v_b_A_example*445 446abcdefghijklmnopqrstuvwxyzSTRING447abc		defghijklmnopqrstuvwxyzSTRING448abcdef  ghi		jklmnopqrstuvwxyzSTRING449abcdefghijklmnopqrstuvwxyzSTRING450 4513. fo<C-v>3j3l<..						*v_b_<_example*452 453abcdefghijklmnopqrstuvwxyz454abc	      defghijklmnopqrstuvwxyz455abcdef  ghi   jklmnopqrstuvwxyz456abcdefghijklmnopqrstuvwxyz457 4584. fo<C-v>3j>..							*v_b_>_example*459 460abcdefghijklmn		  opqrstuvwxyz461abc			    defghijklmnopqrstuvwxyz462abcdef  ghi			    jklmnopqrstuvwxyz463abcdefghijklmn		  opqrstuvwxyz464 4655. fo<C-v>5l3jrX						*v_b_r_example*466 467abcdefghijklmnXXXXXXuvwxyz468abc	      XXXXXXhijklmnopqrstuvwxyz469abcdef  ghi   XXXXXX    jklmnopqrstuvwxyz470abcdefghijklmnXXXXXXuvwxyz471 472==============================================================================4738. Select mode						*Select* *Select-mode*474 475Select mode looks like Visual mode, but the commands accepted are quite476different.  This resembles the selection mode in Microsoft Windows.477When the 'showmode' option is set, "-- SELECT --" is shown in the last line.478 479Entering Select mode:480- Using the mouse to select an area, and 'selectmode' contains "mouse".481  'mouse' must also contain a flag for the current mode.482- Using a non-printable movement command, with the Shift key pressed, and483  'selectmode' contains "key".  For example: <S-Left> and <S-End>.  'keymodel'484  must also contain "startsel".485- Using "v", "V" or CTRL-V command, and 'selectmode' contains "cmd".486- Using "gh", "gH" or "g_CTRL-H" command in Normal mode.487- From Visual mode, press CTRL-G.			*v_CTRL-G*488 489Commands in Select mode:490- Printable characters, <NL> and <CR> cause the selection to be deleted, and491  Vim enters Insert mode.  The typed character is inserted.492- Non-printable movement commands, with the Shift key pressed, extend the493  selection.  'keymodel' must include "startsel".494- Non-printable movement commands, with the Shift key NOT pressed, stop Select495  mode.  'keymodel' must include "stopsel".496- ESC stops Select mode.497- CTRL-O switches to Visual mode for the duration of one command. *v_CTRL-O*498- CTRL-G switches to Visual mode.499- CTRL-R {register} selects the register to be used for the text that is500  deleted when typing text.					  *v_CTRL-R*501  Unless you specify the "_" (black hole) register, the unnamed register is502  also overwritten.503 504 505Otherwise, typed characters are handled as in Visual mode.506 507When using an operator in Select mode, and the selection is linewise, the508selected lines are operated upon, but like in characterwise selection.  For509example, when a whole line is deleted, it can later be pasted halfway a line.510 511 512Mappings and menus in Select mode.			*Select-mode-mapping*513 514When mappings and menus are defined with the |:vmap| or |:vmenu| command they515work both in Visual mode and in Select mode.  When these are used in Select516mode Vim automatically switches to Visual mode, so that the same behavior as517in Visual mode is effective.  If you don't want this use |:xmap| or |:smap|.518 519One particular edge case: >520	:vnoremap <C-K> <Esc>521This ends Visual mode when in Visual mode, but in Select mode it does not522work, because Select mode is restored after executing the mapped keys.  You523need to use: >524	:snoremap <C-K> <Esc>525<526Users will expect printable characters to replace the selected area.527Therefore avoid mapping printable characters in Select mode.  Or use528|:sunmap|  after |:map| and |:vmap| to remove it for Select mode.529 530After the mapping or menu finishes, the selection is enabled again and Select531mode entered, unless the selected area was deleted, another buffer became532the current one or the window layout was changed.533 534When a character was typed that causes the selection to be deleted and Insert535mode started, Insert mode mappings are applied to this character.  This may536cause some confusion, because it means Insert mode mappings apply to a537character typed in Select mode.  Language mappings apply as well.538 539							*gV* *v_gV*540gV			Avoid the automatic reselection of the Visual area541			after a Select mode mapping or menu has finished.542			Put this just before the end of the mapping or menu.543			At least it should be after any operations on the544			selection.545 546							*gh*547gh			Start Select mode, characterwise.  This is like "v",548			but starts Select mode instead of Visual mode.549			Mnemonic: "get highlighted".550 551							*gH*552gH			Start Select mode, linewise.  This is like "V",553			but starts Select mode instead of Visual mode.554			Mnemonic: "get Highlighted".555 556							*g_CTRL-H*557g CTRL-H		Start Select mode, blockwise.  This is like CTRL-V,558			but starts Select mode instead of Visual mode.559			Mnemonic: "get Highlighted".560 561 vim:tw=78:ts=8:noet:ft=help:norl:562