@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@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
- 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
+ A @dfn{frame} is a screen object that contains one or more Emacs
+windows (@pxref{Windows}). It is the kind of object 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.
+way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that
+represents a frame on the screen. @xref{Frame Type}.
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.
+into smaller windows. @xref{Splitting 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 terminal
+ A @dfn{terminal} is a display device capable of displaying one or
+more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp
+object that represents a terminal. @xref{Terminal Type}.
+@cindex terminal frame
@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.
+ There are two classes of terminals: text-only terminals and
+graphical terminals. Text-only terminals are non-graphics-capable
+display devices, including ``terminal emulators'' such as xterm. On
+text-only terminals, each frame occupies the entire terminal screen;
+although you can create additional frames and switch between them,
+only one frame can be shown at any given time. We refer to frames on
+text-only terminals as @dfn{terminal frames}. Graphical terminals, on
+the other hand, are graphics-capable windowing systems, such as the X
+Window System. On a graphical terminal, Emacs can display multiple
+frames simultaneously. We refer to such frames as @dfn{window
+frames}.
+
+ On GNU and Unix systems, you can create additional frames on any
+available terminal, within a single Emacs session, regardless of
+whether Emacs was started on a text-only or graphical terminal. Emacs
+can display on both graphical and text-only terminals simultaneously.
+This comes in handy, for instance, when you connect to the same
+session from several remote locations. @xref{Multiple Terminals}.
@defun framep object
This predicate returns a non-@code{nil} value if @var{object} is a
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 ns
+The frame is displayed on a GNUstep or Macintosh Cocoa display.
@item pc
The frame is displayed on an MS-DOS terminal.
@end table
@end defun
+@defun frame-terminal &optional frame
+This function returns the terminal object that displays @var{frame}.
+If @var{frame} is @code{nil} or unspecified, it defaults to the
+selected frame.
+@end defun
+
+@defun terminal-live-p object
+This predicate returns a non-@code{nil} value if @var{object} is a
+terminal that is alive (i.e.@: was not deleted), and @code{nil}
+otherwise. For live terminals, the return value indicates what kind
+of frames are displayed on that terminal; the list of possible values
+is the same as for @code{framep} above.
+@end defun
+
@menu
-* Creating Frames:: Creating additional frames.
-* Multiple Displays:: Creating frames on other displays.
-* Frame Parameters:: Controlling frame size, position, font, etc.
+* Creating Frames:: Creating additional frames.
+* Multiple Terminals:: Displaying on several different devices.
+* Frame Parameters:: Controlling frame size, position, font, etc.
+* Terminal Parameters:: Parameters common for all frames on terminal.
* 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.
+* 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 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.
+* Color Names:: Getting the definitions of color names.
* Text Terminal Colors:: Defining colors for text-only terminals.
-* Resources:: Getting resource values from the server.
+* 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
@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.
+buffer.
+
+The @var{alist} argument is an alist that specifies frame parameters
+for the new frame. @xref{Frame Parameters}. If you specify the
+@code{terminal} parameter in @var{alist}, the new frame is created on
+that terminal. Otherwise, if you specify the @code{window-system}
+frame parameter in @var{alist}, that determines whether the frame
+should be displayed on a text-only or graphical terminal.
+@xref{Window Systems}. If neither is specified, the new frame is
+created in the same terminal as the selected frame.
+
+Any parameters not mentioned in @var{alist} default to the values in
+the alist @code{default-frame-alist} (@pxref{Initial Parameters});
+parameters not specified there default from the X resources or its
+equivalent on your operating system (@pxref{X Resources,, X Resources,
+emacs, The GNU Emacs Manual}). After the frame is created, Emacs
+applies any parameters listed in @code{frame-inherited-parameters}
+(see below) and not present in the argument, taking the values from
+the frame that was selected when @code{make-frame} was called.
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.
+On graphical terminals, however, the windowing system may select the
+new frame for its own reasons.
@end defun
@defvar before-make-frame-hook
-A normal hook run by @code{make-frame} before it actually creates the
-frame.
+A normal hook run by @code{make-frame} before it creates the frame.
@end defvar
@defvar after-make-frame-functions
frame just created.
@end defvar
-@node Multiple Displays
-@section Multiple Displays
+@defvar frame-inherited-parameters
+This variable specifies the list of frame parameters that a newly
+created frame inherits from the currently selected frame. For each
+parameter (a symbol) that is an element in the list and is not present
+in the argument to @code{make-frame}, the function sets the value of
+that parameter in the created frame to its value in the selected
+frame.
+@end defvar
+
+@node Multiple Terminals
+@section Multiple Terminals
+@cindex multiple terminals
+@cindex multi-tty
@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 represents each terminal, whether graphical or text-only, as a
+@dfn{terminal object} data type (@pxref{Terminal Type}). On GNU and
+Unix systems, Emacs can use multiple terminals simultaneously in each
+session. On other systems, it can only use a single terminal. Each
+terminal object has the following attributes:
+
+@itemize @bullet
+@item
+The name of the device used by the terminal (e.g., @samp{:0.0} or
+@file{/dev/tty}).
+
+@item
+The terminal and keyboard coding systems used on the terminal.
+@xref{Terminal I/O Encoding}.
+
+@item
+The kind of display associated with the terminal. This is the symbol
+returned by the function @code{terminal-live-p} (i.e., @code{x},
+@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.
+
+@item
+A list of terminal parameters. @xref{Terminal Parameters}.
+@end itemize
+
+ There is no primitive for creating terminal objects. Emacs creates
+them as needed, such as when you call @code{make-frame-on-display}
+(which is described below).
+
+@defun terminal-name &optional terminal
+This function returns the file name of the device used by
+@var{terminal}. If @var{terminal} is omitted or @code{nil}, it
+defaults to the selected frame's terminal. @var{terminal} can also be
+a frame, meaning that frame's terminal.
+@end defun
+
+@defun terminal-list
+This function returns a list of all terminal objects currently in use.
+@end defun
+
+@defun get-device-terminal device
+This function returns a terminal whose device name is given by
+@var{device}. If @var{device} is a string, it can be either the file
+name of a terminal device, or the name of an X display of the form
+@samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a
+frame, this function returns that frame's terminal; @code{nil} means
+the selected frame. Finally, if @var{device} is a terminal object
+that represents a live terminal, that terminal is returned. The
+function signals an error if its argument is none of the above.
+@end defun
- 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 ``@emph{the} selected frame'' at any given moment, see
-@ref{Input Focus}.
+@defun delete-terminal &optional terminal force
+This function deletes all frames on @var{terminal} and frees the
+resources used by it. It runs the abnormal hook
+@code{delete-terminal-functions}, passing @var{terminal} as the
+argument to each function.
+
+If @var{terminal} is omitted or @code{nil}, it defaults to the
+selected frame's terminal. @var{terminal} can also be a frame,
+meaning that frame's terminal.
+
+Normally, this function signals an error if you attempt to delete the
+sole active terminal, but if @var{force} is non-@code{nil}, you are
+allowed to do so. Emacs automatically calls this function when the
+last frame on a terminal is deleted (@pxref{Deleting Frames}).
+@end defun
+@defvar delete-terminal-functions
+An abnormal hook run by @code{delete-terminal}. Each function
+receives one argument, the @var{terminal} argument passed to
+@code{delete-terminal}. Due to technical details, the functions may
+be called either just before the terminal is deleted, or just
+afterwards.
+@end defvar
+
+@cindex terminal-local variables
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}).
-
- A single X server can handle more than one screen. A display name
-@samp{@var{host}:@var{server}.@var{screen}} 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.
-
- Note that some graphical terminals can output to more than a one
-monitor (or other output device) at the same time. On these
-``multi-monitor'' setups, a single @var{display} value controls the
-output to all the physical monitors. In this situation, there is
-currently no platform-independent way for Emacs to distinguish between
-the different physical monitors.
+@code{system-key-alist}. They are always terminal-local, and can
+never be buffer-local (@pxref{Buffer-Local Variables}).
+
+ On GNU and Unix systems, each X display is a separate graphical
+terminal. When Emacs is started from within the X window system, it
+uses the X display chosen with the @code{DISPLAY} environment
+variable, or with the @samp{--display} option. @xref{Initial
+Options,,, emacs, The GNU Emacs Manual}. Emacs can connect to other X
+displays via the command @code{make-frame-on-display}. Each X display
+has its own selected frame and its own minibuffer windows; however,
+only one of those frames is ``@emph{the} selected frame'' at any given
+moment (@pxref{Input Focus}). Emacs can even connect to other
+text-only terminals, by interacting with the @command{emacsclient}
+program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
+
+ A single X server can handle more than one display. Each X display
+has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
+The first two parts, @var{host} and @var{server}, identify the X
+server; the third part, @var{screen}, identifies a screen number on
+that X server. When you use two or more screens belonging to one
+server, Emacs knows by the similarity in their names that they share a
+single keyboard.
+
+ On some ``multi-monitor'' setups, a single X display outputs to more
+than one monitor. Currently, there is no way for Emacs to distinguish
+between the different physical monitors.
@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}).
+This function creates and returns a new frame on @var{display}, taking
+the other frame parameters from the alist @var{parameters}.
+@var{display} should be the name of an X display (a string).
+
+Before creating the frame, this function ensures that Emacs is ``set
+up'' to display graphics. For instance, if Emacs has not processed X
+resources (e.g., if it was started on a text-only terminal), it does
+so at this time. In all other respects, this function behaves 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.
+This function 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:
+This function opens a connection to the X display @var{display},
+without creating a frame on that display. Normally, Emacs Lisp
+programs need not call this function, as @code{make-frame-on-display}
+calls it automatically. The only reason for calling it is to check
+whether communication can be established with a given X 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. @xref{X Resources,, X Resources, emacs, The
+GNU Emacs Manual}. These values apply to all Emacs frames created on
+this display, overriding the resource values recorded in the X server.
+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 non-@code{nil}, 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}).
+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
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.
+If the terminal supports frame transparency, the parameter
+@code{alpha} is also meaningful.
+
+ You can use frame parameters to define frame-local bindings for
+variables. @xref{Frame-Local Variables}.
@menu
* Parameter Access:: How to change a frame's parameters.
-* Initial Parameters:: Specifying frame parameters when you make a frame.
+* 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.
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.
+
+You can use this function to define frame-local bindings for
+variables, see @ref{Frame-Local Variables}.
+@end defun
+
+@defun set-frame-parameter frame parm value
+This function sets the frame parameter @var{parm} to the specified
+@var{value}. If @var{frame} is @code{nil}, it defaults to the
+selected frame.
@end defun
@defun modify-all-frames-parameters alist
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
+@defopt 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.
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
+@end defopt
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
+@defopt minibuffer-frame-alist
+This variable's value is an alist of parameter values used when
+creating an initial minibuffer-only frame. This is the
+minibuffer-only frame that Emacs creates if @code{initial-frame-alist}
+specifies a frame with no minibuffer.
+@end defopt
-@defvar default-frame-alist
+@defopt 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
+@end defopt
-See also @code{special-display-frame-alist}. @xref{Definition of
-special-display-frame-alist}.
+Functions that display a buffer in a separate frame can override the
+default parameters by supplying their own parameters. @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
@node Window Frame Parameters
@subsection Window Frame Parameters
+@cindex frame parameters for windowed displays
Just what parameters a frame has depends on what display mechanism
it uses. This section describes the parameters that have special
* 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.
+* Font and Color Parameters:: Fonts and colors for the frame text.
@end menu
@node Basic Parameters
frame. @code{title} and @code{name} are meaningful on all terminals.
@table @code
+@vindex display, a frame parameter
@item display
The display on which to open this frame. It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@code{DISPLAY} environment variable.
+@vindex display-type, a frame parameter
@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}.
+@vindex title, a frame parameter
@item title
If a frame has a non-@code{nil} title, it appears in the window
system's title bar at the top of the frame, and also in the mode line
Emacs is not using a window system, and can only display one frame at
a time. @xref{Frame Titles}.
+@vindex name, a frame parameter
@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
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 display-environment-variable
-The value of the @code{DISPLAY} environment variable for the frame. It
-is passed to child processes.
-
-@item term-environment-variable
-The value of the @code{TERM} environment variable for the frame. It
-is passed to child processes.
@end table
@node Position Parameters
@subsubsection Position Parameters
+@cindex window position on display
Position parameters' values are normally measured in pixels, but on
text-only terminals they count characters or lines instead.
@table @code
+@vindex left, a frame parameter
@item left
The position, in pixels, of the left (or right) edge of the frame with
respect to the left (or right) edge of the screen. The value may be:
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.
+@vindex top, a frame parameter
@item top
The screen position of the top (or bottom) edge, in pixels, with respect
to the top (or bottom) edge of the screen. It works just like
@code{left}, except vertically instead of horizontally.
+@vindex icon-left, a frame parameter
@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
a value for @code{icon-top} and vice versa. The window manager may
ignore these two parameters.
+@vindex icon-top, a frame parameter
@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.
+@vindex user-position, a frame parameter
@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
way by a human user) or merely program-specified (chosen by a program).
A non-@code{nil} value says the position was user-specified.
+@cindex window positions and window managers
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
@node Size Parameters
@subsubsection Size Parameters
+@cindex window size on display
Size parameters' values are normally measured in pixels, but on
text-only terminals they count characters or lines instead.
@table @code
+@vindex height, a frame parameter
@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}.)
+@vindex width, a frame parameter
@item width
The width of the frame contents, in characters. (To get the width in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
+@vindex user-size, a frame parameter
@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}.
+the @code{user-position} parameter (@pxref{Position Parameters,
+user-position}) does for the position parameters @code{top} and
+@code{left}.
+@cindex full-screen frames
+@vindex fullscreen, a frame parameter
@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.
+Specify that width, height or both shall be maximized. The value
+@code{fullwidth} specifies that width shall be as wide as possible.
+The value @code{fullheight} specifies that height shall be as tall as
+possible. The value @code{fullboth} specifies that both the width and
+the height shall be set to the size of the screen. The value
+@code{maximized} specifies that the frame shall be maximized. The
+difference between @code{maximized} and @code{fullboth} is that the
+former still has window manager decorations while the latter really
+covers the whole screen.
@end table
@node Layout Parameters
@subsubsection Layout Parameters
+@cindex layout parameters of frames
+@cindex frame layout parameters
These frame parameters enable or disable various parts of the
frame, or control their sizes.
@table @code
+@vindex border-width, a frame parameter
@item border-width
The width in pixels of the frame's border.
+@vindex internal-border-width, a frame parameter
@item internal-border-width
The distance in pixels between text (or fringe) and the frame's border.
+@vindex vertical-scroll-bars, a frame parameter
@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
+@vindex horizontal-scroll-bars, a frame parameter
@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
+@vindex scroll-bar-width, a frame parameter
@item scroll-bar-width
The width of vertical scroll bars, in pixels, or @code{nil} meaning to
use the default width.
+@vindex left-fringe, a frame parameter
+@vindex right-fringe, a frame parameter
@item left-fringe
@itemx right-fringe
The default width of the left and right fringes of windows in this
width by specifying that width as a negative integer. If both widths are
negative, only the left fringe gets the specified width.
+@vindex menu-bar-lines, a frame parameter
@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.)
+@vindex tool-bar-lines, a frame parameter
@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.)
+means don't display a tool bar. (GTK and Nextstep allow at most one
+tool bar line; they treat larger values as 1.)
+
+@vindex tool-bar-position, a frame parameter
+@item tool-bar-position
+The position of the tool bar. Currently only for the GTK tool bar.
+Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
+The default is @code{top}.
+@vindex line-spacing, a frame parameter
@item line-spacing
Additional space to leave below each text line, in pixels (a positive
integer). @xref{Line Height}, for more information.
with which buffers have been, or should, be displayed in the frame.
@table @code
+@vindex minibuffer, a frame parameter
@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.
+minibuffer. If the value is a minibuffer window (in some other
+frame), the frame uses that minibuffer.
+This frame parameter takes effect when the frame is created, and can
+not be changed afterwards.
+
+@vindex buffer-predicate, a frame parameter
@item buffer-predicate
The buffer-predicate function for this frame. The function
@code{other-buffer} uses this predicate (from the selected frame) to
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.
+@vindex buffer-list, a frame parameter
@item buffer-list
-A list of buffers that have been selected in this frame,
-ordered most-recently-selected first.
+A list of buffers that have been selected in this frame, ordered
+most-recently-selected first.
+@vindex unsplittable, a frame parameter
@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.
@end table
@node Management Parameters
@subsubsection Window Management Parameters
-@cindex window manager, and frame parameters
+@cindex window manager interaction, and frame parameters
These frame parameters, meaningful only on window system displays,
interact with the window manager.
@table @code
+@vindex visibility, a frame parameter
@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}.
+@vindex auto-raise, a frame parameter
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
+@vindex auto-lower, a frame parameter
@item auto-lower
Whether deselecting the frame lowers it (non-@code{nil} means yes).
+@vindex icon-type, a frame parameter
@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 non-@code{nil} value specifies the default bitmap icon (a
picture of a gnu); @code{nil} specifies a text icon.
+@vindex icon-name, a frame parameter
@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.
+@vindex window-id, a frame parameter
@item window-id
The number of the window-system window used by the frame
to contain the actual Emacs windows.
+@vindex outer-window-id, a frame parameter
@item outer-window-id
The number of the outermost window-system window used for the whole frame.
+@vindex wait-for-wm, a frame parameter
@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.
+@vindex sticky, a frame parameter
+@item sticky
+If non-@code{nil}, the frame is visible on all virtual desktops on systems
+with virtual desktops.
+
@ignore
+@vindex parent-id, a frame parameter
@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
@node Cursor Parameters
@subsubsection Cursor Parameters
+@cindex cursor, and frame parameters
This frame parameter controls the way the cursor looks.
@table @code
+@vindex cursor-type, a frame parameter
@item cursor-type
How to display the cursor. Legitimate values are:
the @code{cursor-type} frame parameter, but if it is @code{t}, that
means to use the cursor specified for the frame.
-@defvar blink-cursor-alist
+@defopt 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
the type is not mentioned as an @var{on-state} here. Changes in this
variable do not take effect immediately, only when you specify the
@code{cursor-type} frame parameter.
-@end defvar
+@end defopt
-@defvar cursor-in-non-selected-windows
+@defopt cursor-in-non-selected-windows
This variable controls how the cursor looks in a window that is not
selected. It supports the same values as the @code{cursor-type} frame
parameter; also, @code{nil} means don't display a cursor in
nonselected windows, and @code{t} (the default) means use a standard
-modificatoin of the usual cursor type (solid box becomes hollow box,
+modification of the usual cursor type (solid box becomes hollow box,
and bar becomes a narrower bar).
-@end defvar
+@end defopt
-@node Color Parameters
-@subsubsection Color Parameters
+@node Font and Color Parameters
+@subsubsection Font and Color Parameters
+@cindex font and color, frame parameters
- These frame parameters control the use of colors.
+ These frame parameters control the use of fonts and colors.
@table @code
+@vindex font-backend, a frame parameter
+@item font-backend
+A list of symbols, specifying the @dfn{font backends} to use for
+drawing fonts in the frame, in order of priority. On X, there are
+currently two available font backends: @code{x} (the X core font
+driver) and @code{xft} (the Xft font driver). On other systems, there
+is only one available font backend, so it does not make sense to
+modify this frame parameter.
+
+@vindex background-mode, a frame parameter
@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.
+@vindex tty-color-mode, a frame parameter
@item tty-color-mode
@cindex standard colors for character terminals
This parameter overrides the terminal's color support as given by the
the value of @code{tty-color-mode-alist}, and the associated number is
used instead.
+@vindex screen-gamma, a frame parameter
@item screen-gamma
@cindex gamma correction
If this is a number, Emacs performs ``gamma correction'' which adjusts
@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.
+
+@vindex alpha, a frame parameter
+@item alpha
+@cindex opacity, frame
+@cindex transparency, frame
+@vindex frame-alpha-lower-limit
+This parameter specifies the opacity of the frame, on graphical
+displays that support variable opacity. It should be an integer
+between 0 and 100, where 0 means completely transparent and 100 means
+completely opaque. It can also have a @code{nil} value, which tells
+Emacs not to set the frame opacity (leaving it to the window manager).
+
+To prevent the frame from disappearing completely from view, the
+variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
+If the value of the frame parameter is less than the value of this
+variable, Emacs uses the latter. By default,
+@code{frame-alpha-lower-limit} is 20.
+
+The @code{alpha} frame parameter can also be a cons cell
+@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
+opacity of the frame when it is selected, and @samp{inactive} is the
+opactity when it is not selected.
@end table
-These frame parameters are semi-obsolete in that they are automatically
-equivalent to particular face attributes of particular faces.
-@xref{Standard Faces,,, emacs, The Emacs Manual}.
+The following frame parameters are semi-obsolete in that they are
+automatically equivalent to particular face attributes of particular
+faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
@table @code
+@vindex font, a frame parameter
@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.
+@vindex foreground-color, a frame parameter
@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.
+@vindex background-color, a frame parameter
@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.
+@vindex mouse-color, a frame parameter
@item mouse-color
The color for the mouse pointer. It is equivalent to the @code{:background}
attribute of the @code{mouse} face.
+@vindex cursor-color, a frame parameter
@item cursor-color
The color for the cursor that shows point. It is equivalent to the
@code{:background} attribute of the @code{cursor} face.
+@vindex border-color, a frame parameter
@item border-color
The color for the border of the frame. It is equivalent to the
@code{:background} attribute of the @code{border} face.
+@vindex scroll-bar-foreground, a frame parameter
@item scroll-bar-foreground
If non-@code{nil}, the color for the foreground of scroll bars. It is
equivalent to the @code{:foreground} attribute of the
@code{scroll-bar} face.
+@vindex scroll-bar-background, a frame parameter
@item scroll-bar-background
If non-@code{nil}, the color for the background of scroll bars. It is
equivalent to the @code{:background} attribute of the
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 the main display area
of @var{frame}, measured in pixels. If you don't supply @var{frame},
-they use the selected frame.
+they use the selected frame. For a text-only terminal, the results are
+in characters rather than pixels.
-These values include the internal borders, and windows' scroll bars
-and fringes (which belong to individual windows, not to the frame
-itself), but do not include menu bars or tool bars (except when using
-X without an X toolkit).
+These values include the internal borders, and windows' scroll bars and
+fringes (which belong to individual windows, not to the frame itself).
+The exact value of the heights depends on the window-system and toolkit
+in use. With Gtk+, the height does not include any tool bar or menu
+bar. With the Motif or Lucid toolkits, it includes the tool bar but
+not the menu bar. In a graphical version with no toolkit, it includes
+both the tool bar and menu bar. For a text-only terminal, the result
+includes the menu bar.
@end defun
@defun frame-char-height &optional frame
@end example
@end defun
+@node Terminal Parameters
+@section Terminal Parameters
+@cindex terminal parameters
+
+ Each terminal has a list of associated parameters. These
+@dfn{terminal parameters} are mostly a convenient way of storage for
+terminal-local variables, but some terminal parameters have a special
+meaning.
+
+ This section describes functions to read and change the parameter values
+of a terminal. They all accept as their argument either a terminal or
+a frame; the latter means use that frame's terminal. An argument of
+@code{nil} means the selected frame's terminal.
+
+@defun terminal-parameters &optional terminal
+This function returns an alist listing all the parameters of
+@var{terminal} and their values.
+@end defun
+
+@defun terminal-parameter terminal parameter
+This function returns the value of the parameter @var{parameter} (a
+symbol) of @var{terminal}. If @var{terminal} has no setting for
+@var{parameter}, this function returns @code{nil}.
+@end defun
+
+@defun set-terminal-parameter terminal parameter value
+This function sets the parameter @var{parm} of @var{terminal} to the
+specified @var{value}, and returns the previous value of that
+parameter.
+@end defun
+
+Here's a list of a few terminal parameters that have a special
+meaning:
+
+@table @code
+@item background-mode
+The classification of the terminal's background color, either
+@code{light} or @code{dark}.
+@item normal-erase-is-backspace
+Value is either 1 or 0, depending on whether
+@code{normal-erase-is-backspace-mode} is turned on or off on this
+terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
+@item terminal-initted
+After the terminal is initialized, this is set to the
+terminal-specific initialization function.
+@end table
+
@node Frame Titles
@section Frame Titles
@cindex frame title
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 non-@code{nil}, then you are allowed to do so.
+but if @var{force} is non-@code{nil}, then you are allowed to do so.
@end deffn
@defun frame-live-p frame
@cindex frames, scanning all
@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.
+The function @code{frame-list} returns a list of all the live frames,
+i.e.@: those 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
@node Frames and Windows
@section Frames and Windows
- Each window is part of one and only one frame; you can get the frame
+ Each window is part of one and only one frame; you can get that frame
with @code{window-frame}.
@defun window-frame window
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}.
+frame also selects this window. Conversely, selecting a window for
+Emacs with @code{select-window} also makes that window selected within
+its frame. @xref{Selecting Windows}.
@defun frame-selected-window &optional frame
This function returns the window on @var{frame} that is selected
the selected frame.
@end defun
-@defun set-frame-selected-window frame window
+@defun set-frame-selected-window frame window &optional norecord
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}.
+Optional argument @var{norecord} non-@code{nil} means to neither change
+the order of recently selected windows nor the buffer list (@pxref{The
+Buffer List}).
+@end defun
Another function that (usually) returns one of the windows in a given
frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
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}.
+Terminals}.
@end defvar
@node Input Focus
window always resides on the selected frame.
When Emacs displays its frames on several terminals (@pxref{Multiple
-Displays}), each terminal has its own selected frame. But only one of
-these is ``@emph{the} selected frame'': it's the frame that belongs to
-the terminal from which the most recent input came. That is, when Emacs
-runs a command that came from a certain terminal, the selected frame is
-the one of that terminal. Since Emacs runs only a single command at any
-given time, it needs to consider only one selected frame at a time; this
-frame is what we call @dfn{the selected frame} in this manual. The
-display on which the selected frame is displayed is the @dfn{selected
-frame's display}.
+Terminals}), each terminal has its own selected frame. But only one
+of these is ``@emph{the} selected frame'': it's the frame that belongs
+to the terminal from which the most recent input came. That is, when
+Emacs runs a command that came from a certain terminal, the selected
+frame is the one of that terminal. Since Emacs runs only a single
+command at any given time, it needs to consider only one selected
+frame at a time; this frame is what we call @dfn{the selected frame}
+in this manual. The display on which the selected frame is shown is
+the @dfn{selected frame's display}.
@defun selected-frame
This function returns the selected frame.
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
+explicitly 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
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}).
+remains selected until a subsequent call to @code{select-frame}. 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.
+This function selects @var{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
+@defun select-frame frame &optional norecord
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.
+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. The window selected within @var{frame} becomes the selected
+window. This function returns @var{frame}, or @code{nil} if @var{frame}
+has been deleted.
+
+Optional argument @var{norecord} non-@code{nil} means to neither change
+the order of recently selected windows nor the buffer list. @xref{The
+Buffer List}.
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.
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. (This option has no
-effect on MS-Windows, where the mouse pointer is always automatically
-moved by the OS to the selected frame.)
+position consistent with the new selected frame.
@end defopt
@node Visibility of Frames
A window frame may be @dfn{visible}, @dfn{invisible}, or
@dfn{iconified}. If it is visible, you can see its contents, unless
other windows cover it. 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.
+not appear on the screen, but an icon does. (Note: because of the
+way in which some window managers implement the concept of multiple
+workspaces, or desktops, all frames on other workspaces may appear to
+Emacs to be iconified.) 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.
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:
+ With Emacs, frames constitute the windows in the metaphor sketched
+above. You can raise and lower frames using these functions:
@deffn Command raise-frame &optional frame
This function raises frame @var{frame} (default, the selected frame).
@defspec track-mouse body@dots{}
This special form executes @var{body}, with generation of mouse motion
-events enabled. Typically @var{body} would use @code{read-event} to
+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.
value is not significant.
@end defun
+@defun frame-pointer-visible-p &optional frame
+This predicate function returns non-@code{nil} if the mouse pointer
+displayed on @var{frame} is visible; otherwise it returns @code{nil}.
+@var{frame} omitted or @code{nil} means the selected frame. This is
+useful when @code{make-pointer-invisible} is set to @code{t}: it
+allows to know if the pointer has been hidden.
+@xref{Mouse Avoidance,,,emacs}.
+@end defun
+
@need 3000
@node Pop-Up Menus
The argument @var{menu} says what to display in the menu. It can be a
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.
+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.) On toolkits that support
+menu titles, the title is taken from the prompt string of @var{menu}
+if @var{menu} is a keymap, or from the prompt string of the first
+keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
+Menus}).
Alternatively, @var{menu} can have the following form:
pointer style.
@end defvar
- You can specify what the @code{text} pointer style really looks like
-by setting the variable @code{x-pointer-shape}.
+ When using X, you can specify what the @code{text} pointer style
+really looks like by setting the variable @code{x-pointer-shape}.
@defvar x-pointer-shape
This variable specifies the pointer shape to use ordinarily in the
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 installs the current value of those two variables.
-@xref{Color Parameters}.
+@xref{Font and 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
@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 non-@code{nil}, 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
+@defopt selection-coding-system
This variable specifies the coding system to use when reading and
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
+@end defopt
@cindex clipboard support (for MS-Windows)
When Emacs runs on MS-Windows, it does not implement X selections in
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 and Mac.
+but @code{t} on MS-Windows.
@end defopt
@node Drag and Drop
@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
meaning of the term ``selected frame.''
+ To read user input of color names with completion, use
+@code{read-color} (@pxref{High-Level Completion, read-color}).
+
@defun color-defined-p color &optional frame
This function reports whether a color name is meaningful. It returns
@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
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{frame} argument has no effect.
+terminal) as an optional argument. We hope in the future to make
+Emacs support different colors on different text-only terminals; 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{frame} argument has no effect.
@defun tty-color-define name number &optional rgb frame
This function associates the color name @var{name} with
@node Resources
@section X Resources
+This section describes some of the functions and variables for
+querying and using X resources, or their equivalent on your operating
+system. @xref{X Resources,, X Resources, emacs, The GNU Emacs
+Manual}, for more information about 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.
@end group
@end example
- @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
+@defvar inhibit-x-resources
+If this variable is non-@code{nil}, Emacs does not look up X
+resources, and X resources do not have any effect when creating new
+frames.
+@end defvar
@node Display Feature Testing
@section Display Feature Testing
For graphical terminals, note that on ``multi-monitor'' setups this
refers to the pixel width for all physical monitors associated with
-@var{display}. @xref{Multiple Displays}.
+@var{display}. @xref{Multiple Terminals}.
@end defun
@defun display-pixel-width &optional display
For graphical terminals, note that on ``multi-monitor'' setups this
refers to the pixel width for all physical monitors associated with
-@var{display}. @xref{Multiple Displays}.
+@var{display}. @xref{Multiple Terminals}.
@end defun
@defun display-mm-height &optional display
or @code{nil} if Emacs cannot get that information.
@end defun
-@defvar display-mm-dimensions-alist
+@defopt 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
+@end defopt
@defun display-backing-store &optional display
This function returns the backing store capability of the display.
width and height of an X Window frame, measured in pixels.
@end ignore
-@ignore
- arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
-@end ignore