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

[Kim F. Storm]

Index: emacs/lispref/commands.texi
diff -c emacs/lispref/commands.texi:1.45 emacs/lispref/commands.texi:1.46
*** emacs/lispref/commands.texi:1.45    Sat Nov 22 19:59:23 2003
--- emacs/lispref/commands.texi Thu Nov 27 16:54:19 2003
***************
*** 1155,1161 ****
  the marginal areas, @var{position} has this form:
  
  @example
! (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} 
@var{object} @var{text-pos} (@var{col} . @var{row}))
  @end example
  
  @table @asis
--- 1155,1162 ----
  the marginal areas, @var{position} has this form:
  
  @example
! (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
!  @var{object} @var{text-pos} (@var{col} . @var{row}) (@var{dx} . @var{dy}))
  @end example
  
  @table @asis
***************
*** 1179,1187 ****
  This is the time at which the event occurred, in milliseconds.
  
  @item @var{object}
! This is the object on which the click occurred.  It is either nil (for
! a click in a marginal area with no associated object, or it has the
! form (@var{string} . @var{string-pos}).
  
  @item @var{string}
  This is the string on which the click occurred, including any
--- 1180,1190 ----
  This is the time at which the event occurred, in milliseconds.
  
  @item @var{object}
! This is the object on which the click occurred.  It is either
! @code{nil} if there is no string property or image at the position
! clicked on, or it has the form (@var{string} . @var{string-pos}) when
! there is a string-type text property at the click position, or it is
! an image object as returned by @code{find-image} if click was in an image.
  
  @item @var{string}
  This is the string on which the click occurred, including any
***************
*** 1201,1206 ****
--- 1204,1215 ----
  These are the actual coordinates of the glyph under the @var{x},
  @var{y} position, possibly padded with default character width
  glyphs if @var{x} is beyond the last glyph on the line.
+ 
+ @item @var{dx}, @var{dy}
+ These are the pixel-denominated coordinates of the click, relative to
+ the top left corner of @var{object}, which is @code{(0 . 0)}.  If
+ @var{object} is @code{nil}, the coordinates are relative to the top
+ left corner of the character glyph clicked on.
  @end table
  
  For mouse clicks on a scroll-bar, @var{position} has this form:
***************
*** 1659,1665 ****
  mouse-button event, as a list of this form:
  
  @example
! (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} 
@var{object} @var{text-pos} (@var{col} . @var{row}))
  @end example
  
  @defun event-start event
--- 1668,1675 ----
  mouse-button event, as a list of this form:
  
  @example
! (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
!  @var{object} @var{text-pos} (@var{col} . @var{row}) (@var{dx} . @var{dy}))
  @end example
  
  @defun event-start event
***************
*** 1688,1694 ****
  @end defun
  
  @defun posn-area position
! Return the window area recorded in @var{position}.  It returns nil
  when the event occurred in the text area of the window; otherwise, it
  is a symbol identifying the area in which the the event occurred.
  @end defun
--- 1698,1704 ----
  @end defun
  
  @defun posn-area position
! Return the window area recorded in @var{position}.  It returns @code{nil}
  when the event occurred in the text area of the window; otherwise, it
  is a symbol identifying the area in which the the event occurred.
  @end defun
***************
*** 1700,1710 ****
  is undefined.
  @end defun
  
- @defun posn-timestamp
- Return the timestamp in @var{position}.  This is the time at which the
- event occurred, in milliseconds.
- @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})}.
--- 1710,1715 ----
***************
*** 1721,1734 ****
  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
! 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
  
  @cindex mouse event, timestamp
  @cindex timestamp of a mouse event
! @defun posn-timestamp position
! Return the timestamp in @var{position}.
  @end defun
  
    These functions are useful for decoding scroll bar events.
--- 1726,1751 ----
  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-object position
+ Return the object in @var{position}, either @code{nil}, a cons
+ cell @code{(@var{string} . @var{string-pos})}, or an image
+ @code{(image ...)}.
+ @end defun
+ 
+ @defun posn-object-x-y position
+ Return the pixel-based x and y coordinates relative to the upper left
+ corner of the object in @var{position}, as a cons cell @code{(@var{dx} . 
@var{dy})}.
+ @end defun
+ 
  @cindex mouse event, timestamp
  @cindex timestamp of a mouse event
! @defun posn-timestamp
! Return the timestamp in @var{position}.  This is the time at which the
! event occurred, in milliseconds.
  @end defun
  
    These functions are useful for decoding scroll bar events.