@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
-@dfn{terminal frame}. If you create additional ones, Emacs displays
-one and only one at any given time---on the terminal screen, of course.
+@dfn{terminal frame}. If you create additional frames on the same
+terminal, Emacs displays one and only one at any given time---on that
+terminal screen, of course. You can create additional frames, either
+text-only or GUI, on other terminals from the same Emacs session.
+(This comes in handy when you connect to the same session from several
+remote locations.) @c FIXME: Add an xref to multi-tty doc.
@cindex window frame
When Emacs communicates directly with a supported window system, such
default from the standard X resources or whatever is used instead on
your system.
+After the frame is created, this function applies to it the
+parameters, if any, listed in the value of
+@code{frame-inherited-parameters} (see below) and not present in the
+argument, taking the values from the frame that was selected when
+@code{make-frame} was called.
+
The set of possible parameters depends in principle on what kind of
window system Emacs uses to display its frames. @xref{Window Frame
Parameters}, for documentation of individual parameters you can specify.
frame just created.
@end defvar
+@defvar frame-inherited-parameters
+This variable specifies the list of frame parameters that a newly
+created frame inherits from the currently selected frame. For each
+parameter (a symbol) that is an element in the list and is not present
+in the argument to @code{make-frame}, the function sets the value of
+that parameter in the created frame to its value in the selected
+frame.
+@end defvar
+
@node Multiple Displays
@section Multiple Displays
@cindex multiple X displays
parameters do something special. If the terminal supports colors, the
parameters @code{foreground-color}, @code{background-color},
@code{background-mode} and @code{display-type} are also meaningful.
+If the terminal supports frame transparency, the parameter
+@code{alpha} is also meaningful.
+
+ You can use frame parameters to define frame-local bindings for
+variables. @xref{Frame-Local Variables}.
@menu
* Parameter Access:: How to change a frame's parameters.
parameter. If you don't mention a parameter in @var{alist}, its value
doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
frame.
+
+You can use this function to define frame-local bindings for
+variables, see @ref{Frame-Local Variables}.
+@end defun
+
+@defun set-frame-parameter frame parm value
+This function sets the frame parameter @var{parm} to the specified
+@var{value}. If @var{frame} is @code{nil}, it defaults to the
+selected frame.
@end defun
@defun modify-all-frames-parameters alist
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
If you specify the frame name explicitly when you create the frame, the
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
-
-@item display-environment-variable
-The value of the @code{DISPLAY} environment variable for the frame. It
-is passed to child processes.
-
-@item term-environment-variable
-The value of the @code{TERM} environment variable for the frame. It
-is passed to child processes.
@end table
@node Position Parameters
@code{screen-gamma} value smaller than 2.2. This requests correction
that makes colors darker. A screen gamma value of 1.5 may give good
results for LCD color displays.
+
+@item alpha
+@cindex opacity, frame
+@cindex transparency, frame
+@vindex frame-alpha-lower-limit
+This parameter specifies the opacity of the frame, on graphical
+displays that support variable opacity. It should be an integer
+between 0 and 100, where 0 means completely transparent and 100 means
+completely opaque. It can also have a @code{nil} value, which tells
+Emacs not to set the frame opacity (leaving it to the window manager).
+
+To prevent the frame from disappearing completely from view, the
+variable @var{frame-alpha-lower-limit} defines a lower opacity limit.
+If the value of the frame parameter is less than the value of this
+variable, Emacs uses the latter. By default,
+@var{frame-alpha-lower-limit} is 20.
+
+The @code{alpha} frame parameter can also be a cons cell
+@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
+opacity of the frame when it is selected, and @samp{inactive} is the
+opactity when it is not selected.
@end table
-These frame parameters are semi-obsolete in that they are automatically
-equivalent to particular face attributes of particular faces.
-@xref{Standard Faces,,, emacs, The Emacs Manual}.
+The following frame parameters are semi-obsolete in that they are
+automatically equivalent to particular face attributes of particular
+faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
@table @code
@item font
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
@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
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
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}.
-@end defun
- Conversely, selecting a window for Emacs with @code{select-window} also
-makes that window selected within its frame. @xref{Selecting Windows}.
+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
Another function that (usually) returns one of the windows in a given
frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
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
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
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.
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
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).
@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.
@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
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}).
+
@defun color-defined-p color &optional frame
This function reports whether a color name is meaningful. It returns
@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says