@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 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/frames
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.
+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
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.
to changing the background color of face @code{mouse}.
@item cursor-color
-The color for the cursor that shows point. Changing this parameter is
+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
+The color for the border of the frame. Changing this parameter is
equivalent to changing the background color of face @code{border}.
+@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 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
@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
+Changing this parameter is equivalent to setting the background color of
face @code{scroll-bar}.
@item display-type
@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.
+between characters as the cursor. @code{(bar . @var{width})}
+specifies a bar @var{width} pixels wide. The symbol @code{hbar}
+specifies a horizontal bar, an underscore-like cursor. @code{(hbar .
+@var{width})} specifiles a horizontal bar @var{width} pixels high.
+
+@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).
@item border-width
The width in pixels of the window border.
@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
@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:
+ 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
@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.
+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:
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
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.
+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.
+
+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 top left corner of the inside of @var{frame}.
@end defun
+@defvar mouse-position-function
+If non-@code{nil}, the value of this variable is a function for
+@code{mouse-position} to call. @code{mouse-position} calls this
+function just before returning, with its normal return value as the
+sole argument, and it returns whatever this function returns to it.
+
+This abnormal hook exists for the benefit of packages like
+@file{xt-mouse.el} that need to do mouse handling at the Lisp level.
+@end defvar
+
@defun set-mouse-position frame x y
This function @dfn{warps the mouse} to position @var{x}, @var{y} in
frame @var{frame}. The arguments @var{x} and @var{y} are integers,
@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)
When Emacs runs on MS-Windows, it does not implement X selections in
-general, but it it does support the clipboard. @code{x-get-selection}
+general, but it does support the clipboard. @code{x-get-selection}
and @code{x-set-selection} on MS-Windows support the text data type
only; if the clipboard holds other types of data, Emacs treats the
clipboard as empty.
@section Color Names
These functions provide a way to determine which color names are
-valid, and what they look like.
+valid, and what they look like. In some cases, the value depends on the
+@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
+meaning of the term ``selected frame''.
@defun color-defined-p color &optional frame
@tindex color-defined-p
@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
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). At present, though, the @var{display}
-argument has no effect.
+selected frame's terminal; @pxref{Input Focus}). At present, though,
+the @var{display} argument has no effect.
@defun tty-color-define name number &optional rgb display
@tindex tty-color-define
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}.
+ @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
@node Display Feature Testing
@section Display Feature Testing
The optional argument @var{display} in these functions specifies which
display to ask the question about. It can be a display name, a frame
(which designates the display that frame is on), or @code{nil} (which
-refers to the selected frame's display).
+refers to the selected frame's display, @pxref{Input Focus}).
@xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
obtain information about displays.
(All color displays can do this.)
@end defun
+@anchor{Display Face Attribute Testing}
+@defun display-supports-face-attributes-p attributes &optional display
+@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.
supported in some other cases.
@end defun
+@defun display-images-p &optional display
+This function returns @code{t} if @var{display} can display images.
+Windowed displays ought in principle to handle images, but some
+systems lack the support for that. On a display that does not support
+images, Emacs cannot display a tool bar.
+@end defun
+
@defun display-screens &optional display
@tindex display-screens
This function returns the number of screens associated with the display.