@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 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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.
* 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
+
+@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
- 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}.
+@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.
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
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.
+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 defvar
@defvar default-frame-alist
Setting this variable does not affect existing frames.
@end defvar
-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
* 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
@code{mono}.
@item title
-If a frame has a non-@code{nil} title, it appears in the window system's
-border for the frame, and also in the mode line of windows in that frame
-if @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}.
+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
+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
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
@table @code
@item left
-The screen position of the left edge, in pixels, with respect to the
-left edge of the screen. The value may be a positive number @var{pos},
-or a list of the form @code{(+ @var{pos})} which permits specifying a
-negative @var{pos} value.
-
-A negative number @minus{}@var{pos}, or a list of the form @code{(-
-@var{pos})}, actually specifies the position of the 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 @minus{}@var{pos}, then @var{pos} is
-positive.
+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:
+
+@table @asis
+@item an integer
+A positive integer relates the left edge of the frame to the left edge
+of the screen. A negative integer relates the right frame edge to the
+right screen edge.
+
+@item @code{(+ @var{pos})}
+This specifies the position of the left frame edge relative to the left
+screen edge. The integer @var{pos} may be positive or negative; a
+negative value specifies a position outside the screen.
+
+@item @code{(- @var{pos})}
+This specifies the position of the right frame edge relative to the right
+screen edge. The integer @var{pos} may be positive or negative; a
+negative value specifies a position outside the screen.
+@end table
Some window managers ignore program-specified positions. If you want to
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.
@item top
-The screen position of the top edge, in pixels, with respect to the
-top edge of the screen. It works just like @code{left}, except vertically
-instead of horizontally.
+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.
@item icon-left
The screen position of the left edge @emph{of the frame's icon}, 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
+The width of the frame contents, in characters. (To get the width in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
@item user-size
@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.)
@item line-spacing
Additional space to leave below each text line, in pixels (a positive
@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.
@item buffer-predicate
The buffer-predicate function for this frame. The function
and bar becomes a narrower bar).
@end defvar
-@node Color Parameters
-@subsubsection Color Parameters
+@node Font and Color Parameters
+@subsubsection Font and Color Parameters
- These frame parameters control the use of colors.
+ These frame parameters control the use of fonts and colors.
@table @code
+@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.
+
@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.
@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 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
@item font
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.
+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.
+
+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).
@end defun
@defun frame-char-height &optional frame
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
+instead. The @var{value} possibilities for the position parameters are:
+an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
+as previously described (@pxref{Position Parameters}).
Here is an example:
@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.
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
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
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
width and height of an X Window frame, measured in pixels.
@end ignore
+
@ignore
arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
@end ignore
HCoop / bpt / emacs.git / blobdiff