| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section 38.3 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 section 38.16 Usual Display Conventions.
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, Emacs provides caches which may improve the performance of your code. See section cache-long-line-scans.
vertical-motion returns the number of screen lines over which it
moved point. The value may be less in absolute value than count
if the beginning or end of the buffer was reached.
The window window is used for obtaining parameters such as the
width, the horizontal scrolling, and the display table. But
vertical-motion always operates on the current buffer, even if
window currently displays some other buffer.
nil or omitted,
they default to the beginning and end of the accessible portion of the
buffer.
If the region ends with a newline, that is ignored unless the optional
third argument count-final-newline is non-nil.
The optional fourth argument window specifies the window for obtaining parameters such as width, horizontal scrolling, and so on. The default is to use the selected window's parameters.
Like vertical-motion, count-screen-lines always uses the
current buffer, regardless of which buffer is displayed in
window. This makes possible to use count-screen-lines in
any buffer, whether or not it is currently displayed in some window.
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.
The coordinate arguments frompos and topos are cons cells of
the form (hpos . vpos).
The argument width is the number of columns available to display
text; this affects handling of continuation lines. Use the value
returned by window-width for the window of your choice;
normally, use (window-width window).
The argument offsets is either nil or a cons cell of the
form (hscroll . tab-offset). Here hscroll is
the number of columns not being displayed at the left margin; most
callers get this by calling window-hscroll. Meanwhile,
tab-offset is the offset between column numbers on the screen and
column numbers in the buffer. This can be nonzero in a continuation
line, when the previous screen lines' widths do not add up to a multiple
of tab-width. It is always zero in a non-continuation line.
The window window serves only to specify which display table to
use. compute-motion always operates on the current buffer,
regardless of what buffer is displayed in window.
The return value is a list of five elements:
(pos vpos hpos prevhpos contin) |
Here pos is the buffer position where the scan stopped, vpos is the vertical screen position, and hpos is the horizontal screen position.
The result prevhpos is the horizontal position one character back
from pos. The result contin is t if the last line
was continued after (or within) the previous character.
For example, to find the buffer position of column col of screen line
line of a certain window, pass the window's display start location
as from and the window's upper-left coordinates as frompos.
Pass the buffer's (point-max) as to, to limit the scan to
the end of the accessible portion of the buffer, and pass line and
col as topos. Here's a function that does this:
(defun coordinates-of-position (col line)
(car (compute-motion (window-start)
'(0 . 0)
(point-max)
(cons col line)
(window-width)
(cons (window-hscroll) 0)
(selected-window))))
|
When you use compute-motion for the minibuffer, you need to use
minibuffer-prompt-width to get the horizontal position of the
beginning of the first screen line. See section 20.9 Minibuffer Miscellany.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |