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.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index da7709d354ed93b6d18f55f0834d59123a4ea037..96615cf1d9038c0d2396d7ae99d0f8e25e9509ef 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+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).

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index f9476e5e34c66faa75e3e63fd707626f84673106..fa95c7a74acb15f7ed49d4275e6f73ce3b2adf47 100644 (file)
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -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.

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 493a3d13ad863eae745d6fe4dfd5e8d357b42697..ead1915cef19103cdad1fb6953736b87aebac188 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+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):

diff --git a/lisp/subr.el b/lisp/subr.el
index 7730a4327b4dfe970efda47308e1fbaa68ee5b41..669af38385c0708ce2c3a36fe89d57f30a47b74a 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -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))))