[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/commands.texi
From: |
Kim F. Storm |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/commands.texi |
Date: |
Sat, 22 Nov 2003 19:59:23 -0500 |
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