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

[Kim F. Storm]

Index: emacs/lispref/commands.texi
diff -c emacs/lispref/commands.texi:1.44 emacs/lispref/commands.texi:1.45
*** emacs/lispref/commands.texi:1.44    Sun Nov  2 01:29:56 2003
--- emacs/lispref/commands.texi Sat Nov 22 19:59:23 2003
***************
*** 1119,1145 ****
  @cindex mouse click event
  
  When the user presses a mouse button and releases it at the same
! location, that generates a @dfn{click} event.  Mouse click events have
! this form:
  
  @example
! (@var{event-type}
!  (@var{window} @var{buffer-pos} (@var{x} . @var{y})
!   @var{timestamp})
!  @var{click-count})
  @end example
  
- or, for clicks on strings in the mode line, header line or marginal
- areas:
- 
- @example
- (@var{event-type}
-  (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp} 
(@var{string} . @var{string-pos})
-  @var{click-count})
- @end example
- 
- Here is what the elements normally mean:
- 
  @table @asis
  @item @var{event-type}
  This is a symbol that indicates which mouse button was used.  It is
--- 1119,1131 ----
  @cindex mouse click event
  
  When the user presses a mouse button and releases it at the same
! location, that generates a @dfn{click} event.  All mouse click event
! share the same format:
  
  @example
! (@var{event-type} @var{position} @var{click-count})
  @end example
  
  @table @asis
  @item @var{event-type}
  This is a symbol that indicates which mouse button was used.  It is
***************
*** 1155,1207 ****
  @code{mouse-1}, that binding would apply to all events whose
  @var{event-type} is @code{mouse-1}.
  
  @item @var{window}
  This is the window in which the click occurred.
  
  @item @var{x}, @var{y}
  These are the pixel-denominated coordinates of the click, relative to
! the top left corner of @var{window}, which is @code{(0 . 0)}.
! 
! @item @var{buffer-pos}
! This is the buffer position of the character clicked on.
  
  @item @var{timestamp}
! This is the time at which the event occurred, in milliseconds.  (Since
! this value wraps around the entire range of Emacs Lisp integers in about
! five hours, it is useful only for relating the times of nearby
! events.)
  
  @item @var{string}
  This is the string on which the click occurred, including any
! properties.
  
  @item @var{string-pos}
  This is the position in the string on which the click occurred,
  relevant if properties at the click need to be looked up.
  
! @item @var{click-count}
! This is the number of rapid repeated presses so far of the same mouse
! button.  @xref{Repeat Events}.
  @end table
  
! The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat
! different when the event location is in a special part of the screen,
! such as the mode line or a scroll bar.
! 
! If the location is in a scroll bar, then @var{buffer-pos} is the symbol
! @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair
! @code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion}
! . @var{whole})}, where @var{portion} is the distance of the click from
! the top or left end of the scroll bar, and @var{whole} is the length of
! the entire scroll bar.
! 
! If the position is on a mode line, the vertical line separating
! @var{window} from its neighbor to the right, or in a marginal area,
! then @var{buffer-pos} is the symbol @code{mode-line},
! @code{header-line}, @code{vertical-line}, @code{left-margin}, or
! @code{right-margin}.  For the mode line, @var{y} does not have
! meaningful data.  For the vertical line, @var{x} does not have
! meaningful data.
  
  In one special case, @var{buffer-pos} is a list containing a symbol (one
  of the symbols listed above) instead of just the symbol.  This happens
--- 1141,1237 ----
  @code{mouse-1}, that binding would apply to all events whose
  @var{event-type} is @code{mouse-1}.
  
+ @item @var{position}
+ This is the position where the mouse click occurred.  The actual
+ format of @var{position} depends on what part of a window was clicked
+ on.  The various formats are described below.
+ 
+ @item @var{click-count}
+ This is the number of rapid repeated presses so far of the same mouse
+ button.  @xref{Repeat Events}.
+ @end table
+ 
+ For mouse click events in the text area, mode line, header line, or in
+ 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
  @item @var{window}
  This is the window in which the click occurred.
  
+ @item @var{pos-or-area}
+ This is the buffer position of the character clicked on in the text
+ area, or if clicked outside the text area, it is the window area in
+ which the click occurred.  It is one of the symbols @code{mode-line},
+ @code{header-line}, @code{vertical-line}, @code{left-margin},
+ @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
+ 
  @item @var{x}, @var{y}
  These are the pixel-denominated coordinates of the click, relative to
! the top left corner of @var{window}, which is @code{(0 . 0)}.  
! For the mode or header line, @var{y} does not have meaningful data.
! For the vertical line, @var{x} does not have meaningful data.
  
  @item @var{timestamp}
! 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
! properties.  
  
  @item @var{string-pos}
  This is the position in the string on which the click occurred,
  relevant if properties at the click need to be looked up.
  
! @item @var{text-pos}
! For clicks on a marginal area or on a fringe, this is the buffer
! position of the first visible character in the corresponding line in
! the window.  For other events, it is the current buffer position in
! the window.
! 
! @item @var{col}, @var{row}
! 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.
  @end table
  
! For mouse clicks on a scroll-bar, @var{position} has this form:
! 
! @example
! (@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} 
@var{part})
! @end example
! 
! @table @asis
! @item @var{window}
! This is the window whose scroll-bar was clicked on.
! 
! @item @var{area}
! This is the scroll bar where the click occurred.  It is one of the
! symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
! 
! @item @var{portion}
! This is the distance of the click from the top or left end of
! the scroll bar.
! 
! @item @var{whole}
! This is the length of the entire scroll bar.
! 
! @item @var{timestamp}
! This is the time at which the event occurred, in milliseconds.
! 
! @item @var{part}
! This is the part of the scroll-bar which was clicked on.  It is one
! of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
! @code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
! @end table
  
  In one special case, @var{buffer-pos} is a list containing a symbol (one
  of the symbols listed above) instead of just the symbol.  This happens
***************
*** 1629,1635 ****
  mouse-button event, as a list of this form:
  
  @example
! (@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
  @end example
  
  @defun event-start event
--- 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
***************
*** 1650,1664 ****
  @end defun
  
  @cindex mouse position list, accessing
!   These five functions take a position list as described above, and
  return various parts of it.
  
  @defun posn-window position
  Return the window that @var{position} is in.
  @end defun
  
  @defun posn-point position
! Return the buffer position in @var{position}.  This is an integer.
  @end defun
  
  @defun posn-x-y position
--- 1680,1708 ----
  @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
  Return the window that @var{position} is in.
  @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
+ 
  @defun posn-point position
! Return the buffer position in @var{position}.  When the event occurred
! in the text area of the window, in a marginal area, or on a fringe,
! this is an integer specifying a buffer position.  Otherwise, the value
! 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
***************
*** 1667,1675 ****
  @end defun
  
  @defun posn-col-row position
! Return the row and column (in units of 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
  
  @cindex mouse event, timestamp
--- 1711,1728 ----
  @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
! 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