@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, 2009 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/frames
@node Frames, Positions, Windows, Top
* Frame Parameters:: Controlling frame size, position, font, etc.
* Terminal Parameters:: Parameters common for all frames on terminal.
* 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.
+* 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.
+* Color Names:: Getting the definitions of color names.
* Text Terminal Colors:: Defining colors for text-only terminals.
-* Resources:: Getting resource values from the server.
+* Resources:: Getting resource values from the server.
* Display Feature Testing:: Determining the features of a terminal.
@end menu
@menu
* Parameter Access:: How to change a frame's parameters.
-* Initial Parameters:: Specifying frame parameters when you make a frame.
+* 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.
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
+@defopt 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.
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
+@end defopt
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
+@defopt minibuffer-frame-alist
This variable's value is an alist of parameter values used when
creating an initial minibuffer-only frame. This is the
minibuffer-only frame that Emacs creates if @code{initial-frame-alist}
specifies a frame with no minibuffer.
-@end defvar
+@end defopt
-@defvar default-frame-alist
+@defopt 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
+@end defopt
Functions that display a buffer in a separate frame can override the
default parameters by supplying their own parameters. @xref{Definition
@node Window Frame Parameters
@subsection Window Frame Parameters
+@cindex frame parameters for windowed displays
Just what parameters a frame has depends on what display mechanism
it uses. This section describes the parameters that have special
frame. @code{title} and @code{name} are meaningful on all terminals.
@table @code
+@vindex display, a frame parameter
@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.
+@vindex display-type, a frame parameter
@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}.
+@vindex title, a frame parameter
@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
Emacs is not using a window system, and can only display one frame at
a time. @xref{Frame Titles}.
+@vindex name, a frame parameter
@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
@node Position Parameters
@subsubsection Position Parameters
+@cindex window position on display
Position parameters' values are normally measured in pixels, but on
text-only terminals they count characters or lines instead.
@table @code
+@vindex left, a frame parameter
@item left
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:
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.
+@vindex top, a frame parameter
@item top
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.
+@vindex icon-left, a frame parameter
@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
a value for @code{icon-top} and vice versa. The window manager may
ignore these two parameters.
+@vindex icon-top, a frame parameter
@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.
+@vindex user-position, a frame parameter
@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
way by a human user) or merely program-specified (chosen by a program).
A non-@code{nil} value says the position was user-specified.
+@cindex window positions and window managers
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
@node Size Parameters
@subsubsection Size Parameters
+@cindex window size on display
Size parameters' values are normally measured in pixels, but on
text-only terminals they count characters or lines instead.
@table @code
+@vindex height, a frame parameter
@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}.)
+@vindex width, a frame parameter
@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}.)
+@vindex user-size, a frame parameter
@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}.
+the @code{user-position} parameter (@pxref{Position Parameters,
+user-position}) does for the position parameters @code{top} and
+@code{left}.
+@cindex full-screen frames
+@vindex fullscreen, a frame parameter
@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.
+Specify that width, height or both shall be maximized. The value
+@code{fullwidth} specifies that width shall be as wide as possible.
+The value @code{fullheight} specifies that height shall be as tall as
+possible. The value @code{fullboth} specifies that both the width and
+the height shall be set to the size of the screen. The value
+@code{maximized} specifies that the frame shall be maximized. The
+difference between @code{maximized} and @code{fullboth} is that the
+former still has window manager decorations while the latter really
+covers the whole screen.
@end table
@node Layout Parameters
@subsubsection Layout Parameters
+@cindex layout parameters of frames
+@cindex frame layout parameters
These frame parameters enable or disable various parts of the
frame, or control their sizes.
@table @code
+@vindex border-width, a frame parameter
@item border-width
The width in pixels of the frame's border.
+@vindex internal-border-width, a frame parameter
@item internal-border-width
The distance in pixels between text (or fringe) and the frame's border.
+@vindex vertical-scroll-bars, a frame parameter
@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
+@vindex horizontal-scroll-bars, a frame parameter
@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
+@vindex scroll-bar-width, a frame parameter
@item scroll-bar-width
The width of vertical scroll bars, in pixels, or @code{nil} meaning to
use the default width.
+@vindex left-fringe, a frame parameter
+@vindex right-fringe, a frame parameter
@item left-fringe
@itemx right-fringe
The default width of the left and right fringes of windows in this
width by specifying that width as a negative integer. If both widths are
negative, only the left fringe gets the specified width.
+@vindex menu-bar-lines, a frame parameter
@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.)
+@vindex tool-bar-lines, a frame parameter
@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 and Nextstep allow at most one
tool bar line; they treat larger values as 1.)
+@vindex tool-bar-position, a frame parameter
+@item tool-bar-position
+The position of the tool bar. Currently only for the GTK tool bar.
+Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
+The default is @code{top}.
+
+@vindex line-spacing, a frame parameter
@item line-spacing
Additional space to leave below each text line, in pixels (a positive
integer). @xref{Line Height}, for more information.
with which buffers have been, or should, be displayed in the frame.
@table @code
+@vindex minibuffer, a frame parameter
@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.
+minibuffer. If the value is a minibuffer window (in some other
+frame), the frame uses that minibuffer.
+
+This frame parameter takes effect when the frame is created, and can
+not be changed afterwards.
+@vindex buffer-predicate, a frame parameter
@item buffer-predicate
The buffer-predicate function for this frame. The function
@code{other-buffer} uses this predicate (from the selected frame) to
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.
+@vindex buffer-list, a frame parameter
@item buffer-list
-A list of buffers that have been selected in this frame,
-ordered most-recently-selected first.
+A list of buffers that have been selected in this frame, ordered
+most-recently-selected first.
+@vindex unsplittable, a frame parameter
@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
+@cindex window manager interaction, and frame parameters
These frame parameters, meaningful only on window system displays,
interact with the window manager.
@table @code
+@vindex visibility, a frame parameter
@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}.
+@vindex auto-raise, a frame parameter
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
+@vindex auto-lower, a frame parameter
@item auto-lower
Whether deselecting the frame lowers it (non-@code{nil} means yes).
+@vindex icon-type, a frame parameter
@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.
+@vindex icon-name, a frame parameter
@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.
+@vindex window-id, a frame parameter
@item window-id
The number of the window-system window used by the frame
to contain the actual Emacs windows.
+@vindex outer-window-id, a frame parameter
@item outer-window-id
The number of the outermost window-system window used for the whole frame.
+@vindex wait-for-wm, a frame parameter
@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.
+@vindex sticky, a frame parameter
+@item sticky
+If non-@code{nil}, the frame is visible on all virtual desktops on systems
+with virtual desktops.
+
@ignore
+@vindex parent-id, a frame parameter
@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
@node Cursor Parameters
@subsubsection Cursor Parameters
+@cindex cursor, and frame parameters
This frame parameter controls the way the cursor looks.
@table @code
+@vindex cursor-type, a frame parameter
@item cursor-type
How to display the cursor. Legitimate values are:
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
+@defopt 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
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
+@end defopt
-@defvar cursor-in-non-selected-windows
+@defopt 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,
+modification of the usual cursor type (solid box becomes hollow box,
and bar becomes a narrower bar).
-@end defvar
+@end defopt
@node Font and Color Parameters
@subsubsection Font and Color Parameters
+@cindex font and color, frame parameters
These frame parameters control the use of fonts and colors.
@table @code
+@vindex font-backend, a frame parameter
@item font-backend
A list of symbols, specifying the @dfn{font backends} to use for
drawing fonts in the frame, in order of priority. On X, there are
is only one available font backend, so it does not make sense to
modify this frame parameter.
+@vindex background-mode, a frame parameter
@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.
+@vindex tty-color-mode, a frame parameter
@item tty-color-mode
@cindex standard colors for character terminals
This parameter overrides the terminal's color support as given by the
the value of @code{tty-color-mode-alist}, and the associated number is
used instead.
+@vindex screen-gamma, a frame parameter
@item screen-gamma
@cindex gamma correction
If this is a number, Emacs performs ``gamma correction'' which adjusts
that makes colors darker. A screen gamma value of 1.5 may give good
results for LCD color displays.
+@vindex alpha, a frame parameter
@item alpha
@cindex opacity, frame
@cindex transparency, frame
faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
@table @code
+@vindex font, a frame parameter
@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.
+@vindex foreground-color, a frame parameter
@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.
+@vindex background-color, a frame parameter
@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.
+@vindex mouse-color, a frame parameter
@item mouse-color
The color for the mouse pointer. It is equivalent to the @code{:background}
attribute of the @code{mouse} face.
+@vindex cursor-color, a frame parameter
@item cursor-color
The color for the cursor that shows point. It is equivalent to the
@code{:background} attribute of the @code{cursor} face.
+@vindex border-color, a frame parameter
@item border-color
The color for the border of the frame. It is equivalent to the
@code{:background} attribute of the @code{border} face.
+@vindex scroll-bar-foreground, a frame parameter
@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.
+@vindex scroll-bar-background, a frame parameter
@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
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.
+they use the selected frame. For a text-only terminal, the results are
+in characters rather than pixels.
-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).
+These values include the internal borders, and windows' scroll bars and
+fringes (which belong to individual windows, not to the frame itself).
+The exact value of the heights depends on the window-system and toolkit
+in use. With Gtk+, the height does not include any tool bar or menu
+bar. With the Motif or Lucid toolkits, it includes the tool bar but
+not the menu bar. In a graphical version with no toolkit, it includes
+both the tool bar and menu bar. For a text-only terminal, the result
+includes the menu bar.
@end defun
@defun frame-char-height &optional frame
value is not significant.
@end defun
+@defun frame-pointer-visible-p &optional frame
+This predicate function returns non-@code{nil} if the mouse pointer
+displayed on @var{frame} is visible; otherwise it returns @code{nil}.
+@var{frame} omitted or @code{nil} means the selected frame. This is
+useful when @code{make-pointer-invisible} is set to @code{t}: it
+allows to know if the pointer has been hidden.
+@xref{Mouse Avoidance,,,emacs}.
+@end defun
+
@need 3000
@node Pop-Up Menus
The argument @var{menu} says what to display in the menu. It can be a
keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
return value is the list of events corresponding to the user's choice.
-(This list has more than one element if the choice occurred in a
-submenu.) Note that @code{x-popup-menu} does not actually execute the
-command bound to that sequence of events.
+This list has more than one element if the choice occurred in a
+submenu. (Note that @code{x-popup-menu} does not actually execute the
+command bound to that sequence of events.) On toolkits that support
+menu titles, the title is taken from the prompt string of @var{menu}
+if @var{menu} is a keymap, or from the prompt string of the first
+keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
+Menus}).
Alternatively, @var{menu} can have the following form:
@code{STRING}.
@end defun
-@cindex cut buffer
-The X server also has a set of eight numbered @dfn{cut buffers} which can
-store text or other data being moved between applications. Cut buffers
-are considered obsolete, but Emacs supports them for the sake of X
-clients that still use them. Cut buffers are numbered from 0 to 7.
-
-@defun x-get-cut-buffer &optional n
-This function returns the contents of cut buffer number @var{n}.
-If omitted @var{n} defaults to 0.
-@end defun
-
-@defun x-set-cut-buffer string &optional push
-@anchor{Definition of x-set-cut-buffer}
-This function stores @var{string} into the first cut buffer (cut buffer
-0). If @var{push} is @code{nil}, only the first cut buffer is changed.
-If @var{push} is non-@code{nil}, that says to move the values down
-through the series of cut buffers, much like the way successive kills in
-Emacs move down the kill ring. In other words, the previous value of
-the first cut buffer moves into the second cut buffer, and the second to
-the third, and so on through all eight cut buffers.
-@end defun
-
-@defvar selection-coding-system
+@defopt selection-coding-system
This variable specifies the coding system to use when reading and
writing selections or the clipboard. @xref{Coding
Systems}. The default is @code{compound-text-with-extensions}, which
converts to the text representation that X11 normally uses.
-@end defvar
+@end defopt
@cindex clipboard support (for MS-Windows)
When Emacs runs on MS-Windows, it does not implement X selections in
in @ref{Color Names}.
These functions accept a display (either a frame or the name of a
-terminal) as an optional argument. We hope in the future to make Emacs
-support more than one text-only terminal at one time; then this argument
-will specify which terminal to operate on (the default being the
-selected frame's terminal; @pxref{Input Focus}). At present, though,
-the @var{frame} argument has no effect.
+terminal) as an optional argument. We hope in the future to make
+Emacs support different colors on different text-only terminals; then
+this argument will specify which terminal to operate on (the default
+being the selected frame's terminal; @pxref{Input Focus}). At
+present, though, the @var{frame} argument has no effect.
@defun tty-color-define name number &optional rgb frame
This function associates the color name @var{name} with
@node Resources
@section X Resources
+This section describes some of the functions and variables for
+querying and using X resources, or their equivalent on your operating
+system. @xref{X Resources,, X Resources, emacs, The GNU Emacs
+Manual}, for more information about X resources.
+
@defun x-get-resource attribute class &optional component subclass
The function @code{x-get-resource} retrieves a resource value from the X
Window defaults database.
@end group
@end example
- @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
+@defvar inhibit-x-resources
+If this variable is non-@code{nil}, Emacs does not look up X
+resources, and X resources do not have any effect when creating new
+frames.
+@end defvar
@node Display Feature Testing
@section Display Feature Testing
or @code{nil} if Emacs cannot get that information.
@end defun
-@defvar display-mm-dimensions-alist
+@defopt display-mm-dimensions-alist
This variable allows the user to specify the dimensions of graphical
displays returned by @code{display-mm-height} and
@code{display-mm-width} in case the system provides incorrect values.
-@end defvar
+@end defopt
@defun display-backing-store &optional display
This function returns the backing store capability of the display.
width and height of an X Window frame, measured in pixels.
@end ignore
-
-@ignore
- arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
-@end ignore