elisp: Coordinates and Windows
27.24 Coordinates and Windows
=============================
This section describes functions that report the position of a window.
Most of these functions report positions relative to an origin at the
native position of the window’s frame (
Frame Geometry). Some
functions report positions relative to the origin of the display of the
window’s frame. In any case, the origin has the coordinates (0, 0) and
X and Y coordinates increase rightward and downward respectively.
For the following functions, X and Y coordinates are reported in
integer character units, i.e., numbers of lines and columns
respectively. On a graphical display, each “line” and “column”
corresponds to the height and width of the default character specified
by the frame’s default font (Frame Font).
-- Function: window-edges &optional window body absolute pixelwise
This function returns a list of the edge coordinates of WINDOW. If
WINDOW is omitted or ‘nil’, it defaults to the selected window.
The return value has the form ‘(LEFT TOP RIGHT BOTTOM)’. These
list elements are, respectively, the X coordinate of the leftmost
column occupied by the window, the Y coordinate of the topmost row,
the X coordinate one column to the right of the rightmost column,
and the Y coordinate one row down from the bottommost row.
Note that these are the actual outer edges of the window, including
any header line, mode line, scroll bar, fringes, window divider and
display margins. On a text terminal, if the window has a neighbor
on its right, its right edge includes the separator line between
the window and its neighbor.
If the optional argument BODY is ‘nil’, this means to return the
edges corresponding to the total size of WINDOW. BODY non-‘nil’
means to return the edges of WINDOW’s body (aka text area). If
BODY is non-‘nil’, WINDOW must specify a live window.
If the optional argument ABSOLUTE is ‘nil’, this means to return
edges relative to the native position of WINDOW’s frame. ABSOLUTE
non-‘nil’ means to return coordinates relative to the origin (0, 0)
of WINDOW’s display. On non-graphical systems this argument has no
effect.
If the optional argument PIXELWISE is ‘nil’, this means to return
the coordinates in terms of the default character width and height
of WINDOW’s frame (Frame Font), rounded if necessary.
PIXELWISE non-‘nil’ means to return the coordinates in pixels.
Note that the pixel specified by RIGHT and BOTTOM is immediately
outside of these edges. If ABSOLUTE is non-‘nil’, PIXELWISE is
implicitly non-‘nil’ too.
-- Function: window-body-edges &optional window
This function returns the edges of WINDOW’s body (Window
Sizes). Calling ‘(window-body-edges window)’ is equivalent to
calling ‘(window-edges window t)’, see above.
The following functions can be used to relate a set of frame-relative
coordinates to a window:
-- Function: window-at x y &optional frame
This function returns the live window at the coordinates X and Y
given in default character sizes (Frame Font) relative to
the native position of FRAME (Frame Geometry).
If there is no window at that position, the return value is ‘nil’.
If FRAME is omitted or ‘nil’, it defaults to the selected frame.
-- Function: coordinates-in-window-p coordinates window
This function checks whether a window WINDOW occupies the frame
relative coordinates COORDINATES, and if so, which part of the
window that is. WINDOW should be a live window.
COORDINATES should be a cons cell of the form ‘(X . Y)’, where X
and Y are given in default character sizes (Frame Font)
relative to the native position of WINDOW’s frame (Frame
Geometry).
If there is no window at the specified position, the return value
is ‘nil’ . Otherwise, the return value is one of the following:
‘(RELX . RELY)’
The coordinates are inside WINDOW. The numbers RELX and RELY
are the equivalent window-relative coordinates for the
specified position, counting from 0 at the top left corner of
the window.
‘mode-line’
The coordinates are in the mode line of WINDOW.
‘header-line’
The coordinates are in the header line of WINDOW.
‘right-divider’
The coordinates are in the divider separating WINDOW from a
window on the right.
‘bottom-divider’
The coordinates are in the divider separating WINDOW from a
window beneath.
‘vertical-line’
The coordinates are in the vertical line between WINDOW and
its neighbor to the right. This value occurs only if the
window doesn’t have a scroll bar; positions in a scroll bar
are considered outside the window for these purposes.
‘left-fringe’
‘right-fringe’
The coordinates are in the left or right fringe of the window.
‘left-margin’
‘right-margin’
The coordinates are in the left or right margin of the window.
‘nil’
The coordinates are not in any part of WINDOW.
The function ‘coordinates-in-window-p’ does not require a frame as
argument because it always uses the frame that WINDOW is on.
The following functions return window positions in pixels, rather
than character units. Though mostly useful on graphical displays, they
can also be called on text terminals, where the screen area of each text
character is taken to be one pixel.
-- Function: window-pixel-edges &optional window
This function returns a list of pixel coordinates for the edges of
WINDOW. Calling ‘(window-pixel-edges window)’ is equivalent to
calling ‘(window-edges window nil nil t)’, see above.
-- Function: window-body-pixel-edges &optional window
This function returns the pixel edges of WINDOW’s body. Calling
‘(window-body-pixel-edges window)’ is equivalent to calling
‘(window-edges window t nil t)’, see above.
The following functions return window positions in pixels, relative
to the origin of the display screen rather than that of the frame:
-- Function: window-absolute-pixel-edges &optional window
This function returns the pixel coordinates of WINDOW relative to
an origin at (0, 0) of the display of WINDOW’s frame. Calling
‘(window-absolute-pixel-edges)’ is equivalent to calling
‘(window-edges window nil t t)’, see above.
-- Function: window-absolute-body-pixel-edges &optional window
This function returns the pixel coordinates of WINDOW’s body
relative to an origin at (0, 0) of the display of WINDOW’s frame.
Calling ‘(window-absolute-body-pixel-edges window)’ is equivalent
to calling ‘(window-edges window t t t)’, see above.
Combined with ‘set-mouse-absolute-pixel-position’, this function
can be used to move the mouse pointer to an arbitrary buffer
position visible in some window:
(let ((edges (window-absolute-body-pixel-edges))
(position (pos-visible-in-window-p nil nil t)))
(set-mouse-absolute-pixel-position
(+ (nth 0 edges) (nth 0 position))
(+ (nth 1 edges) (nth 1 position))))
On a graphical terminal this form “warps” the mouse cursor to the
upper left corner of the glyph at the selected window’s point. A
position calculated this way can be also used to show a tooltip
window there.
The following function returns the screen coordinates of a buffer
position visible in a window:
-- Function: window-absolute-pixel-position &optional position window
If the buffer position POSITION is visible in window WINDOW, this
function returns the display coordinates of the upper/left corner
of the glyph at POSITION. The return value is a cons of the X- and
Y-coordinates of that corner, relative to an origin at (0, 0) of
WINDOW’s display. It returns ‘nil’ if POSITION is not visible in
WINDOW.
WINDOW must be a live window and defaults to the selected window.
POSITION defaults to the value of ‘window-point’ of WINDOW.
This means that in order to move the mouse pointer to the position
of point in the selected window, it’s sufficient to write:
(let ((position (window-absolute-pixel-position)))
(set-mouse-absolute-pixel-position
(car position) (cdr position)))
Info Catalog
elisp: Horizontal Scrolling
elisp: Windows
elisp: Window Configurations