@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2004
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/frames
@node Frames, Positions, Windows, Top
* 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 them.
+ 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.
* Display Feature Testing:: Determining the features of a terminal.
@end menu
- @xref{Display}, for information about the related topic of
+ @xref{Display}, for information about the related topic of
controlling Emacs redisplay.
@node Creating Frames
selected frame's parameter.
@end defun
-@defun frame-parameters frame
+@defun frame-parameters &optional frame
The function @code{frame-parameters} returns an alist listing all the
-parameters of @var{frame} and their values.
+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
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.
+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}
+to apply the same parameter values to frames that will be created
+henceforth.
@end defun
@node Initial Parameters
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{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
+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
uses. Here is a table of the parameters that have special meanings in a
window frame; of these, @code{name}, @code{title}, @code{height},
@code{width}, @code{buffer-list} and @code{buffer-predicate} provide
-meaningful information in terminal frames.
+meaningful information in terminal frames, and @code{tty-color-mode}
+is meaningful @emph{only} in terminal frames.
@table @code
@item display
The width of the frame contents, in characters. (To get the height in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
+@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.
+
@item window-id
The number of the window-system window used by the frame
to contain the actual Emacs windows.
A list of buffers that have been selected in this frame,
ordered most-recently-selected first.
-@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}). Changing this frame parameter on a frame
-also changes the font-related attributes of the default face on that
-frame.
-
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
implemented.)
@item scroll-bar-width
-The width of the vertical scroll bar, in pixels.
+The width of the vertical scroll bar, in pixels,
+or @code{nil} meaning to use the default width.
@item icon-type
The type of icon to use for this frame when it is iconified. If the
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 foreground-color
-The color to use for the image of a character. This is a string; the
-window system defines the meaningful color names. Changing this
-parameter is equivalent to changing the foreground color of the face
-@code{default} on the frame in question.
-
-@item background-color
-The color to use for the background of characters. Changing this
-parameter is equivalent to changing the foreground color of the face
-@code{default} on the frame in question.
-
@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 mouse-color
-The color for the mouse pointer. Changing this parameter is equivalent
-to changing the background color of face @code{mouse}.
-
-@item cursor-color
-The color for the cursor that shows point. Changing this parameter is
-equivalent to changing the background color of face @code{cursor}.
-
-@item border-color
-The color for the border of the frame. Changing this parameter is
-equivalent to changing the background color of face @code{border}.
-
-@item scroll-bar-foreground
-If non-@code{nil}, the color for the foreground of scroll bars.
-Changing this parameter is equivalent to setting the foreground color of
-face @code{scroll-bar}.
-
-@item scroll-bar-background
-If non-@code{nil}, the color for the background of scroll bars.
-Changing this parameter is equivalent to setting the foreground color of
-face @code{scroll-bar}.
+@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)} forces Emacs to use
+the ANSI escape sequences for 8 standard text colors; and a value of
+-1 means Emacs should turn off color support. If the parameter's
+value is a symbol, that symbol is looked up in the alist
+@code{tty-color-mode-alist}, and if found, the associated number is
+used as the color support mode.
@item display-type
This parameter describes the range of possible colors that can be used
@code{mono}.
@item cursor-type
-The way to display the cursor. The legitimate values are @code{bar},
-@code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
-specifies an ordinary black box overlaying the character after point;
-that is the default. The symbol @code{bar} specifies a vertical bar
-between characters as the cursor. @code{(bar . @var{width})} specifies
-a bar @var{width} pixels wide.
+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 (bar . @var{width})
+Display a horizontal bar @var{width} pixels high.
+@end table
@vindex cursor-type
The buffer-local variable @code{cursor-type} overrides the value of
-the @code{cursor-type} frame parameter, and can in addition have
-values @code{t} (use the cursor specified for the frame) and
-@code{nil} (don't display a cursor).
+the @code{cursor-type} frame parameter, but if it is @code{t}, that
+means to use the cursor specified for the frame.
@item border-width
The width in pixels of the window border.
@item internal-border-width
The distance in pixels between text and border.
+@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 frame or the other to a precise
+width by specifying that width a negative integer. If both widths are
+negative, only the left fringe gets the specified width.
+
@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.
@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar.
The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
-toolkit, there is only one menu bar line; all that matters about the
+toolkit or GTK, there is only one menu bar line; all that matters about the
number you specify is whether it is greater than zero.)
@item screen-gamma
@cindex gamma correction
-If this is a number, Emacs performs ``gamma correction'' on 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 the default is
-to display for that gamma value. Specifying a smaller value results in
-darker colors, which is desirable for a monitor that tends to display
-colors too light. A screen gamma value of 1.5 may give good results for
-LCD color displays.
+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 they 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.
@item tool-bar-lines
The number of lines to use for the toolbar. A value of @code{nil} means
-don't display a tool bar.
+don't display a tool bar. (In Emacs versions that use GTK, there is
+only one tool bar line; all that matters about the number you specify
+is whether it is greater than zero.)
@item line-spacing
Additional space put below text lines in pixels (a positive integer).
@end ignore
@end table
+@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}), Emacs uses
+@var{off-state} to specify 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, because the variable
+is examined only when you specify a cursor type for a frame.
+@end defvar
+
+These frame parameters are semi-obsolete in that they are automatically
+equivalent to particular face attributes of particular faces.
+
+@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.
+
+@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.
+@end table
+
@node Size and Position
@subsection Frame Size And Position
@cindex size of frame
way windows behave.
@deffn Command delete-frame &optional frame force
-@vindex delete-frame-hook
+@vindex delete-frame-functions
This function deletes the frame @var{frame} after running the hook
-@code{delete-frame-hook}. By default, @var{frame} is the selected
-frame.
+@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,
@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. The list that you get is newly created, so modifying the list
-doesn't have any effect on the internals of Emacs.
+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
@defun next-frame &optional frame minibuf
The function @code{next-frame} lets you cycle conveniently through all
-the frames 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 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:
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 frame
+@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 also selects this window. You can get the frame's current
selected window with @code{frame-selected-window}.
-@defun frame-selected-window frame
+@defun frame-selected-window &optional frame
This function returns the window on @var{frame} that is selected within
-@var{frame}.
+@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.
@end defun
Conversely, selecting a window for Emacs with @code{select-window} also
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.
+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 the selected terminal frame is
-actually displayed on the terminal. @code{switch-frame} is the only way
-to switch frames, and the change lasts until overridden by a subsequent
-call to @code{switch-frame}. Each terminal screen except for the
-initial one has a number, and the number of the selected frame appears
-in the mode line before the buffer name (@pxref{Mode Line Variables}).
+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
the next time the user does something to select a different frame, or
until the next time this function is called. The specified @var{frame}
becomes the selected frame, as explained above, and the terminal that
-@var{frame} is on becomes the selected terminal.
+@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.
Don't call it for any other reason.
@end deffn
-@defun redirect-frame-focus frame focus-frame
+@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 @code{nil}, that cancels any existing
+If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
redirection for @var{frame}, which therefore once again receives its own
events.
selection values.
Each possible @var{type} has its own selection value, which changes
-independently. The usual values of @var{type} are @code{PRIMARY} and
-@code{SECONDARY}; these are symbols with upper-case names, in accord
-with X Window System conventions. The default is @code{PRIMARY}.
+independently. The usual values of @var{type} are @code{PRIMARY},
+@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
+names, in accord with X Window System conventions. The default is
+@code{PRIMARY}.
@end defun
@defun x-get-selection &optional type data-type
The @var{data-type} argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into Lisp
data. Meaningful values include @code{TEXT}, @code{STRING},
+@code{UTF8_STRING},
@code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
@code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
@end defun
@cindex cut buffer
-The X server also has a set of numbered @dfn{cut buffers} which can
+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.
+clients that still use them. Cut buffers are numbered from 0 to 7.
-@defun x-get-cut-buffer n
+@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
@defvar selection-coding-system
This variable specifies the coding system to use when reading and
writing selections, the clipboard, or a cut buffer. @xref{Coding
-Systems}. The default is @code{compound-text}, which converts to
-the text representation that X11 normally uses.
+Systems}. The default is @code{compound-text-with-extensions}, which
+converts to the text representation that X11 normally uses.
@end defvar
@cindex clipboard support (for MS-Windows)
@cindex colors on text-only terminals
Emacs can display color on text-only terminals, starting with version
-21. These terminals support only a small number of colors, and the
-computer uses small integers to select colors on the terminal. This
+21. These terminals usually support only a small number of colors, and
+the computer uses small integers to select colors on the terminal. This
means that the computer cannot reliably tell what the selected color
looks like; instead, you have to inform your application which small
integers correspond to which colors. However, Emacs does know the
standard set of colors and will try to use them automatically.
+ The functions described in this section control how terminal colors
+are used by Emacs.
+
@cindex rgb value
Several of these functions use or return @dfn{rgb values}. An rgb
value is a list of three integers, which give the amount of red, the
@defun x-get-resource attribute class &optional component subclass
The function @code{x-get-resource} retrieves a resource value from the X
-Windows defaults database.
+Window defaults database.
Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
This function searches using a key of the form
variable to some other string, around a call to @code{x-get-resource}.
@end defvar
- @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
+@defvar x-resource-name
+This variable specifies the instance name that @code{x-get-resource}
+should look up. The default value is the name Emacs was invoked with,
+or the value specified with the @samp{-name} or @samp{-rn} switches.
+@end defvar
+
+ @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
@node Display Feature Testing
@section Display Feature Testing
The functions in this section describe the basic capabilities of a
particular display. Lisp programs can use them to adapt their behavior
-to what the display can do. For example, a program that ordinarly uses
+to what the display can do. For example, a program that ordinarily uses
a popup menu could use the minibuffer if popup menus are not supported.
The optional argument @var{display} in these functions specifies which
(All color displays can do this.)
@end defun
+@defun display-supports-face-attributes-p attributes &optional display
+@anchor{Display Face Attribute Testing}
+@tindex display-supports-face-attributes-p
+This function returns non-@code{nil} if all the face attributes in
+@var{attributes} are supported (@pxref{Face Attributes}).
+
+The definition of `supported' is somewhat heuristic, but basically
+means that a face containing all the attributes in @var{attributes},
+when merged with the default face for display, can be represented in a
+way that's
+
+@enumerate
+@item
+different in appearance than the default face, and
+
+@item
+`close in spirit' to what the attributes specify, if not exact.
+@end enumerate
+
+Point (2) implies that a @code{:weight black} attribute will be
+satisfied by any display that can display bold, as will
+@code{:foreground "yellow"} as long as some yellowish color can be
+displayed, but @code{:slant italic} will @emph{not} be satisfied by
+the tty display code's automatic substitution of a `dim' face for
+italic.
+@end defun
+
@defun display-selections-p &optional display
@tindex display-selections-p
This function returns @code{t} if @var{display} supports selections.
The functions @code{x-pixel-width} and @code{x-pixel-height} return the
width and height of an X Window frame, measured in pixels.
@end ignore
+
+@ignore
+ arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
+@end ignore