GNU Info

(elisp)Input Focus

---

Next: Visibility of Frames Prev: Minibuffers and Frames Up: Frames

---

Enter node , (file) or (file)node

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 (Note: Multiple
Displays), 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 displayed 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.

   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-only terminal, only the selected terminal frame is
actually displayed on the terminal.  `switch-frame' is the only way to
switch frames, and the change lasts until overridden by a subsequent
call to `switch-frame'.  Each terminal screen except for the initial
one has a number, and the number of the selected frame appears in the
mode line before the buffer name (Note: Mode Line Variables).

 - Function: select-frame frame
     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.  The specified
     FRAME becomes the selected frame, as explained above, and the
     terminal that FRAME is on becomes the selected terminal.

     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'.  Note: 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 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 `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.

 - 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.