path: root/devdocs/elisp/screen-lines.html

 <h4 class="subsection">Motion by Screen Lines</h4>   <p>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. </p> <p>In some cases, text lines are truncated on the screen rather than continued onto additional screen lines. In these cases, <code>vertical-motion</code> moves point much like <code>forward-line</code>. See <a href="truncation">Truncation</a>. </p> <p>Because the width of a given string depends on the flags that control the appearance of certain characters, <code>vertical-motion</code> 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 <a href="usual-display">Usual Display</a>. </p> <p>These functions scan text to determine where screen lines break, and thus take time proportional to the distance scanned. </p> <dl> <dt id="vertical-motion">Function: <strong>vertical-motion</strong> <em>count &amp;optional window cur-col</em>
</dt> <dd>
<p>This function moves point to the start of the screen line <var>count</var> screen lines down from the screen line containing point. If <var>count</var> is negative, it moves up instead. </p> <p>The <var>count</var> argument can be a cons cell, <code>(<var>cols</var>
. <var>lines</var>)</code>, instead of an integer. Then the function moves by <var>lines</var> screen lines, and puts point <var>cols</var> columns from the visual start of that screen line. Note that <var>cols</var> are counted from the <em>visual</em> start of the line; if the window is scrolled horizontally (see <a href="horizontal-scrolling">Horizontal Scrolling</a>), the column on which point will end is in addition to the number of columns by which the text is scrolled. </p> <p>The return value is the number of screen lines over which point was moved. The value may be less in absolute value than <var>count</var> if the beginning or end of the buffer was reached. </p> <p>The window <var>window</var> is used for obtaining parameters such as the width, the horizontal scrolling, and the display table. But <code>vertical-motion</code> always operates on the current buffer, even if <var>window</var> currently displays some other buffer. </p> <p>The optional argument <var>cur-col</var> specifies the current column when the function is called. This is the window-relative horizontal coordinate of point, measured in units of font width of the frame’s default face. Providing it speeds up the function, especially in very long lines, because the function doesn’t have to go back in the buffer in order to determine the current column. Note that <var>cur-col</var> is also counted from the visual start of the line. </p>
</dd>
</dl> <dl> <dt id="count-screen-lines">Function: <strong>count-screen-lines</strong> <em>&amp;optional beg end count-final-newline window</em>
</dt> <dd>
<p>This function returns the number of screen lines in the text from <var>beg</var> to <var>end</var>. The number of screen lines may be different from the number of actual lines, due to line continuation, the display table, etc. If <var>beg</var> and <var>end</var> are <code>nil</code> or omitted, they default to the beginning and end of the accessible portion of the buffer. </p> <p>If the region ends with a newline, that is ignored unless the optional third argument <var>count-final-newline</var> is non-<code>nil</code>. </p> <p>The optional fourth argument <var>window</var> specifies the window for obtaining parameters such as width, horizontal scrolling, and so on. The default is to use the selected window’s parameters. </p> <p>Like <code>vertical-motion</code>, <code>count-screen-lines</code> always uses the current buffer, regardless of which buffer is displayed in <var>window</var>. This makes possible to use <code>count-screen-lines</code> in any buffer, whether or not it is currently displayed in some window. </p>
</dd>
</dl> <dl> <dt id="move-to-window-line">Command: <strong>move-to-window-line</strong> <em>count</em>
</dt> <dd>
<p>This function moves point with respect to the text currently displayed in the selected window. It moves point to the beginning of the screen line <var>count</var> screen lines from the top of the window; zero means the topmost line. If <var>count</var> is negative, that specifies a position -<var>count</var> lines from the bottom (or the last line of the buffer, if the buffer ends above the specified screen position); thus, <var>count</var> of -1 specifies the last fully visible screen line of the window. </p> <p>If <var>count</var> is <code>nil</code>, then point moves to the beginning of the line in the middle of the window. If the absolute value of <var>count</var> 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. </p> <p>In an interactive call, <var>count</var> is the numeric prefix argument. </p> <p>The value returned is the screen line number point has moved to, relative to the top line of the window. </p>
</dd>
</dl>  <dl> <dt id="move-to-window-group-line">Function: <strong>move-to-window-group-line</strong> <em>count</em>
</dt> <dd><p>This function is like <code>move-to-window-line</code>, except that when the selected window is a part of a group of windows (see <a href="selecting-windows#Window-Group">Window Group</a>), <code>move-to-window-group-line</code> will move to a position with respect to the entire group, not just the single window. This condition holds when the buffer local variable <code>move-to-window-group-line-function</code> is set to a function. In this case, <code>move-to-window-group-line</code> calls the function with the argument <var>count</var>, then returns its result. </p></dd>
</dl> <dl> <dt id="compute-motion">Function: <strong>compute-motion</strong> <em>from frompos to topos width offsets window</em>
</dt> <dd>
<p>This function scans the current buffer, calculating screen positions. It scans the buffer forward from position <var>from</var>, assuming that is at screen coordinates <var>frompos</var>, to position <var>to</var> or coordinates <var>topos</var>, whichever comes first. It returns the ending buffer position and screen coordinates. </p> <p>The coordinate arguments <var>frompos</var> and <var>topos</var> are cons cells of the form <code>(<var>hpos</var> . <var>vpos</var>)</code>. </p> <p>The argument <var>width</var> is the number of columns available to display text; this affects handling of continuation lines. <code>nil</code> means the actual number of usable text columns in the window, which is equivalent to the value returned by <code>(window-width window)</code>. </p> <p>The argument <var>offsets</var> is either <code>nil</code> or a cons cell of the form <code>(<var>hscroll</var> . <var>tab-offset</var>)</code>. Here <var>hscroll</var> is the number of columns not being displayed at the left margin; most callers get this by calling <code>window-hscroll</code>. Meanwhile, <var>tab-offset</var> 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 <code>tab-width</code>. It is always zero in a non-continuation line. </p> <p>The window <var>window</var> serves only to specify which display table to use. <code>compute-motion</code> always operates on the current buffer, regardless of what buffer is displayed in <var>window</var>. </p> <p>The return value is a list of five elements: </p> <div class="example"> <pre class="example">(<var>pos</var> <var>hpos</var> <var>vpos</var> <var>prevhpos</var> <var>contin</var>)
</pre>
</div> <p>Here <var>pos</var> is the buffer position where the scan stopped, <var>vpos</var> is the vertical screen position, and <var>hpos</var> is the horizontal screen position. </p> <p>The result <var>prevhpos</var> is the horizontal position one character back from <var>pos</var>. The result <var>contin</var> is <code>t</code> if the last line was continued after (or within) the previous character. </p> <p>For example, to find the buffer position of column <var>col</var> of screen line <var>line</var> of a certain window, pass the window’s display start location as <var>from</var> and the window’s upper-left coordinates as <var>frompos</var>. Pass the buffer’s <code>(point-max)</code> as <var>to</var>, to limit the scan to the end of the accessible portion of the buffer, and pass <var>line</var> and <var>col</var> as <var>topos</var>. Here’s a function that does this: </p> <div class="example"> <pre class="example">(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))))
</pre>
</div> <p>When you use <code>compute-motion</code> for the minibuffer, you need to use <code>minibuffer-prompt-width</code> to get the horizontal position of the beginning of the first screen line. See <a href="minibuffer-contents">Minibuffer Contents</a>. </p>
</dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Screen-Lines.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Screen-Lines.html</a>
  </p>
</div>