diff lispref/frames.texi @ 83171:09bbf2fc80da

Merged in changes from CVS trunk. Patches applied: * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-439 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-440 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-441 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-442 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-443 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-444 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-445 Tweak permissions * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-446 Update from CVS git-archimport-id: [e-mail]--2004/emacs--multi-tty--0--patch-211

--- a/lispref/frames.texi	Mon Jul 05 01:15:41 2004 +0000
+++ b/lispref/frames.texi	Sat Jul 10 14:37:36 2004 +0000
@@ -1,6 +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 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,19 +996,30 @@
 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.
+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 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}).
+When using a text-only terminal, only one frame can be displayed at a
+time on the terminal, so after a call to @code{select-frame}, the next
+redisplay 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 @var{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 next redisplay displays
+the new frame on the entire terminal screen.  The return value of this
+function is not significant.
+@end defun
 
 @c ??? This is not yet implemented properly.
 @defun select-frame frame
@@ -1017,7 +1028,8 @@
 the next time the user does something to select a different frame, or
 until the next time this function is called.  The specified @var{frame}
 becomes the selected frame, as explained above, and the terminal that
-@var{frame} is on becomes the selected terminal.
+@var{frame} is on becomes the selected terminal.  This function
+returns @var{frame}, or @code{nil} if @var{frame} has been deleted.
 
 In general, you should never use @code{select-frame} in a way that could
 switch to a different terminal without switching back when you're done.