27.23 Coordinates and Windows

This section describes functions that report the position of a window. Most of these functions report positions relative to the window’s frame. In this case, the coordinate origin ‘(0,0)’ lies near the upper left corner of the frame. For technical reasons, on graphical displays the origin is not located at the exact corner of the graphical window as it appears on the screen. If Emacs is built with the GTK+ toolkit, the origin is at the upper left corner of the frame area used for displaying Emacs windows, below the title-bar, GTK+ menu bar, and tool bar (since these are drawn by the window manager and/or GTK+, not by Emacs). But if Emacs is not built with GTK+, the origin is at the upper left corner of the tool bar (since in this case Emacs itself draws the tool bar). In both cases, the X and Y coordinates increase rightward and downward respectively.

Except where noted, 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 a default character specified by the frame’s default font.

Function: window-edges &optional window

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.

Function: window-inside-edges &optional window

This function is similar to window-edges, but the returned edge values are for the text area of the window. They exclude any header line, mode line, scroll bar, fringes, window divider, display margins, and vertical separator.

Function: window-top-line &optional window

This function returns the Y coordinate of the topmost row of window, equivalent to the top entry in the list returned by window-edges.

Function: window-left-column &optional window

This function returns the X coordinate of the leftmost column of window, equivalent to the left entry in the list returned by window-edges.

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 frame-relative coordinates x and y, on frame frame. 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 frame-relative coordinates.

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.

right-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. If window is omitted or nil, it defaults to the selected window.

The return value has the form (left top right bottom). The list elements are, respectively, the X pixel coordinate of the left window edge, the Y pixel coordinate of the top edge, one more than the X pixel coordinate of the right edge, and one more than the Y pixel coordinate of the bottom edge.

Function: window-inside-pixel-edges &optional window

This function is like window-pixel-edges, except that it returns the pixel coordinates for the edges of the window’s text area, rather than the pixel coordinates for the edges of the window itself. window must specify a live window.

The following functions return window positions in pixels, relative to the display screen rather than the frame:

Function: window-absolute-pixel-edges &optional window

This function is like window-pixel-edges, except that it returns the edge pixel coordinates relative to the top left corner of the display screen.

Function: window-inside-absolute-pixel-edges &optional window

This function is like window-inside-pixel-edges, except that it returns the edge pixel coordinates relative to the top left corner of the display screen. window must specify a live window.

Function: window-pixel-left &optional window

This function returns the left pixel edge of window window. window must be a valid window and defaults to the selected one.

Function: window-pixel-top &optional window

This function returns the top pixel edge of window window. window must be a valid window and defaults to the selected one.