home *** CD-ROM | disk | FTP | other *** search
/ vim.ftp.fu-berlin.de / 2015-02-03.vim.ftp.fu-berlin.de.tar / vim.ftp.fu-berlin.de / mac / vim55rt.sit / runtime / doc / visual.txt < prev    next >
Encoding:
Text File  |  1999-09-25  |  17.8 KB  |  464 lines  |  [TEXT/MPS ]

  1. *visual.txt*    For Vim version 5.5.  Last change: 1999 Sep 14
  2.  
  3.  
  4.           VIM REFERENCE MANUAL    by Bram Moolenaar
  5.  
  6.  
  7. Visual mode                *Visual* *Visual-mode* *visual-mode*
  8.  
  9. Visual mode is a flexible and easy way to select a piece of text for an
  10. operator.  It is the only way to select a block of text.
  11.  
  12. 1. Using Visual mode            |visual-use|
  13. 2. Starting and stopping Visual mode    |visual-start|
  14. 3. Changing the Visual area        |visual-change|
  15. 4. Operating on the Visual area        |visual-operators|
  16. 5. Blockwise operators            |blockwise-operators|
  17. 6. Repeating                |visual-repeat|
  18. 7. Examples                |visual-examples|
  19. 8. Select mode                |Select-mode|
  20.  
  21. {Vi has no Visual mode, the name "visual" is used for Normal mode, to
  22. distinguish it from Ex mode}
  23.  
  24. ==============================================================================
  25. 1. Using Visual mode                    *visual-use*
  26.  
  27. Using Visual mode consists of three parts:
  28. 1. Mark the start of the text with "v", "V" or CTRL-V.
  29.    The character under the cursor will be used as the start.
  30. 2. Move to the end of the text.
  31.    The text from the start of the Visual mode up to and including the
  32.    character under the cursor is highlighted.
  33. 3. Hit an operator.
  34.    The highlighted characters will be operated upon.
  35.  
  36. The 'highlight' option can be used to set the display mode to use for
  37. highlighting in Visual mode.
  38.  
  39. The highlighted text includes the character under the cursor.  On terminals
  40. where it is possible to make the cursor invisible the cursor position is
  41. also highlighted.  On terminals where this is not possible the cursor is
  42. displayed normally.  If your cursor cannot be made invisible and you want Vim
  43. to highlight the character under the cursor anyway, you could set the 't_cv'
  44. and 't_ci' options to something harmless, for example:
  45. >    :set t_cv=^[^[ t_ci=^[^[
  46.  
  47. With "v" the text before the start position and after the end position will
  48. not be highlighted.  However, All uppercase and non-alpha operators, except
  49. "~", will work on whole lines anyway.  See the list of operators below.
  50.  
  51.                             *visual-block*
  52. With CTRL-V (blockwise Visual mode) the highlighted text will be a rectangle
  53. between start position and the cursor.  However, some operators work on whole
  54. lines anyway (see the list below).  The change and substitute operators will
  55. delete the highlighted text and then start insertion at the top left
  56. position.
  57.  
  58. ==============================================================================
  59. 2. Starting and stopping Visual mode            *visual-start*
  60.  
  61.                         *v* *characterwise-visual*
  62. v            start Visual mode per character.
  63.  
  64.                         *V* *linewise-visual*
  65. V            start Visual mode linewise.
  66.  
  67.                         *CTRL-V* *blockwise-visual*
  68. CTRL-V            start Visual mode blockwise.  Note: Under Windows
  69.             CTRL-V could be mapped to paste text, it doesn't work
  70.             to start Visual mode then, see |CTRL-V-alternative|.
  71.  
  72. If you use <Esc>, click the left mouse button or use any command that
  73. does a jump to another buffer while in Visual mode, the highlighting stops
  74. and no text is affected.  Also when you hit "v" in characterwise Visual mode,
  75. "CTRL-V" in blockwise Visual mode or "V" in linewise Visual mode.  If you hit
  76. CTRL-Z the highlighting stops and the editor is suspended or a new shell is
  77. started |CTRL-Z|.
  78.  
  79.           new mode after typing:        *v_v* *v_CTRL-V* *v_V*
  80. old mode         "v"          "CTRL-V"             "V"    ~
  81.  
  82. Normal            Visual       blockwise Visual      linewise Visual
  83. Visual            Normal       blockwise Visual      linewise Visual
  84. blockwise Visual    Visual       Normal          linewise Visual
  85. linewise Visual     Visual       blockwise Visual      Normal
  86.  
  87.                             *gv* *v_gv*
  88. gv            Start Visual mode with the same area as the previous
  89.             area and the same mode.  In Visual mode the current and
  90.             the previous Visual area are exchanged.
  91.  
  92.                             *<LeftMouse>*
  93. <LeftMouse>        Set the current cursor position.  If Visual mode is
  94.             active it is stopped.  Only when 'mouse' option is
  95.             contains 'n' or 'a'.  If the position is within 'so'
  96.             lines from the last line on the screen the text is
  97.             scrolled up.  If the position is within 'so' lines from
  98.             the first line on the screen the text is scrolled
  99.             down.
  100.  
  101.                             *<RightMouse>*
  102. <RightMouse>        Start Visual mode if it is not active.  The text from
  103.             the cursor position to the position of the click is
  104.             highlighted.  If Visual mode was already active move
  105.             the start or end of the highlighted text, which ever
  106.             is closest, to the position of the click.  Only when
  107.             'mouse' option contains 'n' or 'a'.
  108.  
  109.             Note: when 'mousemodel' is set to "popup",
  110.             <S-LeftMouse> has to be used instead of <RightMouse>.
  111.  
  112.                             *<LeftRelease>*
  113. <LeftRelease>        This works like a <LeftMouse>, if it is not a
  114.             the same position as <LeftMouse>.  In an xterm you
  115.             won't see the selected area until the button is
  116.             released, unless there is access to the display where
  117.             the xterm is running (via the DISPLAY environment
  118.             variable or the -display argument).  Only when 'mouse'
  119.             option contains 'n' or 'a'.
  120.  
  121. If Visual mode is not active and the "v", "V" or CTRL-V is preceded with a
  122. count, the size of the previously highlighted area is used for a start.  You
  123. can then move the end of the highlighted area and give an operator.  The type
  124. of the old area is used (character, line or blockwise).
  125. - Linewise Visual mode: The number of lines is multiplied with the count.
  126. - Blockwise Visual mode: The number of lines and columns is multiplied with
  127.   the count.
  128. - Normal Visual mode within one line: The number of characters is multiplied
  129.   with the count.
  130. - Normal Visual mode with several lines: The number of lines is multiplied
  131.   with the count, in the last line the same number of characters is used as
  132.   in the last line in the previously highlighted area.
  133. The start of the text is the Cursor position.  If the "$" command was used as
  134. one of the last commands to extend the highlighted text, the area will be
  135. extended to the rightmost column of the longest line.
  136.  
  137. If you want to highlight exactly the same area as the last time, you can use
  138. "gv" |gv| |v_gv|.
  139.  
  140.                             *v_CTRL-C*
  141. CTRL-C            In Visual mode: Stop Visual mode.  When insert mode is
  142.             pending (the mode message shows
  143.             "-- (insert) VISUAL --"), it is also stopped.
  144.  
  145. ==============================================================================
  146. 3. Changing the Visual area                *visual-change*
  147.  
  148.                             *v_o*
  149. o            Go to Other end of highlighted text: The current
  150.             cursor position becomes the start of the highlighted
  151.             text and the cursor is moved to the other end of the
  152.             highlighted text.  The highlighted area remains the
  153.             same.
  154.  
  155.                             *v_O*
  156. O            Go to Other end of highlighted text.  This is like
  157.             "o", but in Visual block mode the cursor moves to the
  158.             other corner in the same line.  When the corner is at
  159.             a character that occupies more than one position on
  160.             the screen (e.g., a <Tab>), the highlighted text may
  161.             change.
  162.  
  163.                             *v_$*
  164. When the "$" command is used with blockwise Visual mode, the right end of the
  165. highlighted text will be determined by the longest highlighted line.  This
  166. stops when a motion command is used that does not move straight up or down.
  167.  
  168. For moving the end of the block many commands can be used, but you cannot
  169. use Ex commands, commands that make changes or abandon the file.  Commands
  170. (starting with) ".pPiIaAO&", CTRL-^, "Z", CTRL-], CTRL-T, CTRL-R, CTRL-I
  171. and CTRL-O cause a beep and Visual mode continues.
  172.  
  173.  
  174. ==============================================================================
  175. 4. Operating on the Visual area                *visual-operators*
  176.  
  177. The operators that can be used are:
  178.     ~    switch case                    |v_~|
  179.     d    delete                        |v_d|
  180.     c    change (4)                    |v_c|
  181.     y    yank                        |v_y|
  182.     >    shift right (4)                    |v_>|
  183.     <    shift left (4)                    |v_<|
  184.     !    filter through external command (1)        |v_!|
  185.     =    filter through 'equalprg' option command (1)    |v_=|
  186.     gq    format lines to 'textwidth' length (1)        |v_gq|
  187.  
  188. The objects that can be used are:
  189.     aw    a word (with white space)            |v_aw|
  190.     iw    inner word                    |v_iw|
  191.     aW    a WORD (with white space)            |v_aW|
  192.     iW    inner WORD                    |v_iW|
  193.     as    a sentence (with white space)            |v_as|
  194.     is    inner sentence                    |v_is|
  195.     ap    a paragraph (with white space)            |v_ap|
  196.     ip    inner paragraph                    |v_ip|
  197.     ab    a () block (with braces)            |v_ab|
  198.     ib    inner () block                    |v_ib|
  199.     aB    a {} block (with brackets)            |v_aB|
  200.     iB    inner {} block                    |v_iB|
  201.  
  202. Additionally the following commands can be used:
  203.     :    start ex command for highlighted lines (1)    |v_:|
  204.     r    change (4)                    |v_r|
  205.     s    change                        |v_s|
  206.     C    change (2)(4)                    |v_C|
  207.     S    change (2)                    |v_S|
  208.     R    change (2)                    |v_R|
  209.     x    delete                        |v_x|
  210.     D    delete (3)                    |v_D|
  211.     X    delete (2)                    |v_X|
  212.     Y    yank (2)                    |v_Y|
  213.     J    join (1)                    |v_J|
  214.     U    make uppercase                    |v_U|
  215.     u    make lowercase                    |v_u|
  216.     ^]    find tag                    |v_CTRL-]|
  217.     I    block insert                    |v_b_I|
  218.     A    block append                    |v_b_A|
  219.  
  220. (1): Always whole lines, see |:visual_example|.
  221. (2): Whole lines when not using CTRL-V.
  222. (3): Whole lines when not using CTRL-V, delete until the end of the line when
  223.      using CTRL-V.
  224. (4): When using CTRL-V operates on the block only.
  225.  
  226. Note that the ":vmap" command can be used to specifically map keys in Visual
  227. mode.  For example, if you would like the "/" command not to extend the Visual
  228. area, but instead use the highlighted text for searching:
  229. >  :vmap / y/<C-R>"
  230.  
  231. If you want to give a register name using the """ command, do this just before
  232. typing the operator character: "v{move-around}"xd".
  233.  
  234. If you want to give a count to the command, do this just before typing the
  235. operator character: "v{move-around}3>" (move lines 3 indents to the right).
  236.  
  237.                             *{move-around}*
  238. The {move-around} is any sequence of movement commands.  Note the difference
  239. with {motion}, which is only ONE movement command.
  240.  
  241. ==============================================================================
  242. 5. Blockwise operators                    *blockwise-operators*
  243.  
  244. {not available when compiled without the |+visualextra| feature}
  245.  
  246. Visual-block Insert                        *v_b_I*
  247. With a blockwise selection, Istring<ESC> will insert string at the start of
  248. block on every line of the block, provided that the line extends into the
  249. block. TABs are split to retain visual columns.
  250. See |v_b_I_example|.
  251.  
  252. Visual-block Append                        *v_b_A*
  253. With a blockwise selection, Astring<ESC> will append string to the end of
  254. block on every line of the block. There is some differing behavior where the
  255. block RHS is not straight, due to different line lengths.
  256.  
  257. a. Block was created with <C-v>$
  258.     In this case the string is appended to the end of each line.
  259. b. Block was created with <C-v>{move-around}
  260.     In this case the string is appended to the end of the block on each
  261.     line which extends into the block, and whitespace is inserted to pad to
  262.     the end-of-block column.
  263.     Note: Padding is buggy (vim 5.4c).
  264. See |v_b_A_example|.
  265.  
  266. Visual-block change                        *v_b_c*
  267. All selected text in the block will be replaced by the same text string.  When
  268. using "c" the selected text is deleted and Insert mode started.  You can then
  269. enter text (without a line break).  When you hit <Esc>, the same string is
  270. inserted in all previously selected lines.
  271.  
  272. Visual-block Change                        *v_b_C*
  273. Like using "c", but the selection is extended until the end of the line for
  274. all lines.
  275.  
  276.                                 *v_b_<*
  277. Visual-block Shift                        *v_b_>*
  278. The block is shifted by 'shiftwidth'. The RHS of the block is irrelevant. The
  279. LHS of the block determines the point from which to apply a right shift, and
  280. padding includes TABs optimally according to 'ts' and 'et'. The LHS of the
  281. block determines the point upto which to shift left.
  282.     Note: v_< padding is buggy if the Visual Block starts and ends in the same
  283.     TAB. (Vim 5.4c).
  284. See |v_b_>_example|.
  285. See |v_b_<_example|.
  286.  
  287. Visual-block Replace                        *v_b_r*
  288. Every screen char in the highlighted region is replaced with the same char, ie
  289. TABs are split and the virtual whitespace is replaced, maintaining screen
  290. layout.
  291. See |v_b_r_example|.
  292.  
  293.  
  294. ==============================================================================
  295. 6. Repeating                        *visual-repeat*
  296.  
  297. When repeating a Visual mode operator, the operator will be applied to the
  298. same amount of text as the last time:
  299. - Linewise Visual mode: The same number of lines.
  300. - Blockwise Visual mode: The same number of lines and columns.
  301. - Normal Visual mode within one line: The same number of characters.
  302. - Normal Visual mode with several lines: The same number of lines, in the
  303.   last line the same number of characters as in the last line the last time.
  304. The start of the text is the Cursor position.  If the "$" command was used as
  305. one of the last commands to extend the highlighted text, the repeating will
  306. be applied up to the rightmost column of the longest line.
  307.  
  308.  
  309. ==============================================================================
  310. 7. Examples                        *visual-examples*
  311.  
  312.                             *:visual_example*
  313. Currently the ":" command works on whole lines only.  When you select part of
  314. a line, doing something like ":!date" will replace the whole line.  If you
  315. want only part of the line to be replaced you will have to make a mapping for
  316. it.  In a future release ":" may work on partial lines.
  317.  
  318. Here is an example, to replace the selected text with the output of "date":
  319. >    :vmap _a <Esc>`>a<CR><Esc>`<i<CR><Esc>!!date<CR>kJJ
  320.  
  321. (In the <> notation |<>|, when typing it you should type it literally; you
  322. need to remove the 'B' and '<' flags from 'cpoptions')
  323.  
  324. What this does is:
  325. <Esc>        stop Visual mode
  326. `>        go to the end of the Visual area
  327. a<CR><Esc>    break the line after the Visual area
  328. `<        jump to the start of the Visual area
  329. i<CR><Esc>    break the line before the Visual area
  330. !!date<CR>    filter the Visual text through date
  331. kJJ        Join the lines back together
  332.  
  333.                             *visual-search*
  334. Here is an idea for a mapping that makes it possible to do a search for the
  335. selected text:
  336. >    :vmap X y/<C-R>"<CR>
  337.  
  338. (In the <> notation |<>|, when typing it you should type it literally; you
  339. need to remove the 'B' and '<' flags from 'cpoptions')
  340.  
  341. Note that special characters (like '.' and '*') will cause problems.
  342.  
  343. Visual-block Examples                                   *blockwise-examples*
  344. With the following text, I will indicate the commands to produce the block and
  345. the results below. In all cases, the cursor begins on the 'a' in the first
  346. line if the test text.
  347. The following modeline settings are assumed :ts=8:sw=4:
  348.  
  349. It will be helpful to
  350. :set hls
  351. /<TAB>
  352. where <TAB> ia a real TAB. This helps visualise the operations.
  353.  
  354. The test text is:
  355.  
  356. abcdefghijklmnopqrstuvwxyz
  357. abc        defghijklmnopqrstuvwxyz
  358. abcdef  ghi        jklmnopqrstuvwxyz
  359. abcdefghijklmnopqrstuvwxyz
  360.  
  361. 1. fo<C-v>3jISTRING<ESC>                    *v_b_I_example*
  362.  
  363. abcdefghijklmnSTRINGopqrstuvwxyz
  364. abc          STRING  defghijklmnopqrstuvwxyz
  365. abcdef  ghi   STRING    jklmnopqrstuvwxyz
  366. abcdefghijklmnSTRINGopqrstuvwxyz
  367.  
  368. 2. fo<C-v>3j$ASTRING<ESC>                    *v_b_A_example*
  369.  
  370. abcdefghijklmnopqrstuvwxyzSTRING
  371. abc        defghijklmnopqrstuvwxyzSTRING
  372. abcdef  ghi        jklmnopqrstuvwxyzSTRING
  373. abcdefghijklmnopqrstuvwxyzSTRING
  374.  
  375. 3. fo<C-v>3j3l<..                        *v_b_<_example*
  376.  
  377. abcdefghijklmnopqrstuvwxyz
  378. abc          defghijklmnopqrstuvwxyz
  379. abcdef  ghi   jklmnopqrstuvwxyz
  380. abcdefghijklmnopqrstuvwxyz
  381.  
  382. 4. fo3j>..                            *v_b_>_example*
  383.  
  384. abcdefghijklmn          opqrstuvwxyz
  385. abc                defghijklmnopqrstuvwxyz
  386. abcdef  ghi                jklmnopqrstuvwxyz
  387. abcdefghijklmn          opqrstuvwxyz
  388.  
  389. 5. fo5l3jrX                            *v_b_r_example*
  390.  
  391. abcdefghijklmnXXXXXXuvwxyz
  392. abc          XXXXXXhijklmnopqrstuvwxyz
  393. abcdef  ghi   XXXXXX    jklmnopqrstuvwxyz
  394. abcdefghijklmnXXXXXXuvwxyz
  395.  
  396. ==============================================================================
  397. 8. Select mode                        *Select* *Select-mode*
  398.  
  399. Select mode looks like Visual mode, but the commands accepted are quite
  400. different.  This resembles the selection mode in Microsoft Windows.
  401. When the 'showmode' option is set, "-- SELECT --" is shown in the last line.
  402.  
  403. Entering Select mode:
  404. - Using the mouse to select an area, and 'selectmode' contains "mouse".
  405.   'mouse' must also contain a flag for the current mode.
  406. - Using a non-printable movement command, with the Shift key pressed, and
  407.   'selectmode' contains "key".  For example: <S-Left> and <S-End>.  'keymodel'
  408.   must also contain "startsel".
  409. - Using "v", "V" or CTRL-V command, and 'selectmode' contains "cmd".
  410. - Using "gh", "gH" or "g_CTRL-H" command in Normal mode.
  411. - From Visual mode, press CTRL-G.            *v_CTRL-G*
  412.  
  413. Commands in Select mode:
  414. - Printable characters, <NL> and <CR> cause the selection to be deleted, and
  415.   Vim enters Insert mode.  The typed character is inserted.
  416. - Non-printable movement commands, with the Shift key pressed, extend the
  417.   selection.  'keymodel' must include "startsel".
  418. - Non-printable movement commands, with the Shift key NOT pressed, stop Select
  419.   mode.  'keymodel' must include "stopsel".
  420. - ESC stops Select mode.
  421. - CTRL-O switches to Visual mode for the duration of one command. *v_CTRL-O*
  422. - CTRL-G switches to Visual mode.
  423.  
  424. Otherwise, typed characters are handled as in Visual mode.
  425.  
  426. When using an operator in Select mode, and the selection is linewise, the
  427. selected lines are operated upon, but like in characterwise selection.  For
  428. example, when a whole line is deleted, it can later be pasted halfway a line.
  429.  
  430.  
  431. Mappings and menus in Select mode.            *Select-mode-mapping*
  432.  
  433. In Select mode the mappings and menus of Visual mode are used.  Before it is
  434. executed, Vim automatically switches to Visual mode, so that the same
  435. behavior as in Visual mode is effective.
  436.  
  437. After the mapping or menu finishes, the selection is enabled again and Select
  438. mode entered, unless the selected area was deleted, another buffer became
  439. the current one or the window layout was changed.
  440.  
  441.                             *gV* *v_gV*
  442. gV            Avoid the automatic reselection of the Visual area
  443.             after a Select mode mapping or menu has finished.
  444.             Put this just before the end of the mapping or menu.
  445.             At least it should be after any operations on the
  446.             selection.
  447.  
  448.                             *gh*
  449. gh            Start Select mode, characterwise.  This is like "v",
  450.             but starts Select mode instead of Visual mode.
  451.             Mnemonic: "get highlighted".
  452.  
  453.                             *gH*
  454. gH            Start Select mode, linewise.  This is like "V",
  455.             but starts Select mode instead of Visual mode.
  456.             Mnemonic: "get Highlighted".
  457.  
  458.                             *g_CTRL-H*
  459. g CTRL-H        Start Select mode, blockwise.  This is like CTRL-V,
  460.             but starts Select mode instead of Visual mode.
  461.             Mnemonic: "get Highlighted".
  462.  
  463.  vim:tw=78:ts=8:sw=8:
  464.