bug#41737: 26.3; (window-text-pixel-size) in console

[Eli Zaretskii]

> From: Tomas Hlavaty <tom@logand.com>
> Date: Sat, 06 Jun 2020 14:47:14 +0200
> 
> (window-text-pixel-size) in console seems to be wrong.

I don't think it's wrong, I think the doc string needs clarification
(which I just did).

> The width seems to the width of the (visible) window.

If the text is as wide or wider than the window, then by default this
is what is expected, yes.

> The height seems to be number of lines in a file.

On a TTY frame, yes.

> However, when evaluated in notmuch thread, the cdr of the return
> value is a number which I cannot interpret (it is not number of
> lines in the buffer and it is now height of the visible window).

I'd need to see an example to respond to that.  But maybe using the
new doc string (below) you will be able to understand what happens in
that use case as well.

>    Return the size 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
>    maximum pixel-height of all text lines.
> 
> I suppose that pixel in console is one character.

Yes, that is a general rule in TTY frames.

>    the maximum pixel-width of any text line
> 
> but this does not seem to be true.  I have file with long line but it
> still returns number of visible columns.

Right, by default text beyond window's width is ignored.  It was not
immediately clear from the doc string; I hope it is more clear now.

>    maximum pixel-height of all text lines
> 
> It is not clean, what does that mean and the returned number doesn't
> seem to be useful for anything.

I clarified that as well.

The doc string now says:

  Return the size 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.

  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 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 large 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.  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 maxcomp 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-AND-HEADER-LINE nil or omitted means do not
  include the height of the mode- or header-line of WINDOW in the return
  value.  If it is either the symbol `mode-line' or `header-line', include
  only the height of that line, if present, in the return value.  If t,
  include the height of both, if present, in the return value.