From: Eli Zaretskii Date: Fri, 4 Nov 2011 10:09:41 +0000 (+0200) Subject: Fix documentation per bug #9949. X-Git-Tag: emacs-pretest-24.0.92~218^2~25 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=89bd5ee15acb93aefd403f3c76d1aff57520608b;p=emacs.git 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. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 1e86e07998c..2da562bdcfb 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,9 @@ +2011-11-04 Eli Zaretskii + + * 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 * windows.texi (Windows and Frames): Remove "iso-" infix from diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 37679aa4a0b..bd20f5d8f44 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -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. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 6352a65e4fc..eb276721dbc 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,9 @@ +2011-11-04 Eli Zaretskii + + * 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 * progmodes/cc-langs.el (c-nonlabel-token-2-key): New variable for diff --git a/lisp/window.el b/lisp/window.el index 9b12c204d48..d6ab5e0e6cc 100644 --- a/lisp/window.el +++ b/lisp/window.el @@ -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. diff --git a/src/ChangeLog b/src/ChangeLog index f198f37d0c1..ccfcb48daf0 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,8 @@ +2011-11-04 Eli Zaretskii + + * 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 * xdisp.c (note_mouse_highlight): Initialize `area'. (Bug#9947) diff --git a/src/window.c b/src/window.c index 422073b1bd3..6b3b7f2a471 100644 --- a/src/window.c +++ b/src/window.c @@ -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);