Commit d6d5fdf8 authored by Lars Ingebrigtsen's avatar Lars Ingebrigtsen

Document the `event-start' and `event-end' functions more completely

* doc/lispref/commands.texi (Accessing Mouse): Mention that these function
also work on keyboard events.

* lisp/subr.el (event-start): Doc fix (bug#14228).
(event-end): Ditto.
parent 6995e5d0
2014-02-09 Lars Ingebrigtsen <larsi@gnus.org>
* commands.texi (Accessing Mouse): Mention that these function
also work on keyboard events (bug#14228).
2014-02-08 Lars Ingebrigtsen <larsi@gnus.org>
* display.texi (Face Attributes): Add an index (bug#14924).
......
......@@ -1934,9 +1934,12 @@ must be the last element of the list. For example,
@node Accessing Mouse
@subsection Accessing Mouse Events
@cindex mouse events, data in
@cindex keyboard events, data in
This section describes convenient functions for accessing the data in
a mouse button or motion event.
a mouse button or motion event. Keyboard event data can be accessed
using the same functions, but data elements that aren't applicable to
keyboard events are zero or @code{nil}.
The following two functions return a mouse position list
(@pxref{Click Events}), specifying the position of a mouse event.
......
2014-02-09 Lars Ingebrigtsen <larsi@gnus.org>
* subr.el (event-start): Doc fix (bug#14228).
(event-end): Ditto.
2014-02-09 Glenn Morris <rgm@gnu.org>
* emacs-lisp/warnings.el (lwarn):
......
......@@ -1019,38 +1019,36 @@ in the current Emacs session, then this function may return nil."
(defun event-start (event)
"Return the starting position of EVENT.
EVENT should be a click, drag, or key press event.
If it is a key press event, the return value has the form
(WINDOW POS (0 . 0) 0)
If it is a click or drag event, it has the form
(WINDOW AREA-OR-POS (X . Y) TIMESTAMP OBJECT POS (COL . ROW)
IMAGE (DX . DY) (WIDTH . HEIGHT))
The `posn-' functions access elements of such lists.
For more information, see Info node `(elisp)Click Events'.
If EVENT is a mouse or key press or a mouse click, this is the
position of the event. If EVENT is a drag, this is the starting
position of the drag."
EVENT should be a mouse click, drag, or key press event.
The following accessor functions are used to access the elements
of the position:
`posn-window': The window the event is in.
`posn-area': A symbol identifying the area the event occurred in,
or nil if the event occurred in the text area.
`posn-point': The buffer position of the event.
`posn-x-y': The pixel-based coordiates of the event.
`posn-col-row': The estimated column and row corresponding to the
position of the event.
`posn-actual-col-row': The actual column and row corresponding to the
position of the event.
`posn-string': The string object of the event, which is either
nil or (STRING . POSITION)'.
`posn-image': The image object of the event, if any.
`posn-object': The image or string object of the event, if any.
`posn-timestamp': The time the event occurred, in milliseconds.
For more information, see Info node `(elisp)Click Events'."
(if (consp event) (nth 1 event)
(or (posn-at-point)
(list (selected-window) (point) '(0 . 0) 0))))
(defun event-end (event)
"Return the ending location of EVENT.
"Return the ending position of EVENT.
EVENT should be a click, drag, or key press event.
If EVENT is a key press event, the return value has the form
(WINDOW POS (0 . 0) 0)
If EVENT is a click event, this function is the same as
`event-start'. For click and drag events, the return value has
the form
(WINDOW AREA-OR-POS (X . Y) TIMESTAMP OBJECT POS (COL . ROW)
IMAGE (DX . DY) (WIDTH . HEIGHT))
The `posn-' functions access elements of such lists.
For more information, see Info node `(elisp)Click Events'.
If EVENT is a mouse or key press or a mouse click, this is the
position of the event. If EVENT is a drag, this is the starting
position of the drag."
See `event-start' for a description of the value returned."
(if (consp event) (nth (if (consp (nth 2 event)) 2 1) event)
(or (posn-at-point)
(list (selected-window) (point) '(0 . 0) 0))))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment