Function: window-text-pixel-size

window-text-pixel-size is a function defined in xdisp.c.

Signature

(window-text-pixel-size &optional WINDOW FROM TO X-LIMIT Y-LIMIT MODE-LINES IGNORE-LINE-AT-END)

Documentation

Return the dimensions of the text of WINDOW's buffer in pixels.

WINDOW must be a live window and defaults to the selected one. The return value is a cons of the maximum pixel-width of any text line and the pixel-height of all the text lines in the accessible portion of buffer text.

If FROM is a cons cell, the return value includes, in addition to the dimensions, also a third element that provides the buffer position from which measuring of the text dimensions was actually started.

This function exists to allow Lisp programs to adjust the dimensions of WINDOW to the buffer text it needs to display.

The optional argument FROM, if non-nil, specifies the first text position to consider, and defaults to the minimum accessible position of the buffer. If FROM is a cons, its car specifies a buffer position, and its cdr specifies the vertical offset in pixels from that position to the first screen line to be measured. If FROM is t, it stands for the minimum accessible position that starts a non-empty line. TO, if non-nil, specifies the last text position and defaults to the maximum accessible position of the buffer. If TO is t, it stands for the maximum accessible position that ends a non-empty line.

The optional argument X-LIMIT, if non-nil, specifies the maximum X coordinate beyond which the text should be ignored. It is therefore also the maximum width that the function can return. X-LIMIT nil or omitted means to use the pixel-width of WINDOW's body. This default means text of truncated lines wider than the window will be ignored; specify a non-nil value for X-LIMIT if lines are truncated and you need to account for the truncated text.

Use nil for X-LIMIT if you want to know how high WINDOW should become in order to fit all of its buffer's text with the width of WINDOW unaltered. Use the maximum width WINDOW may assume if you intend to change WINDOW's width. Use t for the maximum possible value. Since calculating the width of long lines can take some time, it's always a good idea to make this argument as small as possible; in particular, if the buffer contains long lines that shall be truncated anyway.

The optional argument Y-LIMIT, if non-nil, specifies the maximum Y coordinate beyond which the text is to be ignored; it is therefore also the maximum height that the function can return (excluding the height of the mode- or header-line, if any). Y-LIMIT nil or omitted means consider all of the accessible portion of buffer text up to the position specified by TO. Since calculating the text height of a large buffer can take some time, it makes sense to specify this argument if the size of the buffer is large or unknown.

Optional argument MODE-LINES nil or omitted means do not include the height of the mode-, tab- or header-line of WINDOW in the return value. If it is the symbol mode-line, tab-line or header-line, include only the height of that line, if present, in the return value. If t, include the height of any of these, if present, in the return value.

IGNORE-LINE-AT-END, if non-nil, means to not add the height of the screen line that includes TO to the returned height of the text.

View in manual

Probably introduced at or before Emacs version 24.4.

Source Code

// Defined in /usr/src/emacs/src/xdisp.c
{
  struct window *w = decode_live_window (window);
  struct buffer *b = XBUFFER (w->contents);
  struct buffer *old_b = NULL;
  Lisp_Object value;

  if (b != current_buffer)
    {
      old_b = current_buffer;
      set_buffer_internal_1 (b);
    }

  value = window_text_pixel_size (window, from, to, x_limit, y_limit, mode_lines,
				  ignore_line_at_end);

  if (old_b)
    set_buffer_internal_1 (old_b);

  return value;
}