diff options
Diffstat (limited to 'devdocs/elisp/accessing-mouse.html')
| -rw-r--r-- | devdocs/elisp/accessing-mouse.html | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/devdocs/elisp/accessing-mouse.html b/devdocs/elisp/accessing-mouse.html new file mode 100644 index 00000000..786fe29b --- /dev/null +++ b/devdocs/elisp/accessing-mouse.html @@ -0,0 +1,60 @@ + <h4 class="subsection">Accessing Mouse Events</h4> <p>This section describes convenient functions for accessing the data in 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</code>. </p> <p>The following two functions return a mouse position list (see <a href="click-events">Click Events</a>), specifying the position of a mouse event. </p> <dl> <dt id="event-start">Function: <strong>event-start</strong> <em>event</em> +</dt> <dd> +<p>This returns the starting position of <var>event</var>. </p> <p>If <var>event</var> is a click or button-down event, this returns the location of the event. If <var>event</var> is a drag event, this returns the drag’s starting position. </p> +</dd> +</dl> <dl> <dt id="event-end">Function: <strong>event-end</strong> <em>event</em> +</dt> <dd> +<p>This returns the ending position of <var>event</var>. </p> <p>If <var>event</var> is a drag event, this returns the position where the user released the mouse button. If <var>event</var> is a click or button-down event, the value is actually the starting position, which is the only position such events have. </p> +</dd> +</dl> <dl> <dt id="posnp">Function: <strong>posnp</strong> <em>object</em> +</dt> <dd><p>This function returns non-<code>nil</code> if <var>object</var> is a mouse position list, in the format documented in <a href="click-events">Click Events</a>); and <code>nil</code> otherwise. </p></dd> +</dl> <p>These functions take a mouse position list as argument, and return various parts of it: </p> <dl> <dt id="posn-window">Function: <strong>posn-window</strong> <em>position</em> +</dt> <dd><p>Return the window that <var>position</var> is in. If <var>position</var> represents a location outside the frame where the event was initiated, return that frame instead. </p></dd> +</dl> <dl> <dt id="posn-area">Function: <strong>posn-area</strong> <em>position</em> +</dt> <dd><p>Return the window area recorded in <var>position</var>. It returns <code>nil</code> when the event occurred in the text area of the window; otherwise, it is a symbol identifying the area in which the event occurred. </p></dd> +</dl> <dl> <dt id="posn-point">Function: <strong>posn-point</strong> <em>position</em> +</dt> <dd><p>Return the buffer position in <var>position</var>. 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. </p></dd> +</dl> <dl> <dt id="posn-x-y">Function: <strong>posn-x-y</strong> <em>position</em> +</dt> <dd> +<p>Return the pixel-based x and y coordinates in <var>position</var>, as a cons cell <code>(<var>x</var> . <var>y</var>)</code>. These coordinates are relative to the window given by <code>posn-window</code>. </p> <p>This example shows how to convert the window-relative coordinates in the text area of a window into frame-relative coordinates: </p> <div class="example"> <pre class="example">(defun frame-relative-coordinates (position) + "Return frame-relative coordinates from POSITION. +POSITION is assumed to lie in a window text area." + (let* ((x-y (posn-x-y position)) + (window (posn-window position)) + (edges (window-inside-pixel-edges window))) + (cons (+ (car x-y) (car edges)) + (+ (cdr x-y) (cadr edges))))) +</pre> +</div> </dd> +</dl> <dl> <dt id="posn-col-row">Function: <strong>posn-col-row</strong> <em>position</em> +</dt> <dd> +<p>This function returns a cons cell <code>(<var>col</var> . <var>row</var>)</code>, containing the estimated column and row corresponding to buffer position described by <var>position</var>. The return value is given in units of the frame’s default character width and default line height (including spacing), as computed from the <var>x</var> and <var>y</var> values corresponding to <var>position</var>. (So, if the actual characters have non-default sizes, the actual row and column may differ from these computed values.) </p> <p>Note that <var>row</var> is counted from the top of the text area. If the window given by <var>position</var> possesses a header line (see <a href="header-lines">Header Lines</a>) or a tab line, they are <em>not</em> included in the <var>row</var> count. </p> +</dd> +</dl> <dl> <dt id="posn-actual-col-row">Function: <strong>posn-actual-col-row</strong> <em>position</em> +</dt> <dd> +<p>Return the actual row and column in <var>position</var>, as a cons cell <code>(<var>col</var> . <var>row</var>)</code>. The values are the actual row and column numbers in the window given by <var>position</var>. See <a href="click-events">Click Events</a>, for details. The function returns <code>nil</code> if <var>position</var> does not include actual position values; in that case <code>posn-col-row</code> can be used to get approximate values. </p> <p>Note that this function doesn’t account for the visual width of characters on display, like the number of visual columns taken by a tab character or an image. If you need the coordinates in canonical character units, use <code>posn-col-row</code> instead. </p> +</dd> +</dl> <dl> <dt id="posn-string">Function: <strong>posn-string</strong> <em>position</em> +</dt> <dd><p>Return the string object described by <var>position</var>, either <code>nil</code> (which means <var>position</var> describes buffer text), or a cons cell <code>(<var>string</var> . <var><span class="nolinebreak">string-pos</span></var>)</code>. </p></dd> +</dl> <dl> <dt id="posn-image">Function: <strong>posn-image</strong> <em>position</em> +</dt> <dd><p>Return the image object in <var>position</var>, either <code>nil</code> (if there’s no image at <var>position</var>), or an image spec <code>(image …)</code>. </p></dd> +</dl> <dl> <dt id="posn-object">Function: <strong>posn-object</strong> <em>position</em> +</dt> <dd><p>Return the image or string object described by <var>position</var>, either <code>nil</code> (which means <var>position</var> describes buffer text), an image <code>(image …)</code>, or a cons cell <code>(<var>string</var> . <var><span class="nolinebreak">string-pos</span></var>)</code>. </p></dd> +</dl> <dl> <dt id="posn-object-x-y">Function: <strong>posn-object-x-y</strong> <em>position</em> +</dt> <dd><p>Return the pixel-based x and y coordinates relative to the upper left corner of the object described by <var>position</var>, as a cons cell <code>(<var>dx</var> . <var>dy</var>)</code>. If the <var>position</var> describes buffer text, return the relative coordinates of the buffer-text character closest to that position. </p></dd> +</dl> <dl> <dt id="posn-object-width-height">Function: <strong>posn-object-width-height</strong> <em>position</em> +</dt> <dd><p>Return the pixel width and height of the object described by <var>position</var>, as a cons cell <code>(<var>width</var> . <var>height</var>)</code>. If the <var>position</var> describes a buffer position, return the size of the character at that position. </p></dd> +</dl> <dl> <dt id="posn-timestamp">Function: <strong>posn-timestamp</strong> <em>position</em> +</dt> <dd><p>Return the timestamp in <var>position</var>. This is the time at which the event occurred, in milliseconds. </p></dd> +</dl> <p>These functions compute a position list given particular buffer position or screen position. You can access the data in this position list with the functions described above. </p> <dl> <dt id="posn-at-point">Function: <strong>posn-at-point</strong> <em>&optional pos window</em> +</dt> <dd> +<p>This function returns a position list for position <var>pos</var> in <var>window</var>. <var>pos</var> defaults to point in <var>window</var>; <var>window</var> defaults to the selected window. </p> <p><code>posn-at-point</code> returns <code>nil</code> if <var>pos</var> is not visible in <var>window</var>. </p> +</dd> +</dl> <dl> <dt id="posn-at-x-y">Function: <strong>posn-at-x-y</strong> <em>x y &optional frame-or-window whole</em> +</dt> <dd><p>This function returns position information corresponding to pixel coordinates <var>x</var> and <var>y</var> in a specified frame or window, <var>frame-or-window</var>, which defaults to the selected window. The coordinates <var>x</var> and <var>y</var> are relative to the text area of the selected window. If <var>whole</var> is <code>non-nil</code>, the <var>x</var> coordinate is relative to the entire window area including scroll bars, margins and fringes. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Accessing-Mouse.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Accessing-Mouse.html</a> + </p> +</div> |