# HG changeset patch # User Martin Rudalics # Date 1227262689 0 # Node ID 742bad2b3aebe6a7b04d82f5a1ea51e135ea2c46 # Parent 710b20693a81d658c72edc3dc9d395ecae5137ec (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. diff -r 710b20693a81 -r 742bad2b3aeb doc/lispref/frames.texi --- a/doc/lispref/frames.texi Fri Nov 21 10:12:57 2008 +0000 +++ b/doc/lispref/frames.texi Fri Nov 21 10:18:09 2008 +0000 @@ -8,16 +8,16 @@ @chapter Frames @cindex frame - 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 -``window'' in the terminology of graphical environments; but we can't -call it a ``window'' here, because Emacs uses that word in a different -way. + In Emacs editing, a @dfn{frame} is a screen object that contains one +or more Emacs windows, see @ref{Windows}. It's the kind of object that +is called a ``window'' in the terminology of graphical environments; but +we can't call it a ``window'' here, because Emacs uses that word in a +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 window; you can subdivide the main window vertically or horizontally -into smaller windows. In Emacs Lisp, a @dfn{frame object} is a Lisp -object that represents a frame on the screen. +into smaller windows. @xref{Splitting Windows}. @cindex terminal frame When Emacs runs on a text-only terminal, it starts with one @@ -343,8 +343,9 @@ Setting this variable does not affect existing frames. @end defvar -See also @code{special-display-frame-alist}. @xref{Definition of -special-display-frame-alist}. +Functions that display a buffer in a separate frame can override the +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, they take effect by adding elements to @code{default-frame-alist}. One @@ -1006,7 +1007,7 @@ 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, -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 @defun frame-live-p frame @@ -1074,7 +1075,7 @@ @node 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}. @defun window-frame window @@ -1094,8 +1095,9 @@ 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 also selects this window. You can get the frame's current -selected window with @code{frame-selected-window}. +frame also selects this window. Conversely, selecting a window for +Emacs with @code{select-window} also makes that window selected within +its frame. @xref{Selecting Windows}. @defun frame-selected-window &optional frame This function returns the window on @var{frame} that is selected @@ -1103,16 +1105,17 @@ the selected frame. @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}. If @var{frame} is @code{nil}, it operates on the selected frame. If @var{frame} is the selected frame, this makes @var{window} the selected window. This function returns @var{window}. + +Optional argument @var{norecord} non-@code{nil} means to neither change +the order of recently selected windows nor the buffer list (@pxref{The +Buffer List}). @end defun - Conversely, selecting a window for Emacs with @code{select-window} also -makes that window selected within its frame. @xref{Selecting Windows}. - Another function that (usually) returns one of the windows in a given frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}. @@ -1158,7 +1161,7 @@ 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 @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}. @defun selected-frame @@ -1169,7 +1172,7 @@ 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 +explicitly 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 @@ -1180,31 +1183,37 @@ 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 selected 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}). +remains selected until a subsequent call to @code{select-frame}. 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. +This function selects @var{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 +@defun select-frame frame &optional norecord This function selects frame @var{frame}, temporarily disregarding the 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 until the next time this function is called. (If you are using a window system, the previously selected frame may be restored as the selected frame after return to the command loop, because it still may -have the window system's input focus.) The specified @var{frame} -becomes the selected frame, as explained above, and the terminal that -@var{frame} is on becomes the selected terminal. This function -returns @var{frame}, or @code{nil} if @var{frame} has been deleted. +have the window system's input focus.) + +The specified @var{frame} becomes the selected frame, as explained +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 switch to a different terminal without switching back when you're done. @@ -1258,9 +1267,7 @@ 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. 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 -effect on MS-Windows, where the mouse pointer is always automatically -moved by the OS to the selected frame.) +position consistent with the new selected frame. @end defopt @node Visibility of Frames @@ -1337,7 +1344,8 @@ third dimension only, and does not change the position of the window 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 This function raises frame @var{frame} (default, the selected frame). @@ -1399,7 +1407,7 @@ @defspec track-mouse body@dots{} 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 Events}, for the format of mouse motion events.