29.3 Selecting Windows

In each frame, at any time, exactly one Emacs window is designated as selected within the frame. For the selected frame, that window is called the selected window—the one in which most editing takes place, and in which the cursor for selected windows appears (see Cursor Parameters). Keyboard input that inserts or deletes text is also normally directed to this window. The selected window’s buffer is usually also the current buffer, except when set-buffer has been used (see The Current Buffer). As for non-selected frames, the window selected within the frame becomes the selected window if the frame is ever selected.

Function: selected-window

This function returns the selected window (which is always a live window).

The following function explicitly selects a window and its frame.

Function: select-window window &optional norecord

This function makes window the selected window and the window selected within its frame, and selects that frame. It also makes window’s buffer (see Buffers and Windows) current and sets that buffer’s value of point to the value of window-point (see Windows and Point) in window. window must be a live window. The return value is window.

By default, this function also moves window’s buffer to the front of the buffer list (see The Buffer List) and makes window the most recently selected window. If the optional argument norecord is non-nil, these additional actions are omitted.

In addition, this function by default also tells the display engine to update the display of window when its frame gets redisplayed the next time. If norecord is non-nil, such updates are usually not performed. If, however, norecord equals the special symbol mark-for-redisplay, the additional actions mentioned above are omitted but window’s display will be nevertheless updated.

Note that sometimes selecting a window is not enough to show it, or make its frame the top-most frame on display: you may also need to raise the frame or make sure input focus is directed to that frame. See Input Focus.

For historical reasons, Emacs does not run a separate hook whenever a window gets selected. Applications and internal routines often temporarily select a window to perform a few actions on it. They do that either to simplify coding—because many functions by default operate on the selected window when no window argument is specified—or because some functions did not (and still do not) take a window as argument and always operate(d) on the selected window instead. Running a hook every time a window gets selected for a short time and once more when the previously selected window gets restored is not useful.

However, when its norecord argument is nil, select-window updates the buffer list and thus indirectly runs the normal hook buffer-list-update-hook (see The Buffer List). Consequently, that hook provides one way to run a function whenever a window gets selected more “permanently”.

Since buffer-list-update-hook is also run by functions that are not related to window management, it will usually make sense to save the value of the selected window somewhere and compare it with the value of selected-window while running that hook. Also, to avoid false positives when using buffer-list-update-hook, it is good practice that every select-window call supposed to select a window only temporarily passes a non-nil norecord argument. If possible, the macro with-selected-window (see below) should be used in such cases.

Emacs also runs the hook window-selection-change-functions whenever the redisplay routine detects that another window has been selected since last redisplay. See Hooks for Window Scrolling and Changes, for a detailed explanation. window-state-change-functions (described in the same section) is another abnormal hook run after a different window has been selected but is triggered by other window changes as well.

The sequence of calls to select-window with a non-nil norecord argument determines an ordering of windows by their selection or use time, see below. The function get-lru-window, for example, can then be used to retrieve the least recently selected window (see Cyclic Ordering of Windows).

Function: frame-selected-window &optional frame

This function returns the window on frame that is selected within that frame. frame should be a live frame; if omitted or nil, it defaults to the selected frame.

Function: set-frame-selected-window frame window &optional norecord

This function makes window the window selected within the frame frame. frame should be a live frame; if nil, it defaults to the selected frame. window must denote a live window.

If frame is the selected frame, this makes window the selected window.

If the optional argument norecord is non-nil, this function does not alter the ordering of the most recently selected windows, nor the buffer list.

The following macros are useful to temporarily select a window without affecting the ordering of recently selected windows or the buffer list.

Macro: save-selected-window forms…

This macro records the selected frame, as well as the selected window of each frame, executes forms in sequence, then restores the earlier selected frame and windows. It also saves and restores the current buffer. It returns the value of the last form in forms.

This macro does not save or restore anything about the sizes, arrangement or contents of windows; therefore, if forms change them, the change persists. If the previously selected window of some frame is no longer live at the time of exit from forms, that frame’s selected window is left alone. If the previously selected window is no longer live, then whatever window is selected at the end of forms remains selected. The current buffer is restored if and only if it is still live when exiting forms.

This macro changes neither the ordering of recently selected windows nor the buffer list.

Macro: with-selected-window window forms…

This macro selects window, executes forms in sequence, then restores the previously selected window and current buffer. The ordering of recently selected windows and the buffer list remain unchanged unless you deliberately change them within forms; for example, by calling select-window with argument norecord nil. Hence, this macro is the preferred way to temporarily work with window as the selected window without needlessly running buffer-list-update-hook.

Note that this macro temporarily puts the window management code in an unstable state. In particular, the most recently used window (see below) will not necessarily match the selected one. Hence, functions like get-lru-window and get-mru-window may return unexpected results when called from the body of this macro.

Macro: with-selected-frame frame forms…

This macro executes forms with frame as the selected frame. The value returned is the value of the last form in forms. This macro saves and restores the selected frame, and changes the order of neither the recently selected windows nor the buffers in the buffer list.

Function: window-use-time &optional window

This function returns the use time of window window. window must be a live window and defaults to the selected one.

The use time of a window is not really a time value, but an integer that does increase monotonically with each call of select-window with a nil norecord argument. The window with the lowest use time is usually called the least recently used window. The window with the highest use time is called the most recently used one (see Cyclic Ordering of Windows) and is usually the selected window unless with-selected-window has been used.

Function: window-bump-use-time &optional window

This function marks window as being the second most recently used one (after the selected window). It does nothing if window is the selected window or the selected window does not have the highest use time among all windows which may happen within the scope of with-selected-window.

Sometimes several windows collectively and cooperatively display a buffer, for example, under the management of Follow Mode (see (emacs)Follow Mode), where the windows together display a bigger portion of the buffer than one window could alone. It is often useful to consider such a window group as a single entity. Several functions such as window-group-start (see The Window Start and End Positions) allow you to do this by supplying, as an argument, one of the windows as a stand-in for the whole group.

Function: selected-window-group

When the selected window is a member of a group of windows, this function returns a list of the windows in the group, ordered such that the first window in the list is displaying the earliest part of the buffer, and so on. Otherwise the function returns a list containing just the selected window.

The selected window is considered part of a group when the buffer local variable selected-window-group-function is set to a function. In this case, selected-window-group calls it with no arguments and returns its result (which should be the list of windows in the group).