Input Focus

At any time, one frame in Emacs is the selected frame. The selected window always resides on the selected frame.

When Emacs displays its frames on several terminals (see Multiple Terminals), each terminal has its own selected frame. But only one of these is the selected frame: it's the frame that belongs to the terminal from which the most recent input came. That is, when Emacs runs a command that came from a certain terminal, the selected frame is the one of that terminal. Since Emacs runs only a single command at any given time, it needs to consider only one selected frame at a time; this frame is what we call the selected frame in this manual. The display on which the selected frame is shown is the selected frame's display.

— Function: selected-frame

This function returns the selected frame.

Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to shift the focus to various window objects. Either way, Emacs automatically keeps track of which frame has the focus. To explicitly switch to a different frame from a Lisp function, call select-frame-set-input-focus.

Lisp programs can also switch frames temporarily by calling the function select-frame. This does not alter the window system's concept of focus; rather, it escapes from the window manager's control until that control is somehow reasserted.

When using a text terminal, only one frame can be displayed at a time on the terminal, so after a call to select-frame, the next redisplay actually displays the newly selected frame. This frame remains selected until a subsequent call to select-frame. Each frame on a text terminal has a number which appears in the mode line before the buffer name (see Mode Line Variables).

— Function: select-frame-set-input-focus frame &optional norecord

This function selects frame, raises it (should it happen to be obscured by other frames) and tries to give it the X server's focus. On a text terminal, the next redisplay displays the new frame on the entire terminal screen. The optional argument norecord has the same meaning as for select-frame (see below). The return value of this function is not significant.

Ideally, the function described next should focus a frame without also raising it above other frames. Unfortunately, many window-systems or window managers may refuse to comply.

— Function: x-focus-frame frame &optional noactivate

This function gives frame the focus of the X server without necessarily raising it. frame nil means use the selected frame. Under X, the optional argument noactivate, if non-nil, means to avoid making frame's window-system window the “active” window which should insist a bit more on avoiding to raise frame above other frames.
On MS-Windows the noactivate argument has no effect. However, if frame is a child frame (see Child Frames), this function usually focuses frame without raising it above other child frames.
If there is no window system support, this function does nothing.

— Command: select-frame frame &optional norecord

This function selects frame frame, temporarily disregarding the focus of the X server if any. The selection of frame lasts until the next time the user does something to select a different frame, or until the next time this function is called. (If you are using a window system, the previously selected frame may be restored as the selected frame after return to the command loop, because it still may have the window system's input focus.)
The specified frame becomes the selected frame, and its terminal becomes the selected terminal. This function then calls select-window as a subroutine, passing the window selected within frame as its first argument and norecord as its second argument (hence, if norecord is non-nil, this avoids changing the order of recently selected windows and the buffer list). See Selecting Windows.
This function returns frame, or nil if frame has been deleted.
In general, you should never use select-frame in a way that could switch to a different terminal without switching back when you're done.

Emacs cooperates with the window system by arranging to select frames as the server and window manager request. It does so by generating a special kind of input event, called a focus event, when appropriate. The command loop handles a focus event by calling handle-switch-frame. See Focus Events.

— Command: handle-switch-frame frame

This function handles a focus event by selecting frame frame.
Focus events normally do their job by invoking this command. Don't call it for any other reason.

— Function: redirect-frame-focus frame &optional focus-frame

This function redirects focus from frame to focus-frame. This means that focus-frame will receive subsequent keystrokes and events intended for frame. After such an event, the value of last-event-frame will be focus-frame. Also, switch-frame events specifying frame will instead select focus-frame.
If focus-frame is omitted or nil, that cancels any existing redirection for frame, which therefore once again receives its own events.
One use of focus redirection is for frames that don't have minibuffers. These frames use minibuffers on other frames. Activating a minibuffer on another frame redirects focus to that frame. This puts the focus on the minibuffer's frame, where it belongs, even though the mouse remains in the frame that activated the minibuffer.
Selecting a frame can also change focus redirections. Selecting frame bar, when foo had been selected, changes any redirections pointing to foo so that they point to bar instead. This allows focus redirection to work properly when the user switches from one frame to another using select-window.
This means that a frame whose focus is redirected to itself is treated differently from a frame whose focus is not redirected. select-frame affects the former but not the latter.
The redirection lasts until redirect-frame-focus is called to change it.

— Variable: focus-in-hook

This is a normal hook run when an Emacs frame gains input focus. The frame gaining focus is selected when this hook is run.

— Variable: focus-out-hook

This is a normal hook run when an Emacs frame has lost input focus and no other Emacs frame has gained input focus instead.

— User Option: focus-follows-mouse

This option informs Emacs whether and how the window manager transfers focus when you move the mouse pointer into a frame. It can have three meaningful values:

nil
The default value nil should be used when your window manager follows a “click-to-focus” policy where you have to click the mouse inside of a frame in order for that frame to gain focus.
t
The value t should be used when your window manager has the focus automatically follow the position of the mouse pointer but a frame that gains focus is not raised automatically and may even remain occluded by other window-system windows.
auto-raise
The value auto-raise should be used when your window manager has the focus automatically follow the position of the mouse pointer and a frame that gains focus is raised automatically.

If this option is non-nil, Emacs moves the mouse pointer to the frame selected by select-frame-set-input-focus. That function is used by a number of commands like, for example, other-frame and pop-to-buffer.
The distinction between the values t and auto-raise is not needed for “normal” frames because the window manager usually takes care of raising them. It is useful to automatically raise child frames via mouse-autoselect-window (see Mouse Window Auto-selection).
Note that this option does not distinguish “sloppy” focus (where the frame that previously had focus retains focus as long as the mouse pointer does not move into another window manager window) from “strict” focus (where a frame immediately loses focus when it's left by the mouse pointer). Neither does it recognize whether your window manager supports delayed focusing or auto-raising where you can explicitly specify the time until a new frame gets focus or is auto-raised.
You can supply a “focus follows mouse” policy for individual Emacs windows by customizing the variable mouse-autoselect-window (see Mouse Window Auto-selection).

29.10 Input Focus