RE: frame-pixel-(width|height) is incorrect

["Drew Adams" <drew.adams@oracle.com>]

> From: Jason Rumney Sent: Friday, December 21, 2007 1:18 AM
> > emacs -Q
> >
> > I've checked the pixel size of Emacs frames with a couple of tools on
> > Windows, and these functions both return incorrect results:
> > frame-pixel-width, frame-pixel-height.
>
> They return results consistent with their documentation.

Well, their doc is pretty skimpy. I'm using Emacs 22.1 (release).

(My concern is for a window-mgr frame, not a terminal frame, BTW.)

The doc strings say only that the functions "return frame's width in pixels"
(or height). Practically useless. The Elisp manual says only: "the height
and width of FRAME, measured in pixels". Just as useless. There is nowhere
any information about which parts of the frame are included.

David quotes the doc as stating that only the height available for text is
counted. Perhaps he has a more recent version of Emacs - I don't see that
doc in Emacs 22.1.

Checking the code, I'm led from `frame-pixel-width' to `x_pixel_width' to
`FRAME_PIXEL_WIDTH' to `FRAME_TEXT_COLS_TO_PIXEL_WIDTH' after several greps.
And there I see this:

#define FRAME_TEXT_COLS_TO_PIXEL_WIDTH(f, cols) \
  (FRAME_COL_TO_PIXEL_X (f, cols) \
   + (f)->scroll_bar_actual_width \
   + FRAME_TOTAL_FRINGE_WIDTH (f)      \
   + FRAME_INTERNAL_BORDER_WIDTH (f))

So, it looks like the doc should say that it is the width of the text area
inside a frame plus the width of the scroll bar (if visible) plus the width
of the internal frame border. Similarly, for height.

I agree with David that these functions, or possibly some other functions,
should give the _outside_ dimensions of the frame.

For this or whatever functions do provide the _outside_ frame dimensions:

If the window-mgr title bar thickness (height) cannot be known, then so be
it - just mention that it includes everything else - but see below for a
better approach. If there is another exception (I don't think there is),
then mention that too. The doc must be explicit about what is measured;
otherwise, it is little help.

In particular, this means that the outside-dimension functions should
include the `border-width' frame parameter, that is, the external frame
border, as well as the internal border.

David gave the reason that outside-dimension functions are needed:
calculating frame sizes and positions. One example is tiling frames.

Another suggestion: If it is indeed impossible for Emacs to obtain the
title-bar thickness (height), then this should be a user option, and its
value should be included in the outside frame dimension calculations. That
way, a user can at least measure the title bar by hand once, customize the
option, and thereafter count on accurate frame-size calculations.

BTW, in my original bug report, I was mistakenly assuming that the functions
frame-pixel-* returned outside dimensions. That is what I am after, whether
by these functions or some new functions.

Thx.