@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/frames
@node Frames, Positions, Windows, Top
@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
The frame is displayed in an X window.
@item t
A terminal frame on a character display.
-@item mac
-The frame is displayed on a Macintosh.
@item w32
The frame is displayed on MS-Windows 9X/NT.
@item pc
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
to. These variables include @code{default-minibuffer-frame},
@code{defining-kbd-macro}, @code{last-kbd-macro}, and
@code{system-key-alist}. They are always terminal-local, and can never
-be buffer-local (@pxref{Buffer-Local Variables}) or frame-local.
+be buffer-local (@pxref{Buffer-Local Variables}).
A single X server can handle more than one screen. A display name
@samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
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
@code{mono}.
@item title
-If a frame has a non-@code{nil} title, it appears in the window system's
-border for the frame, and also in the mode line of windows in that frame
-if @code{mode-line-frame-identification} uses @samp{%F}
-(@pxref{%-Constructs}). This is normally the case when Emacs is not
-using a window system, and can only display one frame at a time.
-@xref{Frame Titles}.
+If a frame has a non-@code{nil} title, it appears in the window
+system's title bar at the top of the frame, and also in the mode line
+of windows in that frame if @code{mode-line-frame-identification} uses
+@samp{%F} (@pxref{%-Constructs}). This is normally the case when
+Emacs is not using a window system, and can only display one frame at
+a time. @xref{Frame Titles}.
@item name
The name of the frame. The frame name serves as a default for the frame
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
@table @code
@item left
-The screen position of the left edge, in pixels, with respect to the
-left edge of the screen. The value may be a positive number @var{pos},
-or a list of the form @code{(+ @var{pos})} which permits specifying a
-negative @var{pos} value.
-
-A negative number @minus{}@var{pos}, or a list of the form @code{(-
-@var{pos})}, actually specifies the position of the right edge of the
-window with respect to the right edge of the screen. A positive value
-of @var{pos} counts toward the left. @strong{Reminder:} if the
-parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
-positive.
+The position, in pixels, of the left (or right) edge of the frame with
+respect to the left (or right) edge of the screen. The value may be:
+
+@table @asis
+@item an integer
+A positive integer relates the left edge of the frame to the left edge
+of the screen. A negative integer relates the right frame edge to the
+right screen edge.
+
+@item @code{(+ @var{pos})}
+This specifies the position of the left frame edge relative to the left
+screen edge. The integer @var{pos} may be positive or negative; a
+negative value specifies a position outside the screen.
+
+@item @code{(- @var{pos})}
+This specifies the position of the right frame edge relative to the right
+screen edge. The integer @var{pos} may be positive or negative; a
+negative value specifies a position outside the screen.
+@end table
Some window managers ignore program-specified positions. If you want to
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.
@item top
-The screen position of the top edge, in pixels, with respect to the
-top edge of the screen. It works just like @code{left}, except vertically
-instead of horizontally.
+The screen position of the top (or bottom) edge, in pixels, with respect
+to the top (or bottom) edge of the screen. It works just like
+@code{left}, except vertically instead of horizontally.
@item icon-left
The screen position of the left edge @emph{of the frame's icon}, in
pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
@item width
-The width of the frame contents, in characters. (To get the height in
+The width of the frame contents, in characters. (To get the width in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
@item user-size
@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
@defun frame-pixel-height &optional frame
@defunx frame-pixel-width &optional frame
-These functions return the height and width of @var{frame}, measured in
-pixels. If you don't supply @var{frame}, they use the selected frame.
+These functions return the height and width of the main display area
+of @var{frame}, measured in pixels. If you don't supply @var{frame},
+they use the selected frame.
+
+These values include the internal borders, and windows' scroll bars
+and fringes (which belong to individual windows, not to the frame
+itself), but do not include menu bars or tool bars (except when using
+X without an X toolkit).
@end defun
@defun frame-char-height &optional frame
For the size parameters, the value must be an integer. The position
parameter names @code{left} and @code{top} are not totally accurate,
because some values indicate the position of the right or bottom edges
-instead. These are the @var{value} possibilities for the position
-parameters:
-
-@table @asis
-@item an integer
-A positive integer relates the left edge or top edge of the window to
-the left or top edge of the screen. A negative integer relates the
-right or bottom edge of the window to the right or bottom edge of the
-screen.
-
-@item @code{(+ @var{position})}
-This specifies the position of the left or top edge of the window
-relative to the left or top edge of the screen. The integer
-@var{position} may be positive or negative; a negative value specifies a
-position outside the screen.
-
-@item @code{(- @var{position})}
-This specifies the position of the right or bottom edge of the window
-relative to the right or bottom edge of the screen. The integer
-@var{position} may be positive or negative; a negative value specifies a
-position outside the screen.
-@end table
+instead. The @var{value} possibilities for the position parameters are:
+an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
+as previously described (@pxref{Position Parameters}).
Here is an example:
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.
only; if the clipboard holds other types of data, Emacs treats the
clipboard as empty.
-@cindex scrap support (for Mac OS)
-On Mac OS, selection-like data transfer between applications is
-performed through a mechanism called @dfn{scraps}. The clipboard is a
-particular scrap named @code{com.apple.scrap.clipboard}. Types of scrap
-data are called @dfn{scrap flavor types}, which are identified by
-four-char codes such as @code{TEXT}. Emacs associates a selection with
-a scrap, and a selection type with a scrap flavor type via
-@code{mac-scrap-name} and @code{mac-ostype} properties, respectively.
-
-@example
-(get 'CLIPBOARD 'mac-scrap-name)
- @result{} "com.apple.scrap.clipboard"
-(get 'com.apple.traditional-mac-plain-text 'mac-ostype)
- @result{} "TEXT"
-@end example
-
-Conventionally, selection types for scrap flavor types on Mac OS have
-the form of @acronym{UTI, Uniform Type Identifier} such as
-@code{com.apple.traditional-mac-plain-text},
-@code{public.utf16-plain-text}, and @code{public.file-url}.
-
@defopt x-select-enable-clipboard
If this is non-@code{nil}, the Emacs yank functions consult the
clipboard before the primary selection, and the kill functions store in
the clipboard as well as the primary selection. Otherwise they do not
access the clipboard at all. The default is @code{nil} on most systems,
-but @code{t} on MS-Windows and Mac.
+but @code{t} on MS-Windows.
@end defopt
@node Drag and Drop
@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