[Emacs-diffs] /srv/bzr/emacs/trunk r106493: Update Coordinates and Windows node of Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106493
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Thu 2011-11-24 00:25:11 +0800
message:
  Update Coordinates and Windows node of Lisp manual.
  
  * doc/lispref/windows.texi (Window Sizes): Move window-top-line,
  window-left-column, and window-*-pixel-edges to Coordinates and
  Windows node.
  (Coordinates and Windows): Restore window-edges doc.
modified:
  doc/lispref/ChangeLog
  doc/lispref/windows.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-11-21 07:28:06 +0000
+++ b/doc/lispref/ChangeLog     2011-11-23 16:25:11 +0000
@@ -1,3 +1,10 @@
+2011-11-23  Chong Yidong  <address@hidden>
+
+       * windows.texi (Window Sizes): Move window-top-line,
+       window-left-column, and window-*-pixel-edges to Coordinates and
+       Windows node.
+       (Coordinates and Windows): Restore window-edges doc.
+
 2011-11-21  Martin Rudalics  <address@hidden>
 
        * windows.texi (Windows and Frames, Splitting Windows): Fix

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2011-11-21 07:28:06 +0000
+++ b/doc/lispref/windows.texi  2011-11-23 16:25:11 +0000
@@ -376,7 +376,7 @@
 line (@pxref{Mode Line Format}).
 
   Emacs provides several functions for finding the height and width of
-a window.  Except where noted, these heights and widths are reported
+a window.  Except where noted, Emacs reports window heights and widths
 as integer numbers of lines and columns respectively.  On a graphical
 display, each ``line'' and ``column'' actually corresponds to the
 height and width of a ``default'' character specified by the frame's
@@ -439,26 +439,6 @@
 @code{nil}, it defaults to the selected window.
 @end defun
 
address@hidden window position
-  The following functions can be used to determine the position of a
-window relative to the window area of its frame:
-
address@hidden window-top-line &optional window
-This function returns the distance, in lines, between the top of
address@hidden and the top of the frame's window area.  For instance,
-the return value is 0 if there is no window above @var{window}.  If
address@hidden is omitted or @code{nil}, it defaults to the selected
-window.
address@hidden defun
-
address@hidden window-left-column &optional window
-This function returns the distance, in columns, between the left edge
-of @var{window} and the left edge of the frame's window area.  For
-instance, the return value is 0 if there is no window to the left of
address@hidden  If @var{window} is omitted or @code{nil}, it defaults
-to the selected window.
address@hidden defun
-
 @cindex window body height
 @cindex body height of a window
 @cindex window body width
@@ -535,45 +515,12 @@
 function @code{window-resizable}.  @xref{Resizing Windows}.
 @end defun
 
-  The following functions can be used to find a window's size and
-position in pixels.  Though mostly useful on graphical displays, they
-can also be called on text-only terminals, where the screen area of
-each text character is taken to be ``one pixel''.
-
address@hidden window-pixel-edges &optional window
-This function return a list of pixel coordinates for the edges of
address@hidden  If @var{window} is omitted or @code{nil}, it defaults
-to the selected window.
-
-The return value has the form @code{(@var{left} @var{top} @var{right}
address@hidden)}.  The list elements are, respectively, the X coordinate
-of the left window edge, the Y coordinate of the top edge, one more
-than the X coordinate of the right edge, and one more than the Y
-coordinate of the bottom edge.  The origin coordinate @samp{(0,0)} is
-taken to be the top left corner of the frame's window area.
-
-These edge values include the space used by the window's scroll bar,
-margins, fringes, header line, and mode line, if any.
address@hidden defun
-
address@hidden window-inside-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the edge coordinates for the window's text area, rather than
-the edge coordinates for the window itself.  @var{window} must specify
-a live window.
address@hidden defun
-
address@hidden window-absolute-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the edge coordinates relative to the top left corner of the
-display screen.
address@hidden defun
-
address@hidden window-inside-absolute-pixel-edges &optional window
-This function is like @code{window-inside-pixel-edges}, except that it
-returns the edge coordinates relative to the top left corner of the
-display screen.  @var{window} must specify a live window.
address@hidden defun
+  @xref{Coordinates and Windows}, for more functions that report the
+positions of various parts of a window relative to the frame, from
+which you can calculate its size.  In particular, you can use the
+functions @code{window-pixel-edges} and
address@hidden to find the size in pixels, for
+graphical displays.
 
 @node Resizing Windows
 @section Resizing Windows
@@ -2976,32 +2923,90 @@
 @end group
 @end example
 
-
 @node Coordinates and Windows
 @section Coordinates and Windows
-
-This section describes how to relate screen coordinates to windows.
address@hidden frame-relative coordinate
address@hidden coordinate, relative to frame
address@hidden window position
+
+  This section describes functions that report the position of a
+window.  Most of these functions report positions relative to the
+window's frame.  In this case, the coordinate origin @samp{(0,0)} lies
+near the upper left corner of the frame.  For technical reasons, on
+graphical displays the origin is not located at the exact corner of
+the graphical window as it appears on the screen.  If Emacs is built
+with the GTK+ toolkit, the origin is at the upper left corner of the
+frame area used for displaying Emacs windows, below the title-bar,
+GTK+ menu bar, and tool bar (since these are drawn by the window
+manager and/or GTK+, not by Emacs).  But if Emacs is not built with
+GTK+, the origin is at the upper left corner of the tool bar (since in
+this case Emacs itself draws the tool bar).  In both cases, the X and
+Y coordinates increase rightward and downward respectively.
+
+  Except where noted, X and Y coordinates are reported in integer
+character units, i.e. numbers of lines and columns respectively.  On a
+graphical display, each ``line'' and ``column'' corresponds to the
+height and width of a default character specified by the frame's
+default font.
+
address@hidden window-edges &optional window
+This function returns a list of the edge coordinates of @var{window}.
+If @var{window} is omitted or @code{nil}, it defaults to the selected
+window.
+
+The return value has the form @code{(@var{left} @var{top} @var{right}
address@hidden)}.  These list elements are, respectively, the X
+coordinate of the leftmost column occupied by the window, the Y
+coordinate of the topmost row, the X coordinate one column to the
+right of the rightmost column, and the Y coordinate one row down from
+the bottommost row.
+
+Note that these are the actual outer edges of the window, including
+any header line, mode line, scroll bar, fringes, and display margins.
+On a text-only terminal, if the window has a neighbor on its right,
+its right edge includes the separator line between the window and its
+neighbor.
address@hidden defun
+
address@hidden window-inside-edges &optional window
+This function is similar to @code{window-edges}, but the returned edge
+values are for the text area of the window.  They exclude any header
+line, mode line, scroll bar, fringes, display margins, and vertical
+separator.
address@hidden defun
+
address@hidden window-top-line &optional window
+This function returns the Y coordinate of the topmost row of
address@hidden, equivalent to the @var{top} entry in the list returned
+by @code{window-edges}.
address@hidden defun
+
address@hidden window-left-column &optional window
+This function returns the X coordinate of the leftmost column of
address@hidden, equivalent to the @var{left} entry in the list returned
+by @code{window-edges}.
address@hidden defun
+
+  The following functions can be used to relate a set of
+frame-relative coordinates to a window:
 
 @defun window-at x y &optional frame
-This function returns the window containing the specified cursor
-position in the frame @var{frame}.  The coordinates @var{x} and @var{y}
-are measured in characters and count from the top left corner of the
-frame.  If they are out of range, @code{window-at} returns @code{nil}.
-
-If you omit @var{frame}, the selected frame is used.
+This function returns the live window at the frame-relative
+coordinates @var{x} and @var{y}, on frame @var{frame}.  If there is no
+window at that position, the return value is @code{nil}.  If
address@hidden is omitted or @code{nil}, it defaults to the selected
+frame.
 @end defun
 
 @defun coordinates-in-window-p coordinates window
-This function checks whether a particular frame position falls within
-the window @var{window}.
-
-The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
-. @var{y})}.  The coordinates @var{x} and @var{y} are measured in
-characters, and count from the top left corner of the screen or frame.
-
-The value returned by @code{coordinates-in-window-p} is address@hidden
-if the coordinates are inside @var{window}.  The value also indicates
-what part of the window the position is in, as follows:
+This function checks whether a window @var{window} occupies the
+frame-relative coordinates @var{coordinates}, and if so which part of
+the window that is.  @var{window} should be a live window.
address@hidden should be a cons cell of the form @code{(@var{x}
+. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
+
+If there is no window at the specified position, the return value is
address@hidden .  Otherwise, the return value is one of the following:
 
 @table @code
 @item (@var{relx} . @var{rely})
@@ -3038,6 +3043,44 @@
 argument because it always uses the frame that @var{window} is on.
 @end defun
 
+  The following functions return window positions in pixels, rather
+than character units.  Though mostly useful on graphical displays,
+they can also be called on text-only terminals, where the screen area
+of each text character is taken to be ``one pixel''.
+
address@hidden window-pixel-edges &optional window
+This function returns a list of pixel coordinates for the edges of
address@hidden  If @var{window} is omitted or @code{nil}, it defaults
+to the selected window.
+
+The return value has the form @code{(@var{left} @var{top} @var{right}
address@hidden)}.  The list elements are, respectively, the X pixel
+coordinate of the left window edge, the Y pixel coordinate of the top
+edge, one more than the X pixel coordinate of the right edge, and one
+more than the Y pixel coordinate of the bottom edge.
address@hidden defun
+
address@hidden window-inside-pixel-edges &optional window
+This function is like @code{window-pixel-edges}, except that it
+returns the pixel coordinates for the edges of the window's text area,
+rather than the pixel coordinates for the edges of the window itself.
address@hidden must specify a live window.
address@hidden defun
+
+  The following functions return window positions in pixels, relative
+to the display screen rather than the frame:
+
address@hidden window-absolute-pixel-edges &optional window
+This function is like @code{window-pixel-edges}, except that it
+returns the edge pixel coordinates relative to the top left corner of
+the display screen.
address@hidden defun
+
address@hidden window-inside-absolute-pixel-edges &optional window
+This function is like @code{window-inside-pixel-edges}, except that it
+returns the edge pixel coordinates relative to the top left corner of
+the display screen.  @var{window} must specify a live window.
address@hidden defun
 
 @node Window Configurations
 @section Window Configurations