@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/frames
-@node Frames, Positions, Windows, Top
+@node Frames
@chapter Frames
@cindex frame
To create a new frame, call the function @code{make-frame}.
-@defun make-frame &optional alist
+@deffn Command make-frame &optional alist
This function creates and returns a new frame, displaying the current
buffer.
@xref{Input Focus}. The previously selected frame remains selected.
On graphical terminals, however, the windowing system may select the
new frame for its own reasons.
-@end defun
+@end deffn
@defvar before-make-frame-hook
A normal hook run by @code{make-frame} before it creates the frame.
Window System, you can get the same results by means of X resources
in many cases.
-Setting this variable does not affect existing frames.
+Setting this variable does not affect existing frames. Furthermore,
+functions that display a buffer in a separate frame may override the
+default parameters by supplying their own parameters.
@end defopt
-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 invoke Emacs with command-line options that specify frame
appearance, those options take effect by adding elements to either
@code{initial-frame-alist} or @code{default-frame-alist}. Options
form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
type equals @var{on-state} (comparing using @code{equal}), the
corresponding @var{off-state} specifies what the cursor looks like
-when it blinks ``off.'' Both @var{on-state} and @var{off-state}
+when it blinks ``off''. Both @var{on-state} and @var{off-state}
should be suitable values for the @code{cursor-type} frame parameter.
There are various defaults for how to blink each type of cursor, if
of this function is not significant.
@end defun
-@defun select-frame frame &optional norecord
+@deffn Command 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
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.
-@end defun
+@end deffn
Emacs cooperates with the window system by arranging to select frames as
the server and window manager request. It does so by generating a
@node Raising and Lowering
@section Raising and Lowering Frames
- Most window systems use a desktop metaphor. Part of this metaphor is
-the idea that windows are stacked in a notional third dimension
-perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest.'' Where two windows overlap, the one higher up covers
-the one underneath. Even a window at the bottom of the stack can be
-seen if no other window overlaps it.
-
-@c @cindex raising a frame redundant with raise-frame
+@cindex raising a frame
@cindex lowering a frame
- A window's place in this ordering is not fixed; in fact, users tend
-to change the order frequently. @dfn{Raising} a window means moving
-it ``up,'' to the top of the stack. @dfn{Lowering} a window means
-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
-on the screen.
-
- With Emacs, frames constitute the windows in the metaphor sketched
-above. You can raise and lower frames using these functions:
+ Most window systems use a desktop metaphor. Part of this metaphor
+is the idea that system-level windows (e.g.@: Emacs frames) are
+stacked in a notional third dimension perpendicular to the screen
+surface. Where two overlap, the one higher up covers the one
+underneath. You can @dfn{raise} or @dfn{lower} a frame using the
+functions @code{raise-frame} and @code{lower-frame}.
@deffn Command raise-frame &optional frame
This function raises frame @var{frame} (default, the selected frame).
(@var{title} @var{item1} @var{item2}...)
@end example
-Each item should normally be a cons cell @code{(@var{line} . @var{value})},
-where @var{line} is a string, and @var{value} is the value to return if
-that @var{line} is chosen. An item can also be a string; this makes a
-non-selectable line in the menu.
+Each @var{item} should be a cons cell, @code{(@var{line} . @var{value})},
+where @var{line} is a string and @var{value} is the value to return if
+that @var{line} is chosen. Unlike in a menu keymap, a @code{nil}
+@var{value} does not make the menu item non-selectable.
+Alternatively, each @var{item} can be a string rather than a cons
+cell; this makes a non-selectable menu item.
If the user gets rid of the menu without making a valid choice, for
instance by clicking the mouse away from a valid choice or by typing
A dialog box is a variant of a pop-up menu---it looks a little
different, it always appears in the center of a frame, and it has just
one level and one or more buttons. The main use of dialog boxes is
-for asking questions that the user can answer with ``yes,'' ``no,''
+for asking questions that the user can answer with ``yes'', ``no'',
and a few other alternatives. With a single button, they can also
force the user to acknowledge important information. The functions
@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
@code{arrow} style, but you can specify a different style (one of
those above) by setting @code{void-text-area-pointer}.
-@defvar void-text-area-pointer
+@defopt void-text-area-pointer
This variable specifies the mouse pointer style for void text areas.
These include the areas after the end of a line or below the last line
in the buffer. The default is to use the @code{arrow} (non-text)
pointer style.
-@end defvar
+@end defopt
When using X, you can specify what the @code{text} pointer style
really looks like by setting the variable @code{x-pointer-shape}.
These functions provide a way to determine which color names are
valid, and what they look like. In some cases, the value depends on the
@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
-meaning of the term ``selected frame.''
+meaning of the term ``selected frame''.
To read user input of color names with completion, use
@code{read-color} (@pxref{High-Level Completion, read-color}).
server.
When the developers of X labeled software distributors as
-``vendors,'' they showed their false assumption that no system could
+``vendors'', they showed their false assumption that no system could
ever be developed and distributed noncommercially.
@end defun