[Emacs-diffs] Changes to emacs/lispref/commands.texi

[Richard M . Stallman]

Index: emacs/lispref/commands.texi
diff -c emacs/lispref/commands.texi:1.50 emacs/lispref/commands.texi:1.51
*** emacs/lispref/commands.texi:1.50    Wed Feb 18 04:49:52 2004
--- emacs/lispref/commands.texi Thu Jun 24 20:11:31 2004
***************
*** 1695,1701 ****
  @end defun
  
  @cindex mouse position list, accessing
!   These seven functions take a position list as described above, and
  return various parts of it.
  
  @defun posn-window position
--- 1695,1701 ----
  @end defun
  
  @cindex mouse position list, accessing
!   These functions take a position list as described above, and
  return various parts of it.
  
  @defun posn-window position
***************
*** 1716,1738 ****
  @end defun
  
  @defun posn-x-y position
! Return the pixel-based x and y coordinates in @var{position}, as a cons
! cell @code{(@var{x} . @var{y})}.
  @end defun
  
  @defun posn-col-row position
! Return the row and column (in units of frame default characters) of
! @var{position}, as a cons cell @code{(@var{col} . @var{row})}.  These
! are computed from the @var{x} and @var{y} values actually found in
! @var{position}.
  @end defun
  
  @defun posn-actual-col-row position
  Return the actual row and column in @var{position}, as a cons cell
  @code{(@var{col} . @var{row})}.  The values are the actual row number
! in the window, and the actual character number in that row.  Return
! @code{nil} if @var{position} does not include the actual positions; in that
! case, @code{posn-col-row} can be used to get approximate values.
  @end defun
  
  @defun posn-string position
--- 1716,1752 ----
  @end defun
  
  @defun posn-x-y position
! Return the pixel-based x and y coordinates in @var{position}, as a
! cons cell @code{(@var{x} . @var{y})}.  These coordinates are relative
! to the window given by @code{posn-window}.
! 
! This example shows how to convert these window-relative coordinates
! into frame-relative coordinates:
! 
! @example
! (defun frame-relative-coordinates (position)
!   "Return frame-relative coordinates from POSITION."
!   (let* ((x-y (posn-x-y position))
!          (window (posn-window position))
!          (edges (window-inside-pixel-edges window)))
!     (cons (+ (car x-y) (car edges))
!           (+ (cdr x-y) (cadr edges)))))
! @end example
  @end defun
  
  @defun posn-col-row position
! Return the row and column (in units of the frame's default character
! height and width) of @var{position}, as a cons cell @code{(@var{col} .
! @var{row})}.  These are computed from the @var{x} and @var{y} values
! actually found in @var{position}.
  @end defun
  
  @defun posn-actual-col-row position
  Return the actual row and column in @var{position}, as a cons cell
  @code{(@var{col} . @var{row})}.  The values are the actual row number
! in the window, and the actual character number in that row.  It returns
! @code{nil} if @var{position} does not include actual positions values.
! You can use @code{posn-col-row} to get approximate values.
  @end defun
  
  @defun posn-string position
***************
*** 1771,1776 ****
--- 1785,1811 ----
  event occurred, in milliseconds.
  @end defun
  
+   These functions compute a position list given particular buffer
+ position or screen position.  You can access the data in this position
+ list with the functions described above.
+ 
+ @defun posn-at-point &optional pos window
+ This function returns a position list for position @var{pos} in
+ @var{window}.  @var{pos} defaults to point in @var{window};
+ @var{window} defaults to the selected window.
+ 
+ @code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
+ @var{window}.
+ @end defun
+ 
+ @defun posn-at-x-y x y &optional frame-or-window
+ This function returns position information corresponding to pixel
+ coordinates @var{x} and @var{y} in a specified frame or window,
+ @var{frame-or-window}, which defaults to the selected window.
+ The coordinates @var{x} and @var{y} are relative to the
+ frame or window used.
+ @end defun
+ 
    These functions are useful for decoding scroll bar events.
  
  @defun scroll-bar-event-ratio event