@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/frames
@node Frames, Positions, Windows, Top
@cindex window frame
When Emacs communicates directly with a supported window system, such
-as X Windows, it does not have a terminal frame; instead, it starts with
+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.
* Color Names:: Getting the definitions of color names.
* Text Terminal Colors:: Defining colors for text-only terminals.
* Resources:: Getting resource values from the server.
-* Server Data:: Getting info about the X server.
+* Display Feature Testing:: Determining the features of a terminal.
@end menu
@xref{Display}, for information about the related topic of
@end defun
@defvar before-make-frame-hook
-@tindex 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
@tindex after-make-frame-functions
An abnormal hook run by @code{make-frame} after it creates the frame.
-Each function in @code{after-make-frame-hook} receives one argument, the
+Each function in @code{after-make-frame-functions} receives one argument, the
frame just created.
@end defvar
@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,
+fontset (@pxref{Fontsets}). Changing this frame parameter on a frame
also changes the font-related attributes of the default face on that
frame.
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. Smaller values
-result in darker colors; you might want to try a screen gamma of 1.5 for
-LCD color displays. The viewing gamma Emacs uses is 0.4545 (1/2.2).
+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.
@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.
+@item line-spacing
+Additional space put below text lines in pixels (a positive integer).
+
@ignore
@item parent-id
@c ??? Not yet working.
way windows behave.
@deffn Command delete-frame &optional frame force
-This function deletes the frame @var{frame}. By default, @var{frame} is
-the selected frame.
+@vindex delete-frame-hook
+This function deletes the frame @var{frame} after running the hook
+@code{delete-frame-hook}. 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,
@end defun
@defopt focus-follows-mouse
-@tindex focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers
focus when the user moves the mouse. Non-@code{nil} says that it does.
When this is so, the command @code{other-frame} moves the mouse to a
@node Window System Selections
@section Window System Selections
-@cindex selection (for X windows)
+@cindex selection (for window systems)
The X server records a set of @dfn{selections} which permit transfer of
data between application programs. The various selections are
@end defun
@defvar selection-coding-system
-@tindex 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
@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.
Note that this does not tell you whether the display you are using
really supports that color. When using X, you can ask for any defined
color on any kind of display, and you will get some result---typically,
-the best it knows how to do. Here's an approximate way to test whether
-your display supports the color @var{color}:
-
-@example
-(defun x-color-supported-p (color &optional frame)
- (and (color-defined-p color frame)
- (or (x-display-color-p frame)
- (member color '("black" "white"))
- (and (> (x-display-planes frame) 1)
- (equal color "gray")))))
-@end example
+the closest it can do. To determine whether a frame can really display
+a certain color, use @code{color-supported-p} (see below).
+@findex x-color-defined-p
This function used to be called @code{x-color-defined-p},
and that name is still supported as an alias.
@end defun
This function returns a list of the color names that are defined
and supported on frame @var{frame} (default, the selected frame).
+@findex x-defined-colors
This function used to be called @code{x-defined-colors},
and that name is still supported as an alias.
@end defun
+@defun color-supported-p color &optional frame background-p
+@tindex color-supported-p
+This returns @code{t} if @var{frame} can really display the color
+@var{color} (or at least something close to it). If @var{frame} is
+omitted or @code{nil}, the question applies to the selected frame.
+
+Some terminals support a different set of colors for foreground and
+background. If @var{background-p} is non-@code{nil}, that means you are
+asking whether @var{color} can be used as a background; otherwise you
+are asking whether it can be used as a foreground.
+
+The argument @var{color} must be a valid color name.
+@end defun
+
+@defun color-gray-p color &optional frame
+@tindex color-gray-p
+This returns @code{t} if @var{color} is a shade of gray, as defined on
+@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
+question applies to the selected frame. The argument @var{color} must
+be a valid color name.
+@end defun
+
@defun color-values color &optional frame
@tindex color-values
This function returns a value that describes what @var{color} should
is omitted or @code{nil}, the information is returned for the selected
frame's display.
+@findex x-color-values
This function used to be called @code{x-color-values},
and that name is still supported as an alias.
@end defun
principle from 0 to 65535, but in practice the largest value used is
65280.
-@defun tty-define-color name number &optional rgb
-@tindex tty-define-color
+ 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). At present, though, the @var{display}
+argument has no effect.
+
+@defun tty-color-define name number &optional rgb display
+@tindex tty-color-define
This function associates the color name @var{name} with
color number @var{number} on the terminal.
like.
@end defun
-@defun tty-clear-colors
-@tindex tty-clear-colors
+@defun tty-color-clear &optional display
+@tindex tty-color-clear
This function clears the table of defined colors for a text-only terminal.
@end defun
-@defvar tty-color-alist
+@defun tty-color-alist &optional display
@tindex tty-color-alist
-This variable holds an alist recording the colors supported by the
-terminal.
+This function returns an alist recording the known colors supported by a
+text-only terminal.
Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
or @code{(@var{name} @var{number})}. Here, @var{name} is the color
name, @var{number} is the number used to specify it to the terminal.
If present, @var{rgb} is an rgb value that says what the color
actually looks like.
-@end defvar
+@end defun
-@defun tty-color-approximate rgb
+@defun tty-color-approximate rgb &optional display
@tindex tty-color-approximate
-This function finds the closest available color, among those in
-@code{tty-color-alist}, to that described by the rgb value @var{rgb}.
+This function finds the closest color, among the known colors supported
+for @var{display}, to that described by the rgb value @var{rgb}.
@end defun
-@defun tty-color-translate color
+@defun tty-color-translate color &optional display
@tindex tty-color-translate
-This function finds the closest available color, among those in
-@code{tty-color-alist}, to the name @var{color}. If that name
-is not defined, the value is @code{nil}.
+This function finds the closest color to @var{color} among the known
+colors supported for @var{display}. If the name @var{color} is not
+defined, the value is @code{nil}.
-@var{color} can be an X-style @code{#@var{xxxyyyzzz}} specification
-instead of an actual name.
+@var{color} can be an X-style @code{"#@var{xxxyyyzzz}"} specification
+instead of an actual name. The format
+@code{"RGB:@var{xx}/@var{yy}/@var{zz}"} is also supported.
@end defun
@node Resources
@xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
-@node Server Data
-@section Data about the X Server
+@node Display Feature Testing
+@section Display Feature Testing
+@cindex display feature testing
- This section describes functions you can use to get information about
-the capabilities and origin of an X display that Emacs is using. Each
-of these functions lets you specify the display you are interested in:
-the @var{display} argument can be either a display name, or a frame
-(meaning use the display that frame is on). If you omit the
-@var{display} argument, or specify @code{nil}, that means to use the
-selected frame's display.
+ 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
+a popup menu could use the minibuffer if popup menus are not supported.
-@defun x-display-screens &optional display
-This function returns the number of screens associated with the display.
+ 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).
+
+ @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
+obtain information about displays.
+
+@defun display-popup-menus-p &optional display
+@tindex display-popup-menus-p
+This function returns @code{t} if popup menus are supported on
+@var{display}, @code{nil} if not. Support for popup menus requires that
+the mouse be available, since the user cannot choose menu items without
+a mouse.
@end defun
-@defun x-server-version &optional display
-This function returns the list of version numbers of the X server
-running the display.
+@defun display-graphic-p &optional display
+@tindex display-graphic-p
+@cindex frames, more than one on display
+@cindex fonts, more than one on display
+This function returns @code{t} if @var{display} is a graphic display
+capable of displaying several frames and several different fonts at
+once. This is true for displays that use a window system such as X, and
+false for text-only terminals.
@end defun
-@defun x-server-vendor &optional display
-This function returns the vendor that provided the X server software.
+@defun display-mouse-p &optional display
+@tindex display-mouse-p
+@cindex mouse, availability
+This function returns @code{t} if @var{display} has a mouse available,
+@code{nil} if not.
@end defun
-@defun x-display-pixel-height &optional display
+@defun display-color-p &optional display
+@tindex display-color-p
+@findex x-display-color-p
+This function returns @code{t} if the screen is a color screen.
+It used to be called @code{x-display-color-p}, and that name
+is still supported as an alias.
+@end defun
+
+@defun display-grayscale-p &optional display
+@tindex display-grayscale-p
+This function returns @code{t} if the screen can display shades of gray.
+(All color displays can do this.)
+@end defun
+
+@defun display-selections-p &optional display
+@tindex display-selections-p
+This function returns @code{t} if @var{display} supports selections.
+Windowed displays normally support selections, but they may also be
+supported in some other cases.
+@end defun
+
+@defun display-screens &optional display
+@tindex display-screens
+This function returns the number of screens associated with the display.
+@end defun
+
+@defun display-pixel-height &optional display
+@tindex display-pixel-height
This function returns the height of the screen in pixels.
@end defun
-@defun x-display-mm-height &optional display
-This function returns the height of the screen in millimeters.
+@defun display-mm-height &optional display
+@tindex display-mm-height
+This function returns the height of the screen in millimeters,
+or @code{nil} if Emacs cannot get that information.
@end defun
-@defun x-display-pixel-width &optional display
+@defun display-pixel-width &optional display
+@tindex display-pixel-width
This function returns the width of the screen in pixels.
@end defun
-@defun x-display-mm-width &optional display
-This function returns the width of the screen in millimeters.
+@defun display-mm-width &optional display
+@tindex display-mm-width
+This function returns the width of the screen in millimeters,
+or @code{nil} if Emacs cannot get that information.
@end defun
-@defun x-display-backing-store &optional display
-This function returns the backing store capability of the screen.
+@defun display-backing-store &optional display
+@tindex display-backing-store
+This function returns the backing store capability of the display.
+Backing store means recording the pixels of windows (and parts of
+windows) that are not exposed, so that when exposed they can be
+displayed very quickly.
+
Values can be the symbols @code{always}, @code{when-mapped}, or
-@code{not-useful}.
+@code{not-useful}. The function can also return @code{nil}
+when the question is inapplicable to a certain kind of display.
@end defun
-@defun x-display-save-under &optional display
+@defun display-save-under &optional display
+@tindex display-save-under
This function returns non-@code{nil} if the display supports the
-SaveUnder feature.
+SaveUnder feature. That feature is used by pop-up windows
+to save the pixels they obscure, so that they can pop down
+quickly.
@end defun
-@defun x-display-planes &optional display
+@defun display-planes &optional display
+@tindex display-planes
This function returns the number of planes the display supports.
+This is typically the number of bits per pixel.
+For a tty display, it is log to base two of the number of colours supported.
@end defun
-@defun x-display-visual-class &optional display
+@defun display-visual-class &optional display
+@tindex display-visual-class
This function returns the visual class for the screen. The value is one
of the symbols @code{static-gray}, @code{gray-scale},
@code{static-color}, @code{pseudo-color}, @code{true-color}, and
@code{direct-color}.
@end defun
-@defun x-display-grayscale-p &optional display
-This function returns @code{t} if the screen can display shades of gray.
+@defun display-color-cells &optional display
+@tindex display-color-cells
+This function returns the number of color cells the screen supports.
@end defun
-@defun x-display-color-p &optional display
-This function returns @code{t} if the screen is a color screen.
+ These functions obtain additional information specifically
+about X displays.
+
+@defun x-server-version &optional display
+This function returns the list of version numbers of the X server
+running the display.
@end defun
-@defun x-display-color-cells &optional display
-This function returns the number of color cells the screen supports.
+@defun x-server-vendor &optional display
+This function returns the vendor that provided the X server software.
@end defun
@ignore