@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c 2004, 2005, 2006 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
- A @dfn{frame} is a rectangle on the screen that contains one or more
-Emacs windows. A frame initially contains a single main window (plus
-perhaps a minibuffer window), which you can subdivide vertically or
-horizontally into smaller windows.
+ 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
* 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 Shapes:: Specifying the shape of the mouse pointer.
+* 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.
To create a new frame, call the function @code{make-frame}.
@defun make-frame &optional alist
-This function creates a new frame. If you are using a supported window
-system, it makes a window frame; otherwise, it makes a terminal frame.
+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
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
@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-functions} receives one argument, the
frame just created.
terminal.
@deffn Command make-frame-on-display display &optional parameters
-This creates 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}).
+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
"*BorderWidth: 3\n*InternalBorder: 2\n"
@end example
-@xref{Resources}.
+@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.
* 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
frame.
@defun frame-parameter frame parameter
-@tindex frame-parameter
-This function returns the value of the parameter named @var{parameter}
-of @var{frame}. If @var{frame} is @code{nil}, it returns the
-selected frame's 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
@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.
+(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
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}, in @ref{Choosing Window}.
+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{Command Arguments,,, emacs,
-The GNU Emacs Manual}.
+@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. 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, and @code{tty-color-mode}
-is meaningful @emph{only} in terminal frames.
+ 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
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
border for the frame, and also in the mode line of windows in that frame
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},
@item top
The screen position of the top edge, in pixels, with respect to the
-top 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 bottom edge of the
-window with respect to the bottom edge of the screen. A positive value
-of @var{pos} counts toward the top. @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.
+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
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}.)
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 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
-@item window-id
-The number of the window-system window used by the frame
-to contain the actual Emacs windows.
+@node Layout Parameters
+@subsubsection Layout Parameters
-@item outer-window-id
-The number of the outermost window-system window used for the whole frame.
+ 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
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
+
+ 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 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.
-
-@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.)
-
-@item scroll-bar-width
-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
value is a string, that specifies a file containing a bitmap to use.
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 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 window-id
+The number of the window-system window used by the frame
+to contain the actual Emacs windows.
-@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 outer-window-id
+The number of the outermost window-system window used for the whole frame.
-@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 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:
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.
+@item (hbar . @var{height})
+Display a horizontal bar @var{height} pixels high.
+@end table
@end table
@vindex cursor-type
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.
+@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, because the variable is
+examined only when you specify the @code{cursor-type} parameter.
+@end defvar
-@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.
+@node Color Parameters
+@subsubsection Color Parameters
-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.
+ These frame parameters control the use of colors.
-@item unsplittable
-If non-@code{nil}, this frame's window is never split automatically.
+@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 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 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.
-@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 or GTK, there is only one menu bar line; all that matters about the
-number you specify is whether it is greater than zero.)
+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
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
+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.
-
-@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. (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).
-
-@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
-@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.
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
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
@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}. @xref{Mode Line
+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
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
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. There is no
-way to cancel the deletion of a frame aside from restoring a saved frame
-configuration (@pxref{Frame Configurations}); this is similar to the
-way windows behave.
+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} after running the hook
-@code{delete-frame-functions} (each function gets one argument,
-@var{frame}). By default, @var{frame} is the selected frame.
+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,
@defun frame-live-p frame
The function @code{frame-live-p} returns non-@code{nil} if the frame
-@var{frame} has not been deleted.
+@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
@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.)
+``visible,'' even though only the selected one is actually displayed.)
@end defun
@defun next-frame &optional frame minibuf
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.
+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.
+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{Minibuffer Misc}.
+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{Minibuffer Misc}).
+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
@defvar default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by
-default. It is always local to the current terminal and cannot be
-buffer-local. @xref{Multiple Displays}.
+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
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 displayed until a subsequent call to @code{select-frame} or
+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}).
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. The specified @var{frame}
+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.
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
-position consistent with the new selected frame.
+position consistent with the new selected frame. (This option has no
+effect on MS-Windows, where the mouse pointer is always automatically
+moved by the OS to the selected frame.)
@end defopt
@node Visibility of Frames
it makes the selected frame visible.
@end deffn
-@deffn Command make-frame-invisible &optional frame
+@deffn Command make-frame-invisible &optional frame force
This function makes frame @var{frame} invisible. If you omit
@var{frame}, it makes the selected frame invisible.
+
+Unless @var{force} is non-@code{nil}, this function refuses to make
+@var{frame} invisible if all other frames are invisible..
@end deffn
@deffn Command iconify-frame &optional frame
This returns the visibility status of frame @var{frame}. The value is
@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
@code{icon} if it is iconified.
+
+On a text-only terminal, all frames are considered visible, whether
+they are currently being displayed or not, and this function returns
+@code{t} for all frames.
@end defun
The visibility status of a frame is also available as a frame
-parameter. You can read or change it as such. @xref{Window Frame
+parameter. You can read or change it as such. @xref{Management
Parameters}.
The user can iconify and deiconify frames with the window manager.
Most window systems use a desktop metaphor. Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest''. Where two windows overlap, the one higher up covers
+to ``lowest.'' Where two windows overlap, the one higher up covers
the one underneath. Even a window at the bottom of the stack can be
seen if no other window overlaps it.
@cindex lowering a frame
A window's place in this ordering is not fixed; in fact, users tend
to change the order frequently. @dfn{Raising} a window means moving
-it ``up'', to the top of the stack. @dfn{Lowering} a window means
+it ``up,'' to the top of the stack. @dfn{Lowering} a window means
moving it to the bottom of the stack. This motion is in the notional
third dimension only, and does not change the position of the window
on the screen.
@deffn Command raise-frame &optional frame
This function raises frame @var{frame} (default, the selected frame).
+If @var{frame} is invisible or iconified, this makes it visible.
@end deffn
@deffn Command lower-frame &optional frame
You can also enable auto-raise (raising automatically when a frame is
selected) or auto-lower (lowering automatically when it is deselected)
-for any frame using frame parameters. @xref{Window Frame Parameters}.
+for any frame using frame parameters. @xref{Management Parameters}.
@node Frame Configurations
@section Frame Configurations
@defun set-frame-configuration configuration &optional nodelete
This function restores the state of frames described in
-@var{configuration}.
+@var{configuration}. However, this function does not restore deleted
+frames.
Ordinarily, this function deletes all existing frames not listed in
@var{configuration}. But if @var{nodelete} is non-@code{nil}, the
what selection the user makes.
The argument @var{position} specifies where on the screen to put the
-menu. It can be either a mouse button event (which says to put the menu
-where the user actuated the button) or a list of this form:
+top left corner of the menu. It can be either a mouse button event
+(which says to put the menu where the user actuated the button) or a
+list of this form:
@example
((@var{xoffset} @var{yoffset}) @var{window})
@noindent
where @var{xoffset} and @var{yoffset} are coordinates, measured in
-pixels, counting from the top left corner of @var{window}'s frame.
+pixels, counting from the top left corner of @var{window}. @var{window}
+may be a window or a frame.
If @var{position} is @code{t}, it means to use the current mouse
position. If @var{position} is @code{nil}, it means to precompute the
without actually displaying or popping up the menu.
The argument @var{menu} says what to display in the menu. It can be a
-keymap or a list of keymaps (@pxref{Menu Keymaps}). Alternatively, it
-can have the following form:
+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.
+
+Alternatively, @var{menu} can have the following form:
@example
(@var{title} @var{pane1} @var{pane2}...)
where each pane is a list of form
@example
-(@var{title} (@var{line} . @var{item})...)
+(@var{title} @var{item1} @var{item2}...)
@end example
-Each @var{line} should be a string, and each @var{item} should be the
-value to return if that @var{line} is chosen.
+Each item should normally be a cons cell @code{(@var{line} . @var{value})},
+where @var{line} is a string, and @var{value} is the value to return if
+that @var{line} is chosen. An item can also be a string; this makes a
+non-selectable line in the menu.
+
+If the user gets rid of the menu without making a valid choice, for
+instance by clicking the mouse away from a valid choice or by typing
+keyboard input, then this normally results in a quit and
+@code{x-popup-menu} does not return. But if @var{position} is a mouse
+button event (indicating that the user invoked the menu with the
+mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
@end defun
@strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
submenu using @code{x-popup-menu}, it cannot work with the menu bar in
an integrated fashion. This is why all menu bar submenus are
implemented with menu keymaps within the parent menu, and never with
-@code{x-popup-menu}. @xref{Menu Bar},
+@code{x-popup-menu}. @xref{Menu Bar}.
If you want a menu bar submenu to have contents that vary, you should
still use a menu keymap to implement it. To make the contents vary, add
A dialog box is a variant of a pop-up menu---it looks a little
different, it always appears in the center of a frame, and it has just
-one level and one pane. The main use of dialog boxes is for asking
-questions that the user can answer with ``yes'', ``no'', and a few other
-alternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} use
-dialog boxes instead of the keyboard, when called from commands invoked
-by mouse clicks.
-
-@defun x-popup-dialog position contents
+one level and one or more buttons. The main use of dialog boxes is
+for asking questions that the user can answer with ``yes,'' ``no,''
+and a few other alternatives. With a single button, they can also
+force the user to acknowledge important information. The functions
+@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
+keyboard, when called from commands invoked by mouse clicks.
+
+@defun x-popup-dialog position contents &optional header
This function displays a pop-up dialog box and returns an indication of
what selection the user makes. The argument @var{contents} specifies
the alternatives to offer; it has this format:
The return value is @var{value} from the chosen alternative.
-An element of the list may be just a string instead of a cons cell
-@code{(@var{string} . @var{value})}. That makes a box that cannot
-be selected.
+As for @code{x-popup-menu}, an element of the list may be just a
+string instead of a cons cell @code{(@var{string} . @var{value})}.
+That makes a box that cannot be selected.
If @code{nil} appears in the list, it separates the left-hand items from
the right-hand items; items that precede the @code{nil} appear on the
Dialog boxes always appear in the center of a frame; the argument
@var{position} specifies which frame. The possible values are as in
-@code{x-popup-menu}, but the precise coordinates don't matter; only the
-frame matters.
+@code{x-popup-menu}, but the precise coordinates or the individual
+window don't matter; only the frame matters.
+
+If @var{header} is non-@code{nil}, the frame title for the box is
+@samp{Information}, otherwise it is @samp{Question}. The former is used
+for @code{message-box} (@pxref{message-box}).
In some configurations, Emacs cannot display a real dialog box; so
instead it displays the same items in a pop-up menu in the center of the
frame.
+
+If the user gets rid of the dialog box without making a valid choice,
+for instance using the window manager, then this produces a quit and
+@code{x-popup-dialog} does not return.
@end defun
-@node Pointer Shapes
-@section Pointer Shapes
+@node Pointer Shape
+@section Pointer Shape
@cindex pointer shape
@cindex mouse pointer shape
- These variables specify which shape to use for the mouse pointer in
-various situations, when using the X Window System:
+ You can specify the mouse pointer style for particular text or
+images using the @code{pointer} text property, and for images with the
+@code{:pointer} and @code{:map} image properties. The values you can
+use in these properties are @code{text} (or @code{nil}), @code{arrow},
+@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
+@code{hourglass}. @code{text} stands for the usual mouse pointer
+style used over text.
+
+ Over void parts of the window (parts that do not correspond to any
+of the buffer contents), the mouse pointer usually uses the
+@code{arrow} style, but you can specify a different style (one of
+those above) by setting @code{void-text-area-pointer}.
+
+@defvar void-text-area-pointer
+This variable specifies the mouse pointer style for void text areas.
+These include the areas after the end of a line or below the last line
+in the buffer. The default is to use the @code{arrow} (non-text)
+pointer style.
+@end defvar
+
+ You can specify what the @code{text} pointer style really looks like
+by setting the variable @code{x-pointer-shape}.
-@table @code
-@item x-pointer-shape
-@vindex x-pointer-shape
-This variable specifies the pointer shape to use ordinarily in the Emacs
-frame.
+@defvar x-pointer-shape
+This variable specifies the pointer shape to use ordinarily in the
+Emacs frame, for the @code{text} pointer style.
+@end defvar
-@item x-sensitive-text-pointer-shape
-@vindex x-sensitive-text-pointer-shape
+@defvar x-sensitive-text-pointer-shape
This variable specifies the pointer shape to use when the mouse
is over mouse-sensitive text.
-@end table
+@end defvar
These variables affect newly created frames. They do not normally
-affect existing frames; however, if you set the mouse color of a frame,
-that also updates its pointer shapes based on the current values of
-these variables. @xref{Window Frame Parameters}.
+affect existing frames; however, if you set the mouse color of a
+frame, that also installs the current value of those two variables.
+@xref{Color Parameters}.
The values you can use, to specify either of these pointer shapes, are
defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
symbols. X clients including Emacs can read or set the selection for
any given type.
-@defun x-set-selection type data
+@deffn Command x-set-selection type data
This function sets a ``selection'' in the X server. It takes two
arguments: a selection type @var{type}, and the value to assign to it,
@var{data}. If @var{data} is @code{nil}, it means to clear out the
Each possible @var{type} has its own selection value, which changes
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
+names, in accord with X Window System conventions. If @var{type} is
+@code{nil}, that stands for @code{PRIMARY}.
+
+This function returns @var{data}.
+@end deffn
@defun x-get-selection &optional type data-type
This function accesses selections set up by Emacs or by other X
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},
-@code{NAME}, @code{ATOM}, and @code{INTEGER}. (These are symbols with
-upper-case names in accord with X conventions.) The default for
-@var{data-type} is @code{STRING}.
+@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
+@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
+@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
+@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
+@code{INTEGER}. (These are symbols with upper-case names in accord
+with X conventions.) The default for @var{data-type} is
+@code{STRING}.
@end defun
@cindex cut buffer
@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
+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
only; if the clipboard holds other types of data, Emacs treats the
clipboard as empty.
+@cindex scrap support (for Mac OS)
+On Mac OS, selection-like data transfer between applications is
+performed through a mechanism called @dfn{scraps}. The clipboard is a
+particular scrap named @code{com.apple.scrap.clipboard}. Types of scrap
+data are called @dfn{scrap flavor types}, which are identified by
+four-char codes such as @code{TEXT}. Emacs associates a selection with
+a scrap, and a selection type with a scrap flavor type via
+@code{mac-scrap-name} and @code{mac-ostype} properties, respectively.
+
+@example
+(get 'CLIPBOARD 'mac-scrap-name)
+ @result{} "com.apple.scrap.clipboard"
+(get 'com.apple.traditional-mac-plain-text 'mac-ostype)
+ @result{} "TEXT"
+@end example
+
+Conventionally, selection types for scrap flavor types on Mac OS have
+the form of @acronym{UTI, Uniform Type Identifier} such as
+@code{com.apple.traditional-mac-plain-text},
+@code{public.utf16-plain-text}, and @code{public.file-url}.
+
@defopt x-select-enable-clipboard
If this is non-@code{nil}, the Emacs yank functions consult the
clipboard before the primary selection, and the kill functions store in
the clipboard as well as the primary selection. Otherwise they do not
access the clipboard at all. The default is @code{nil} on most systems,
-but @code{t} on MS-Windows.
+but @code{t} on MS-Windows and Mac.
@end defopt
+@node Drag and Drop
+@section Drag and Drop
+
+@vindex x-dnd-test-function
+@vindex x-dnd-known-types
+ When a user drags something from another application over Emacs, that other
+application expects Emacs to tell it if Emacs can handle the data that is
+dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
+what to reply. The default value is @code{x-dnd-default-test-function}
+which accepts drops if the type of the data to be dropped is present in
+@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
+@code{x-dnd-known-types} if you want Emacs to accept or reject drops based
+on some other criteria.
+
+@vindex x-dnd-types-alist
+ If you want to change the way Emacs handles drop of different types
+or add a new type, customize @code{x-dnd-types-alist}. This requires
+detailed knowledge of what types other applications use for drag and
+drop.
+
+@vindex dnd-protocol-alist
+ When an URL is dropped on Emacs it may be a file, but it may also be
+another URL type (ftp, http, etc.). Emacs first checks
+@code{dnd-protocol-alist} to determine what to do with the URL. If
+there is no match there and if @code{browse-url-browser-function} is
+an alist, Emacs looks for a match there. If no match is found the
+text for the URL is inserted. If you want to alter Emacs behavior,
+you can customize these variables.
+
@node Color Names
@section Color Names
+@cindex color names
+@cindex specify color
+@cindex numerical RGB color specification
+ A color name is text (usually in a string) that specifies a color.
+Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
+are allowed; use @kbd{M-x list-colors-display} to see a list of
+defined names. You can also specify colors numerically in forms such
+as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
+@var{r} specifies the red level, @var{g} specifies the green level,
+and @var{b} specifies the blue level. You can use either one, two,
+three, or four hex digits for @var{r}; then you must use the same
+number of hex digits for all @var{g} and @var{b} as well, making
+either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
+X Window System for more details about numerical RGB specification of
+colors.)
+
These functions provide a way to determine which color names are
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''.
+meaning of the term ``selected frame.''
@defun color-defined-p color &optional frame
-@tindex color-defined-p
This function reports whether a color name is meaningful. It returns
@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
which frame's display to ask about; if @var{frame} is omitted or
@end defun
@defun defined-colors &optional frame
-@tindex defined-colors
This function returns a list of the color names that are defined
and supported on frame @var{frame} (default, the selected frame).
+If @var{frame} does not support colors, the value is @code{nil}.
@findex x-defined-colors
This function used to be called @code{x-defined-colors},
@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.
@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.
+question applies to the selected frame. If @var{color} is not a valid
+color name, this function returns @code{nil}.
@end defun
@defun color-values color &optional frame
-@tindex color-values
+@cindex rgb value
This function returns a value that describes what @var{color} should
-ideally look like. If @var{color} is defined, the value is a list of
-three integers, which give the amount of red, the amount of green, and
-the amount of blue. Each integer ranges in principle from 0 to 65535,
-but in practice no value seems to be above 65280. This kind
-of three-element list is called an @dfn{rgb value}.
+ideally look like on @var{frame}. If @var{color} is defined, the
+value is a list of three integers, which give the amount of red, the
+amount of green, and the amount of blue. Each integer ranges in
+principle from 0 to 65535, but some displays may not use the full
+range. This three-element list is called the @dfn{rgb values} of the
+color.
If @var{color} is not defined, the value is @code{nil}.
@result{} nil
@end example
-The color values are returned for @var{frame}'s display. If @var{frame}
-is omitted or @code{nil}, the information is returned for the selected
-frame's display.
+The color values are returned for @var{frame}'s display. If
+@var{frame} is omitted or @code{nil}, the information is returned for
+the selected frame's display. If the frame cannot display colors, the
+value is @code{nil}.
@findex x-color-values
This function used to be called @code{x-color-values},
@section Text Terminal Colors
@cindex colors on text-only terminals
- Emacs can display color on text-only terminals, starting with version
-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.
+ Text-only 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
-amount of green, and the amount of blue. Each integer ranges in
-principle from 0 to 65535, but in practice the largest value used is
-65280.
+ Several of these functions use or return @dfn{rgb values}, described
+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{display} argument has no effect.
+the @var{frame} argument has no effect.
-@defun tty-color-define name number &optional rgb display
-@tindex tty-color-define
+@defun tty-color-define name number &optional rgb frame
This function associates the color name @var{name} with
color number @var{number} on the terminal.
-The optional argument @var{rgb}, if specified, is an rgb value; it says
-what the color actually looks like. If you do not specify @var{rgb},
-then this color cannot be used by @code{tty-color-approximate} to
-approximate other colors, because Emacs does not know what it looks
-like.
+The optional argument @var{rgb}, if specified, is an rgb value, a list
+of three numbers that specify what the color actually looks like.
+If you do not specify @var{rgb}, then this color cannot be used by
+@code{tty-color-approximate} to approximate other colors, because
+Emacs will not know what it looks like.
@end defun
-@defun tty-color-clear &optional display
-@tindex tty-color-clear
+@defun tty-color-clear &optional frame
This function clears the table of defined colors for a text-only terminal.
@end defun
-@defun tty-color-alist &optional display
-@tindex tty-color-alist
+@defun tty-color-alist &optional frame
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.
+If present, @var{rgb} is a list of three color values (for red, green,
+and blue) that says what the color actually looks like.
@end defun
-@defun tty-color-approximate rgb &optional display
-@tindex tty-color-approximate
-This function finds the closest color, among the known colors supported
-for @var{display}, to that described by the rgb value @var{rgb}.
+@defun tty-color-approximate rgb &optional frame
+This function finds the closest color, among the known colors
+supported for @var{display}, to that described by the rgb value
+@var{rgb} (a list of color values). The return value is an element of
+@code{tty-color-alist}.
@end defun
-@defun tty-color-translate color &optional display
-@tindex tty-color-translate
+@defun tty-color-translate color &optional frame
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. The format
-@code{"RGB:@var{xx}/@var{yy}/@var{zz}"} is also supported.
+colors supported for @var{display} and returns its index (an integer).
+If the name @var{color} is not defined, the value is @code{nil}.
@end defun
@node Resources
or the value specified with the @samp{-name} or @samp{-rn} switches.
@end defvar
+To illustrate some of the above, suppose that you have the line:
+
+@example
+xterm.vt100.background: yellow
+@end example
+
+@noindent
+in your X resources file (whose name is usually @file{~/.Xdefaults}
+or @file{~/.Xresources}). Then:
+
+@example
+@group
+(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
+ (x-get-resource "vt100.background" "VT100.Background"))
+ @result{} "yellow"
+@end group
+@group
+(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
+ (x-get-resource "background" "VT100" "vt100" "Background"))
+ @result{} "yellow"
+@end group
+@end example
+
@xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
@node Display Feature Testing
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
@end defun
@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
@end defun
@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 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
@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-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}).
@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.
+On a character terminal, it gives the height in characters.
+@end defun
+
+@defun display-pixel-width &optional display
+This function returns the width of the screen in pixels.
+On a character terminal, it gives the width in characters.
@end defun
@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 display-pixel-width &optional display
-@tindex display-pixel-width
-This function returns the width of the screen in pixels.
-@end defun
-
@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
+@defvar 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
+
@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
@end defun
@defun display-save-under &optional display
-@tindex display-save-under
This function returns non-@code{nil} if the display supports the
SaveUnder feature. That feature is used by pop-up windows
to save the pixels they obscure, so that they can pop down
@end defun
@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.
+For a tty display, it is log to base two of the number of colors supported.
@end defun
@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
@end defun
@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-server-version &optional display
This function returns the list of version numbers of the X server
-running the display.
+running the display. The value is a list of three integers: the major
+and minor version numbers of the X protocol, and the
+distributor-specific release number of the X server software itself.
@end defun
@defun x-server-vendor &optional display
-This function returns the vendor that provided the X server software.
+This function returns the ``vendor'' that provided the X server
+software (as a string). Really this means whoever distributes the X
+server.
+
+When the developers of X labelled software distributors as
+``vendors,'' they showed their false assumption that no system could
+ever be developed and distributed noncommercially.
@end defun
@ignore