[Emacs-diffs] Changes to emacs/lispref/frames.texi [gnus-5_10-branch]

[Miles Bader]

Index: emacs/lispref/frames.texi
diff -c /dev/null emacs/lispref/frames.texi:1.76.2.1
*** /dev/null   Sat Sep  4 12:02:40 2004
--- emacs/lispref/frames.texi   Sat Sep  4 12:01:14 2004
***************
*** 0 ****
--- 1,2005 ----
+ @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 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.
+ 
+ @cindex terminal frame
+   When Emacs runs on a text-only terminal, it starts with one
+ @dfn{terminal frame}.  If you create additional ones, Emacs displays
+ one and only one at any given time---on the terminal screen, of course.
+ 
+ @cindex window frame
+   When Emacs communicates directly with a supported window system, such
+ 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.
+ 
+ @defun framep object
+ This predicate returns a address@hidden value if @var{object} is a
+ frame, and @code{nil} otherwise.  For a frame, the value indicates which
+ kind of display the frame uses:
+ 
+ @table @code
+ @item x
+ The frame is displayed in an X window.
+ @item t
+ A terminal frame on a character display.
+ @item mac
+ The frame is displayed on a Macintosh.
+ @item w32
+ The frame is displayed on MS-Windows 9X/NT.
+ @item pc
+ The frame is displayed on an MS-DOS terminal.
+ @end table
+ @end defun
+ 
+ @menu
+ * Creating Frames::           Creating additional frames.
+ * Multiple Displays::           Creating frames on other displays.
+ * Frame Parameters::          Controlling frame size, position, font, etc.
+ * Frame Titles::                Automatic updating of frame titles.
+ * Deleting Frames::           Frames last until explicitly deleted.
+ * Finding All Frames::                How to examine all existing frames.
+ * Frames and Windows::                A frame contains windows;
+                                 display of text always works through windows.
+ * Minibuffers and Frames::    How a frame finds the minibuffer to use.
+ * Input Focus::                       Specifying the selected frame.
+ * Visibility of Frames::      Frames may be visible or invisible, or icons.
+ * Raising and Lowering::      Raising a frame makes it hide other windows;
+                                 lowering it makes the others hide it.
+ * Frame Configurations::      Saving the state of all frames.
+ * Mouse Tracking::            Getting events that say when the mouse moves.
+ * Mouse Position::            Asking where the mouse is, or moving it.
+ * Pop-Up Menus::              Displaying a menu for the user to select from.
+ * Dialog Boxes::                Displaying a box to ask yes or no.
+ * Pointer Shapes::              Specifying the shape of the mouse pointer.
+ * Window System Selections::    Transferring text to and from other X clients.
+ * Color Names::                       Getting the definitions of color names.
+ * Text Terminal Colors::        Defining colors for text-only terminals.
+ * Resources::                 Getting resource values from the server.
+ * Display Feature Testing::     Determining the features of a terminal.
+ @end menu
+ 
+   @xref{Display}, for information about the related topic of
+ controlling Emacs redisplay.
+ 
+ @node Creating Frames
+ @section Creating Frames
+ 
+ To create a new frame, call the function @code{make-frame}.
+ 
+ @defun make-frame &optional alist
+ 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
+ variable @code{default-frame-alist}; parameters not specified even there
+ default from the standard X resources or whatever is used instead on
+ your system.
+ 
+ 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
+ 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-functions} receives one argument, the
+ frame just created.
+ @end defvar
+ 
+ @node Multiple Displays
+ @section Multiple Displays
+ @cindex multiple X displays
+ @cindex displays, multiple
+ 
+   A single Emacs can talk to more than one X display.
+ Initially, Emacs uses just one display---the one chosen with the
+ @code{DISPLAY} environment variable or with the @samp{--display} option
+ (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}).  To connect to
+ another display, use the command @code{make-frame-on-display} or specify
+ 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.  However, only one of
+ those frames is address@hidden 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
+ is the one for the terminal that the currently selected frame belongs
+ to.  These variables include @code{default-minibuffer-frame},
+ @code{defining-kbd-macro}, @code{last-kbd-macro}, and
+ @code{system-key-alist}.  They are always terminal-local, and can never
+ be buffer-local (@pxref{Buffer-Local Variables}) or frame-local.
+ 
+   A single X server can handle more than one screen.  A display name
+ @address@hidden:@address@hidden has three parts; the last
+ part specifies the screen number for a given server.  When you use two
+ screens belonging to one server, Emacs knows by the similarity in their
+ names that they share a single keyboard, and it treats them as a single
+ terminal.
+ 
+ @deffn Command make-frame-on-display display &optional parameters
+ 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
+ This returns a list that indicates which X displays Emacs has a
+ connection to.  The elements of the list are strings, and each one is
+ a display name.
+ @end defun
+ 
+ @defun x-open-connection display &optional xrm-string must-succeed
+ This function opens a connection to the X display @var{display}.  It
+ does not create a frame on that display, but it permits you to check
+ that communication can be established with that display.
+ 
+ The optional argument @var{xrm-string}, if not @code{nil}, is a
+ string of resource names and values, in the same format used in the
+ @file{.Xresources} file.  The values you specify override the resource
+ values recorded in the X server itself; they apply to all Emacs frames
+ created on this display.  Here's an example of what this string might
+ look like:
+ 
+ @example
+ "*BorderWidth: 3\n*InternalBorder: 2\n"
+ @end example
+ 
+ @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
+ 
+ If @var{must-succeed} is address@hidden, failure to open the connection
+ terminates Emacs.  Otherwise, it is an ordinary Lisp error.
+ @end defun
+ 
+ @defun x-close-connection display
+ This function closes the connection to display @var{display}.  Before
+ you can do this, you must first delete all the frames that were open on
+ that display (@pxref{Deleting Frames}).
+ @end defun
+ 
+ @node Frame Parameters
+ @section Frame Parameters
+ 
+   A frame has many parameters that control its appearance and behavior.
+ Just what parameters a frame has depends on what display mechanism it
+ uses.
+ 
+   Frame parameters exist mostly for the sake of window systems.  A
+ terminal frame has a few parameters, mostly for compatibility's sake;
+ only the @code{height}, @code{width}, @code{name}, @code{title},
+ @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
+ parameters do something special.  If the terminal supports colors, the
+ parameters @code{foreground-color}, @code{background-color},
+ @code{background-mode} and @code{display-type} are also meaningful.
+ 
+ @menu
+ * Parameter Access::       How to change a frame's parameters.
+ * 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.
+ @end menu
+ 
+ @node Parameter Access
+ @subsection Access to Frame Parameters
+ 
+ These functions let you read and change the parameter values of a
+ frame.
+ 
+ @defun frame-parameter frame parameter
+ @tindex frame-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
+ The function @code{frame-parameters} returns an alist listing all the
+ parameters of @var{frame} and their values.  If @var{frame} is
+ @code{nil} or omitted, this returns the selected frame's parameters
+ @end defun
+ 
+ @defun modify-frame-parameters frame alist
+ This function alters the parameters of frame @var{frame} based on the
+ elements of @var{alist}.  Each element of @var{alist} has the form
+ @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
+ parameter.  If you don't mention a parameter in @var{alist}, its value
+ doesn't change.  If @var{frame} is @code{nil}, it defaults to the selected
+ frame.
+ @end defun
+ 
+ @defun modify-all-frames-parameters alist
+ This function alters the frame parameters of all existing frames
+ according to @var{alist}, then modifies @code{default-frame-alist}
+ (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
+ @subsection Initial Frame Parameters
+ 
+ You can specify the parameters for the initial startup frame
+ by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
+ 
+ @defvar initial-frame-alist
+ This variable's value is an alist of parameter values used when creating
+ the initial window frame.  You can set this variable to specify the
+ appearance of the initial frame without altering subsequent frames.
+ Each element has the form:
+ 
+ @example
+ (@var{parameter} . @var{value})
+ @end example
+ 
+ Emacs creates the initial frame before it reads your init
+ file.  After reading that file, Emacs checks @code{initial-frame-alist},
+ and applies the parameter settings in the altered value to the already
+ created initial frame.
+ 
+ If these settings affect the frame geometry and appearance, you'll see
+ 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{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
+ you don't want them to apply to subsequent frames, here's how to achieve
+ this.  Specify parameters in @code{default-frame-alist} to override the
+ X resources for subsequent frames; then, to prevent these from affecting
+ the initial frame, specify the same parameters in
+ @code{initial-frame-alist} with values that match the X resources.
+ @end defvar
+ 
+ If these parameters specify a separate minibuffer-only frame with
+ @code{(minibuffer . nil)}, and you have not created one, Emacs creates
+ one for you.
+ 
+ @defvar minibuffer-frame-alist
+ This variable's value is an alist of parameter values used when creating
+ an initial minibuffer-only frame---if such a frame is needed, according
+ to the parameters for the main initial frame.
+ @end defvar
+ 
+ @defvar default-frame-alist
+ This is an alist specifying default values of frame parameters for all
+ Emacs frames---the first frame, and subsequent frames.  When using the X
+ Window System, you can get the same results by means of X resources
+ in many cases.
+ 
+ Setting this variable does not affect existing frames.
+ @end defvar
+ 
+ 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}.
+ 
+ @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.
+ 
+ @table @code
+ @item display
+ The display on which to open this frame.  It should be a string of the
+ form @code{"@var{host}:@address@hidden"}, just like the
+ @code{DISPLAY} environment variable.
+ 
+ @item title
+ If a frame has a address@hidden title, it appears in the window system's
+ border for the frame, and also in the mode line of windows in that frame
+ if @code{mode-line-frame-identification} uses @samp{%F}
+ (@pxref{%-Constructs}).  This is normally the case when Emacs is not
+ using a window system, and can only display one frame at a time.
+ @xref{Frame Titles}.
+ 
+ @item name
+ The name of the frame.  The frame name serves as a default for the frame
+ title, if the @code{title} parameter is unspecified or @code{nil}.  If
+ you don't specify a name, Emacs sets the frame name automatically
+ (@pxref{Frame Titles}).
+ 
+ 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.
+ 
+ @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},
+ or a list of the form @code{(+ @var{pos})} which permits specifying a
+ negative @var{pos} value.
+ 
+ A negative number @address@hidden, or a list of the form @code{(-
+ @var{pos})}, actually specifies the position of the right edge of the
+ window with respect to the right edge of the screen.  A positive value
+ of @var{pos} counts toward the left.  @strong{Reminder:} if the
+ parameter is a negative integer @address@hidden, 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
+ address@hidden value for the @code{user-position} parameter as well.
+ 
+ @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 @address@hidden, 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 @address@hidden, 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
+ address@hidden value for the @code{user-position} parameter as well.
+ 
+ @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
+ and when the frame is iconified.
+ 
+ @item user-position
+ When you create a frame and specify its screen position with the
+ @code{left} and @code{top} parameters, use this parameter to say whether
+ the specified position was user-specified (explicitly requested in some
+ way by a human user) or merely program-specified (chosen by a program).
+ A address@hidden value says the position was user-specified.
+ 
+ Window managers generally heed user-specified positions, and some heed
+ program-specified positions too.  But many ignore program-specified
+ positions, placing the window in a default fashion or letting the user
+ place it with the mouse.  Some window managers, including @code{twm},
+ let the user specify whether to obey program-specified positions or
+ ignore them.
+ 
+ When you call @code{make-frame}, you should specify a address@hidden
+ 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}.
+ 
+ @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}.)
+ 
+ @item width
+ 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.
+ 
+ @item outer-window-id
+ The number of the outermost window-system window used for the whole frame.
+ 
+ @item minibuffer
+ Whether this frame has its own minibuffer.  The value @code{t} means
+ yes, @code{nil} means no, @code{only} means this frame is just a
+ minibuffer.  If the value is a minibuffer window (in some other frame),
+ the new frame uses that minibuffer.
+ 
+ @item buffer-predicate
+ The buffer-predicate function for this frame.  The function
+ @code{other-buffer} uses this predicate (from the selected frame) to
+ decide which buffers it should consider, if the predicate is not
+ @code{nil}.  It calls the predicate with one argument, a buffer, once for
+ each buffer; if the predicate returns a address@hidden value, it
+ considers that buffer.
+ 
+ @item buffer-list
+ A list of buffers that have been selected in this frame,
+ ordered most-recently-selected first.
+ 
+ @item auto-raise
+ Whether selecting the frame raises it (address@hidden means yes).
+ 
+ @item auto-lower
+ Whether deselecting the frame lowers it (address@hidden 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
+ (address@hidden 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.
+ Any other address@hidden value specifies the default bitmap icon (a
+ picture of a gnu); @code{nil} specifies a text icon.
+ 
+ @item icon-name
+ The name to use in the icon for this frame, when and if the icon
+ appears.  If this is @code{nil}, the frame's title is used.
+ 
+ @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 tty-color-mode
+ @cindex standard colors for character terminals
+ This parameter overrides the terminal's color support as given by the
+ system's terminal capabilities database in that this parameter's value
+ specifies the color mode to use in terminal frames.  The value can be
+ either a symbol or a number.  A number specifies the number of colors
+ to use (and, indirectly, what commands to issue to produce each
+ color).  For example, @code{(tty-color-mode . 8)} forces Emacs to use
+ the ANSI escape sequences for 8 standard text colors; and a value of
+ -1 means Emacs should turn off color support.  If the parameter's
+ value is a symbol, that symbol is looked up in the alist
+ @code{tty-color-mode-alist}, and if found, the associated number is
+ used as the color support mode.
+ 
+ @item display-type
+ This parameter describes the range of possible colors that can be used
+ in this frame.  Its value is @code{color}, @code{grayscale} or
+ @code{mono}.
+ 
+ @item cursor-type
+ How to display the cursor.  Legitimate values are:
+ 
+ @table @code
+ @item box
+ Display a filled box.  (This is the default.)
+ @item hollow
+ Display a hollow box.
+ @item nil
+ Don't display a cursor.
+ @item bar
+ Display a vertical bar between characters.
+ @item (bar . @var{width})
+ Display a vertical bar @var{width} pixels wide between characters.
+ @item hbar
+ Display a horizontal bar.
+ @item (bar . @var{width})
+ Display a horizontal bar @var{width} pixels high.
+ @end table
+ 
+ @vindex cursor-type
+ The buffer-local variable @code{cursor-type} overrides the value of
+ the @code{cursor-type} frame parameter, but if it is @code{t}, that
+ means to use the cursor specified for the frame.
+ 
+ @item border-width
+ The width in pixels of the window border.
+ 
+ @item internal-border-width
+ The distance in pixels between text and border.
+ 
+ @item left-fringe
+ @itemx right-fringe
+ The default width of the left and right fringes of windows in this
+ frame (@pxref{Fringes}).  If either of these is zero, that effectively
+ removes the corresponding fringe.  A value of @code{nil} stands for
+ the standard fringe width, which is the width needed to display the
+ fringe bitmaps.
+ 
+ The combined fringe widths must add up to an integral number of
+ columns, so the actual default fringe widths for the frame may be
+ larger than the specified values.  The extra width needed to reach an
+ acceptable total is distributed evenly between the left and right
+ fringe.  However, you can force one 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 unsplittable
+ If address@hidden, this frame's window is never split automatically.
+ 
+ @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 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 screen-gamma
+ @cindex gamma correction
+ 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 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 line-spacing
+ Additional space put below text lines, in pixels (a positive integer)
+ 
+ @item wait-for-wm
+ If address@hidden, 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
+ 
+ @defvar blink-cursor-alist
+ This variable specifies how to blink the cursor.  Each element has the
+ form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
+ type equals @var{on-state} (comparing using @code{equal}), Emacs uses
+ @var{off-state} to specify what the cursor looks like when it blinks
+ ``off''.  Both @var{on-state} and @var{off-state} should be suitable
+ values for the @code{cursor-type} frame parameter.
+ 
+ There are various defaults for how to blink each type of cursor,
+ if the type is not mentioned as an @var{on-state} here.  Changes
+ in this variable do not take effect immediately, because the variable
+ is examined only when you specify a cursor type for a frame.
+ @end defvar
+ 
+ These frame parameters are semi-obsolete in that they are automatically
+ equivalent to particular face attributes of particular faces.
+ 
+ @table @code
+ @item font
+ The name of the font for displaying text in the frame.  This is a
+ string, either a valid font name for your system or the name of an Emacs
+ fontset (@pxref{Fontsets}).  It is equivalent to the @code{font}
+ attribute of the @code{default} face.
+ 
+ @item foreground-color
+ The color to use for the image of a character.  It is equivalent to
+ the @code{:foreground} attribute of the @code{default} face.
+ 
+ @item background-color
+ The color to use for the background of characters.  It is equivalent to
+ the @code{:background} attribute of the @code{default} face.
+ 
+ @item mouse-color
+ The color for the mouse pointer.  It is equivalent to the @code{:background}
+ attribute of the @code{mouse} face.
+ 
+ @item cursor-color
+ The color for the cursor that shows point.  It is equivalent to the
+ @code{:background} attribute of the @code{cursor} face.
+ 
+ @item border-color
+ The color for the border of the frame.  It is equivalent to the
+ @code{:background} attribute of the @code{border} face.
+ 
+ @item scroll-bar-foreground
+ If address@hidden, the color for the foreground of scroll bars.  It is
+ equivalent to the @code{:foreground} attribute of the
+ @code{scroll-bar} face.
+ 
+ @item scroll-bar-background
+ If address@hidden, the color for the background of scroll bars.  It is
+ equivalent to the @code{:background} attribute of the
+ @code{scroll-bar} face.
+ @end table
+ 
+ @node Size and Position
+ @subsection Frame Size And Position
+ @cindex size of frame
+ @cindex screen size
+ @cindex frame size
+ @cindex resize frame
+ 
+   You can read or change the size and position of a frame using the
+ frame parameters @code{left}, @code{top}, @code{height}, and
+ @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.
+ (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
+ @var{left} and @var{top}.  These arguments are measured in pixels, and
+ normally count from the top left corner of the screen.
+ 
+ Negative parameter values position the bottom edge of the window up from
+ the bottom edge of the screen, or the right window edge to the left of
+ the right edge of the screen.  It would probably be better if the values
+ were always counted from the left and top, so that negative arguments
+ would position the frame partly off the top or left edge of the screen,
+ but it seems inadvisable to change that now.
+ @end defun
+ 
+ @defun frame-height &optional frame
+ @defunx frame-width &optional frame
+ These functions return the height and width of @var{frame}, measured in
+ lines and columns.  If you don't supply @var{frame}, they use the
+ selected frame.
+ @end defun
+ 
+ @defun screen-height
+ @defunx screen-width
+ These functions are old aliases for @code{frame-height} and
+ @code{frame-width}.  When you are using a non-window terminal, the size
+ of the frame is normally the same as the size of the terminal screen.
+ @end defun
+ 
+ @defun frame-pixel-height &optional frame
+ @defunx frame-pixel-width &optional frame
+ These functions return the height and width of @var{frame}, measured in
+ pixels.  If you don't supply @var{frame}, they use the selected frame.
+ @end defun
+ 
+ @defun frame-char-height &optional frame
+ @defunx frame-char-width &optional frame
+ These functions return the height and width of a character in
+ @var{frame}, measured in pixels.  The values depend on the choice of
+ font.  If you don't supply @var{frame}, these functions use the selected
+ frame.
+ @end defun
+ 
+ @defun set-frame-size frame cols rows
+ This function sets the size of @var{frame}, measured in characters;
+ @var{cols} and @var{rows} specify the new width and height.
+ 
+ To set the size based on values measured in pixels, use
+ @code{frame-char-height} and @code{frame-char-width} to convert
+ them to units of characters.
+ @end defun
+ 
+ @defun set-frame-height frame lines &optional pretend
+ This function resizes @var{frame} to a height of @var{lines} lines.  The
+ sizes of existing windows in @var{frame} are altered proportionally to
+ fit.
+ 
+ If @var{pretend} is address@hidden, then Emacs displays @var{lines}
+ lines of output in @var{frame}, but does not change its value for the
+ actual height of the frame.  This is only useful for a terminal frame.
+ Using a smaller height than the terminal actually implements may be
+ useful to reproduce behavior observed on a smaller screen, or if the
+ terminal malfunctions when using its whole screen.  Setting the frame
+ height ``for real'' does not always work, because knowing the correct
+ actual size may be necessary for correct cursor positioning on a
+ terminal frame.
+ @end defun
+ 
+ @defun set-frame-width frame width &optional pretend
+ This function sets the width of @var{frame}, measured in characters.
+ The argument @var{pretend} has the same meaning as in
+ @code{set-frame-height}.
+ @end defun
+ 
+ @findex set-screen-height
+ @findex set-screen-width
+   The older functions @code{set-screen-height} and
+ @code{set-screen-width} were used to specify the height and width of the
+ screen, in Emacs versions that did not support multiple frames.  They
+ are semi-obsolete, but still work; they apply to the selected frame.
+ 
+ @defun x-parse-geometry geom
+ @cindex geometry specification
+ The function @code{x-parse-geometry} converts a standard X window
+ geometry string to an alist that you can use as part of the argument to
+ @code{make-frame}.
+ 
+ The alist describes which parameters were specified in @var{geom}, and
+ gives the values specified for them.  Each element looks like
+ @code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
+ values are @code{left}, @code{top}, @code{width}, and @code{height}.
+ 
+ For the size parameters, the value must be an integer.  The position
+ parameter names @code{left} and @code{top} are not totally accurate,
+ because some values indicate the position of the right or bottom edges
+ instead.  These are the @var{value} possibilities for the position
+ parameters:
+ 
+ @table @asis
+ @item an integer
+ A positive integer relates the left edge or top edge of the window to
+ the left or top edge of the screen.  A negative integer relates the
+ right or bottom edge of the window to the right or bottom edge of the
+ screen.
+ 
+ @item @code{(+ @var{position})}
+ This specifies the position of the left or top edge of the window
+ relative to the left or top edge of the screen.  The integer
+ @var{position} may be positive or negative; a negative value specifies a
+ position outside the screen.
+ 
+ @item @code{(- @var{position})}
+ This specifies the position of the right or bottom edge of the window
+ relative to the right or bottom edge of the screen.  The integer
+ @var{position} may be positive or negative; a negative value specifies a
+ position outside the screen.
+ @end table
+ 
+ Here is an example:
+ 
+ @example
+ (x-parse-geometry "35x70+0-0")
+      @result{} ((height . 70) (width . 35)
+          (top - 0) (left . 0))
+ @end example
+ @end defun
+ 
+ @node Frame Titles
+ @section Frame Titles
+ 
+   Every frame has a @code{name} parameter; this serves as the default
+ for the frame title which window systems typically display at the top of
+ the frame.  You can specify a name explicitly by setting the @code{name}
+ frame property.
+ 
+   Normally you don't specify the name explicitly, and Emacs computes the
+ frame name automatically based on a template stored in the variable
+ @code{frame-title-format}.  Emacs recomputes the name each time the
+ frame is redisplayed.
+ 
+ @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
+ Data}.
+ @end defvar
+ 
+ @defvar icon-title-format
+ This variable specifies how to compute the name for an iconified frame,
+ when you have not explicitly specified the frame title.  This title
+ appears in the icon itself.
+ @end defvar
+ 
+ @defvar multiple-frames
+ This variable is set automatically by Emacs.  Its value is @code{t} when
+ there are two or more frames (not counting minibuffer-only frames or
+ 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
+ @section Deleting Frames
+ @cindex deletion of 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.
+ 
+ @deffn Command delete-frame &optional frame force
+ @vindex delete-frame-functions
+ 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,
+ but if the @var{force} is address@hidden, then you are allowed to do so.
+ @end deffn
+ 
+ @defun frame-live-p frame
+ The function @code{frame-live-p} returns address@hidden if the frame
+ @var{frame} has not been deleted.  The possible address@hidden return
+ values are like those of @code{framep}.  @xref{Frames}.
+ @end defun
+ 
+   Some window managers provide a command to delete a window.  These work
+ by sending a special message to the program that operates the window.
+ When Emacs gets one of these commands, it generates a
+ @code{delete-frame} event, whose normal definition is a command that
+ calls the function @code{delete-frame}.  @xref{Misc Events}.
+ 
+ @node Finding All Frames
+ @section Finding All Frames
+ 
+ @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, 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
+ 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.)
+ @end defun
+ 
+ @defun next-frame &optional frame minibuf
+ The function @code{next-frame} lets you cycle conveniently through all
+ 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:
+ 
+ @table @asis
+ @item @code{nil}
+ Exclude minibuffer-only frames.
+ @item @code{visible}
+ Consider all visible frames.
+ @item 0
+ Consider all visible or iconified frames.
+ @item a window
+ Consider only the frames using that particular window as their
+ minibuffer.
+ @item anything else
+ Consider all frames.
+ @end table
+ @end defun
+ 
+ @defun previous-frame &optional frame minibuf
+ Like @code{next-frame}, but cycles through all frames in the opposite
+ direction.
+ @end defun
+ 
+   See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
+ Window Ordering}.
+ 
+ @node Frames and Windows
+ @section Frames and Windows
+ 
+   Each window is part of one and only one frame; you can get the frame
+ with @code{window-frame}.
+ 
+ @defun window-frame window
+ This function returns the frame that @var{window} is on.
+ @end defun
+ 
+   All the non-minibuffer windows in a frame are arranged in a cyclic
+ order.  The order runs from the frame's top window, which is at the
+ upper left corner, down and to the right, until it reaches the window at
+ the lower right corner (always the minibuffer window, if the frame has
+ one), and then it moves back to the top.  @xref{Cyclic Window Ordering}.
+ 
+ @defun frame-first-window &optional frame
+ This returns the topmost, leftmost window of frame @var{frame}.
+ If omitted or @code{nil}, @var{frame} defaults to the selected frame.
+ @end defun
+ 
+ At any time, exactly one window on any frame is @dfn{selected within the
+ frame}.  The significance of this designation is that selecting the
+ frame also selects this window.  You can get the frame's current
+ 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.
+ @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.  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{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{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
+ frame, you can specify explicitly the minibuffer window to use (in some
+ other frame).  If you don't, then the minibuffer is found in the frame
+ which is the value of the variable @code{default-minibuffer-frame}.  Its
+ value should be a frame that does have a minibuffer.
+ 
+ If you use a minibuffer-only frame, you might want that frame to raise
+ when you enter the minibuffer.  If so, set the variable
+ @code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.
+ 
+ @defvar default-minibuffer-frame
+ This variable specifies the frame to use for the minibuffer window, by
+ 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
+ @section Input Focus
+ @cindex input focus
+ @cindex selected frame
+ 
+ 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 address@hidden 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
+ 
+ Some window systems and window managers direct keyboard input to the
+ window object that the mouse is in; others require explicit clicks or
+ commands to @dfn{shift the focus} to various window objects.  Either
+ way, Emacs automatically keeps track of which frame has the focus.  To
+ switch to a different frame from a Lisp function, call
+ @code{select-frame-set-input-focus}.
+ 
+ Lisp programs can also switch frames ``temporarily'' by calling the
+ function @code{select-frame}.  This does not alter the window system's
+ concept of focus; rather, it escapes from the window manager's control
+ until that control is somehow reasserted.
+ 
+ When using a text-only terminal, only one frame can be displayed at a
+ time on the terminal, so after a call to @code{select-frame}, the next
+ redisplay actually displays the newly selected frame.  This frame
+ remains selected until a subsequent call to @code{select-frame} or
+ @code{select-frame-set-input-focus}.  Each terminal frame has a number
+ which appears in the mode line before the buffer name (@pxref{Mode
+ Line Variables}).
+ 
+ @defun select-frame-set-input-focus frame
+ This function makes @var{frame} the selected frame, raises it (should
+ it happen to be obscured by other frames) and tries to give it the X
+ server's focus.  On a text-only terminal, the next redisplay displays
+ the new frame on the entire terminal screen.  The return value of this
+ function is not significant.
+ @end defun
+ 
+ @c ??? This is not yet implemented properly.
+ @defun select-frame frame
+ 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.  (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.
+ 
+ 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 server and window manager request.  It does so by generating a
+ special kind of input event, called a @dfn{focus} event, when
+ appropriate.  The command loop handles a focus event by calling
+ @code{handle-switch-frame}.  @xref{Focus Events}.
+ 
+ @deffn Command handle-switch-frame frame
+ This function handles a focus event by selecting frame @var{frame}.
+ 
+ Focus events normally do their job by invoking this command.
+ Don't call it for any other reason.
+ @end deffn
+ 
+ @defun redirect-frame-focus frame &optional focus-frame
+ This function redirects focus from @var{frame} to @var{focus-frame}.
+ This means that @var{focus-frame} will receive subsequent keystrokes and
+ events intended for @var{frame}.  After such an event, the value of
+ @code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
+ events specifying @var{frame} will instead select @var{focus-frame}.
+ 
+ If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
+ redirection for @var{frame}, which therefore once again receives its own
+ events.
+ 
+ One use of focus redirection is for frames that don't have minibuffers.
+ These frames use minibuffers on other frames.  Activating a minibuffer
+ on another frame redirects focus to that frame.  This puts the focus on
+ the minibuffer's frame, where it belongs, even though the mouse remains
+ in the frame that activated the minibuffer.
+ 
+ Selecting a frame can also change focus redirections.  Selecting frame
+ @code{bar}, when @code{foo} had been selected, changes any redirections
+ pointing to @code{foo} so that they point to @code{bar} instead.  This
+ allows focus redirection to work properly when the user switches from
+ one frame to another using @code{select-window}.
+ 
+ This means that a frame whose focus is redirected to itself is treated
+ differently from a frame whose focus is not redirected.
+ @code{select-frame} affects the former but not the latter.
+ 
+ The redirection lasts until @code{redirect-frame-focus} is called to
+ change it.
+ @end defun
+ 
+ @defopt focus-follows-mouse
+ This option is how you inform Emacs whether the window manager transfers
+ focus when the user moves the mouse.  address@hidden 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.
+ @end defopt
+ 
+ @node Visibility of Frames
+ @section Visibility of Frames
+ @cindex visible frame
+ @cindex invisible frame
+ @cindex iconified frame
+ @cindex frame visibility
+ 
+ A window frame may be @dfn{visible}, @dfn{invisible}, or
+ @dfn{iconified}.  If it is visible, you can see its contents.  If it is
+ iconified, the frame's contents do not appear on the screen, but an icon
+ does.  If the frame is invisible, it doesn't show on the screen, not
+ even as an icon.
+ 
+ Visibility is meaningless for terminal frames, since only the selected
+ one is actually displayed in any case.
+ 
+ @deffn Command make-frame-visible &optional frame
+ This function makes frame @var{frame} visible.  If you omit @var{frame},
+ it makes the selected frame visible.
+ @end deffn
+ 
+ @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 address@hidden, this function refuses to make
+ @var{frame} invisible if all other frames are invisible..
+ @end deffn
+ 
+ @deffn Command iconify-frame &optional frame
+ This function iconifies frame @var{frame}.  If you omit @var{frame}, it
+ iconifies the selected frame.
+ @end deffn
+ 
+ @defun frame-visible-p 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
+ Parameters}.
+ 
+   The user can iconify and deiconify frames with the window manager.
+ This happens below the level at which Emacs can exert any control, but
+ Emacs does provide events that you can use to keep track of such
+ changes.  @xref{Misc Events}.
+ 
+ @node Raising and Lowering
+ @section Raising and Lowering Frames
+ 
+   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
+ the one underneath.  Even a window at the bottom of the stack can be
+ seen if no other window overlaps it.
+ 
+ @cindex raising a frame
+ @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
+ 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.
+ 
+   You can raise and lower Emacs frame Windows with these functions:
+ 
+ @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
+ This function lowers frame @var{frame} (default, the selected frame).
+ @end deffn
+ 
+ @defopt minibuffer-auto-raise
+ If this is address@hidden, activation of the minibuffer raises the frame
+ that the minibuffer window is in.
+ @end defopt
+ 
+ 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}.
+ 
+ @node Frame Configurations
+ @section Frame Configurations
+ @cindex frame configuration
+ 
+   A @dfn{frame configuration} records the current arrangement of frames,
+ all their properties, and the window configuration of each one.
+ (@xref{Window Configurations}.)
+ 
+ @defun current-frame-configuration
+ This function returns a frame configuration list that describes
+ the current arrangement of frames and their contents.
+ @end defun
+ 
+ @defun set-frame-configuration configuration &optional nodelete
+ This function restores the state of frames described in
+ @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 address@hidden, the
+ unwanted frames are iconified instead.
+ @end defun
+ 
+ @node Mouse Tracking
+ @section Mouse Tracking
+ @cindex mouse tracking
+ @cindex tracking the mouse
+ 
+ Sometimes it is useful to @dfn{track} the mouse, which means to display
+ something to indicate where the mouse is and move the indicator as the
+ mouse moves.  For efficient mouse tracking, you need a way to wait until
+ the mouse actually moves.
+ 
+ The convenient way to track the mouse is to ask for events to represent
+ mouse motion.  Then you can wait for motion by waiting for an event.  In
+ addition, you can easily handle any other sorts of events that may
+ occur.  That is useful, because normally you don't want to track the
+ mouse forever---only until some other event, such as the release of a
+ button.
+ 
+ @defspec track-mouse address@hidden
+ This special form executes @var{body}, with generation of mouse motion
+ events enabled.  Typically @var{body} would use @code{read-event} to
+ read the motion events and modify the display accordingly.  @xref{Motion
+ Events}, for the format of mouse motion events.
+ 
+ The value of @code{track-mouse} is that of the last form in @var{body}.
+ You should design @var{body} to return when it sees the up-event that
+ indicates the release of the button, or whatever kind of event means
+ it is time to stop tracking.
+ @end defspec
+ 
+ The usual purpose of tracking mouse motion is to indicate on the screen
+ the consequences of pushing or releasing a button at the current
+ position.
+ 
+ In many cases, you can avoid the need to track the mouse by using
+ the @code{mouse-face} text property (@pxref{Special Properties}).
+ That works at a much lower level and runs more smoothly than
+ Lisp-level mouse tracking.
+ 
+ @ignore
+ @c These are not implemented yet.
+ 
+ These functions change the screen appearance instantaneously.  The
+ effect is transient, only until the next ordinary Emacs redisplay.  That
+ is OK for mouse tracking, since it doesn't make sense for mouse tracking
+ to change the text, and the body of @code{track-mouse} normally reads
+ the events itself and does not do redisplay.
+ 
+ @defun x-contour-region window beg end
+ This function draws lines to make a box around the text from @var{beg}
+ to @var{end}, in window @var{window}.
+ @end defun
+ 
+ @defun x-uncontour-region window beg end
+ This function erases the lines that would make a box around the text
+ from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
+ a contour that you previously made by calling @code{x-contour-region}.
+ @end defun
+ 
+ @defun x-draw-rectangle frame left top right bottom
+ This function draws a hollow rectangle on frame @var{frame} with the
+ specified edge coordinates, all measured in pixels from the inside top
+ left corner.  It uses the cursor color, the one used for indicating the
+ location of point.
+ @end defun
+ 
+ @defun x-erase-rectangle frame left top right bottom
+ This function erases a hollow rectangle on frame @var{frame} with the
+ specified edge coordinates, all measured in pixels from the inside top
+ left corner.  Erasure means redrawing the text and background that
+ normally belong in the specified rectangle.
+ @end defun
+ @end ignore
+ 
+ @node Mouse Position
+ @section Mouse Position
+ @cindex mouse position
+ @cindex position of mouse
+ 
+   The functions @code{mouse-position} and @code{set-mouse-position}
+ give access to the current position of the mouse.
+ 
+ @defun mouse-position
+ This function returns a description of the position of the mouse.  The
+ value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
+ and @var{y} are integers giving the position in characters relative to
+ the top left corner of the inside of @var{frame}.
+ @end defun
+ 
+ @defvar mouse-position-function
+ If address@hidden, 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,
+ giving the position in characters relative to the top left corner of the
+ inside of @var{frame}.  If @var{frame} is not visible, this function
+ does nothing.  The return value is not significant.
+ @end defun
+ 
+ @defun mouse-pixel-position
+ This function is like @code{mouse-position} except that it returns
+ coordinates in units of pixels rather than units of characters.
+ @end defun
+ 
+ @defun set-mouse-pixel-position frame x y
+ This function warps the mouse like @code{set-mouse-position} except that
+ @var{x} and @var{y} are in units of pixels rather than units of
+ characters.  These coordinates are not required to be within the frame.
+ 
+ If @var{frame} is not visible, this function does nothing.  The return
+ value is not significant.
+ @end defun
+ 
+ @need 3000
+ 
+ @node Pop-Up Menus
+ @section Pop-Up Menus
+ 
+   When using a window system, a Lisp program can pop up a menu so that
+ the user can choose an alternative with the mouse.
+ 
+ @defun x-popup-menu position menu
+ This function displays a pop-up menu and returns an indication of
+ 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:
+ 
+ @example
+ ((@var{xoffset} @var{yoffset}) @var{window})
+ @end example
+ 
+ @noindent
+ where @var{xoffset} and @var{yoffset} are coordinates, measured in
+ pixels, counting from the top left corner of @var{window}'s 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
+ key binding equivalents for the keymaps specified in @var{menu},
+ 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:
+ 
+ @example
+ (@var{title} @var{pane1} @var{pane2}...)
+ @end example
+ 
+ @noindent
+ where each pane is a list of form
+ 
+ @example
+ (@var{title} (@var{line} . @var{item})...)
+ @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.
+ @end defun
+ 
+   @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
+ if you could do the job with a prefix key defined with a menu keymap.
+ If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
+ a} can see the individual items in that menu and provide help for them.
+ If instead you implement the menu by defining a command that calls
+ @code{x-popup-menu}, the help facilities cannot know what happens inside
+ that command, so they cannot give any help for the menu's items.
+ 
+   The menu bar mechanism, which lets you switch between submenus by
+ moving the mouse, cannot look within the definition of a command to see
+ that it calls @code{x-popup-menu}.  Therefore, if you try to implement a
+ 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},
+ 
+   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 hook function to @code{menu-bar-update-hook} to update the contents of
+ the menu keymap as necessary.
+ 
+ @node Dialog Boxes
+ @section Dialog Boxes
+ @cindex dialog boxes
+ 
+   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
+ 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:
+ 
+ @example
+ (@var{title} (@var{string} . @var{value})@dots{})
+ @end example
+ 
+ @noindent
+ which looks like the list that specifies a single pane for
+ @code{x-popup-menu}.
+ 
+ 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.
+ 
+ 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
+ left, and items that follow the @code{nil} appear on the right.  If you
+ don't include a @code{nil} in the list, then approximately half the
+ items appear on each side.
+ 
+ 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.
+ 
+ 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.
+ @end defun
+ 
+ @node Pointer Shapes
+ @section Pointer Shapes
+ @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:
+ 
+ @table @code
+ @item x-pointer-shape
+ @vindex x-pointer-shape
+ This variable specifies the pointer shape to use ordinarily in the Emacs
+ frame.
+ 
+ @item x-sensitive-text-pointer-shape
+ @vindex x-sensitive-text-pointer-shape
+ This variable specifies the pointer shape to use when the mouse
+ is over mouse-sensitive text.
+ @end table
+ 
+   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}.
+ 
+   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
+ @key{RET} x-pointer @key{RET}} to see a list of them.
+ 
+ @node Window System Selections
+ @section Window System Selections
+ @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
+ distinguished by @dfn{selection types}, represented in Emacs by
+ symbols.  X clients including Emacs can read or set the selection for
+ any given type.
+ 
+ @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
+ selection.  Otherwise, @var{data} may be a string, a symbol, an integer
+ (or a cons of two integers or list of two integers), an overlay, or a
+ cons of two markers pointing to the same buffer.  An overlay or a pair
+ of markers stands for text in the overlay or between the markers.
+ 
+ The argument @var{data} may also be a vector of valid non-vector
+ selection values.
+ 
+ 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.  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
+ clients.  It takes two optional arguments, @var{type} and
+ @var{data-type}.  The default for @var{type}, the selection type, is
+ @code{PRIMARY}.
+ 
+ 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}.
+ @end defun
+ 
+ @cindex cut buffer
+ The X server also has a set of eight numbered @dfn{cut buffers} which can
+ store text or other data being moved between applications.  Cut buffers
+ are considered obsolete, but Emacs supports them for the sake of X
+ clients that still use them.  Cut buffers are numbered from 0 to 7.
+ 
+ @defun x-get-cut-buffer &optional n
+ This function returns the contents of cut buffer number @var{n}.
+ If omitted @var{n} defaults to 0.
+ @end defun
+ 
+ @defun x-set-cut-buffer string &optional push
+ @anchor{Definition of x-set-cut-buffer}
+ This function stores @var{string} into the first cut buffer (cut buffer
+ 0).  If @var{push} is @code{nil}, only the first cut buffer is changed.
+ If @var{push} is address@hidden, that says to move the values down
+ through the series of cut buffers, much like the way successive kills in
+ Emacs move down the kill ring.  In other words, the previous value of
+ the first cut buffer moves into the second cut buffer, and the second to
+ the third, and so on through all eight cut buffers.
+ @end defun
+ 
+ @defvar selection-coding-system
+ 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-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 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.
+ 
+ @defopt x-select-enable-clipboard
+ If this is address@hidden, 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.
+ @end defopt
+ 
+ @node Color Names
+ @section Color Names
+ 
+   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''.
+ 
+ @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
+ @code{nil}, the selected frame is used.
+ 
+ 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 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
+ 
+ @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},
+ 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 address@hidden, 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.  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
+ This function returns a value that describes what @var{color} should
+ 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 kind of three-element list is called an @dfn{rgb value}.
+ 
+ If @var{color} is not defined, the value is @code{nil}.
+ 
+ @example
+ (color-values "black")
+      @result{} (0 0 0)
+ (color-values "white")
+      @result{} (65280 65280 65280)
+ (color-values "red")
+      @result{} (65280 0 0)
+ (color-values "pink")
+      @result{} (65280 49152 51968)
+ (color-values "hungry")
+      @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.
+ 
+ @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
+ 
+ @node Text Terminal Colors
+ @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.
+ 
+   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 some displays may not use the full range.  .
+ 
+   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.
+ 
+ @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.
+ 
+ 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.
+ @end defun
+ 
+ @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
+ 
+ @defun tty-color-alist &optional display
+ @tindex tty-color-alist
+ 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 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}.
+ The return value is an element of @code{tty-color-alist}.
+ @end defun
+ 
+ @defun tty-color-translate color &optional display
+ @tindex tty-color-translate
+ This function finds the closest color to @var{color} among the known
+ colors supported for @var{display} and returns its index (an integer).
+ If the name @var{color} is not defined, the value is @code{nil}.
+ 
+ @var{color} can be an X-style @code{"address@hidden"} specification
+ instead of an actual name.  The format
+ @code{"RGB:@var{xx}/@var{yy}/@var{zz}"} is also supported.
+ @end defun
+ 
+ @node Resources
+ @section X Resources
+ 
+ @defun x-get-resource attribute class &optional component subclass
+ The function @code{x-get-resource} retrieves a resource value from the X
+ Window defaults database.
+ 
+ Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
+ This function searches using a key of the form
+ @address@hidden@var{attribute}} (where @var{instance} is the name
+ under which Emacs was invoked), and using @address@hidden as
+ the class.
+ 
+ The optional arguments @var{component} and @var{subclass} add to the key
+ and the class, respectively.  You must specify both of them or neither.
+ If you specify them, the key is
+ @address@hidden@address@hidden, and the class is
+ @address@hidden@var{subclass}}.
+ @end defun
+ 
+ @defvar x-resource-class
+ This variable specifies the application name that @code{x-get-resource}
+ should look up.  The default value is @code{"Emacs"}.  You can examine X
+ resources for application names other than ``Emacs'' by binding this
+ variable to some other string, around a call to @code{x-get-resource}.
+ @end defvar
+ 
+ @defvar x-resource-name
+ This variable specifies the instance name that @code{x-get-resource}
+ should look up.  The default value is the name Emacs was invoked with,
+ or the value specified with the @samp{-name} or @samp{-rn} switches.
+ @end defvar
+ 
+ To illustrate some of the above, suppose that you have the line:
+ 
+ @example
+ xterm.vt100.background: yellow
+ @end example
+ 
+ @noindent
+ in in your X resources file (usually named @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
+ @section Display Feature Testing
+ @cindex display feature testing
+ 
+   The functions in this section describe the basic capabilities of a
+ particular display.  Lisp programs can use them to adapt their behavior
+ to what the display can do.  For example, a program that ordinarily uses
+ a popup menu could use the minibuffer if popup menus are not supported.
+ 
+   The optional argument @var{display} in these functions specifies which
+ 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, @pxref{Input Focus}).
+ 
+   @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 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 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
+ 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-supports-face-attributes-p attributes &optional display
+ @anchor{Display Face Attribute Testing}
+ @tindex display-supports-face-attributes-p
+ This function returns address@hidden 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.
+ Windowed displays normally support selections, but they may also be
+ 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.
+ @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-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.
+ On a character terminal, it gives the width in characters.
+ @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
+ 
+ @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}.  The function can also return @code{nil}
+ when the question is inapplicable to a certain kind of display.
+ @end defun
+ 
+ @defun display-save-under &optional display
+ @tindex display-save-under
+ This function returns address@hidden 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
+ quickly.
+ @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.
+ @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
+ @code{direct-color}.
+ @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
+ 
+   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.  The value is a list of three integers: the major
+ and minor version numbers, and the vendor-specific release number.
+ @end defun
+ 
+ @defun x-server-vendor &optional display
+ This function returns the ``vendor'' that provided the X server software
+ (as a string).
+ @end defun
+ 
+ @ignore
+ @defvar x-no-window-manager
+ This variable's value is @code{t} if no X window manager is in use.
+ @end defvar
+ @end ignore
+ 
+ @ignore
+ @item
+ The functions @code{x-pixel-width} and @code{x-pixel-height} return the
+ width and height of an X Window frame, measured in pixels.
+ @end ignore
+ 
+ @ignore
+    arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
+ @end ignore