Commit 6a4cfb0c authored by Martin Rudalics's avatar Martin Rudalics

(Frames): Fix typo, add cross references, reword.

(Initial Parameters): Reword special-display-frame-alist text.
(Frames and Windows): Reword.  Describe argument norecord for
set-frame-selected-window.
(Input Focus): Describe argument norecord for select-frame.
Remove comment on MS-Windows behavior for focus-follows-mouse.
(Raising and Lowering): Mention windows-frames dichotomy in
metaphor.
parent 4b65254d
2008-11-21 Martin Rudalics <rudalics@gmx.at> 2008-11-21 Martin Rudalics <rudalics@gmx.at>
* frames.texi (Frames): Fix typo, add cross references, reword.
(Initial Parameters): Reword special-display-frame-alist text.
(Frames and Windows): Reword. Describe argument norecord for
set-frame-selected-window.
(Input Focus): Describe argument norecord for select-frame.
Remove comment on MS-Windows behavior for focus-follows-mouse.
(Raising and Lowering): Mention windows-frames dichotomy in
metaphor.
* windows.texi (Displaying Buffers, Vertical Scrolling) * windows.texi (Displaying Buffers, Vertical Scrolling)
(Horizontal Scrolling): Fix indenting and rewording issues (Horizontal Scrolling): Fix indenting and rewording issues
introduced with 2008-11-07 change. introduced with 2008-11-07 change.
......
...@@ -8,16 +8,16 @@ ...@@ -8,16 +8,16 @@
@chapter Frames @chapter Frames
@cindex frame @cindex frame
In Emacs editing, A @dfn{frame} is a screen object that contains one In Emacs editing, a @dfn{frame} is a screen object that contains one
or more Emacs windows. It's the kind of object that is called a or more Emacs windows, see @ref{Windows}. It's the kind of object that
``window'' in the terminology of graphical environments; but we can't is called a ``window'' in the terminology of graphical environments; but
call it a ``window'' here, because Emacs uses that word in a different we can't call it a ``window'' here, because Emacs uses that word in a
way. different way. In Emacs Lisp, a @dfn{frame object} is a Lisp object
that represents a frame on the screen.
A frame initially contains a single main window and/or a minibuffer A frame initially contains a single main window and/or a minibuffer
window; you can subdivide the main window vertically or horizontally window; you can subdivide the main window vertically or horizontally
into smaller windows. In Emacs Lisp, a @dfn{frame object} is a Lisp into smaller windows. @xref{Splitting Windows}.
object that represents a frame on the screen.
@cindex terminal frame @cindex terminal frame
When Emacs runs on a text-only terminal, it starts with one When Emacs runs on a text-only terminal, it starts with one
...@@ -343,8 +343,9 @@ in many cases. ...@@ -343,8 +343,9 @@ in many cases.
Setting this variable does not affect existing frames. Setting this variable does not affect existing frames.
@end defvar @end defvar
See also @code{special-display-frame-alist}. @xref{Definition of Functions that display a buffer in a separate frame can override the
special-display-frame-alist}. default parameters by supplying their own parameters. @xref{Definition
of special-display-frame-alist}.
If you use options that specify window appearance when you invoke Emacs, If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to @code{default-frame-alist}. One they take effect by adding elements to @code{default-frame-alist}. One
...@@ -1006,7 +1007,7 @@ the selected frame. ...@@ -1006,7 +1007,7 @@ the selected frame.
A frame cannot be deleted if its minibuffer is used by other frames. A frame cannot be deleted if its minibuffer is used by other frames.
Normally, you cannot delete a frame if all other frames are invisible, Normally, you cannot delete a frame if all other frames are invisible,
but if the @var{force} is non-@code{nil}, then you are allowed to do so. but if @var{force} is non-@code{nil}, then you are allowed to do so.
@end deffn @end deffn
@defun frame-live-p frame @defun frame-live-p frame
...@@ -1074,7 +1075,7 @@ Window Ordering}. ...@@ -1074,7 +1075,7 @@ Window Ordering}.
@node Frames and Windows @node Frames and Windows
@section Frames and Windows @section Frames and Windows
Each window is part of one and only one frame; you can get the frame Each window is part of one and only one frame; you can get that frame
with @code{window-frame}. with @code{window-frame}.
@defun window-frame window @defun window-frame window
...@@ -1094,8 +1095,9 @@ If omitted or @code{nil}, @var{frame} defaults to the selected frame. ...@@ -1094,8 +1095,9 @@ If omitted or @code{nil}, @var{frame} defaults to the selected frame.
At any time, exactly one window on any frame is @dfn{selected within the At any time, exactly one window on any frame is @dfn{selected within the
frame}. The significance of this designation is that selecting the frame}. The significance of this designation is that selecting the
frame also selects this window. You can get the frame's current frame also selects this window. Conversely, selecting a window for
selected window with @code{frame-selected-window}. Emacs with @code{select-window} also makes that window selected within
its frame. @xref{Selecting Windows}.
@defun frame-selected-window &optional frame @defun frame-selected-window &optional frame
This function returns the window on @var{frame} that is selected This function returns the window on @var{frame} that is selected
...@@ -1103,15 +1105,16 @@ within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to ...@@ -1103,15 +1105,16 @@ within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to
the selected frame. the selected frame.
@end defun @end defun
@defun set-frame-selected-window frame window @defun set-frame-selected-window frame window &optional norecord
This sets the selected window of frame @var{frame} to @var{window}. This sets the selected window of frame @var{frame} to @var{window}.
If @var{frame} is @code{nil}, it operates on the selected frame. If If @var{frame} is @code{nil}, it operates on the selected frame. If
@var{frame} is the selected frame, this makes @var{window} the @var{frame} is the selected frame, this makes @var{window} the
selected window. This function returns @var{window}. selected window. This function returns @var{window}.
@end defun
Conversely, selecting a window for Emacs with @code{select-window} also Optional argument @var{norecord} non-@code{nil} means to neither change
makes that window selected within its frame. @xref{Selecting Windows}. the order of recently selected windows nor the buffer list (@pxref{The
Buffer List}).
@end defun
Another function that (usually) returns one of the windows in a given Another function that (usually) returns one of the windows in a given
frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}. frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
...@@ -1158,7 +1161,7 @@ runs a command that came from a certain terminal, the selected frame is ...@@ -1158,7 +1161,7 @@ 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 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 given time, it needs to consider only one selected frame at a time; this
frame is what we call @dfn{the selected frame} in this manual. The frame is what we call @dfn{the selected frame} in this manual. The
display on which the selected frame is displayed is the @dfn{selected display on which the selected frame is shown is the @dfn{selected
frame's display}. frame's display}.
@defun selected-frame @defun selected-frame
...@@ -1169,7 +1172,7 @@ Some window systems and window managers direct keyboard input to the ...@@ -1169,7 +1172,7 @@ Some window systems and window managers direct keyboard input to the
window object that the mouse is in; others require explicit clicks or window object that the mouse is in; others require explicit clicks or
commands to @dfn{shift the focus} to various window objects. Either commands to @dfn{shift the focus} to various window objects. Either
way, Emacs automatically keeps track of which frame has the focus. To way, Emacs automatically keeps track of which frame has the focus. To
switch to a different frame from a Lisp function, call explicitly switch to a different frame from a Lisp function, call
@code{select-frame-set-input-focus}. @code{select-frame-set-input-focus}.
Lisp programs can also switch frames ``temporarily'' by calling the Lisp programs can also switch frames ``temporarily'' by calling the
...@@ -1180,31 +1183,37 @@ until that control is somehow reasserted. ...@@ -1180,31 +1183,37 @@ until that control is somehow reasserted.
When using a text-only terminal, only one frame can be displayed at a 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 time on the terminal, so after a call to @code{select-frame}, the next
redisplay actually displays the newly selected frame. This frame redisplay actually displays the newly selected frame. This frame
remains selected until a subsequent call to @code{select-frame} or remains selected until a subsequent call to @code{select-frame}. Each
@code{select-frame-set-input-focus}. Each terminal frame has a number terminal frame has a number which appears in the mode line before the
which appears in the mode line before the buffer name (@pxref{Mode buffer name (@pxref{Mode Line Variables}).
Line Variables}).
@defun select-frame-set-input-focus frame @defun select-frame-set-input-focus frame
This function makes @var{frame} the selected frame, raises it (should This function selects @var{frame}, raises it (should it happen to be
it happen to be obscured by other frames) and tries to give it the X obscured by other frames) and tries to give it the X server's focus. On
server's focus. On a text-only terminal, the next redisplay displays a text-only terminal, the next redisplay displays the new frame on the
the new frame on the entire terminal screen. The return value of this entire terminal screen. The return value of this function is not
function is not significant. significant.
@end defun @end defun
@c ??? This is not yet implemented properly. @c ??? This is not yet implemented properly.
@defun select-frame frame @defun select-frame frame &optional norecord
This function selects frame @var{frame}, temporarily disregarding the This function selects frame @var{frame}, temporarily disregarding the
focus of the X server if any. The selection of @var{frame} lasts until focus of the X server if any. The selection of @var{frame} lasts until
the next time the user does something to select a different frame, or 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 until the next time this function is called. (If you are using a
window system, the previously selected frame may be restored as the window system, the previously selected frame may be restored as the
selected frame after return to the command loop, because it still may selected frame after return to the command loop, because it still may
have the window system's input focus.) The specified @var{frame} have the window system's input focus.)
becomes the selected frame, as explained above, and the terminal that
@var{frame} is on becomes the selected terminal. This function The specified @var{frame} becomes the selected frame, as explained
returns @var{frame}, or @code{nil} if @var{frame} has been deleted. above, and the terminal that @var{frame} is on becomes the selected
terminal. The window selected within @var{frame} becomes the selected
window. This function returns @var{frame}, or @code{nil} if @var{frame}
has been deleted.
Optional argument @var{norecord} non-@code{nil} means to neither change
the order of recently selected windows nor the buffer list. @xref{The
Buffer List}.
In general, you should never use @code{select-frame} in a way that could 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. switch to a different terminal without switching back when you're done.
...@@ -1258,9 +1267,7 @@ change it. ...@@ -1258,9 +1267,7 @@ change it.
This option is how you inform Emacs whether the window manager transfers This option is how you inform Emacs whether the window manager transfers
focus when the user moves the mouse. Non-@code{nil} says that it does. focus when the user moves the mouse. Non-@code{nil} says that it does.
When this is so, the command @code{other-frame} moves the mouse to a When this is so, the command @code{other-frame} moves the mouse to a
position consistent with the new selected frame. (This option has no position consistent with the new selected frame.
effect on MS-Windows, where the mouse pointer is always automatically
moved by the OS to the selected frame.)
@end defopt @end defopt
@node Visibility of Frames @node Visibility of Frames
...@@ -1337,7 +1344,8 @@ moving it to the bottom of the stack. This motion is in the notional ...@@ -1337,7 +1344,8 @@ moving it to the bottom of the stack. This motion is in the notional
third dimension only, and does not change the position of the window third dimension only, and does not change the position of the window
on the screen. on the screen.
You can raise and lower Emacs frame Windows with these functions: With Emacs, frames constitute the windows in the metaphor sketched
above. You can raise and lower frames using these functions:
@deffn Command raise-frame &optional frame @deffn Command raise-frame &optional frame
This function raises frame @var{frame} (default, the selected frame). This function raises frame @var{frame} (default, the selected frame).
...@@ -1399,7 +1407,7 @@ button. ...@@ -1399,7 +1407,7 @@ button.
@defspec track-mouse body@dots{} @defspec track-mouse body@dots{}
This special form executes @var{body}, with generation of mouse motion This special form executes @var{body}, with generation of mouse motion
events enabled. Typically @var{body} would use @code{read-event} to events enabled. Typically, @var{body} would use @code{read-event} to
read the motion events and modify the display accordingly. @xref{Motion read the motion events and modify the display accordingly. @xref{Motion
Events}, for the format of mouse motion events. Events}, for the format of mouse motion events.
......
...@@ -1260,6 +1260,7 @@ to override the default splitting mechanism of display-buffer. ...@@ -1260,6 +1260,7 @@ to override the default splitting mechanism of display-buffer.
*** If pop-up-frames has the value `graphic-only', display-buffer only *** If pop-up-frames has the value `graphic-only', display-buffer only
makes a separate frame on graphic displays. makes a separate frame on graphic displays.
+++
*** select-frame and set-frame-selected-window have new optional *** select-frame and set-frame-selected-window have new optional
argument NORECORD. If non-nil, this will avoid messing with the order argument NORECORD. If non-nil, this will avoid messing with the order
of recently selected windows and the buffer list. of recently selected windows and the buffer list.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment