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

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  <acm@muc.de>

	* 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)
acm@muc.de

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

[Richard Stallman]

Your patch looks basically good, but there are Texinfo usage
errors.  It would be good for someone who knows Texinfo well enough
to install it and fix the Texinfo usage.

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

[Luc Teirlinck]

Richard Stallman wrote:

   Your patch looks basically good, but there are Texinfo usage
   errors.  It would be good for someone who knows Texinfo well enough
   to install it and fix the Texinfo usage.

Done.  I must say that I only found one single Texinfo error (FRAME
should have been @var{frame}).

Sincerely,

Luc.