41.2.5 Motion by Screen Lines

The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen lines, which are defined by the way the text appears on the screen. A text line is a single screen line if it is short enough to fit the width of the selected window, but otherwise it may occupy several screen lines.

In some cases, text lines are truncated on the screen rather than continued onto additional screen lines. In these cases, vertical-motion moves point much like forward-line. See Truncation.

Because the width of a given string depends on the flags that control the appearance of certain characters, vertical-motion behaves differently, for a given piece of text, depending on the buffer it is in, and even on the selected window (because the width, the truncation flag, and display table may vary between windows). See Usual Display.

These functions scan text to determine where screen lines break, and thus take time proportional to the distance scanned. If you intend to use them heavily, SXEmacs provides caches which may improve the performance of your code. See cache-long-line-scans.

Function: vertical-motion count &optional window pixels

This function moves point to the start of the frame line count frame lines down from the frame line containing point. If count is negative, it moves up instead. The optional second argument window may be used to specify a window other than the selected window in which to perform the motion.

Normally, vertical-motion returns the number of lines moved. The value may be less in absolute value than count if the beginning or end of the buffer was reached. If the optional third argument, pixels is non-nil, the vertical pixel height of the motion which took place is returned instead of the actual number of lines moved. A motion of zero lines returns the height of the current line.

Note that vertical-motion sets window’s buffer’s point, not window’s point. (This differs from FSF Emacs, which buggily always sets current buffer’s point, regardless of window.)

Function: vertical-motion-pixels count &optional window how

This function moves point to the start of the frame line pixels vertical pixels down from the frame line containing point, or up if pixels is negative. The optional second argument window is the window to move in, and defaults to the selected window. The optional third argument how specifies the stopping condition. A negative integer indicates that the motion should be no more than pixels. A positive value indicates that the motion should be at least pixels. Any other value indicates that the motion should be as close as possible to pixels.

Command: move-to-window-line count &optional window

This function moves point with respect to the text currently displayed in window, which defaults to the selected window. It moves point to the beginning of the screen line count screen lines from the top of the window. If count is negative, that specifies a position -count lines from the bottom (or the last line of the buffer, if the buffer ends above the specified screen position).

If count is nil, then point moves to the beginning of the line in the middle of the window. If the absolute value of count is greater than the size of the window, then point moves to the place that would appear on that screen line if the window were tall enough. This will probably cause the next redisplay to scroll to bring that location onto the screen.

In an interactive call, count is the numeric prefix argument.

The value returned is the window line number point has moved to, with the top line in the window numbered 0.