@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2004
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/frames
@node Frames, Positions, Windows, Top
horizontally into smaller windows.
@cindex terminal frame
-@cindex X window frame
When Emacs runs on a text-only terminal, it starts with one
@dfn{terminal frame}. If you create additional ones, Emacs displays
one and only one at any given time---on the terminal screen, of course.
+@cindex window frame
When Emacs communicates directly with a supported window system, such
-as X Windows, it does not have a terminal frame; instead, it starts with
+as X, it does not have a terminal frame; instead, it starts with
a single @dfn{window frame}, but you can create more, and Emacs can
display several such frames at once as is usual for window systems.
@defun framep object
-This predicate returns @code{t} if @var{object} is a frame, and
-@code{nil} otherwise.
+This predicate returns a non-@code{nil} value if @var{object} is a
+frame, and @code{nil} otherwise. For a frame, the value indicates which
+kind of display the frame uses:
+
+@table @code
+@item x
+The frame is displayed in an X window.
+@item t
+A terminal frame on a character display.
+@item mac
+The frame is displayed on a Macintosh.
+@item w32
+The frame is displayed on MS-Windows 9X/NT.
+@item pc
+The frame is displayed on an MS-DOS terminal.
+@end table
@end defun
@menu
* 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 them.
+ 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.
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shapes:: Specifying the shape of the mouse pointer.
* Window System Selections:: Transferring text to and from other X clients.
-* Font Names:: Looking up font 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.
-* Server Data:: Getting info about the X server.
+* Display Feature Testing:: Determining the features of a terminal.
@end menu
- @xref{Display}, for related information.
+ @xref{Display}, for information about the related topic of
+controlling Emacs redisplay.
@node Creating Frames
@section Creating Frames
Parameters}, for documentation of individual parameters you can specify.
@end defun
-@tindex before-make-frame-hook
@defvar before-make-frame-hook
A normal hook run by @code{make-frame} before it actually creates the
frame.
@end defvar
-@tindex after-make-frame-hook
-@defvar after-make-frame-hook
+@defvar after-make-frame-functions
+@tindex after-make-frame-functions
An abnormal hook run by @code{make-frame} after it creates the frame.
-Each function in @code{after-make-frame-hook} receives one argument, the
+Each function in @code{after-make-frame-functions} receives one argument, the
frame just created.
@end defvar
@node Multiple Displays
@section Multiple Displays
-@cindex multiple displays
-@cindex multiple X terminals
+@cindex multiple X displays
@cindex displays, multiple
- A single Emacs can talk to more than one X Window display.
+ 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
the @code{display} frame parameter when you create the frame.
Emacs treats each X server as a separate terminal, giving each one its
-own selected frame and its own minibuffer windows. A few Lisp variables
-have values local to the current terminal (that is, the terminal
-corresponding to the currently selected frame): these are
-@code{default-minibuffer-frame}, @code{defining-kbd-macro},
-@code{last-kbd-macro}, and @code{system-key-alist}. These variables are
-always terminal-local and can never be buffer-local or frame-local
-(@pxref{Buffer-Local Variables}).
+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}.
+
+ A few Lisp variables are @dfn{terminal-local}; that is, they have a
+separate binding for each terminal. The binding in effect at any time
+is the one for the terminal that the currently selected frame belongs
+to. These variables include @code{default-minibuffer-frame},
+@code{defining-kbd-macro}, @code{last-kbd-macro}, and
+@code{system-key-alist}. They are always terminal-local, and can never
+be buffer-local (@pxref{Buffer-Local Variables}) or frame-local.
A single X server can handle more than one screen. A display name
-@samp{@var{host}.@var{server}.@var{screen}} has three parts; the last
+@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
a display name.
@end defun
-@defun x-open-connection display &optional xrm-string
+@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.
@end example
@xref{Resources}.
+
+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
@node Frame Parameters
@section Frame Parameters
-A frame has many parameters that control its appearance and behavior.
+ A frame has many parameters that control its appearance and behavior.
Just what parameters a frame has depends on what display mechanism it
uses.
-Frame parameters exist for the sake of window systems. A terminal frame
-has a few parameters, mostly for compatibility's sake; only the height,
-width, @code{name}, @code{title}, @code{buffer-list} and
-@code{buffer-predicate} parameters do something special.
+ Frame parameters exist mostly for the sake of window systems. A
+terminal frame has a few parameters, mostly for compatibility's sake;
+only the @code{height}, @code{width}, @code{name}, @code{title},
+@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
+parameters do something special. If the terminal supports colors, the
+parameters @code{foreground-color}, @code{background-color},
+@code{background-mode} and @code{display-type} are also meaningful.
@menu
* Parameter Access:: How to change a frame's parameters.
These functions let you read and change the parameter values of a
frame.
-@defun frame-parameters frame
+@defun frame-parameter frame parameter
+@tindex frame-parameter
+This function returns the value of the parameter named @var{parameter}
+of @var{frame}. If @var{frame} is @code{nil}, it returns the
+selected frame's parameter.
+@end defun
+
+@defun frame-parameters &optional frame
The function @code{frame-parameters} returns an alist listing all the
-parameters of @var{frame} and their values.
+parameters of @var{frame} and their values. If @var{frame} is
+@code{nil} or omitted, this returns the selected frame's parameters
@end defun
@defun modify-frame-parameters frame alist
elements of @var{alist}. Each element of @var{alist} has the form
@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
parameter. If you don't mention a parameter in @var{alist}, its value
-doesn't change.
+doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
+frame.
+@end defun
+
+@defun modify-all-frames-parameters alist
+This function alters the frame parameters of all existing frames
+according to @var{alist}, then modifies @code{default-frame-alist}
+to apply the same parameter values to frames that will be created
+henceforth.
@end defun
@node Initial Parameters
@subsection Initial Frame Parameters
You can specify the parameters for the initial startup frame
-by setting @code{initial-frame-alist} in your @file{.emacs} file.
+by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
@defvar initial-frame-alist
This variable's value is an alist of parameter values used when creating
(@var{parameter} . @var{value})
@end example
-Emacs creates the initial frame before it reads your @file{~/.emacs}
+Emacs creates the initial frame before it reads your init
file. After reading that file, Emacs checks @code{initial-frame-alist},
and applies the parameter settings in the altered value to the already
created initial frame.
If these settings affect the frame geometry and appearance, you'll see
the frame appear with the wrong ones and then change to the specified
ones. If that bothers you, you can specify the same geometry and
-appearance with X resources; those do take affect before the frame is
-created. @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
+appearance with X resources; those do take effect before the frame is
+created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
X resource settings typically apply to all frames. If you want to
specify some X resources solely for the sake of the initial frame, and
uses. Here is a table of the parameters that have special meanings in a
window frame; of these, @code{name}, @code{title}, @code{height},
@code{width}, @code{buffer-list} and @code{buffer-predicate} provide
-meaningful information in terminal frames.
+meaningful information in terminal frames, and @code{tty-color-mode}
+is meaningful @emph{only} in terminal frames.
@table @code
+@item display
+The display on which to open this frame. It should be a string of the
+form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
+@code{DISPLAY} environment variable.
+
@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
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
-@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.
-
@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},
The width of the frame contents, in characters. (To get the height in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
+@item fullscreen
+Specify that width, height or both shall be set to the size of the screen.
+The value @code{fullwidth} specifies that width shall be the size of the
+screen. The value @code{fullheight} specifies that height shall be the
+size of the screen. The value @code{fullboth} specifies that both the
+width and the height shall be set to the size of the screen.
+
@item window-id
-The number of the window-system window used by the frame.
+The number of the window-system window used by the frame
+to contain the actual Emacs windows.
+
+@item outer-window-id
+The number of the outermost window-system window used for the whole frame.
@item minibuffer
Whether this frame has its own minibuffer. The value @code{t} means
A list of buffers that have been selected in this frame,
ordered most-recently-selected first.
-@item font
-The name of the font for displaying text in the frame. This is a
-string.
-
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
implemented.)
@item scroll-bar-width
-The width of the vertical scroll bar, in pixels.
+The width of the vertical scroll bar, in pixels,
+or @code{nil} meaning to use the default width.
@item icon-type
The type of icon to use for this frame when it is iconified. If the
The name to use in the icon for this frame, when and if the icon
appears. If this is @code{nil}, the frame's title is used.
-@item foreground-color
-The color to use for the image of a character. This is a string; the
-window system defines the meaningful color names.
-
-@item background-color
-The color to use for the background of characters.
+@item background-mode
+This parameter is either @code{dark} or @code{light}, according
+to whether the background color is a light one or a dark one.
+
+@item tty-color-mode
+@cindex standard colors for character terminals
+This parameter overrides the terminal's color support as given by the
+system's terminal capabilities database in that this parameter's value
+specifies the color mode to use in terminal frames. The value can be
+either a symbol or a number. A number specifies the number of colors
+to use (and, indirectly, what commands to issue to produce each
+color). For example, @code{(tty-color-mode . 8)} forces Emacs to use
+the ANSI escape sequences for 8 standard text colors; and a value of
+-1 means Emacs should turn off color support. If the parameter's
+value is a symbol, that symbol is looked up in the alist
+@code{tty-color-mode-alist}, and if found, the associated number is
+used as the color support mode.
+
+@item display-type
+This parameter describes the range of possible colors that can be used
+in this frame. Its value is @code{color}, @code{grayscale} or
+@code{mono}.
-@item mouse-color
-The color for the mouse pointer.
-
-@item cursor-color
-The color for the cursor that shows point.
+@item cursor-type
+How to display the cursor. Legitimate values are:
-@item border-color
-The color for the border of the frame.
+@table @code
+@item box
+Display a filled box. (This is the default.)
+@item hollow
+Display a hollow box.
+@item nil
+Don't display a cursor.
+@item bar
+Display a vertical bar between characters.
+@item (bar . @var{width})
+Display a vertical bar @var{width} pixels wide between characters.
+@item hbar
+Display a horizontal bar.
+@item (bar . @var{width})
+Display a horizontal bar @var{width} pixels high.
+@end table
-@item cursor-type
-The way to display the cursor. The legitimate values are @code{bar},
-@code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
-specifies an ordinary black box overlaying the character after point;
-that is the default. The symbol @code{bar} specifies a vertical bar
-between characters as the cursor. @code{(bar . @var{width})} specifies
-a bar @var{width} pixels wide.
+@vindex cursor-type
+The buffer-local variable @code{cursor-type} overrides the value of
+the @code{cursor-type} frame parameter, but if it is @code{t}, that
+means to use the cursor specified for the frame.
@item border-width
The width in pixels of the window border.
@item internal-border-width
The distance in pixels between text and border.
+@item left-fringe
+@itemx right-fringe
+The default width of the left and right fringes of windows in this
+frame (@pxref{Fringes}). If either of these is zero, that effectively
+removes the corresponding fringe. A value of @code{nil} stands for
+the standard fringe width, which is the width needed to display the
+fringe bitmaps.
+
+The combined fringe widths must add up to an integral number of
+columns, so the actual default fringe widths for the frame may be
+larger than the specified values. The extra width needed to reach an
+acceptable total is distributed evenly between the left and right
+fringe. However, you can force one frame or the other to a precise
+width by specifying that width a negative integer. If both widths are
+negative, only the left fringe gets the specified width.
+
@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.
@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar.
The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
-toolkit, there is only one menu bar line; all that matters about the
+toolkit or GTK, there is only one menu bar line; all that matters about the
number you specify is whether it is greater than zero.)
+@item screen-gamma
+@cindex gamma correction
+If this is a number, Emacs performs ``gamma correction'' which adjusts
+the brightness of all colors. The value should be the screen gamma of
+your display, a floating point number.
+
+Usual PC monitors have a screen gamma of 2.2, so color values in
+Emacs, and in X windows generally, are calibrated to display properly
+on a monitor with that gamma value. If you specify 2.2 for
+@code{screen-gamma}, that means no correction is needed. Other values
+request correction, designed to make the corrected colors appear on
+your screen they way they would have appeared without correction on an
+ordinary monitor with a gamma value of 2.2.
+
+If your monitor displays colors too light, you should specify a
+@code{screen-gamma} value smaller than 2.2. This requests correction
+that makes colors darker. A screen gamma value of 1.5 may give good
+results for LCD color displays.
+
+@item tool-bar-lines
+The number of lines to use for the toolbar. A value of @code{nil} means
+don't display a tool bar. (In Emacs versions that use GTK, there is
+only one tool bar line; all that matters about the number you specify
+is whether it is greater than zero.)
+
+@item line-spacing
+Additional space put below text lines in pixels (a positive integer).
+
+@ignore
@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
Specifying this lets you create an Emacs window inside some other
application's window. (It is not certain this will be implemented; try
it and see if it works.)
+@end ignore
+@end table
+
+@defvar blink-cursor-alist
+This variable specifies how to blink the cursor. Each element has the
+form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
+type equals @var{on-state} (comparing using @code{equal}), Emacs uses
+@var{off-state} to specify what the cursor looks like when it blinks
+``off''. Both @var{on-state} and @var{off-state} should be suitable
+values for the @code{cursor-type} frame parameter.
+
+There are various defaults for how to blink each type of cursor,
+if the type is not mentioned as an @var{on-state} here. Changes
+in this variable do not take effect immediately, because the variable
+is examined only when you specify a cursor type for a frame.
+@end defvar
+
+These frame parameters are semi-obsolete in that they are automatically
+equivalent to particular face attributes of particular faces.
+
+@table @code
+@item font
+The name of the font for displaying text in the frame. This is a
+string, either a valid font name for your system or the name of an Emacs
+fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
+attribute of the @code{default} face.
+
+@item foreground-color
+The color to use for the image of a character. It is equivalent to
+the @code{:foreground} attribute of the @code{default} face.
+
+@item background-color
+The color to use for the background of characters. It is equivalent to
+the @code{:background} attribute of the @code{default} face.
+
+@item mouse-color
+The color for the mouse pointer. It is equivalent to the @code{:background}
+attribute of the @code{mouse} face.
+
+@item cursor-color
+The color for the cursor that shows point. It is equivalent to the
+@code{:background} attribute of the @code{cursor} face.
+
+@item border-color
+The color for the border of the frame. It is equivalent to the
+@code{:background} attribute of the @code{border} face.
+
+@item scroll-bar-foreground
+If 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.
+
+@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
+@code{scroll-bar} face.
+
+@item wait-for-wm
+If non-@code{nil}, tell Xt to wait for the window manager to confirm
+geometry changes. Some window managers, including versions of Fvwm2
+and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
+prevent hanging with those window managers.
@end table
@node Size and Position
@subsection Frame Size And Position
+@cindex size of frame
+@cindex screen size
+@cindex frame size
+@cindex resize frame
You can read or change the size and position of a frame using the
frame parameters @code{left}, @code{top}, @code{height}, and
@code{width}. Whatever geometry parameters you don't specify are chosen
by the window manager in its usual fashion.
- Here are some special features for working with sizes and positions:
+ Here are some special features for working with sizes and positions.
+(For the precise meaning of ``selected frame'' used by these functions,
+see @ref{Input Focus}.)
@defun set-frame-position frame left top
This function sets the position of the top left corner of @var{frame} to
@var{left} and @var{top}. These arguments are measured in pixels, and
-count from the top left corner of the screen. Negative parameter values
-count up or rightward from the top left corner of the screen.
+normally count from the top left corner of the screen.
+
+Negative parameter values position the bottom edge of the window up from
+the bottom edge of the screen, or the right window edge to the left of
+the right edge of the screen. It would probably be better if the values
+were always counted from the left and top, so that negative arguments
+would position the frame partly off the top or left edge of the screen,
+but it seems inadvisable to change that now.
@end defun
@defun frame-height &optional frame
@defunx frame-width &optional frame
These functions return the height and width of @var{frame}, measured in
-characters. If you don't supply @var{frame}, they use the selected
-frame.
+lines and columns. If you don't supply @var{frame}, they use the
+selected frame.
+@end defun
+
+@defun screen-height
+@defunx screen-width
+These functions are old aliases for @code{frame-height} and
+@code{frame-width}. When you are using a non-window terminal, the size
+of the frame is normally the same as the size of the terminal screen.
@end defun
@defun frame-pixel-height &optional frame
them to units of characters.
@end defun
- The old-fashioned functions @code{set-screen-height} and
-@code{set-screen-width}, which were used to specify the height and width
-of the screen in Emacs versions that did not support multiple frames,
-are still usable. They apply to the selected frame. @xref{Screen
-Size}.
+@defun set-frame-height frame lines &optional pretend
+This function resizes @var{frame} to a height of @var{lines} lines. The
+sizes of existing windows in @var{frame} are altered proportionally to
+fit.
+
+If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
+lines of output in @var{frame}, but does not change its value for the
+actual height of the frame. This is only useful for a terminal frame.
+Using a smaller height than the terminal actually implements may be
+useful to reproduce behavior observed on a smaller screen, or if the
+terminal malfunctions when using its whole screen. Setting the frame
+height ``for real'' does not always work, because knowing the correct
+actual size may be necessary for correct cursor positioning on a
+terminal frame.
+@end defun
+
+@defun set-frame-width frame width &optional pretend
+This function sets the width of @var{frame}, measured in characters.
+The argument @var{pretend} has the same meaning as in
+@code{set-frame-height}.
+@end defun
+
+@findex set-screen-height
+@findex set-screen-width
+ The older functions @code{set-screen-height} and
+@code{set-screen-width} were used to specify the height and width of the
+screen, in Emacs versions that did not support multiple frames. They
+are semi-obsolete, but still work; they apply to the selected frame.
@defun x-parse-geometry geom
@cindex geometry specification
-The function @code{x-parse-geometry} converts a standard X Windows
+The function @code{x-parse-geometry} converts a standard X window
geometry string to an alist that you can use as part of the argument to
@code{make-frame}.
@example
(x-parse-geometry "35x70+0-0")
- @result{} ((width . 35) (height . 70)
- (left . 0) (top - 0))
+ @result{} ((height . 70) (width . 35)
+ (top - 0) (left . 0))
@end example
@end defun
-@ignore
-New functions @code{set-frame-height} and @code{set-frame-width} set the
-size of a specified frame. The frame is the first argument; the size is
-the second.
-@end ignore
-
@node Frame Titles
@section Frame Titles
configuration (@pxref{Frame Configurations}); this is similar to the
way windows behave.
-@deffn Command delete-frame &optional frame
-This function deletes the frame @var{frame}. By default, @var{frame} is
-the selected frame.
+@deffn Command delete-frame &optional frame force
+@vindex delete-frame-functions
+This function deletes the frame @var{frame} after running the hook
+@code{delete-frame-functions} (each function gets one argument,
+@var{frame}). By default, @var{frame} is the selected frame.
+
+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.
@end deffn
@defun frame-live-p frame
@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. The list that you get is newly created, so modifying the list
-doesn't have any effect on the internals of Emacs.
+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
@defun next-frame &optional frame minibuf
The function @code{next-frame} lets you cycle conveniently through all
-the frames from an arbitrary starting point. It returns the ``next''
-frame after @var{frame} in the cycle. If @var{frame} is omitted or
-@code{nil}, it defaults to the selected frame.
+the frames on the current display from an arbitrary starting point. It
+returns the ``next'' frame after @var{frame} in the cycle. If
+@var{frame} is omitted or @code{nil}, it defaults to the selected frame
+(@pxref{Input Focus}).
The second argument, @var{minibuf}, says which frames to consider:
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
-@defun frame-top-window frame
+@defun frame-first-window &optional frame
This returns the topmost, leftmost window of frame @var{frame}.
+If omitted or @code{nil}, @var{frame} defaults to the selected frame.
@end defun
At any time, exactly one window on any frame is @dfn{selected within the
frame also selects this window. You can get the frame's current
selected window with @code{frame-selected-window}.
-@defun frame-selected-window frame
+@defun frame-selected-window &optional frame
This function returns the window on @var{frame} that is selected within
-@var{frame}.
+@var{frame}. If omitted or @code{nil}, @var{frame} defaults to the selected frame.
+@end defun
+
+@defun set-frame-selected-window frame window
+This sets the selected window of frame @var{frame} to @var{window}.
+If @var{frame} is @code{nil}, it operates on the selected frame. If
+@var{frame} is the selected frame, this makes @var{window} the
+selected window.
@end defun
Conversely, selecting a window for Emacs with @code{select-window} also
At any time, one frame in Emacs is the @dfn{selected frame}. The selected
window always resides on the selected frame.
+When Emacs displays its frames on several terminals (@pxref{Multiple
+Displays}), each terminal has its own selected frame. But only one of
+these is ``@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}.
+
@defun selected-frame
This function returns the selected frame.
@end defun
Some window systems and window managers direct keyboard input to the
window object that the mouse is in; others require explicit clicks or
commands to @dfn{shift the focus} to various window objects. Either
-way, Emacs automatically keeps track of which frame has the focus.
+way, Emacs automatically keeps track of which frame has the focus. To
+switch to a different frame from a Lisp function, call
+@code{select-frame-set-input-focus}.
Lisp programs can also switch frames ``temporarily'' by calling the
function @code{select-frame}. This does not alter the window system's
concept of focus; rather, it escapes from the window manager's control
until that control is somehow reasserted.
-When using a text-only terminal, only the selected terminal frame is
-actually displayed on the terminal. @code{switch-frame} is the only way
-to switch frames, and the change lasts until overridden by a subsequent
-call to @code{switch-frame}. Each terminal screen except for the
-initial one has a number, and the number of the selected frame appears
-in the mode line after the word @samp{Emacs} (@pxref{Mode Line
-Variables}).
+When using a text-only terminal, only one frame can be displayed at a
+time on the terminal, so after a call to @code{select-frame}, the next
+redisplay actually displays the newly selected frame. This frame
+remains selected until a subsequent call to @code{select-frame} or
+@code{select-frame-set-input-focus}. Each terminal frame has a number
+which appears in the mode line before the buffer name (@pxref{Mode
+Line Variables}).
+
+@defun select-frame-set-input-focus frame
+This function makes @var{frame} the selected frame, raises it (should
+it happen to be obscured by other frames) and tries to give it the X
+server's focus. On a text-only terminal, the next redisplay displays
+the new frame on the entire terminal screen. The return value of this
+function is not significant.
+@end defun
@c ??? This is not yet implemented properly.
@defun select-frame frame
This function selects frame @var{frame}, temporarily disregarding the
focus of the X server if any. The selection of @var{frame} lasts until
the next time the user does something to select a different frame, or
-until the next time this function is called.
+until the next time this function is called. The specified @var{frame}
+becomes the selected frame, as explained above, and the terminal that
+@var{frame} is on becomes the selected terminal. This function
+returns @var{frame}, or @code{nil} if @var{frame} has been deleted.
+
+In general, you should never use @code{select-frame} in a way that could
+switch to a different terminal without switching back when you're done.
@end defun
Emacs cooperates with the window system by arranging to select frames as
Don't call it for any other reason.
@end deffn
-@defun redirect-frame-focus frame focus-frame
+@defun redirect-frame-focus frame &optional focus-frame
This function redirects focus from @var{frame} to @var{focus-frame}.
This means that @var{focus-frame} will receive subsequent keystrokes and
events intended for @var{frame}. After such an event, the value of
@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
events specifying @var{frame} will instead select @var{focus-frame}.
-If @var{focus-frame} is @code{nil}, that cancels any existing
+If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
redirection for @var{frame}, which therefore once again receives its own
events.
change it.
@end defun
-@tindex focus-follows-mouse
@defopt focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers
focus when the user moves the mouse. Non-@code{nil} says that it does.
You can raise and lower Emacs frame Windows with these functions:
-@deffn Command raise-frame frame
-This function raises frame @var{frame}.
+@deffn Command raise-frame &optional frame
+This function raises frame @var{frame} (default, the selected frame).
@end deffn
-@deffn Command lower-frame frame
-This function lowers frame @var{frame}.
+@deffn Command lower-frame &optional frame
+This function lowers frame @var{frame} (default, the selected frame).
@end deffn
@defopt minibuffer-auto-raise
the current arrangement of frames and their contents.
@end defun
-@defun set-frame-configuration configuration
+@defun set-frame-configuration configuration &optional nodelete
This function restores the state of frames described in
@var{configuration}.
+
+Ordinarily, this function deletes all existing frames not listed in
+@var{configuration}. But if @var{nodelete} is non-@code{nil}, the
+unwanted frames are iconified instead.
@end defun
@node Mouse Tracking
the top left corner of the inside of @var{frame}.
@end defun
+@defvar mouse-position-function
+If non-@code{nil}, the value of this variable is a function for
+@code{mouse-position} to call. @code{mouse-position} calls this
+function just before returning, with its normal return value as the
+sole argument, and it returns whatever this function returns to it.
+
+This abnormal hook exists for the benefit of packages like
+@file{xt-mouse.el} that need to do mouse handling at the Lisp level.
+@end defvar
+
@defun set-mouse-position frame x y
This function @dfn{warps the mouse} to position @var{x}, @var{y} in
frame @var{frame}. The arguments @var{x} and @var{y} are integers,
giving the position in characters relative to the top left corner of the
-inside of @var{frame}.
+inside of @var{frame}. If @var{frame} is not visible, this function
+does nothing. The return value is not significant.
@end defun
@defun mouse-pixel-position
This function warps the mouse like @code{set-mouse-position} except that
@var{x} and @var{y} are in units of pixels rather than units of
characters. These coordinates are not required to be within the frame.
+
+If @var{frame} is not visible, this function does nothing. The return
+value is not significant.
@end defun
@need 3000
@node Window System Selections
@section Window System Selections
-@cindex selection (for X windows)
+@cindex selection (for window systems)
The X server records a set of @dfn{selections} which permit transfer of
data between application programs. The various selections are
selection values.
Each possible @var{type} has its own selection value, which changes
-independently. The usual values of @var{type} are @code{PRIMARY} and
-@code{SECONDARY}; these are symbols with upper-case names, in accord
-with X Window System conventions. The default is @code{PRIMARY}.
+independently. The usual values of @var{type} are @code{PRIMARY},
+@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
+names, in accord with X Window System conventions. The default is
+@code{PRIMARY}.
@end defun
@defun x-get-selection &optional type data-type
The @var{data-type} argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into Lisp
data. Meaningful values include @code{TEXT}, @code{STRING},
+@code{UTF8_STRING},
@code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
@code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
@end defun
@cindex cut buffer
-The X server also has a set of numbered @dfn{cut buffers} which can
+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.
+clients that still use them. Cut buffers are numbered from 0 to 7.
-@defun x-get-cut-buffer n
+@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
+@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), moving the other values down through the series of cut buffers, much
-like the way successive kills in Emacs move down the kill ring.
+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
-@node Font Names
-@section Looking up Font Names
-
-@defun x-list-font pattern &optional face frame maximum
-This function returns a list of available font names that match
-@var{pattern}. If the optional arguments @var{face} and @var{frame} are
-specified, then the list is limited to fonts that are the same size as
-@var{face} currently is on @var{frame}.
-
-The argument @var{pattern} should be a string, perhaps with wildcard
-characters: the @samp{*} character matches any substring, and the
-@samp{?} character matches any single character. Pattern matching
-of font names ignores case.
-
-If you specify @var{face} and @var{frame}, @var{face} should be a face name
-(a symbol) and @var{frame} should be a frame.
+@defvar selection-coding-system
+This variable specifies the coding system to use when reading and
+writing selections, the clipboard, or a cut buffer. @xref{Coding
+Systems}. The default is @code{compound-text-with-extensions}, which
+converts to the text representation that X11 normally uses.
+@end defvar
-The optional argument @var{maximum} sets a limit on how many fonts to
-return. If this is non-@code{nil}, then the return value is truncated
-after the first @var{maximum} matching fonts. Specifying a small value
-for @var{maximum} can make this function much faster, in cases where
-many fonts match the pattern.
-@end defun
+@cindex clipboard support (for MS-Windows)
+When Emacs runs on MS-Windows, it does not implement X selections in
+general, but it does support the clipboard. @code{x-get-selection}
+and @code{x-set-selection} on MS-Windows support the text data type
+only; if the clipboard holds other types of data, Emacs treats the
+clipboard as empty.
+
+@defopt x-select-enable-clipboard
+If this is 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.
+@end defopt
@node Color Names
@section Color Names
-@defun x-color-defined-p color &optional frame
+ These functions provide a way to determine which color names are
+valid, and what they look like. In some cases, the value depends on the
+@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
+meaning of the term ``selected frame''.
+
+@defun color-defined-p color &optional frame
+@tindex color-defined-p
This function reports whether a color name is meaningful. It returns
@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
which frame's display to ask about; if @var{frame} is omitted or
@code{nil}, the selected frame is used.
Note that this does not tell you whether the display you are using
-really supports that color. You can ask for any defined color on any
-kind of display, and you will get some result---that is how the X server
-works. Here's an approximate way to test whether your display supports
-the color @var{color}:
+really supports that color. When using X, you can ask for any defined
+color on any kind of display, and you will get some result---typically,
+the closest it can do. To determine whether a frame can really display
+a certain color, use @code{color-supported-p} (see below).
+
+@findex x-color-defined-p
+This function used to be called @code{x-color-defined-p},
+and that name is still supported as an alias.
+@end defun
-@example
-(defun x-color-supported-p (color &optional frame)
- (and (x-color-defined-p color frame)
- (or (x-display-color-p frame)
- (member color '("black" "white"))
- (and (> (x-display-planes frame) 1)
- (equal color "gray")))))
-@end example
+@defun defined-colors &optional frame
+@tindex defined-colors
+This function returns a list of the color names that are defined
+and supported on frame @var{frame} (default, the selected frame).
+
+@findex x-defined-colors
+This function used to be called @code{x-defined-colors},
+and that name is still supported as an alias.
+@end defun
+
+@defun color-supported-p color &optional frame background-p
+@tindex color-supported-p
+This returns @code{t} if @var{frame} can really display the color
+@var{color} (or at least something close to it). If @var{frame} is
+omitted or @code{nil}, the question applies to the selected frame.
+
+Some terminals support a different set of colors for foreground and
+background. If @var{background-p} is non-@code{nil}, that means you are
+asking whether @var{color} can be used as a background; otherwise you
+are asking whether it can be used as a foreground.
+
+The argument @var{color} must be a valid color name.
+@end defun
+
+@defun color-gray-p color &optional frame
+@tindex color-gray-p
+This returns @code{t} if @var{color} is a shade of gray, as defined on
+@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
+question applies to the selected frame. The argument @var{color} must
+be a valid color name.
@end defun
-@defun x-color-values color &optional frame
+@defun color-values color &optional frame
+@tindex color-values
This function returns a value that describes what @var{color} should
ideally look like. If @var{color} is defined, the value is a list of
three integers, which give the amount of red, the amount of green, and
the amount of blue. Each integer ranges in principle from 0 to 65535,
-but in practice no value seems to be above 65280. If @var{color} is not
-defined, the value is @code{nil}.
+but in practice no value seems to be above 65280. This kind
+of three-element list is called an @dfn{rgb value}.
+
+If @var{color} is not defined, the value is @code{nil}.
@example
-(x-color-values "black")
+(color-values "black")
@result{} (0 0 0)
-(x-color-values "white")
+(color-values "white")
@result{} (65280 65280 65280)
-(x-color-values "red")
+(color-values "red")
@result{} (65280 0 0)
-(x-color-values "pink")
+(color-values "pink")
@result{} (65280 49152 51968)
-(x-color-values "hungry")
+(color-values "hungry")
@result{} nil
@end example
The color values are returned for @var{frame}'s display. If @var{frame}
-is omitted or @code{nil}, the information is return for the selected
+is omitted or @code{nil}, the information is returned for the selected
frame's display.
+
+@findex x-color-values
+This function used to be called @code{x-color-values},
+and that name is still supported as an alias.
+@end defun
+
+@node Text Terminal Colors
+@section Text Terminal Colors
+@cindex colors on text-only terminals
+
+ Emacs can display color on text-only terminals, starting with version
+21. These terminals usually support only a small number of colors, and
+the computer uses small integers to select colors on the terminal. This
+means that the computer cannot reliably tell what the selected color
+looks like; instead, you have to inform your application which small
+integers correspond to which colors. However, Emacs does know the
+standard set of colors and will try to use them automatically.
+
+ The functions described in this section control how terminal colors
+are used by Emacs.
+
+@cindex rgb value
+ Several of these functions use or return @dfn{rgb values}. An rgb
+value is a list of three integers, which give the amount of red, the
+amount of green, and the amount of blue. Each integer ranges in
+principle from 0 to 65535, but in practice the largest value used is
+65280.
+
+ These functions accept a display (either a frame or the name of a
+terminal) as an optional argument. We hope in the future to make Emacs
+support more than one text-only terminal at one time; then this argument
+will specify which terminal to operate on (the default being the
+selected frame's terminal; @pxref{Input Focus}). At present, though,
+the @var{display} argument has no effect.
+
+@defun tty-color-define name number &optional rgb display
+@tindex tty-color-define
+This function associates the color name @var{name} with
+color number @var{number} on the terminal.
+
+The optional argument @var{rgb}, if specified, is an rgb value; it says
+what the color actually looks like. If you do not specify @var{rgb},
+then this color cannot be used by @code{tty-color-approximate} to
+approximate other colors, because Emacs does not know what it looks
+like.
+@end defun
+
+@defun tty-color-clear &optional display
+@tindex tty-color-clear
+This function clears the table of defined colors for a text-only terminal.
+@end defun
+
+@defun tty-color-alist &optional display
+@tindex tty-color-alist
+This function returns an alist recording the known colors supported by a
+text-only terminal.
+
+Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
+or @code{(@var{name} @var{number})}. Here, @var{name} is the color
+name, @var{number} is the number used to specify it to the terminal.
+If present, @var{rgb} is an rgb value that says what the color
+actually looks like.
+@end defun
+
+@defun tty-color-approximate rgb &optional display
+@tindex tty-color-approximate
+This function finds the closest color, among the known colors supported
+for @var{display}, to that described by the rgb value @var{rgb}.
+@end defun
+
+@defun tty-color-translate color &optional display
+@tindex tty-color-translate
+This function finds the closest color to @var{color} among the known
+colors supported for @var{display}. If the name @var{color} is not
+defined, the value is @code{nil}.
+
+@var{color} can be an X-style @code{"#@var{xxxyyyzzz}"} specification
+instead of an actual name. The format
+@code{"RGB:@var{xx}/@var{yy}/@var{zz}"} is also supported.
@end defun
@node Resources
@defun x-get-resource attribute class &optional component subclass
The function @code{x-get-resource} retrieves a resource value from the X
-Windows defaults database.
+Window defaults database.
Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
This function searches using a key of the form
variable to some other string, around a call to @code{x-get-resource}.
@end defvar
- @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
+@defvar x-resource-name
+This variable specifies the instance name that @code{x-get-resource}
+should look up. The default value is the name Emacs was invoked with,
+or the value specified with the @samp{-name} or @samp{-rn} switches.
+@end defvar
-@node Server Data
-@section Data about the X Server
+ @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
- This section describes functions you can use to get information about
-the capabilities and origin of an X display that Emacs is using. Each
-of these functions lets you specify the display you are interested in:
-the @var{display} argument can be either a display name, or a frame
-(meaning use the display that frame is on). If you omit the
-@var{display} argument, or specify @code{nil}, that means to use the
-selected frame's display.
+@node Display Feature Testing
+@section Display Feature Testing
+@cindex display feature testing
-@defun x-display-screens &optional display
-This function returns the number of screens associated with the display.
+ The functions in this section describe the basic capabilities of a
+particular display. Lisp programs can use them to adapt their behavior
+to what the display can do. For example, a program that ordinarily uses
+a popup menu could use the minibuffer if popup menus are not supported.
+
+ The optional argument @var{display} in these functions specifies which
+display to ask the question about. It can be a display name, a frame
+(which designates the display that frame is on), or @code{nil} (which
+refers to the selected frame's display, @pxref{Input Focus}).
+
+ @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
+obtain information about displays.
+
+@defun display-popup-menus-p &optional display
+@tindex display-popup-menus-p
+This function returns @code{t} if popup menus are supported on
+@var{display}, @code{nil} if not. Support for popup menus requires that
+the mouse be available, since the user cannot choose menu items without
+a mouse.
@end defun
-@defun x-server-version &optional display
-This function returns the list of version numbers of the X server
-running the display.
+@defun display-graphic-p &optional display
+@tindex display-graphic-p
+@cindex frames, more than one on display
+@cindex fonts, more than one on display
+This function returns @code{t} if @var{display} is a graphic display
+capable of displaying several frames and several different fonts at
+once. This is true for displays that use a window system such as X, and
+false for text-only terminals.
@end defun
-@defun x-server-vendor &optional display
-This function returns the vendor that provided the X server software.
+@defun display-mouse-p &optional display
+@tindex display-mouse-p
+@cindex mouse, availability
+This function returns @code{t} if @var{display} has a mouse available,
+@code{nil} if not.
+@end defun
+
+@defun display-color-p &optional display
+@tindex display-color-p
+@findex x-display-color-p
+This function returns @code{t} if the screen is a color screen.
+It used to be called @code{x-display-color-p}, and that name
+is still supported as an alias.
+@end defun
+
+@defun display-grayscale-p &optional display
+@tindex display-grayscale-p
+This function returns @code{t} if the screen can display shades of gray.
+(All color displays can do this.)
+@end defun
+
+@defun display-supports-face-attributes-p attributes &optional display
+@anchor{Display Face Attribute Testing}
+@tindex display-supports-face-attributes-p
+This function returns non-@code{nil} if all the face attributes in
+@var{attributes} are supported (@pxref{Face Attributes}).
+
+The definition of `supported' is somewhat heuristic, but basically
+means that a face containing all the attributes in @var{attributes},
+when merged with the default face for display, can be represented in a
+way that's
+
+@enumerate
+@item
+different in appearance than the default face, and
+
+@item
+`close in spirit' to what the attributes specify, if not exact.
+@end enumerate
+
+Point (2) implies that a @code{:weight black} attribute will be
+satisfied by any display that can display bold, as will
+@code{:foreground "yellow"} as long as some yellowish color can be
+displayed, but @code{:slant italic} will @emph{not} be satisfied by
+the tty display code's automatic substitution of a `dim' face for
+italic.
+@end defun
+
+@defun display-selections-p &optional display
+@tindex display-selections-p
+This function returns @code{t} if @var{display} supports selections.
+Windowed displays normally support selections, but they may also be
+supported in some other cases.
@end defun
-@defun x-display-pixel-height &optional display
+@defun display-images-p &optional display
+This function returns @code{t} if @var{display} can display images.
+Windowed displays ought in principle to handle images, but some
+systems lack the support for that. On a display that does not support
+images, Emacs cannot display a tool bar.
+@end defun
+
+@defun display-screens &optional display
+@tindex display-screens
+This function returns the number of screens associated with the display.
+@end defun
+
+@defun display-pixel-height &optional display
+@tindex display-pixel-height
This function returns the height of the screen in pixels.
@end defun
-@defun x-display-mm-height &optional display
-This function returns the height of the screen in millimeters.
+@defun display-mm-height &optional display
+@tindex display-mm-height
+This function returns the height of the screen in millimeters,
+or @code{nil} if Emacs cannot get that information.
@end defun
-@defun x-display-pixel-width &optional display
+@defun display-pixel-width &optional display
+@tindex display-pixel-width
This function returns the width of the screen in pixels.
@end defun
-@defun x-display-mm-width &optional display
-This function returns the width of the screen in millimeters.
+@defun display-mm-width &optional display
+@tindex display-mm-width
+This function returns the width of the screen in millimeters,
+or @code{nil} if Emacs cannot get that information.
@end defun
-@defun x-display-backing-store &optional display
-This function returns the backing store capability of the screen.
+@defun display-backing-store &optional display
+@tindex display-backing-store
+This function returns the backing store capability of the display.
+Backing store means recording the pixels of windows (and parts of
+windows) that are not exposed, so that when exposed they can be
+displayed very quickly.
+
Values can be the symbols @code{always}, @code{when-mapped}, or
-@code{not-useful}.
+@code{not-useful}. The function can also return @code{nil}
+when the question is inapplicable to a certain kind of display.
@end defun
-@defun x-display-save-under &optional display
+@defun display-save-under &optional display
+@tindex display-save-under
This function returns non-@code{nil} if the display supports the
-SaveUnder feature.
+SaveUnder feature. That feature is used by pop-up windows
+to save the pixels they obscure, so that they can pop down
+quickly.
@end defun
-@defun x-display-planes &optional display
+@defun display-planes &optional display
+@tindex display-planes
This function returns the number of planes the display supports.
+This is typically the number of bits per pixel.
+For a tty display, it is log to base two of the number of colours supported.
@end defun
-@defun x-display-visual-class &optional display
+@defun display-visual-class &optional display
+@tindex display-visual-class
This function returns the visual class for the screen. The value is one
of the symbols @code{static-gray}, @code{gray-scale},
@code{static-color}, @code{pseudo-color}, @code{true-color}, and
@code{direct-color}.
@end defun
-@defun x-display-grayscale-p &optional display
-This function returns @code{t} if the screen can display shades of gray.
+@defun display-color-cells &optional display
+@tindex display-color-cells
+This function returns the number of color cells the screen supports.
@end defun
-@defun x-display-color-p &optional display
-This function returns @code{t} if the screen is a color screen.
+ These functions obtain additional information specifically
+about X displays.
+
+@defun x-server-version &optional display
+This function returns the list of version numbers of the X server
+running the display.
@end defun
-@defun x-display-color-cells &optional display
-This function returns the number of color cells the screen supports.
+@defun x-server-vendor &optional display
+This function returns the vendor that provided the X server software.
@end defun
@ignore
@defvar x-no-window-manager
-This variable's value is is @code{t} if no X window manager is in use.
+This variable's value is @code{t} if no X window manager is in use.
@end defvar
@end ignore
The functions @code{x-pixel-width} and @code{x-pixel-height} return the
width and height of an X Window frame, measured in pixels.
@end ignore
+
+@ignore
+ arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
+@end ignore
HCoop / bpt / emacs.git / blobdiff