elisp: Input Focus
28.10 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 (
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 (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.
-- 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 nor the buffer list). 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’.
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.
-- Variable: focus-out-hook
This is a normal hook run when an Emacs frame loses input focus.
-- User Option: focus-follows-mouse
This option is how you inform Emacs whether the window manager
transfers focus when the user moves the mouse. Non-‘nil’ says that
it does. When this is so, the command ‘other-frame’ moves the
mouse to a position consistent with the new selected frame.
Info Catalog
elisp: Minibuffers and Frames
elisp: Frames
elisp: Visibility of Frames