From: Lars Ingebrigtsen Date: Sun, 9 Feb 2014 02:13:23 +0000 (-0800) Subject: Document the `event-start' and `event-end' functions more completely X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~83 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=d6d5fdf826ce74ac3a99cb72aae54cbc2974ffe2;p=emacs.git 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 da7709d354e..96615cf1d90 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2014-02-09 Lars Ingebrigtsen + + * commands.texi (Accessing Mouse): Mention that these function + also work on keyboard events (bug#14228). + 2014-02-08 Lars Ingebrigtsen * display.texi (Face Attributes): Add an index (bug#14924). diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index f9476e5e34c..fa95c7a74ac 100644 --- 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 493a3d13ad8..ead1915cef1 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,8 @@ +2014-02-09 Lars Ingebrigtsen + + * subr.el (event-start): Doc fix (bug#14228). + (event-end): Ditto. + 2014-02-09 Glenn Morris * emacs-lisp/warnings.el (lwarn): diff --git a/lisp/subr.el b/lisp/subr.el index 7730a4327b4..669af38385c 100644 --- 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))))