root/trunk/lispref/frames.texi

@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, 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.

  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.

@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.

@cindex window frame
  When Emacs communicates directly with a supported window system, such
as X, it does not have a terminal frame; instead, it starts with
a single @dfn{window frame}, but you can create more, and Emacs can
display several such frames at once as is usual for window systems.

@defun framep object
This predicate returns a non-@code{nil} value if @var{object} is a
frame, and @code{nil} otherwise.  For a frame, the value indicates which
kind of display the frame uses:

@table @code
@item x
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
The frame is displayed on an MS-DOS terminal.
@end table
@end defun

@menu
* Creating Frames::             Creating additional frames.
* Multiple Displays::           Creating frames on other displays.
* Frame Parameters::            Controlling frame size, position, font, etc.
* Frame Titles::                Automatic updating of frame titles.
* Deleting Frames::             Frames last until explicitly deleted.
* Finding All Frames::          How to examine all existing frames.
* Frames and Windows::          A frame contains windows;
                                  display of text always works through windows.
* Minibuffers and Frames::      How a frame finds the minibuffer to use.
* Input Focus::                 Specifying the selected frame.
* Visibility of Frames::        Frames may be visible or invisible, or icons.
* Raising and Lowering::        Raising a frame makes it hide other windows;
                                  lowering it makes the others hide it.
* Frame Configurations::        Saving the state of all frames.
* Mouse Tracking::              Getting events that say when the mouse moves.
* Mouse Position::              Asking where the mouse is, or moving it.
* Pop-Up Menus::                Displaying a menu for the user to select from.
* Dialog Boxes::                Displaying a box to ask yes or no.
* Pointer Shape::               Specifying the shape of the mouse pointer.
* Window System Selections::    Transferring text to and from other X clients.
* Drag and Drop::               Internals of Drag-and-Drop implementation.
* Color Names::                 Getting the definitions of color names.
* Text Terminal Colors::        Defining colors for text-only terminals.
* Resources::                   Getting resource values from the server.
* Display Feature Testing::     Determining the features of a terminal.
@end menu

  @xref{Display}, for information about the related topic of
controlling Emacs redisplay.

@node Creating Frames
@section Creating Frames

To create a new frame, call the function @code{make-frame}.

@defun make-frame &optional alist
This function creates and returns a new frame, displaying the current
buffer.  If you are using a supported window system, it makes a window
frame; otherwise, it makes a terminal frame.

The argument is an alist specifying frame parameters.  Any parameters
not mentioned in @var{alist} default according to the value of the
variable @code{default-frame-alist}; parameters not specified even there
default from the standard X resources or whatever is used instead on
your system.

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.

This function itself does not make the new frame the selected frame.
@xref{Input Focus}.  The previously selected frame remains selected.
However, the window system may select the new frame for its own reasons,
for instance if the frame appears under the mouse pointer and your
setup is for focus to follow the pointer.
@end defun

@defvar before-make-frame-hook
A normal hook run by @code{make-frame} before it actually creates the
frame.
@end defvar

@defvar after-make-frame-functions
An abnormal hook run by @code{make-frame} after it creates the frame.
Each function in @code{after-make-frame-functions} receives one argument, the
frame just created.
@end defvar

@node Multiple Displays
@section Multiple Displays
@cindex multiple X displays
@cindex displays, multiple

  A single Emacs can talk to more than one X display.
Initially, Emacs uses just one display---the one chosen with the
@code{DISPLAY} environment variable or with the @samp{--display} option
(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}).  To connect to
another display, use the command @code{make-frame-on-display} or specify
the @code{display} frame parameter when you create the frame.

  Emacs treats each X server as a separate terminal, giving each one its
own selected frame and its own minibuffer windows.  However, only one of
those frames is ``@emph{the} selected frame'' at any given moment, see
@ref{Input Focus}.

  A few Lisp variables are @dfn{terminal-local}; that is, they have a
separate binding for each terminal.  The binding in effect at any time
is the one for the terminal that the currently selected frame belongs
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}).

  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
part specifies the screen number for a given server.  When you use two
screens belonging to one server, Emacs knows by the similarity in their
names that they share a single keyboard, and it treats them as a single
terminal.

  Note that some graphical terminals can output to more than a one
monitor (or other output device) at the same time.  On these
``multi-monitor'' setups, a single @var{display} value controls the
output to all the physical monitors.  In this situation, there is
currently no platform-independent way for Emacs to distinguish between
the different physical monitors.

@deffn Command make-frame-on-display display &optional parameters
This creates and returns a new frame on display @var{display}, taking
the other frame parameters from @var{parameters}.  Aside from the
@var{display} argument, it is like @code{make-frame} (@pxref{Creating
Frames}).
@end deffn

@defun x-display-list
This returns a list that indicates which X displays Emacs has a
connection to.  The elements of the list are strings, and each one is
a display name.
@end defun

@defun x-open-connection display &optional xrm-string must-succeed
This function opens a connection to the X display @var{display}.  It
does not create a frame on that display, but it permits you to check
that communication can be established with that display.

The optional argument @var{xrm-string}, if not @code{nil}, is a
string of resource names and values, in the same format used in the
@file{.Xresources} file.  The values you specify override the resource
values recorded in the X server itself; they apply to all Emacs frames
created on this display.  Here's an example of what this string might
look like:

@example
"*BorderWidth: 3\n*InternalBorder: 2\n"
@end example

@xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.

If @var{must-succeed} is non-@code{nil}, failure to open the connection
terminates Emacs.  Otherwise, it is an ordinary Lisp error.
@end defun

@defun x-close-connection display
This function closes the connection to display @var{display}.  Before
you can do this, you must first delete all the frames that were open on
that display (@pxref{Deleting Frames}).
@end defun

@node Frame Parameters
@section Frame Parameters
@cindex frame parameters

  A frame has many parameters that control its appearance and behavior.
Just what parameters a frame has depends on what display mechanism it
uses.

  Frame parameters exist mostly for the sake of window systems.  A
terminal frame has a few parameters, mostly for compatibility's sake;
only the @code{height}, @code{width}, @code{name}, @code{title},
@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
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.

@menu
* Parameter Access::       How to change a frame's parameters.
* Initial Parameters::     Specifying frame parameters when you make a frame.
* Window Frame Parameters:: List of frame parameters for window systems.
* Size and Position::      Changing the size and position of a frame.
* Geometry::               Parsing geometry specifications.
@end menu

@node Parameter Access
@subsection Access to Frame Parameters

These functions let you read and change the parameter values of a
frame.

@defun frame-parameter frame parameter
This function returns the value of the parameter @var{parameter} (a
symbol) of @var{frame}.  If @var{frame} is @code{nil}, it returns the
selected frame's parameter.  If @var{frame} has no setting for
@var{parameter}, this function returns @code{nil}.
@end defun

@defun frame-parameters &optional frame
The function @code{frame-parameters} returns an alist listing all the
parameters of @var{frame} and their values.  If @var{frame} is
@code{nil} or omitted, this returns the selected frame's parameters
@end defun

@defun modify-frame-parameters frame alist
This function alters the parameters of frame @var{frame} based on the
elements of @var{alist}.  Each element of @var{alist} has the form
@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
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.
@end defun

@defun modify-all-frames-parameters alist
This function alters the frame parameters of all existing frames
according to @var{alist}, then modifies @code{default-frame-alist}
(and, if necessary, @code{initial-frame-alist}) to apply the same
parameter values to frames that will be created henceforth.
@end defun

@node Initial Parameters
@subsection Initial Frame Parameters

You can specify the parameters for the initial startup frame
by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).

@defvar initial-frame-alist
This variable's value is an alist of parameter values used when creating
the initial window frame.  You can set this variable to specify the
appearance of the initial frame without altering subsequent frames.
Each element has the form:

@example
(@var{parameter} . @var{value})
@end example

Emacs creates the initial frame before it reads your init
file.  After reading that file, Emacs checks @code{initial-frame-alist},
and applies the parameter settings in the altered value to the already
created initial frame.

If these settings affect the frame geometry and appearance, you'll see
the frame appear with the wrong ones and then change to the specified
ones.  If that bothers you, you can specify the same geometry and
appearance with X resources; those do take effect before the frame is
created.  @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.

X resource settings typically apply to all frames.  If you want to
specify some X resources solely for the sake of the initial frame, and
you don't want them to apply to subsequent frames, here's how to achieve
this.  Specify parameters in @code{default-frame-alist} to override the
X resources for subsequent frames; then, to prevent these from affecting
the initial frame, specify the same parameters in
@code{initial-frame-alist} with values that match the X resources.
@end defvar

If these parameters specify a separate minibuffer-only frame with
@code{(minibuffer . nil)}, and you have not created one, Emacs creates
one for you.

@defvar minibuffer-frame-alist
This variable's value is an alist of parameter values used when creating
an initial minibuffer-only frame---if such a frame is needed, according
to the parameters for the main initial frame.
@end defvar

@defvar default-frame-alist
This is an alist specifying default values of frame parameters for all
Emacs frames---the first frame, and subsequent frames.  When using the X
Window System, you can get the same results by means of X resources
in many cases.

Setting this variable does not affect existing frames.
@end defvar

See also @code{special-display-frame-alist}.  @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
exception is @samp{-geometry}, which adds the specified position to
@code{initial-frame-alist} instead.  @xref{Emacs Invocation,, Command
Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.

@node Window Frame Parameters
@subsection Window Frame Parameters

  Just what parameters a frame has depends on what display mechanism
it uses.  This section describes the parameters that have special
meanings on some or all kinds of terminals.  Of these, @code{name},
@code{title}, @code{height}, @code{width}, @code{buffer-list} and
@code{buffer-predicate} provide meaningful information in terminal
frames, and @code{tty-color-mode} is meaningful @emph{only} in
terminal frames.

@menu
* Basic Parameters::            Parameters that are fundamental.
* Position Parameters::         The position of the frame on the screen.
* Size Parameters::             Frame's size.
* Layout Parameters::           Size of parts of the frame, and
                                  enabling or disabling some parts.
* Buffer Parameters::           Which buffers have been or should be shown.
* Management Parameters::       Communicating with the window manager.
* Cursor Parameters::           Controlling the cursor appearance.
* Color Parameters::            Colors of various parts of the frame.
@end menu

@node Basic Parameters
@subsubsection Basic Parameters

  These frame parameters give the most basic information about the
frame.  @code{title} and @code{name} are meaningful on all terminals.

@table @code
@item display
The display on which to open this frame.  It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@code{DISPLAY} environment variable.

@item display-type
This parameter describes the range of possible colors that can be used
in this frame.  Its value is @code{color}, @code{grayscale} or
@code{mono}.

@item title
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
title, if the @code{title} parameter is unspecified or @code{nil}.  If
you don't specify a name, Emacs sets the frame name automatically
(@pxref{Frame Titles}).

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.
@end table

@node Position Parameters
@subsubsection Position Parameters

  Position parameters' values are normally measured in pixels, but on
text-only terminals they count characters or lines instead.

@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.

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.

@item icon-left
The screen position of the left edge @emph{of the frame's icon}, in
pixels, counting from the left edge of the screen.  This takes effect if
and when the frame is iconified.

If you specify a value for this parameter, then you must also specify
a value for @code{icon-top} and vice versa.  The window manager may
ignore these two parameters.

@item icon-top
The screen position of the top edge @emph{of the frame's icon}, in
pixels, counting from the top edge of the screen.  This takes effect if
and when the frame is iconified.

@item user-position
When you create a frame and specify its screen position with the
@code{left} and @code{top} parameters, use this parameter to say whether
the specified position was user-specified (explicitly requested in some
way by a human user) or merely program-specified (chosen by a program).
A non-@code{nil} value says the position was user-specified.

Window managers generally heed user-specified positions, and some heed
program-specified positions too.  But many ignore program-specified
positions, placing the window in a default fashion or letting the user
place it with the mouse.  Some window managers, including @code{twm},
let the user specify whether to obey program-specified positions or
ignore them.

When you call @code{make-frame}, you should specify a non-@code{nil}
value for this parameter if the values of the @code{left} and @code{top}
parameters represent the user's stated preference; otherwise, use
@code{nil}.
@end table

@node Size Parameters
@subsubsection Size Parameters

  Size parameters' values are normally measured in pixels, but on
text-only terminals they count characters or lines instead.

@table @code
@item height
The height of the frame contents, in characters.  (To get the height 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 width in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)

@item user-size
This does for the size parameters @code{height} and @code{width} what
the @code{user-position} parameter (see above) does for the position
parameters @code{top} and @code{left}.

@item fullscreen
Specify that width, height or both shall be set to the size of the screen.
The value @code{fullwidth} specifies that width shall be the size of the
screen.  The value @code{fullheight} specifies that height shall be the
size of the screen.  The value @code{fullboth} specifies that both the
width and the height shall be set to the size of the screen.
@end table

@node Layout Parameters
@subsubsection Layout Parameters

  These frame parameters enable or disable various parts of the
frame, or control their sizes.

@table @code
@item border-width
The width in pixels of the frame's border.

@item internal-border-width
The distance in pixels between text (or fringe) and the frame's border.

@item vertical-scroll-bars
Whether the frame has scroll bars for vertical scrolling, and which side
of the frame they should be on.  The possible values are @code{left},
@code{right}, and @code{nil} for no scroll bars.

@ignore
@item horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling
(non-@code{nil} means yes).  Horizontal scroll bars are not currently
implemented.
@end ignore

@item scroll-bar-width
The width of vertical scroll bars, in pixels, or @code{nil} meaning to
use the default width.

@item left-fringe
@itemx right-fringe
The default width of the left and right fringes of windows in this
frame (@pxref{Fringes}).  If either of these is zero, that effectively
removes the corresponding fringe.  A value of @code{nil} stands for
the standard fringe width, which is the width needed to display the
fringe bitmaps.

The combined fringe widths must add up to an integral number of
columns, so the actual default fringe widths for the frame may be
larger than the specified values.  The extra width needed to reach an
acceptable total is distributed evenly between the left and right
fringe.  However, you can force one fringe or the other to a precise
width by specifying that width as a negative integer.  If both widths are
negative, only the left fringe gets the specified width.

@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu
bar.  The default is 1.  A value of @code{nil} means don't display a
menu bar.  @xref{Menu Bar}.  (The X toolkit and GTK allow at most one
menu bar line; they treat larger values as 1.)

@item tool-bar-lines
The number of lines to use for the tool bar.  A value of @code{nil}
means don't display a tool bar.  (GTK allows at most one tool bar line;
it treats larger values as 1.)

@item line-spacing
Additional space to leave below each text line, in pixels (a positive
integer).  @xref{Line Height}, for more information.
@end table

@node Buffer Parameters
@subsubsection Buffer Parameters

  These frame parameters, meaningful on all kinds of terminals, deal
with which buffers have been, or should, be displayed in the frame.

@table @code
@item minibuffer
Whether this frame has its own minibuffer.  The value @code{t} means
yes, @code{nil} means no, @code{only} means this frame is just a
minibuffer.  If the value is a minibuffer window (in some other frame),
the new frame uses that minibuffer.

@item buffer-predicate
The buffer-predicate function for this frame.  The function
@code{other-buffer} uses this predicate (from the selected frame) to
decide which buffers it should consider, if the predicate is not
@code{nil}.  It calls the predicate with one argument, a buffer, once for
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.

@item buffer-list
A list of buffers that have been selected in this frame,
ordered most-recently-selected first.

@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.
@end table

@node Management Parameters
@subsubsection Window Management Parameters
@cindex window manager, and frame parameters

  These frame parameters, meaningful only on window system displays,
interact with the window manager.

@table @code
@item visibility
The state of visibility of the frame.  There are three possibilities:
@code{nil} for invisible, @code{t} for visible, and @code{icon} for
iconified.  @xref{Visibility of Frames}.

@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).

@item auto-lower
Whether deselecting the frame lowers it (non-@code{nil} means yes).

@item icon-type
The type of icon to use for this frame when it is iconified.  If the
value is a string, that specifies a file containing a bitmap to use.
Any other non-@code{nil} value specifies the default bitmap icon (a
picture of a gnu); @code{nil} specifies a text icon.

@item icon-name
The name to use in the icon for this frame, when and if the icon
appears.  If this is @code{nil}, the frame's title is used.

@item window-id
The number of the window-system window used by the frame
to contain the actual Emacs windows.

@item outer-window-id
The number of the outermost window-system window used for the whole frame.

@item wait-for-wm
If non-@code{nil}, tell Xt to wait for the window manager to confirm
geometry changes.  Some window managers, including versions of Fvwm2
and KDE, fail to confirm, so Xt hangs.  Set this to @code{nil} to
prevent hanging with those window managers.

@ignore
@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
Specifying this lets you create an Emacs window inside some other
application's window.  (It is not certain this will be implemented; try
it and see if it works.)
@end ignore
@end table

@node Cursor Parameters
@subsubsection Cursor Parameters

  This frame parameter controls the way the cursor looks.

@table @code
@item cursor-type
How to display the cursor.  Legitimate values are:

@table @code
@item box
Display a filled box.  (This is the default.)
@item hollow
Display a hollow box.
@item nil
Don't display a cursor.
@item bar
Display a vertical bar between characters.
@item (bar . @var{width})
Display a vertical bar @var{width} pixels wide between characters.
@item hbar
Display a horizontal bar.
@item (hbar . @var{height})
Display a horizontal bar @var{height} pixels high.
@end table
@end table

@vindex cursor-type
The buffer-local variable @code{cursor-type} overrides the value of
the @code{cursor-type} frame parameter, but if it is @code{t}, that
means to use the cursor specified for the frame.

@defvar blink-cursor-alist
This variable specifies how to blink the cursor.  Each element has the
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}
should be suitable values for the @code{cursor-type} frame parameter.

There are various defaults for how to blink each type of cursor, if
the type is not mentioned as an @var{on-state} here.  Changes in this
variable do not take effect immediately, only when you specify the
@code{cursor-type} frame parameter.
@end defvar

@defvar cursor-in-non-selected-windows
This variable controls how the cursor looks in a window that is not
selected.  It supports the same values as the @code{cursor-type} frame
parameter; also, @code{nil} means don't display a cursor in
nonselected windows, and @code{t} (the default) means use a standard
modificatoin of the usual cursor type (solid box becomes hollow box,
and bar becomes a narrower bar).
@end defvar

@node Color Parameters
@subsubsection Color Parameters

  These frame parameters control the use of colors.

@table @code
@item background-mode
This parameter is either @code{dark} or @code{light}, according
to whether the background color is a light one or a dark one.

@item tty-color-mode
@cindex standard colors for character terminals
This parameter overrides the terminal's color support as given by the
system's terminal capabilities database in that this parameter's value
specifies the color mode to use in terminal frames.  The value can be
either a symbol or a number.  A number specifies the number of colors
to use (and, indirectly, what commands to issue to produce each
color).  For example, @code{(tty-color-mode . 8)} specifies use of the
ANSI escape sequences for 8 standard text colors.  A value of -1 turns
off color support.

If the parameter's value is a symbol, it specifies a number through
the value of @code{tty-color-mode-alist}, and the associated number is
used instead.

@item screen-gamma
@cindex gamma correction
If this is a number, Emacs performs ``gamma correction'' which adjusts
the brightness of all colors.  The value should be the screen gamma of
your display, a floating point number.

Usual PC monitors have a screen gamma of 2.2, so color values in
Emacs, and in X windows generally, are calibrated to display properly
on a monitor with that gamma value.  If you specify 2.2 for
@code{screen-gamma}, that means no correction is needed.  Other values
request correction, designed to make the corrected colors appear on
your screen the way they would have appeared without correction on an
ordinary monitor with a gamma value of 2.2.

If your monitor displays colors too light, you should specify a
@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.
@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}.

@table @code
@item font
The name of the font for displaying text in the frame.  This is a
string, either a valid font name for your system or the name of an Emacs
fontset (@pxref{Fontsets}).  It is equivalent to the @code{font}
attribute of the @code{default} face.

@item foreground-color
The color to use for the image of a character.  It is equivalent to
the @code{:foreground} attribute of the @code{default} face.

@item background-color
The color to use for the background of characters.  It is equivalent to
the @code{:background} attribute of the @code{default} face.

@item mouse-color
The color for the mouse pointer.  It is equivalent to the @code{:background}
attribute of the @code{mouse} face.

@item cursor-color
The color for the cursor that shows point.  It is equivalent to the
@code{:background} attribute of the @code{cursor} face.

@item border-color
The color for the border of the frame.  It is equivalent to the
@code{:background} attribute of the @code{border} face.

@item scroll-bar-foreground
If non-@code{nil}, the color for the foreground of scroll bars.  It is
equivalent to the @code{:foreground} attribute of the
@code{scroll-bar} face.

@item scroll-bar-background
If non-@code{nil}, the color for the background of scroll bars.  It is
equivalent to the @code{:background} attribute of the
@code{scroll-bar} face.
@end table

@node Size and Position
@subsection Frame Size And Position
@cindex size of frame
@cindex screen size
@cindex frame size
@cindex resize frame

  You can read or change the size and position of a frame using the
frame parameters @code{left}, @code{top}, @code{height}, and
@code{width}.  Whatever geometry parameters you don't specify are chosen
by the window manager in its usual fashion.

  Here are some special features for working with sizes and positions.
(For the precise meaning of ``selected frame'' used by these functions,
see @ref{Input Focus}.)

@defun set-frame-position frame left top
This function sets the position of the top left corner of @var{frame} to
@var{left} and @var{top}.  These arguments are measured in pixels, and
normally count from the top left corner of the screen.

Negative parameter values position the bottom edge of the window up from
the bottom edge of the screen, or the right window edge to the left of
the right edge of the screen.  It would probably be better if the values
were always counted from the left and top, so that negative arguments
would position the frame partly off the top or left edge of the screen,
but it seems inadvisable to change that now.
@end defun

@defun frame-height &optional frame
@defunx frame-width &optional frame
These functions return the height and width of @var{frame}, measured in
lines and columns.  If you don't supply @var{frame}, they use the
selected frame.
@end defun

@defun screen-height
@defunx screen-width
These functions are old aliases for @code{frame-height} and
@code{frame-width}.  When you are using a non-window terminal, the size
of the frame is normally the same as the size of the terminal screen.
@end defun

@defun frame-pixel-height &optional frame
@defunx frame-pixel-width &optional 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
@defunx frame-char-width &optional frame
These functions return the height and width of a character in
@var{frame}, measured in pixels.  The values depend on the choice of
font.  If you don't supply @var{frame}, these functions use the selected
frame.
@end defun

@defun set-frame-size frame cols rows
This function sets the size of @var{frame}, measured in characters;
@var{cols} and @var{rows} specify the new width and height.

To set the size based on values measured in pixels, use
@code{frame-char-height} and @code{frame-char-width} to convert
them to units of characters.
@end defun

@defun set-frame-height frame lines &optional pretend
This function resizes @var{frame} to a height of @var{lines} lines.  The
sizes of existing windows in @var{frame} are altered proportionally to
fit.

If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
lines of output in @var{frame}, but does not change its value for the
actual height of the frame.  This is only useful for a terminal frame.
Using a smaller height than the terminal actually implements may be
useful to reproduce behavior observed on a smaller screen, or if the
terminal malfunctions when using its whole screen.  Setting the frame
height ``for real'' does not always work, because knowing the correct
actual size may be necessary for correct cursor positioning on a
terminal frame.
@end defun

@defun set-frame-width frame width &optional pretend
This function sets the width of @var{frame}, measured in characters.
The argument @var{pretend} has the same meaning as in
@code{set-frame-height}.
@end defun

@findex set-screen-height
@findex set-screen-width
  The older functions @code{set-screen-height} and
@code{set-screen-width} were used to specify the height and width of the
screen, in Emacs versions that did not support multiple frames.  They
are semi-obsolete, but still work; they apply to the selected frame.

@node Geometry
@subsection Geometry

  Here's how to examine the data in an X-style window geometry
specification:

@defun x-parse-geometry geom
@cindex geometry specification
The function @code{x-parse-geometry} converts a standard X window
geometry string to an alist that you can use as part of the argument to
@code{make-frame}.

The alist describes which parameters were specified in @var{geom}, and
gives the values specified for them.  Each element looks like
@code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
values are @code{left}, @code{top}, @code{width}, and @code{height}.

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

Here is an example:

@example
(x-parse-geometry "35x70+0-0")
     @result{} ((height . 70) (width . 35)
         (top - 0) (left . 0))
@end example
@end defun

@node Frame Titles
@section Frame Titles
@cindex frame title

  Every frame has a @code{name} parameter; this serves as the default
for the frame title which window systems typically display at the top of
the frame.  You can specify a name explicitly by setting the @code{name}
frame property.

  Normally you don't specify the name explicitly, and Emacs computes the
frame name automatically based on a template stored in the variable
@code{frame-title-format}.  Emacs recomputes the name each time the
frame is redisplayed.

@defvar frame-title-format
This variable specifies how to compute a name for a frame when you have
not explicitly specified one.  The variable's value is actually a mode
line construct, just like @code{mode-line-format}, except that the
@samp{%c} and @samp{%l} constructs are ignored.  @xref{Mode Line
Data}.
@end defvar

@defvar icon-title-format
This variable specifies how to compute the name for an iconified frame,
when you have not explicitly specified the frame title.  This title
appears in the icon itself.
@end defvar

@defvar multiple-frames
This variable is set automatically by Emacs.  Its value is @code{t} when
there are two or more frames (not counting minibuffer-only frames or
invisible frames).  The default value of @code{frame-title-format} uses
@code{multiple-frames} so as to put the buffer name in the frame title
only when there is more than one frame.

The value of this variable is not guaranteed to be accurate except
while processing @code{frame-title-format} or
@code{icon-title-format}.
@end defvar

@node Deleting Frames
@section Deleting Frames
@cindex deleting frames

Frames remain potentially visible until you explicitly @dfn{delete}
them.  A deleted frame cannot appear on the screen, but continues to
exist as a Lisp object until there are no references to it.

@deffn Command delete-frame &optional frame force
@vindex delete-frame-functions
This function deletes the frame @var{frame}.  Unless @var{frame} is a
tooltip, it first runs the hook @code{delete-frame-functions} (each
function gets one argument, @var{frame}).  By default, @var{frame} is
the selected frame.

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.
@end deffn

@defun frame-live-p frame
The function @code{frame-live-p} returns non-@code{nil} if the frame
@var{frame} has not been deleted.  The possible non-@code{nil} return
values are like those of @code{framep}.  @xref{Frames}.
@end defun

  Some window managers provide a command to delete a window.  These work
by sending a special message to the program that operates the window.
When Emacs gets one of these commands, it generates a
@code{delete-frame} event, whose normal definition is a command that
calls the function @code{delete-frame}.  @xref{Misc Events}.

@node Finding All Frames
@section Finding All Frames
@cindex frames, scanning all

@defun frame-list
The function @code{frame-list} returns a list of all the frames that
have not been deleted.  It is analogous to @code{buffer-list} for
buffers, and includes frames on all terminals.  The list that you get is
newly created, so modifying the list doesn't have any effect on the
internals of Emacs.
@end defun

@defun visible-frame-list
This function returns a list of just the currently visible frames.
@xref{Visibility of Frames}.  (Terminal frames always count as
``visible,'' even though only the selected one is actually displayed.)
@end defun

@defun next-frame &optional frame minibuf
The function @code{next-frame} lets you cycle conveniently through all
the frames on the current display from an arbitrary starting point.  It
returns the ``next'' frame after @var{frame} in the cycle.  If
@var{frame} is omitted or @code{nil}, it defaults to the selected frame
(@pxref{Input Focus}).

The second argument, @var{minibuf}, says which frames to consider:

@table @asis
@item @code{nil}
Exclude minibuffer-only frames.
@item @code{visible}
Consider all visible frames.
@item 0
Consider all visible or iconified frames.
@item a window
Consider only the frames using that particular window as their
minibuffer.
@item anything else
Consider all frames.
@end table
@end defun

@defun previous-frame &optional frame minibuf
Like @code{next-frame}, but cycles through all frames in the opposite
direction.
@end defun

  See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
Window Ordering}.

@node Frames and Windows
@section Frames and Windows

  Each window is part of one and only one frame; you can get the frame
with @code{window-frame}.

@defun window-frame window
This function returns the frame that @var{window} is on.
@end defun

  All the non-minibuffer windows in a frame are arranged in a cyclic
order.  The order runs from the frame's top window, which is at the
upper left corner, down and to the right, until it reaches the window at
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top.  @xref{Cyclic Window Ordering}.

@defun frame-first-window &optional frame
This returns the topmost, leftmost window of frame @var{frame}.
If omitted or @code{nil}, @var{frame} defaults to the selected frame.
@end defun

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}.

@defun frame-selected-window  &optional frame
This function returns the window on @var{frame} that is selected
within @var{frame}.  If omitted or @code{nil}, @var{frame} defaults to
the selected frame.
@end defun

@defun set-frame-selected-window frame 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
@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}.

  Another function that (usually) returns one of the windows in a given
frame is @code{minibuffer-window}.  @xref{Definition of minibuffer-window}.

@node Minibuffers and Frames
@section Minibuffers and Frames

Normally, each frame has its own minibuffer window at the bottom, which
is used whenever that frame is selected.  If the frame has a minibuffer,
you can get it with @code{minibuffer-window} (@pxref{Definition of
minibuffer-window}).

However, you can also create a frame with no minibuffer.  Such a frame
must use the minibuffer window of some other frame.  When you create the
frame, you can specify explicitly the minibuffer window to use (in some
other frame).  If you don't, then the minibuffer is found in the frame
which is the value of the variable @code{default-minibuffer-frame}.  Its
value should be a frame that does have a minibuffer.

If you use a minibuffer-only frame, you might want that frame to raise
when you enter the minibuffer.  If so, set the variable
@code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.

@defvar default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by
default.  It does not affect existing frames.  It is always local to
the current terminal and cannot be buffer-local.  @xref{Multiple
Displays}.
@end defvar

@node Input Focus
@section Input Focus
@cindex input focus
@c @cindex selected frame    Duplicates selected-frame

At any time, one frame in Emacs is the @dfn{selected frame}.  The selected
window always resides on the selected frame.

When Emacs displays its frames on several terminals (@pxref{Multiple
Displays}), each terminal has its own selected frame.  But only one of
these is ``@emph{the} selected frame'': it's the frame that belongs to
the terminal from which the most recent input came.  That is, when Emacs
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
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
frame's display}.

@defun selected-frame
This function returns the selected frame.
@end defun

Some window systems and window managers direct keyboard input to the
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
@code{select-frame-set-input-focus}.

Lisp programs can also switch frames ``temporarily'' by calling the
function @code{select-frame}.  This does not alter the window system's
concept of focus; rather, it escapes from the window manager's control
until that control is somehow reasserted.

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}).

@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.
@end defun

@c ??? This is not yet implemented properly.
@defun select-frame frame
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.

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

Emacs cooperates with the window system by arranging to select frames as
the server and window manager request.  It does so by generating a
special kind of input event, called a @dfn{focus} event, when
appropriate.  The command loop handles a focus event by calling
@code{handle-switch-frame}.  @xref{Focus Events}.

@deffn Command handle-switch-frame frame
This function handles a focus event by selecting frame @var{frame}.

Focus events normally do their job by invoking this command.
Don't call it for any other reason.
@end deffn

@defun redirect-frame-focus frame &optional focus-frame
This function redirects focus from @var{frame} to @var{focus-frame}.
This means that @var{focus-frame} will receive subsequent keystrokes and
events intended for @var{frame}.  After such an event, the value of
@code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
events specifying @var{frame} will instead select @var{focus-frame}.

If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
redirection for @var{frame}, which therefore once again receives its own
e