path: root/devdocs/elisp/mouse-position.html

 <h3 class="section">Mouse Position</h3>   <p>The functions <code>mouse-position</code> and <code>set-mouse-position</code> give access to the current position of the mouse. </p> <dl> <dt id="mouse-position">Function: <strong>mouse-position</strong>
</dt> <dd><p>This function returns a description of the position of the mouse. The value looks like <code>(<var>frame</var> <var>x</var> . <var>y</var>)</code>, where <var>x</var> and <var>y</var> are integers giving the (possibly rounded) position in multiples of the default character size of <var>frame</var> (see <a href="frame-font">Frame Font</a>) relative to the native position of <var>frame</var> (see <a href="frame-geometry">Frame Geometry</a>). </p></dd>
</dl> <dl> <dt id="mouse-position-function">Variable: <strong>mouse-position-function</strong>
</dt> <dd>
<p>If non-<code>nil</code>, the value of this variable is a function for <code>mouse-position</code> to call. <code>mouse-position</code> calls this function just before returning, with its normal return value as the sole argument, and it returns whatever this function returns to it. </p> <p>This abnormal hook exists for the benefit of packages like <samp>xt-mouse.el</samp> that need to do mouse handling at the Lisp level. </p>
</dd>
</dl> <dl> <dt id="tty-menu-calls-mouse-position-function">Variable: <strong>tty-menu-calls-mouse-position-function</strong>
</dt> <dd><p>If non-<code>nil</code>, TTY menus will call <code>mouse-position-function</code> as described above. This exists for cases where <code>mouse-position-function</code> is not safe to be called by the TTY menus, such as if it could trigger redisplay. </p></dd>
</dl> <dl> <dt id="set-mouse-position">Function: <strong>set-mouse-position</strong> <em>frame x y</em>
</dt> <dd>
<p>This function <em>warps the mouse</em> to position <var>x</var>, <var>y</var> in frame <var>frame</var>. The arguments <var>x</var> and <var>y</var> are integers, giving the position in multiples of the default character size of <var>frame</var> (see <a href="frame-font">Frame Font</a>) relative to the native position of <var>frame</var> (see <a href="frame-geometry">Frame Geometry</a>). </p> <p>The resulting mouse position is constrained to the native frame of <var>frame</var>. If <var>frame</var> is not visible, this function does nothing. The return value is not significant. </p>
</dd>
</dl> <dl> <dt id="mouse-pixel-position">Function: <strong>mouse-pixel-position</strong>
</dt> <dd><p>This function is like <code>mouse-position</code> except that it returns coordinates in units of pixels rather than units of characters. </p></dd>
</dl> <dl> <dt id="set-mouse-pixel-position">Function: <strong>set-mouse-pixel-position</strong> <em>frame x y</em>
</dt> <dd>
<p>This function warps the mouse like <code>set-mouse-position</code> except that <var>x</var> and <var>y</var> are in units of pixels rather than units of characters. </p> <p>The resulting mouse position is not constrained to the native frame of <var>frame</var>. If <var>frame</var> is not visible, this function does nothing. The return value is not significant. </p>
</dd>
</dl> <p>On a graphical terminal the following two functions allow the absolute position of the mouse cursor to be retrieved and set. </p> <dl> <dt id="mouse-absolute-pixel-position">Function: <strong>mouse-absolute-pixel-position</strong>
</dt> <dd><p>This function returns a cons cell (<var>x</var> . <var>y</var>) of the coordinates of the mouse cursor position in pixels, relative to a position (0, 0) of the selected frame’s display. </p></dd>
</dl> <dl> <dt id="set-mouse-absolute-pixel-position">Function: <strong>set-mouse-absolute-pixel-position</strong> <em>x y</em>
</dt> <dd><p>This function moves the mouse cursor to the position (<var>x</var>, <var>y</var>). The coordinates <var>x</var> and <var>y</var> are interpreted in pixels relative to a position (0, 0) of the selected frame’s display. </p></dd>
</dl> <p>The following function can tell whether the mouse cursor is currently visible on a frame: </p> <dl> <dt id="frame-pointer-visible-p">Function: <strong>frame-pointer-visible-p</strong> <em>&amp;optional frame</em>
</dt> <dd><p>This predicate function returns non-<code>nil</code> if the mouse pointer displayed on <var>frame</var> is visible; otherwise it returns <code>nil</code>. <var>frame</var> omitted or <code>nil</code> means the selected frame. This is useful when <code>make-pointer-invisible</code> is set to <code>t</code>: it allows you to know if the pointer has been hidden. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Mouse-Avoidance.html#Mouse-Avoidance">Mouse Avoidance</a> in <cite>The Emacs Manual</cite>. </p></dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 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/Mouse-Position.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Mouse-Position.html</a>
  </p>
</div>