Quick links: help overview · quick reference · reference manual toc · command index

visual.txt    For Vim version 5.6.  Last change: 2000 Jan 05

(also see: http://jvi.sourceforge.net/javahelpset/jvi-vis_block.html)

                  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.

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}

==============================================================================
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. Hit an operator.
   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.

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
"~", 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.

              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
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.


                        Note: when 'mousemodel' is set to "popup",
                        <S-LeftMouse> has to be used instead of <RightMouse>.

                                                        <LeftRelease>

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.

==============================================================================
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) ".pPiIaAO&", CTRL-^, "Z", CTRL-], CTRL-T, CTRL-R, CTRL-I
and CTRL-O cause a beep and Visual mode continues.


==============================================================================
4. Operating on the Visual area                         visual-operators

LEGEND FOR THE FIRST COLUMN:    " " works
                                "e" works if platform support, eg an IDE
                                "." future support, may be partial
                                "x" not supported or planned (but plans change)

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 braces)                        v_ab
.       ib      inner () block                                  v_ib
.       aB      a {} block (with brackets)                      v_aB
.       iB      inner {} block                                  v_iB

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.

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.

==============================================================================
5. Blockwise operators                                  blockwise-operators

{not available when compiled without the |+visualextra| feature}

Visual-block Insert                                             v_b_I
With a blockwise selection, Istring<ESC> will insert string at the start of
block on every line of the block, provided that the line extends into the
block. TABs are split to retain visual columns.
See v_b_I_example.

Visual-block Append                                             v_b_A
With a blockwise selection, Astring<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.

a. Block was created with <C-v>$
    In this case the string is appended to the end of each line.
b. Block was created with <C-v>{move-around}
    In this case the string is appended to the end of the block on each
    line which extends into the block, and whitespace is inserted to pad to
    the end-of-block column.
See v_b_A_example.

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              { NOT in jVi }                  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 if the test text.
The following modeline settings are assumed :ts=8:sw=4:

It will be helpful to
:set hls
/<TAB>
where <TAB> ia 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

 vim:tw=78:ts=8:sw=8:noet:

Quick links: help overview · quick reference · reference manual toc · command index