1*scroll.txt*    For Vim version 7.3.  Last change: 2006 Aug 27
2
3
4		  VIM REFERENCE MANUAL    by Bram Moolenaar
5
6
7Scrolling						*scrolling*
8
9These commands move the contents of the window.  If the cursor position is
10moved 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
12window minus two.  The mnemonics for these commands may be a bit confusing.
13Remember that the commands refer to moving the window (the part of the buffer
14that you see) upwards or downwards in the buffer.  When the window moves
15upwards in the buffer, the text in the window moves downwards on your screen.
16
17See section |03.7| of the user manual for an introduction.
18
191. Scrolling downwards		|scroll-down|
202. Scrolling upwards		|scroll-up|
213. Scrolling relative to cursor	|scroll-cursor|
224. Scrolling horizontally	|scroll-horizontal|
235. Scrolling synchronously	|scroll-binding|
246. Scrolling with a mouse wheel |scroll-mouse-wheel|
25
26==============================================================================
271. Scrolling downwards					*scroll-down*
28
29The following commands move the edit window (the part of the buffer that you
30see) downwards (this means that more lines downwards in the text buffer can be
31seen):
32
33							*CTRL-E*
34CTRL-E			Scroll window [count] lines downwards in the buffer.
35			Mnemonic: Extra lines.
36
37							*CTRL-D*
38CTRL-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*
53CTRL-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+*
59z+			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==============================================================================
652. Scrolling upwards					*scroll-up*
66
67The following commands move the edit window (the part of the buffer that you
68see) upwards (this means that more lines upwards in the text buffer can be
69seen):
70
71							*CTRL-Y*
72CTRL-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*
77CTRL-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*
92CTRL-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^*
98z^			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==============================================================================
1083. Scrolling relative to cursor				*scroll-cursor*
109
110The following commands reposition the edit window (the part of the buffer that
111you see) while keeping the cursor on the same line:
112
113							*z<CR>*
114z<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*
119zt			Like "z<CR>", but leave the cursor in the same
120			column.  {not in Vi}
121
122							*zN<CR>*
123z{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.*
129z.			Redraw, line [count] at center of window (default
130			cursor line).  Put cursor at first non-blank in the
131			line.
132
133							*zz*
134zz			Like "z.", but leave the cursor in the same column.
135			Careful: If caps-lock is on, this command becomes
136			"ZZ": write buffer and exit!  {not in Vi}
137
138							*z-*
139z-			Redraw, line [count] at bottom of window (default
140			cursor line).  Put cursor at first non-blank in the
141			line.
142
143							*zb*
144zb			Like "z-", but leave the cursor in the same column.
145			{not in Vi}
146
147==============================================================================
1484. Scrolling horizontally				*scroll-horizontal*
149
150For the following four commands the cursor follows the screen.  If the
151character that the cursor is on is moved off the screen, the cursor is moved
152to the closest character that is on the screen.  The value of 'sidescroll' is
153not used.
154
155z<Right>    or						*zl* *z<Right>*
156zl			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
161z<Left>      or						*zh* *z<Left>*
162zh			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*
168zL			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*
174zH			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
179For the following two commands the cursor is not moved in the text, only the
180text scrolls on the screen.
181
182							*zs*
183zs			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*
188ze			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==============================================================================
1935. Scrolling synchronously				*scroll-binding*
194
195Occasionally, it is desirable to bind two or more windows together such that
196when one window is scrolled, the other windows are also scrolled.  In Vim,
197windows can be given this behavior by setting the (window-specific)
198'scrollbind' option.  When a window that has 'scrollbind' set is scrolled, all
199other 'scrollbind' windows are scrolled the same amount, if possible.  The
200behavior of 'scrollbind' can be modified by the 'scrollopt' option.
201
202When using the scrollbars, the binding only happens when scrolling the window
203with focus (where the cursor is).  You can use this to avoid scroll-binding
204for a moment without resetting options.
205
206When a window also has the 'diff' option set, the scroll-binding uses the
207differences between the two buffers to synchronize the position precisely.
208Otherwise the following method is used.
209
210							*scrollbind-relative*
211Each 'scrollbind' window keeps track of its "relative offset," which can be
212thought of as the difference between the current window's vertical scroll
213position 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
215limit of its text, the window no longer scrolls, but remembers how far past
216the limit it wishes to be.  The window keeps this information so that it can
217maintain the same relative offset, regardless of its being asked to scroll
218past its buffer's limits.
219
220However, if a 'scrollbind' window that has a relative offset that is past its
221buffer's limits is given the cursor focus, the other 'scrollbind' windows must
222jump to a location where the current window's relative offset is valid.  This
223behavior can be changed by clearing the 'jump' flag from the 'scrollopt'
224option.
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*
234The 'scrollbind' flag is meaningful when using keyboard commands to vertically
235scroll a window, and also meaningful when using the vertical scrollbar of the
236window which has the cursor focus.  However, when using the vertical scrollbar
237of a window which doesn't have the cursor focus, 'scrollbind' is ignored.
238This allows quick adjustment of the relative offset of 'scrollbind' windows.
239
240==============================================================================
2416. Scrolling with a mouse wheel				*scroll-mouse-wheel*
242
243When your mouse has a scroll wheel, it should work with Vim in the GUI.  How
244it works depends on your system.  It might also work in an xterm
245|xterm-mouse-wheel|.  By default only vertical scroll wheels are supported,
246but some GUIs also support horizontal scroll wheels.
247
248For the Win32 GUI the scroll action is hard coded.  It works just like
249dragging the scrollbar of the current window.  How many lines are scrolled
250depends on your mouse driver.  If the scroll action causes input focus
251problems, see |intellimouse-wheel-problems|.
252
253For the X11 GUIs (Motif, Athena and GTK) scrolling the wheel generates key
254presses <ScrollWheelUp>, <ScrollWheelDown>, <ScrollWheelLeft> and
255<ScrollWheelRight>.  For example, if you push the scroll wheel upwards a
256<ScrollWheelUp> key press is generated causing the window to scroll upwards
257(while the text is actually moving downwards).  The default action for these
258keys are:
259    <ScrollWheelUp>	    scroll three lines up	*<ScrollWheelUp>*
260    <S-ScrollWheelUp>	    scroll one page up		*<S-ScrollWheelUp>*
261    <C-ScrollWheelUp>	    scroll one page up		*<C-ScrollWheelUp>*
262    <ScrollWheelDown>	    scroll three lines down	*<ScrollWheelDown>*
263    <S-ScrollWheelDown>	    scroll one page down	*<S-ScrollWheelDown>*
264    <C-ScrollWheelDown>	    scroll one page down	*<C-ScrollWheelDown>*
265    <ScrollWheelLeft>	    scroll six columns left	*<ScrollWheelLeft>*
266    <S-ScrollWheelLeft>	    scroll one page left	*<S-ScrollWheelLeft>*
267    <C-ScrollWheelLeft>	    scroll one page left	*<C-ScrollWheelLeft>*
268    <ScrollWheelRight>	    scroll six columns right	*<ScrollWheelRight>*
269    <S-ScrollWheelRight>    scroll one page right	*<S-ScrollWheelRight>*
270    <C-ScrollWheelRight>    scroll one page right	*<C-ScrollWheelRight>*
271This should work in all modes, except when editing the command line.
272
273Note that horizontal scrolling only works if 'nowrap' is set.  Also, unless
274the "h" flag in 'guioptions' is set, the cursor moves to the longest visible
275line if the cursor line is about to be scrolled off the screen (similarly to
276how the horizontal scrollbar works).
277
278You can modify the default behavior by mapping the keys.  For example, to make
279the scroll wheel move one line or half a page in Normal mode: >
280   :map <ScrollWheelUp> <C-Y>
281   :map <S-ScrollWheelUp> <C-U>
282   :map <ScrollWheelDown> <C-E>
283   :map <S-ScrollWheelDown> <C-D>
284You can also use Alt and Ctrl modifiers.
285
286This only works when Vim gets the scroll wheel events, of course.  You can
287check if this works with the "xev" program.
288
289When using XFree86, the /etc/XF86Config file should have the correct entry for
290your mouse.  For FreeBSD, this entry works for a Logitech scrollmouse: >
291    Protocol     "MouseMan"
292    Device       "/dev/psm0"
293    ZAxisMapping 4 5
294See the XFree86 documentation for information.
295
296						*<MouseDown>* *<MouseUp>*
297The keys <MouseDown> and <MouseUp> have been deprecated.  Use <ScrollWheelUp>
298instead of <MouseDown> and use <ScrollWheelDown> instead of <MouseUp>.
299
300							*xterm-mouse-wheel*
301To use the mouse wheel in a new xterm you only have to make the scroll wheel
302work in your Xserver, as mentioned above.
303
304To use the mouse wheel in an older xterm you must do this:
3051. Make it work in your Xserver, as mentioned above.
3062. Add translations for the xterm, so that the xterm will pass a scroll event
307   to Vim as an escape sequence.
3083. Add mappings in Vim, to interpret the escape sequences as <ScrollWheelDown>
309   or <ScrollWheelUp> keys.
310
311You can do the translations by adding this to your ~.Xdefaults file (or other
312file where your X resources are kept): >
313
314  XTerm*VT100.Translations:		#override \n\
315		s<Btn4Down>: string("0x9b") string("[64~") \n\
316		s<Btn5Down>: string("0x9b") string("[65~") \n\
317		<Btn4Down>: string("0x9b") string("[62~") \n\
318		<Btn5Down>: string("0x9b") string("[63~") \n\
319		<Btn4Up>: \n\
320		<Btn5Up>:
321
322Add these mappings to your vimrc file: >
323	:map <M-Esc>[62~ <ScrollWheelUp>
324	:map! <M-Esc>[62~ <ScrollWheelUp>
325	:map <M-Esc>[63~ <ScrollWheelDown>
326	:map! <M-Esc>[63~ <ScrollWheelDown>
327	:map <M-Esc>[64~ <S-ScrollWheelUp>
328	:map! <M-Esc>[64~ <S-ScrollWheelUp>
329	:map <M-Esc>[65~ <S-ScrollWheelDown>
330	:map! <M-Esc>[65~ <S-ScrollWheelDown>
331<
332 vim:tw=78:ts=8:ft=help:norl:
333