Commit 89bd5ee1 authored by Eli Zaretskii's avatar Eli Zaretskii

Fix documentation per bug #9949.

 src/window.c (Fwindow_body_size): Mention in the doc string that the
 return value is in frame's canonical units.
 lisp/window.el (window-body-height, window-body-width): Mention in
 the doc string that the return values are in frame's canonical
 units.
 doc/lispref/windows.texi (Window Sizes): Mention in the doc string that the
 return values of `window-body-height' and `window-body-width' are
 in frame's canonical units.
parent 56c31147
2011-11-04 Eli Zaretskii <eliz@gnu.org>
* windows.texi (Window Sizes): Mention in the doc string that the
return values of `window-body-height' and `window-body-width' are
in frame's canonical units. (Bug#9949)
2011-10-30 Martin Rudalics <rudalics@gmx.at>
* windows.texi (Windows and Frames): Remove "iso-" infix from
......
......@@ -563,8 +563,18 @@ window's body width.
@cindex body size of a window
@cindex window body size
The following functions retrieve height and width of the body of a live
window:
@cindex canonical units of window/frame size
The following functions retrieve height and width of the body of a
live window. Note that the values these functions return are measured
in @dfn{canonical units}, i.e.@: for the default frame's face. If the
window shows some characters with non-default face, e.g., if the font
of some characters is larger or smaller than the default font, the
values returned by these functions will not match the actual number of
lines or characters per line shown in the window. To get the actual
number of columns and lines, move to the last character in the line
(e.g., with @code{end-of-visual-line}) or to the last line of the
window (e.g., with @code{window-end}), and use @code{posn-at-point} to
find the line or column there.
@defun window-body-size &optional window horizontal
This function returns the number of lines of @var{window}'s text area.
......
2011-11-04 Eli Zaretskii <eliz@gnu.org>
* window.el (window-body-height, window-body-width): Mention in
the doc string that the return values are in frame's canonical
units. (Bug#9949)
2011-11-03 Alan Mackenzie <acm@muc.de>
* progmodes/cc-langs.el (c-nonlabel-token-2-key): New variable for
......
......@@ -972,7 +972,14 @@ The return value does not include WINDOW's mode line and header
line, if any. If a line at the bottom of the window is only
partially visible, that line is included in the return value. If
you do not want to include a partially visible bottom line in the
return value, use `window-text-height' instead."
return value, use `window-text-height' instead.
Note that the return value is measured in canonical units, i.e. for
the default frame's face. If the window shows some characters with
non-default face, e.g., if the font of some characters is larger or
smaller than the default font, the value returned by this function
will not match the actual number of lines shown in the window. To
get the actual number of lines, use `posn-at-point'."
(window-body-size window))
(defsubst window-body-width (&optional window)
......@@ -982,7 +989,14 @@ WINDOW must be a live window and defaults to the selected one.
The return value does not include any vertical dividers or scroll
bars owned by WINDOW. On a window-system the return value does
not include the number of columns used for WINDOW's fringes or
display margins either."
display margins either.
Note that the return value is measured in canonical units, i.e. for
the default frame's face. If the window shows some characters with
non-default face, e.g., if the font of some characters is larger or
smaller than the default font, the value returned by this function
will not match the actual number of characters per line shown in the
window. To get the actual number of columns, use `posn-at-point'."
(window-body-size window t))
;; Eventually we should make `window-height' obsolete.
......
2011-11-04 Eli Zaretskii <eliz@gnu.org>
* window.c (Fwindow_body_size): Mention in the doc string that the
return value is in frame's canonical units. (Bug#9949)
2011-11-03 Eli Zaretskii <eliz@gnu.org>
* xdisp.c (note_mouse_highlight): Initialize `area'. (Bug#9947)
......
......@@ -653,16 +653,25 @@ window_body_cols (struct window *w)
}
DEFUN ("window-body-size", Fwindow_body_size, Swindow_body_size, 0, 2, 0,
doc: /* Return the number of lines of WINDOW's body.
WINDOW must be a live window and defaults to the selected one. The
return value does not include WINDOW's mode line and header line, if
any.
Optional argument HORIZONTAL non-nil means return the number of columns
of WINDOW's body. In this case, the return value does not include any
vertical dividers or scroll bars owned by WINDOW. On a window-system
the return value does not include the number of columns used for
WINDOW's fringes or display margins either. */)
doc: /* Return the number of lines or columns of WINDOW's body.
WINDOW must be a live window and defaults to the selected one.
If the optional argument HORIZONTAL is omitted or nil, the function
returns the number of WINDOW's lines, excluding the mode line and
header line, if any.
If HORIZONTAL is non-nil, the function returns the number of columns
excluding any vertical dividers or scroll bars owned by WINDOW. On a
window-system the return value also excludes the number of columns
used for WINDOW's fringes or display margins.
Note that the return value is measured in canonical units, i.e. for
the default frame's face. If the window shows some characters with
non-default face, e.g., if the font of some characters is larger or
smaller than the default font, the value returned by this function
will not match the actual number of lines or characters per line
shown in the window. To get the actual number of columns and lines,
use `posn-at-point'. */)
(Lisp_Object window, Lisp_Object horizontal)
{
struct window *w = decode_any_window (window);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment