runtime/doc/scroll.txt

   1 *scroll.txt*    For Vim version 7.2.  Last change: 2006 Aug 27
   2
   3
   4                   VIM REFERENCE MANUAL    by Bram Moolenaar
   5
   6
   7 Scrolling                                               *scrolling*
   8
   9 These commands move the contents of the window.  If the cursor position is
  10 moved off of the window, the cursor is moved onto the window (with
  11 'scrolloff' screen lines around it).  A page is the number of lines in the
  12 window minus two.  The mnemonics for these commands may be a bit confusing.
  13 Remember that the commands refer to moving the window (the part of the buffer
  14 that you see) upwards or downwards in the buffer.  When the window moves
  15 upwards in the buffer, the text in the window moves downwards on your screen.
  16
  17 See section |03.7| of the user manual for an introduction.
  18
  19 1. Scrolling downwards          |scroll-down|
  20 2. Scrolling upwards            |scroll-up|
  21 3. Scrolling relative to cursor |scroll-cursor|
  22 4. Scrolling horizontally       |scroll-horizontal|
  23 5. Scrolling synchronously      |scroll-binding|
  24 6. Scrolling with a mouse wheel |scroll-mouse-wheel|
  25
  26 ==============================================================================
  27 1. Scrolling downwards                                  *scroll-down*
  28
  29 The following commands move the edit window (the part of the buffer that you
  30 see) downwards (this means that more lines downwards in the text buffer can be
  31 seen):
  32
  33                                                         *CTRL-E*
  34 CTRL-E                  Scroll window [count] lines downwards in the buffer.
  35                         Mnemonic: Extra lines.
  36
  37                                                         *CTRL-D*
  38 CTRL-D                  Scroll window Downwards in the buffer.  The number of
  39                         lines comes from the 'scroll' option (default: half a
  40                         screen).  If [count] given, first set 'scroll' option
  41                         to [count].  The cursor is moved the same number of
  42                         lines down in the file (if possible; when lines wrap
  43                         and when hitting the end of the file there may be a
  44                         difference).  When the cursor is on the last line of
  45                         the buffer nothing happens and a beep is produced.
  46                         See also 'startofline' option.
  47                         {difference from vi: Vim scrolls 'scroll' screen
  48                         lines, instead of file lines; makes a difference when
  49                         lines wrap}
  50
  51 <S-Down>        or                              *<S-Down>* *<kPageDown>*
  52 <PageDown>      or                              *<PageDown>* *CTRL-F*
  53 CTRL-F                  Scroll window [count] pages Forwards (downwards) in
  54                         the buffer.  See also 'startofline' option.
  55                         When there is only one window the 'window' option
  56                         might be used.
  57
  58                                                         *z+*
  59 z+                      Without [count]: Redraw with the line just below the
  60                         window at the top of the window.  Put the cursor in
  61                         that line, at the first non-blank in the line.
  62                         With [count]: just like "z<CR>".
  63
  64 ==============================================================================
  65 2. Scrolling upwards                                    *scroll-up*
  66
  67 The following commands move the edit window (the part of the buffer that you
  68 see) upwards (this means that more lines upwards in the text buffer can be
  69 seen):
  70
  71                                                         *CTRL-Y*
  72 CTRL-Y                  Scroll window [count] lines upwards in the buffer.
  73                         Note: When using the MS-Windows key bindings CTRL-Y is
  74                         remapped to redo.
  75
  76                                                         *CTRL-U*
  77 CTRL-U                  Scroll window Upwards in the buffer.  The number of
  78                         lines comes from the 'scroll' option (default: half a
  79                         screen).  If [count] given, first set the 'scroll'
  80                         option to [count].  The cursor is moved the same
  81                         number of lines up in the file (if possible; when
  82                         lines wrap and when hitting the end of the file there
  83                         may be a difference).  When the cursor is on the first
  84                         line of the buffer nothing happens and a beep is
  85                         produced.  See also 'startofline' option.
  86                         {difference from vi: Vim scrolls 'scroll' screen
  87                         lines, instead of file lines; makes a difference when
  88                         lines wrap}
  89
  90 <S-Up>          or                                      *<S-Up>* *<kPageUp>*
  91 <PageUp>        or                                      *<PageUp>* *CTRL-B*
  92 CTRL-B                  Scroll window [count] pages Backwards (upwards) in the
  93                         buffer.  See also 'startofline' option.
  94                         When there is only one window the 'window' option
  95                         might be used.
  96
  97                                                         *z^*
  98 z^                      Without [count]: Redraw with the line just above the
  99                         window at the bottom of the window.  Put the cursor in
 100                         that line, at the first non-blank in the line.
 101                         With [count]: First scroll the text to put the [count]
 102                         line at the bottom of the window, then redraw with the
 103                         line which is now at the top of the window at the
 104                         bottom of the window.  Put the cursor in that line, at
 105                         the first non-blank in the line.
 106
 107 ==============================================================================
 108 3. Scrolling relative to cursor                         *scroll-cursor*
 109
 110 The following commands reposition the edit window (the part of the buffer that
 111 you see) while keeping the cursor on the same line:
 112
 113                                                         *z<CR>*
 114 z<CR>                   Redraw, line [count] at top of window (default
 115                         cursor line).  Put cursor at first non-blank in the
 116                         line.
 117
 118                                                         *zt*
 119 zt                      Like "z<CR>", but leave the cursor in the same
 120                         column.  {not in Vi}
 121
 122                                                         *zN<CR>*
 123 z{height}<CR>           Redraw, make window {height} lines tall.  This is
 124                         useful to make the number of lines small when screen
 125                         updating is very slow.  Cannot make the height more
 126                         than the physical screen height.
 127
 128                                                         *z.*
 129 z.                      Redraw, line [count] at center of window (default
 130                         cursor line).  Put cursor at first non-blank in the
 131                         line.
 132
 133                                                         *zz*
 134 zz                      Like "z.", but leave the cursor in the same column.
 135                         Careful: If caps-lock is on, this commands becomes
 136                         "ZZ": write buffer and exit!  {not in Vi}
 137
 138                                                         *z-*
 139 z-                      Redraw, line [count] at bottom of window (default
 140                         cursor line).  Put cursor at first non-blank in the
 141                         line.
 142
 143                                                         *zb*
 144 zb                      Like "z-", but leave the cursor in the same column.
 145                         {not in Vi}
 146
 147 ==============================================================================
 148 4. Scrolling horizontally                               *scroll-horizontal*
 149
 150 For the following four commands the cursor follows the screen.  If the
 151 character that the cursor is on is moved off the screen, the cursor is moved
 152 to the closest character that is on the screen.  The value of 'sidescroll' is
 153 not used.
 154
 155 z<Right>    or                                          *zl* *z<Right>*
 156 zl                      Move the view on the text [count] characters to the
 157                         right, thus scroll the text [count] characters to the
 158                         left.  This only works when 'wrap' is off.  {not in
 159                         Vi}
 160
 161 z<Left>      or                                         *zh* *z<Left>*
 162 zh                      Move the view on the text [count] characters to the
 163                         left, thus scroll the text [count] characters to the
 164                         right.  This only works when 'wrap' is off.  {not in
 165                         Vi}
 166
 167                                                         *zL*
 168 zL                      Move the view on the text half a screenwidth to the
 169                         right, thus scroll the text half a screenwidth to the
 170                         left.  This only works when 'wrap' is off.  {not in
 171                         Vi}
 172
 173                                                         *zH*
 174 zH                      Move the view on the text half a screenwidth to the
 175                         left, thus scroll the text half a screenwidth to the
 176                         right.  This only works when 'wrap' is off.  {not in
 177                         Vi}
 178
 179 For the following two commands the cursor is not moved in the text, only the
 180 text scrolls on the screen.
 181
 182                                                         *zs*
 183 zs                      Scroll the text horizontally to position the cursor
 184                         at the start (left side) of the screen.  This only
 185                         works when 'wrap' is off.  {not in Vi}
 186
 187                                                         *ze*
 188 ze                      Scroll the text horizontally to position the cursor
 189                         at the end (right side) of the screen.  This only
 190                         works when 'wrap' is off.  {not in Vi}
 191
 192 ==============================================================================
 193 5. Scrolling synchronously                              *scroll-binding*
 194
 195 Occasionally, it is desirable to bind two or more windows together such that
 196 when one window is scrolled, the other windows are scrolled also.  In Vim,
 197 windows can be given this behavior by setting the (window-specific)
 198 'scrollbind' option.  When a window that has 'scrollbind' set is scrolled, all
 199 other 'scrollbind' windows are scrolled the same amount, if possible.  The
 200 behavior of 'scrollbind' can be modified by the 'scrollopt' option.
 201
 202 When using the scrollbars, the binding only happens when scrolling the window
 203 with focus (where the cursor is).  You can use this to avoid scroll-binding
 204 for a moment without resetting options.
 205
 206 When a window also has the 'diff' option set, the scroll-binding uses the
 207 differences between the two buffers to synchronize the position precisely.
 208 Otherwise the following method is used.
 209
 210                                                         *scrollbind-relative*
 211 Each 'scrollbind' window keeps track of its "relative offset," which can be
 212 thought of as the difference between the current window's vertical scroll
 213 position and the other window's vertical scroll position.  When one of the
 214 'scrollbind' windows is asked to vertically scroll past the beginning or end
 215 limit of its text, the window no longer scrolls, but remembers how far past
 216 the limit it wishes to be.  The window keeps this information so that it can
 217 maintain the same relative offset, regardless of its being asked to scroll
 218 past its buffer's limits.
 219
 220 However, if a 'scrollbind' window that has a relative offset that is past its
 221 buffer's limits is given the cursor focus, the other 'scrollbind' windows must
 222 jump to a location where the current window's relative offset is valid.  This
 223 behavior can be changed by clearing the 'jump' flag from the 'scrollopt'
 224 option.
 225
 226                                                 *syncbind* *:syncbind* *:sync*
 227 :syncbind               Force all 'scrollbind' windows to have the same
 228                         relative offset.  I.e., when any of the 'scrollbind'
 229                         windows is scrolled to the top of its buffer, all of
 230                         the 'scrollbind' windows will also be at the top of
 231                         their buffers.
 232
 233                                                         *scrollbind-quickadj*
 234 The 'scrollbind' flag is meaningful when using keyboard commands to vertically
 235 scroll a window, and also meaningful when using the vertical scrollbar of the
 236 window which has the cursor focus.  However, when using the vertical scrollbar
 237 of a window which doesn't have the cursor focus, 'scrollbind' is ignored.
 238 This allows quick adjustment of the relative offset of 'scrollbind' windows.
 239
 240 ==============================================================================
 241 6. Scrolling with a mouse wheel                         *scroll-mouse-wheel*
 242
 243 When your mouse has a scroll wheel, it should work with Vim in the GUI.  How
 244 it works depends on your system.  It might also work in an xterm
 245 |xterm-mouse-wheel|.
 246
 247 For the Win32 GUI the scroll action is hard coded.  It works just like
 248 dragging the scrollbar of the current window.  How many lines are scrolled
 249 depends on your mouse driver.  If the scroll action causes input focus
 250 problems, see |intellimouse-wheel-problems|.
 251
 252 For the X11 GUIs (Motif, Athena and GTK) scrolling the wheel generates key
 253 presses <MouseDown> and <MouseUp>.  The default action for these keys are:
 254     <MouseDown>         scroll three lines down.        *<MouseDown>*
 255     <S-MouseDown>       scroll a full page down.        *<S-MouseDown>*
 256     <C-MouseDown>       scroll a full page down.        *<C-MouseDown>*
 257     <MouseUp>           scroll three lines up.          *<MouseUp>*
 258     <S-MouseUp>         scroll a full page up.          *<S-MouseUp>*
 259     <C-MouseUp>         scroll a full page up.          *<C-MouseUp>*
 260 This should work in all modes, except when editing the command line.
 261
 262 Note that <MouseDown> is used for scrolling the text down, this happens when
 263 you turn the mouse wheel up!
 264
 265 You can modify this behavior by mapping the keys.  For example, to make the
 266 scroll wheel move one line or half a page in Normal mode: >
 267    :map <MouseDown> <C-Y>
 268    :map <S-MouseDown> <C-U>
 269    :map <MouseUp> <C-E>
 270    :map <S-MouseUp> <C-D>
 271 You can also use Alt and Ctrl modifiers.
 272
 273 This only works when Vim gets the scroll wheel events, of course.  You can
 274 check if this works with the "xev" program.
 275
 276 When using XFree86, the /etc/XF86Config file should have the correct entry for
 277 your mouse.  For FreeBSD, this entry works for a Logitech scrollmouse: >
 278     Protocol     "MouseMan"
 279     Device       "/dev/psm0"
 280     ZAxisMapping 4 5
 281 See the XFree86 documentation for information.
 282
 283                                                         *xterm-mouse-wheel*
 284 To use the mouse wheel in a new xterm you only have to make the scroll wheel
 285 work in your Xserver, as mentioned above.
 286
 287 To use the mouse wheel in an older xterm you must do this:
 288 1. Make it work in your Xserver, as mentioned above.
 289 2. Add translations for the xterm, so that the xterm will pass a scroll event
 290    to Vim as an escape sequence.
 291 3. Add mappings in Vim, to interpret the escape sequences as <MouseUp> or
 292    <MouseDown> keys.
 293
 294 You can do the translations by adding this to your ~.Xdefaults file (or other
 295 file where your X resources are kept): >
 296
 297   XTerm*VT100.Translations:             #override \n\
 298                 s<Btn4Down>: string("0x9b") string("[64~") \n\
 299                 s<Btn5Down>: string("0x9b") string("[65~") \n\
 300                 <Btn4Down>: string("0x9b") string("[62~") \n\
 301                 <Btn5Down>: string("0x9b") string("[63~") \n\
 302                 <Btn4Up>: \n\
 303                 <Btn5Up>:
 304
 305 Add these mappings to your vimrc file: >
 306         :map <M-Esc>[62~ <MouseDown>
 307         :map! <M-Esc>[62~ <MouseDown>
 308         :map <M-Esc>[63~ <MouseUp>
 309         :map! <M-Esc>[63~ <MouseUp>
 310         :map <M-Esc>[64~ <S-MouseDown>
 311         :map! <M-Esc>[64~ <S-MouseDown>
 312         :map <M-Esc>[65~ <S-MouseUp>
 313         :map! <M-Esc>[65~ <S-MouseUp>
 314 <
 315  vim:tw=78:ts=8:ft=help:norl: