elisp's frames.texi. Add doc for `select-frame-set-input-focus', etc.

[Alan Mackenzie]

Hi, everybody!

Had problems finding the function `select-frame-set-input-focus', an
essential function for switching frames on a windowing system by any
method other than mouse clicks.  Currently, the only way to find it is to
bring up the source for `other-frame' in frame.el.  What makes it even
more confusing is that `select-frame' works fine on a text-terminal, but
has no apparent effect on a windowing system.

Thus the following patch to elisp's frames.texi.  This file made reference
to a mysterious function `switch-frame', which I assume ought to have
been `select-frame'.  Also, _every_ frame on a tty gets a frame number
(such as "F2"), not just the second and subsequent ones.  I also took the
liberty of doing a little tidying up of the tty paragraph in the `select
frame' description.  I found the existing version a little confusing, in
that it wasn't too clear that the second sentence was continuing to refer
only to ttys.


2004-07-03  Alan Mackenzie  <address@hidden>

        * frames.texi (Input Focus): Add documentation for
        select-frame-set-input-focus.  Replace refs to non-existent
        `switch-frame' with `select-frame'.  Minor corrections and tidying
        up of text-only terminal stuff.


*** frames-1.72.texi    Sat Jul  3 08:18:40 2004
--- frames-1.72.acm.texi        Sat Jul  3 14:22:34 2004
***************
*** 1,6 ****
  @c -*-texinfo-*-
  @c This is part of the GNU Emacs Lisp Reference Manual.
! @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002
  @c   Free Software Foundation, Inc.
  @c See the file elisp.texi for copying conditions.
  @setfilename ../info/frames
--- 1,6 ----
  @c -*-texinfo-*-
  @c This is part of the GNU Emacs Lisp Reference Manual.
! @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2004
  @c   Free Software Foundation, Inc.
  @c See the file elisp.texi for copying conditions.
  @setfilename ../info/frames
***************
*** 996,1014 ****
  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 @dfn{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 @code{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.  @code{switch-frame} is the only way
! to switch frames, and the change lasts until overridden by a subsequent
! call to @code{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 (@pxref{Mode Line Variables}).
  
  @c ??? This is not yet implemented properly.
  @defun select-frame frame
--- 996,1023 ----
  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 @dfn{shift the focus} to various window objects.  Either
! way, Emacs automatically keeps track of which frame has the focus.  To
! switch to a different frame from a lisp function, call
! @code{select-frame-set-input-focus}.
  
  Lisp programs can also switch frames ``temporarily'' by calling the
  function @code{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 one frame can be displayed at a
! time on the terminal, so @code{select-frame} actually displays the
! newly selected frame.  This frame remains displayed until a subsequent
! call to @code{select-frame} or @code{select-frame-set-input-focus}.
! Each terminal frame has a number which appears in the mode line before
! the buffer name (@pxref{Mode Line Variables}).
! 
! @defun select-frame-set-input-focus frame
! This function makes FRAME the selected 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-only terminal, the new frame gets displayed
! on the entire terminal screen.
! @end defun
  
  @c ??? This is not yet implemented properly.
  @defun select-frame frame


-- 
Alan Mackenzie (Munich, Germany)
address@hidden