@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/frames
@node Frames, Positions, Windows, Top
@chapter Frames
@cindex frame
- A @var{frame} is a rectangle on the screen that contains one or more
+ A @dfn{frame} is a rectangle on the screen that contains one or more
Emacs windows. A frame initially contains a single main window (plus
perhaps a minibuffer window), which you can subdivide vertically or
horizontally into smaller windows.
@cindex terminal frame
-@cindex X window frame
When Emacs runs on a text-only terminal, it starts with one
-@dfn{terminal frames}. If you create additional ones, Emacs displays
+@dfn{terminal frame}. If you create additional ones, Emacs displays
one and only one at any given time---on the terminal screen, of course.
- When Emacs uses X for display, it does not have a terminal frame;
-instead, it starts with a single @dfn{X window frame}. It can display
-multiple X window frames at the same time, each in its own X window.
+@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
+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
* Creating Frames:: Creating additional frames.
-* Multiple Displays:: Creating frames on other X displays.
+* Multiple Displays:: Creating frames on other displays.
* Frame Parameters:: Controlling frame size, position, font, etc.
* Frame Titles:: Automatic updating of frame titles.
* Deleting Frames:: Frames last until explicitly deleted.
* Minibuffers and Frames:: How a frame finds the minibuffer to use.
* Input Focus:: Specifying the selected frame.
* Visibility of Frames:: Frames may be visible or invisible, or icons.
-* Raising and Lowering:: Raising a frame makes it hide other X windows;
+* Raising and Lowering:: Raising a frame makes it hide other windows;
lowering it makes the others hide them.
* Frame Configurations:: Saving the state of all frames.
* Mouse Tracking:: Getting events that say when the mouse moves.
* Pop-Up Menus:: Displaying a menu for the user to select from.
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shapes:: Specifying the shape of the mouse pointer.
-* X Selections:: Transferring text to and from other X clients.
-* X Connections:: Opening and closing the X server connection.
+* Window System Selections:: Transferring text to and from other X clients.
+* Color Names:: Getting the definitions of color names.
+* Text Terminal Colors:: Defining colors for text-only terminals.
* Resources:: Getting resource values from the server.
-* 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
To create a new frame, call the function @code{make-frame}.
-@defun make-frame alist
-This function creates a new frame. If you are using X, it makes
-an X window frame; otherwise, it makes a terminal frame.
+@defun make-frame &optional alist
+This function creates a new frame. If you are using a supported window
+system, it makes a window frame; otherwise, it makes a terminal frame.
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 there
-either default from the standard X defaults file and X resources.
+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{X Frame
+window system Emacs uses to display its frames. @xref{Window Frame
Parameters}, for documentation of individual parameters you can specify.
@end defun
frame.
@end defvar
-@defvar after-make-frame-hook
-A normal hook run by @code{make-frame} after it creates the frame.
+@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
+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 Windows 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}, @code{multiple-frames} and
-@code{system-key-alist}. These variables are always terminal-local and
-can never be buffer-local.
+own selected frame and its own minibuffer windows.
+
+ 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
@defun x-display-list
This returns a list that indicates which X displays Emacs has a
-connection to. The elements of the list are display names (strings).
+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
+@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 second argument @var{xrm-string} should be a string of
-resources in xrdb format, or @code{nil}. The resources, if specified,
-apply to all Emacs frames created on this display.
+The optional argument @var{xrm-string}, if not @code{nil}, is a
+string of resource names and values, in the same format used in the
+@file{.Xresources} file. The values you specify override the resource
+values recorded in the X server itself; they apply to all Emacs frames
+created on this display. Here's an example of what this string might
+look like:
+
+@example
+"*BorderWidth: 3\n*InternalBorder: 2\n"
+@end example
+
+@xref{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, for compatibility's sake only. You can't change
-these parameters directly; the only ones that ever change are the height
-and width.
+ Frame parameters exist mostly for the sake of window systems. A
+terminal frame has a few parameters, mostly for compatibility's sake;
+only the @code{height}, @code{width}, @code{name}, @code{title},
+@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
+parameters do something special. If the terminal supports colors, the
+parameters @code{foreground-color}, @code{background-color},
+@code{background-mode} and @code{display-type} are also meaningful.
@menu
* Parameter Access:: How to change a frame's parameters.
* Initial Parameters:: Specifying frame parameters when you make a frame.
-* X Frame Parameters:: List of frame parameters.
+* Window Frame Parameters:: List of frame parameters for window systems.
* Size and Position:: Changing the size and position of a frame.
@end menu
These functions let you read and change the parameter values of a
frame.
+@defun frame-parameter frame parameter
+@tindex frame-parameter
+This function returns the value of the parameter named @var{parameter}
+of @var{frame}. If @var{frame} is @code{nil}, it returns the
+selected frame's parameter.
+@end defun
+
@defun frame-parameters frame
The function @code{frame-parameters} returns an alist listing all the
parameters of @var{frame} and their values.
@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
-the initial X window frame. Each element has the form:
+the initial window frame. You can set this variable to specify the
+appearance of the initial frame without altering subsequent frames.
+Each element has the form:
@example
(@var{parameter} . @var{value})
@end example
-Emacs creates the initial frame before it reads your @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, you'll see the frame appear
-with the wrong geometry and then change to the specified one. If you
-like, you can specify the same geometry with X resources; those do take
-affect before the frame is created. @xref{Resources X,, X Resources,
-emacs, The GNU Emacs Manual}.
+If these settings affect the frame geometry and appearance, you'll see
+the frame appear with the wrong ones and then change to the specified
+ones. If that bothers you, you can specify the same geometry and
+appearance with X resources; those do take effect before the frame is
+created. @xref{Resources X,, 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
@code{initial-frame-alist} with values that match the X resources.
@end defvar
-If these parameters specify a separate minibuffer-only frame,
-and you have not created one, Emacs creates one for you.
+If these parameters specify a separate minibuffer-only frame with
+@code{(minibuffer . nil)}, and you have not created one, Emacs creates
+one for you.
@defvar minibuffer-frame-alist
This variable's value is an alist of parameter values used when creating
to the parameters for the main initial frame.
@end defvar
-@defvar special-display-frame-alist
-The variable @code{special-display-frame-alist} specifies the frame
-parameters for special display frames.
-@end defvar
-
@defvar default-frame-alist
-This is an alist specifying default values of frame parameters for
-subsequent Emacs frames (not the initial ones).
+This is an alist specifying default values of frame parameters for all
+Emacs frames---the first frame, and subsequent frames. When using the X
+Window System, you can get the same results by means of X resources
+in many cases.
@end defvar
+See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
+
If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to @code{default-frame-alist}. One
-exception is @samp{-geometry}, which adds to @code{initial-frame-alist}
-instead. @xref{Command Arguments,,, emacs, The GNU Emacs Manual}.
+exception is @samp{-geometry}, which adds the specified position to
+@code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
+The GNU Emacs Manual}.
-@node X Frame Parameters
-@subsection X Window Frame Parameters
+@node Window Frame Parameters
+@subsection Window Frame Parameters
Just what parameters a frame has depends on what display mechanism it
-uses. Here is a table of the parameters of an X window frame; of these,
-@code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
-provide meaningful information in non-X frames.
+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.
@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
+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. Most window managers display the frame's name in
-the frame's border, at the top of the frame. If you don't specify a
-name, and you have more than one frame, Emacs sets the frame name based
-on the buffer displayed in the frame's selected window.
+The name of the frame. The frame name serves as a default for the frame
+title, if the @code{title} parameter is unspecified or @code{nil}. If
+you don't specify a name, Emacs sets the frame name automatically
+(@pxref{Frame Titles}).
If you specify the frame name explicitly when you create the frame, the
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
-@item 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},
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, counting toward the
-left.
+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.
+
+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
A negative number @minus{}@var{pos}, or a list of the form @code{(-
@var{pos})}, actually specifies the position of the bottom edge of the
-window with respect to the bottom edge of the screen, counting toward the
-top.
+window with respect to the bottom edge of the screen. A positive value
+of @var{pos} counts toward the top. @strong{Reminder:} if the
+parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
+positive.
+
+Some window managers ignore program-specified positions. If you want to
+be sure the position you specify is not ignored, specify a
+non-@code{nil} value for the @code{user-position} parameter as well.
@item icon-left
The screen position of the left edge @emph{of the frame's icon}, in
and when the frame is iconified.
@item user-position
-Non-@code{nil} if the screen position of the frame was explicitly
-requested by the user (for example, with the @samp{-geometry} option).
-Nothing automatically makes this parameter non-@code{nil}; it is up to
-Lisp programs that call @code{make-frame} to specify this parameter as
-well as specifying the @code{left} and @code{top} parameters.
+When you create a frame and specify its screen position with the
+@code{left} and @code{top} parameters, use this parameter to say whether
+the specified position was user-specified (explicitly requested in some
+way by a human user) or merely program-specified (chosen by a program).
+A non-@code{nil} value says the position was user-specified.
+
+Window managers generally heed user-specified positions, and some heed
+program-specified positions too. But many ignore program-specified
+positions, placing the window in a default fashion or letting the user
+place it with the mouse. Some window managers, including @code{twm},
+let the user specify whether to obey program-specified positions or
+ignore them.
+
+When you call @code{make-frame}, you should specify a non-@code{nil}
+value for this parameter if the values of the @code{left} and @code{top}
+parameters represent the user's stated preference; otherwise, use
+@code{nil}.
@item height
The height of the frame contents, in characters. (To get the height in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
@item window-id
-The number of the X window for 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
yes, @code{nil} means no, @code{only} means this frame is just a
-minibuffer, a minibuffer window (in some other frame) means the new
-frame uses that minibuffer.
+minibuffer. If the value is a minibuffer window (in some other frame),
+the new frame uses that minibuffer.
@item buffer-predicate
The buffer-predicate function for this frame. The function
@code{other-buffer} uses this predicate (from the selected frame) to
decide which buffers it should consider, if the predicate is not
-@code{nil}. It calls the predicate with one arg, a buffer, once for
+@code{nil}. It calls the predicate with one argument, a buffer, once for
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.
+@item buffer-list
+A list of buffers that have been selected in this frame,
+ordered most-recently-selected first.
+
@item font
The name of the font for displaying text in the frame. This is a
-string.
+string, either a valid font name for your system or the name of an Emacs
+fontset (@pxref{Fontsets}). Changing this frame parameter on a frame
+also changes the font-related attributes of the default face on that
+frame.
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
Whether deselecting the frame lowers it (non-@code{nil} means yes).
@item vertical-scroll-bars
-Whether the frame has scroll bars for vertical scrolling
-(non-@code{nil} means yes).
+Whether the frame has scroll bars for vertical scrolling, and which side
+of the frame they should be on. The possible values are @code{left},
+@code{right}, and @code{nil} for no scroll bars.
@item horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling
Any other non-@code{nil} value specifies the default bitmap icon (a
picture of a gnu); @code{nil} specifies a text icon.
+@item icon-name
+The name to use in the icon for this frame, when and if the icon
+appears. If this is @code{nil}, the frame's title is used.
+
@item foreground-color
-The color to use for the image of a character. This is a string; the X
-server defines the meaningful color names.
+The color to use for the image of a character. This is a string; the
+window system defines the meaningful color names. Changing this
+parameter is equivalent to changing the foreground color of the face
+@code{default} on the frame in question.
@item background-color
-The color to use for the background of characters.
+The color to use for the background of characters. Changing this
+parameter is equivalent to changing the foreground color of the face
+@code{default} on the frame in question.
+
+@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 mouse-color
-The color for the mouse pointer.
+The color for the mouse pointer. Changing this parameter is equivalent
+to changing the background color of face @code{mouse}.
@item cursor-color
-The color for the cursor that shows point.
+The color for the cursor that shows point. Changing this parameter is
+equivalent to changing the background color of face @code{cursor}.
@item border-color
-The color for the border of the frame.
+The color for the border of the frame. Changing this parameter is
+equivalent to changing the background color of face @code{border}.
+
+@item scroll-bar-foreground
+If non-@code{nil}, the color for the foreground of scroll bars.
+Changing this parameter is equivalent to setting the foreground color of
+face @code{scroll-bar}.
+
+@item scroll-bar-background
+If non-@code{nil}, the color for the background of scroll bars.
+Changing this parameter is equivalent to setting the foreground color of
+face @code{scroll-bar}.
+
+@item display-type
+This parameter describes the range of possible colors that can be used
+in this frame. Its value is @code{color}, @code{grayscale} or
+@code{mono}.
@item cursor-type
The way to display the cursor. The legitimate values are @code{bar},
toolkit, 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'' on 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 the default is
+to display for that gamma value. Specifying a smaller value results in
+darker colors, which is desirable for a monitor that tends to display
+colors too light. 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.
+
+@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
@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
Here are some special features for working with sizes and positions:
@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, counting from the top left corner of the screen.
+This function sets the position of the top left corner of @var{frame} to
+@var{left} and @var{top}. These arguments are measured in pixels, and
+normally count from the top left corner of the screen.
+
+Negative parameter values position the bottom edge of the window up from
+the bottom edge of the screen, or the right window edge to the left of
+the right edge of the screen. It would probably be better if the values
+were always counted from the left and top, so that negative arguments
+would position the frame partly off the top or left edge of the screen,
+but it seems inadvisable to change that now.
@end defun
@defun frame-height &optional frame
@defunx frame-width &optional frame
These functions return the height and width of @var{frame}, measured in
-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}.
right or bottom edge of the window to the right or bottom edge of the
screen.
-@item (+ @var{position})
+@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 (- @var{position})
+@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
Here is an example:
-@smallexample
+@example
(x-parse-geometry "35x70+0-0")
- @result{} ((width . 35) (height . 70) (left . 0) (top - 0))
-@end smallexample
+ @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
-Every frame has a title; most window managers display the frame title at
-the top of the frame. You can specify an explicit title with the
-@code{name} frame property. But normally you don't specify this
-explicitly, and Emacs computes the title automatically.
+ Every frame has a @code{name} parameter; this serves as the default
+for the frame title which window systems typically display at the top of
+the frame. You can specify a name explicitly by setting the @code{name}
+frame property.
-Emacs computes the frame title based on a template stored in the
-variable @code{frame-title-format}.
+ Normally you don't specify the name explicitly, and Emacs computes the
+frame name automatically based on a template stored in the variable
+@code{frame-title-format}. Emacs recomputes the name each time the
+frame is redisplayed.
@defvar frame-title-format
-This variable specifies how to compute a title for a frame
-when you have not explicitly specified one.
-
-The variable's value is actually a mode line construct, just like
-@code{mode-line-format}. @xref{Mode Line Data}.
+This variable specifies how to compute a name for a frame when you have
+not explicitly specified one. The variable's value is actually a mode
+line construct, just like @code{mode-line-format}. @xref{Mode Line
+Data}.
@end defvar
@defvar icon-title-format
-This variable specifies how to compute the title for an iconified frame,
+This variable specifies how to compute the name for an iconified frame,
when you have not explicitly specified the frame title. This title
appears in the icon itself.
@end defvar
invisible frames). The default value of @code{frame-title-format} uses
@code{multiple-frames} so as to put the buffer name in the frame title
only when there is more than one frame.
-
-The variable is always local to the current X terminal and cannot be
-buffer-local. @xref{Multiple Displays}.
@end defvar
@node Deleting Frames
configuration (@pxref{Frame Configurations}); this is similar to the
way windows behave.
-@deffn Command delete-frame &optional frame
+@deffn Command delete-frame &optional frame force
This function deletes the frame @var{frame}. By default, @var{frame} is
-the selected frame.
+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
@end defun
Some window managers provide a command to delete a window. These work
-by sending a special message to the program than operates the window.
+by sending a special message to the program that operates the window.
When Emacs gets one of these commands, it generates a
@code{delete-frame} event, whose normal definition is a command that
calls the function @code{delete-frame}. @xref{Misc Events}.
Exclude minibuffer-only frames.
@item @code{visible}
Consider all visible frames.
+@item 0
+Consider all visible or iconified frames.
@item a window
Consider only the frames using that particular window as their
minibuffer.
direction.
@end defun
+ See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
+Window Ordering}.
+
@node Frames and Windows
@section Frames and Windows
order. The order runs from the frame's top window, which is at the
upper left corner, down and to the right, until it reaches the window at
the lower right corner (always the minibuffer window, if the frame has
-one), and then it moves back to the top.
+one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
-@defun frame-top-window frame
+@defun frame-first-window frame
This returns the topmost, leftmost window of frame @var{frame}.
@end defun
@var{frame}.
@end defun
-Conversely, selecting a window for Emacs with @code{select-window} also
+ Conversely, selecting a window for Emacs with @code{select-window} also
makes that window selected within its frame. @xref{Selecting Windows}.
+ Another function that (usually) returns one of the windows in a given
+frame is @code{minibuffer-window}. @xref{Minibuffer Misc}.
+
@node Minibuffers and Frames
@section Minibuffers and Frames
However, you can also create a frame with no minibuffer. Such a frame
must use the minibuffer window of some other frame. When you create the
-frame, you can specify explicitly the frame on which to find the
-minibuffer to use. If you don't, then the minibuffer is found in the
-frame which is the value of the variable
-@code{default-minibuffer-frame}. Its value should be a frame that does
-have a minibuffer.
+frame, you can specify explicitly the minibuffer window to use (in some
+other frame). If you don't, then the minibuffer is found in the frame
+which is the value of the variable @code{default-minibuffer-frame}. Its
+value should be a frame that does have a minibuffer.
If you use a minibuffer-only frame, you might want that frame to raise
when you enter the minibuffer. If so, set the variable
@defvar default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by
-default. It is always local to the current X terminal and cannot be
+default. It is always local to the current terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@end defvar
This function returns the selected frame.
@end defun
-The X server normally directs keyboard input to the X window that the
-mouse is in. Some window managers use mouse clicks or keyboard events
-to @dfn{shift the focus} to various X windows, overriding the normal
-behavior of the server.
+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.
-Lisp programs can switch frames ``temporarily'' by calling
-the function @code{select-frame}. This does not override the window
-manager; rather, it escapes from the window manager's control until
-that control is somehow reasserted.
+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, there is no window manager; therefore,
-@code{switch-frame} is the only way to switch frames, and the effect
-lasts until overridden by a subsequent call to @code{switch-frame}.
-Only the selected terminal frame is actually displayed on the terminal.
-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}.
+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 before the buffer name (@pxref{Mode Line Variables}).
@c ??? This is not yet implemented properly.
@defun select-frame frame
until the next time this function is called.
@end defun
-Emacs cooperates with the X server and the window managers by arranging
-to select frames according to what the server and window manager ask
-for. It does so by generating a special kind of input event, called a
-@dfn{focus} event. The command loop handles a focus event by calling
-@code{handle-select-frame}. @xref{Focus Events}.
+Emacs cooperates with the window system by arranging to select frames as
+the server and window manager request. It does so by generating a
+special kind of input event, called a @dfn{focus} event, when
+appropriate. The command loop handles a focus event by calling
+@code{handle-switch-frame}. @xref{Focus Events}.
@deffn Command handle-switch-frame frame
This function handles a focus event by selecting frame @var{frame}.
@defun redirect-frame-focus frame focus-frame
This function redirects focus from @var{frame} to @var{focus-frame}.
-This means that @var{focus-frame} will receive subsequent keystrokes
-intended for @var{frame}. After such an event, the value of
+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}.
change it.
@end defun
+@defopt focus-follows-mouse
+This option is how you inform Emacs whether the window manager transfers
+focus when the user moves the mouse. 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.
+@end defopt
+
@node Visibility of Frames
@section Visibility of Frames
@cindex visible frame
@cindex iconified frame
@cindex frame visibility
-An X windo frame may be @dfn{visible}, @dfn{invisible}, or
+A window frame may be @dfn{visible}, @dfn{invisible}, or
@dfn{iconified}. If it is visible, you can see its contents. If it is
iconified, the frame's contents do not appear on the screen, but an icon
does. If the frame is invisible, it doesn't show on the screen, not
@end defun
The visibility status of a frame is also available as a frame
-parameter. You can read or change it as such. @xref{X Frame
+parameter. You can read or change it as such. @xref{Window Frame
Parameters}.
The user can iconify and deiconify frames with the window manager.
@node Raising and Lowering
@section Raising and Lowering Frames
-The X Window System uses a desktop metaphor. Part of this metaphor is
+ Most window systems use a desktop metaphor. Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest''. Where two windows overlap, the one higher up covers the
-one underneath. Even a window at the bottom of the stack can be seen if
-no other window overlaps it.
+to ``lowest''. Where two windows overlap, the one higher up covers
+the one underneath. Even a window at the bottom of the stack can be
+seen if no other window overlaps it.
@cindex raising a frame
@cindex lowering a frame
-A window's place in this ordering is not fixed; in fact, users tend to
-change the order frequently. @dfn{Raising} a window means moving it
-``up'', to the top of the stack. @dfn{Lowering} a window means moving
-it to the bottom of the stack. This motion is in the notional third
-dimension only, and does not change the position of the window on the
-screen.
+ A window's place in this ordering is not fixed; in fact, users tend
+to change the order frequently. @dfn{Raising} a window means moving
+it ``up'', to the top of the stack. @dfn{Lowering} a window means
+moving it to the bottom of the stack. This motion is in the notional
+third dimension only, and does not change the position of the window
+on the screen.
-You can raise and lower Emacs's X windows with these functions:
+ 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
You can also enable auto-raise (raising automatically when a frame is
selected) or auto-lower (lowering automatically when it is deselected)
-for any frame using frame parameters. @xref{X Frame Parameters}.
+for any frame using frame parameters. @xref{Window Frame Parameters}.
@node Frame Configurations
@section Frame Configurations
A @dfn{frame configuration} records the current arrangement of frames,
all their properties, and the window configuration of each one.
+(@xref{Window Configurations}.)
@defun current-frame-configuration
This function returns a frame configuration list that describes
the current arrangement of frames and their contents.
@end defun
-@defun set-frame-configuration configuration
+@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
button.
@defspec track-mouse body@dots{}
-Execute @var{body}, meanwhile generating input events for mouse motion.
-The code in @var{body} can read these events with @code{read-event} or
-@code{read-key-sequence}. @xref{Motion Events}, for the format of mouse
-motion events.
+This special form executes @var{body}, with generation of mouse motion
+events enabled. Typically @var{body} would use @code{read-event} to
+read the motion events and modify the display accordingly. @xref{Motion
+Events}, for the format of mouse motion events.
The value of @code{track-mouse} is that of the last form in @var{body}.
+You should design @var{body} to return when it sees the up-event that
+indicates the release of the button, or whatever kind of event means
+it is time to stop tracking.
@end defspec
The usual purpose of tracking mouse motion is to indicate on the screen
the consequences of pushing or releasing a button at the current
position.
+In many cases, you can avoid the need to track the mouse by using
+the @code{mouse-face} text property (@pxref{Special Properties}).
+That works at a much lower level and runs more smoothly than
+Lisp-level mouse tracking.
+
@ignore
@c These are not implemented yet.
These functions change the screen appearance instantaneously. The
effect is transient, only until the next ordinary Emacs redisplay. That
-is ok for mouse tracking, since it doesn't make sense for mouse tracking
+is OK for mouse tracking, since it doesn't make sense for mouse tracking
to change the text, and the body of @code{track-mouse} normally reads
the events itself and does not do redisplay.
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 Pop-Up Menus
@section Pop-Up Menus
- When using X windows, a Lisp program can pop up a menu which the
-user can choose from with the mouse.
+ When using a window system, a Lisp program can pop up a menu so that
+the user can choose an alternative with the mouse.
@defun x-popup-menu position menu
This function displays a pop-up menu and returns an indication of
where each pane is a list of form
@example
-(@var{title} (@var{line} @var{item})...)
+(@var{title} (@var{line} . @var{item})...)
@end example
Each @var{line} should be a string, and each @var{item} should be the
value to return if that @var{line} is chosen.
@end defun
-@strong{Usage note:} Don't use @code{x-popup-menu} to display a menu if
-a prefix key with a menu keymap would do the job. If you use a menu
-keymap to implement a menu, @kbd{C-h c} and @kbd{C-h a} can see the
-individual items in that menu and provide help for them. If instead you
-implement the menu by defining a command that calls @code{x-popup-menu},
-the help facilities cannot know what happens inside that command, so
-they cannot give any help for the menu's items. This is the reason why
-all the menu bar items except @samp{Buffers} are implemented with menu
-keymaps (@pxref{Menu Keymaps}).
+ @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
+if you could do the job with a prefix key defined with a menu keymap.
+If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
+a} can see the individual items in that menu and provide help for them.
+If instead you implement the menu by defining a command that calls
+@code{x-popup-menu}, the help facilities cannot know what happens inside
+that command, so they cannot give any help for the menu's items.
+
+ The menu bar mechanism, which lets you switch between submenus by
+moving the mouse, cannot look within the definition of a command to see
+that it calls @code{x-popup-menu}. Therefore, if you try to implement a
+submenu using @code{x-popup-menu}, it cannot work with the menu bar in
+an integrated fashion. This is why all menu bar submenus are
+implemented with menu keymaps within the parent menu, and never with
+@code{x-popup-menu}. @xref{Menu Bar},
+
+ If you want a menu bar submenu to have contents that vary, you should
+still use a menu keymap to implement it. To make the contents vary, add
+a hook function to @code{menu-bar-update-hook} to update the contents of
+the menu keymap as necessary.
@node Dialog Boxes
@section Dialog Boxes
@cindex dialog boxes
- A dialog box is a variant of a pop-up menu. It looks a little
-different (if Emacs uses an X toolkit), it always appears in the center
-of a frame, and it has just one level and one pane. The main use of
-dialog boxes is for asking questions that the user can answer with
-``yes'', ``no'', and a few other alternatives. The functions
-@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
-keyboard, when called from commands invoked by mouse clicks.
+ A dialog box is a variant of a pop-up menu---it looks a little
+different, it always appears in the center of a frame, and it has just
+one level and one pane. The main use of dialog boxes is for asking
+questions that the user can answer with ``yes'', ``no'', and a few other
+alternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} use
+dialog boxes instead of the keyboard, when called from commands invoked
+by mouse clicks.
@defun x-popup-dialog position contents
This function displays a pop-up dialog box and returns an indication of
@code{x-popup-menu}, but the precise coordinates don't matter; only the
frame matters.
-If your Emacs executable does not use an X toolkit, then it cannot
-display a real dialog box; so instead it displays the same items in a
-pop-up menu in the center of the frame.
+In some configurations, Emacs cannot display a real dialog box; so
+instead it displays the same items in a pop-up menu in the center of the
+frame.
@end defun
@node Pointer Shapes
@cindex mouse pointer shape
These variables specify which shape to use for the mouse pointer in
-various situations:
+various situations, when using the X Window System:
@table @code
@item x-pointer-shape
These variables affect newly created frames. They do not normally
affect existing frames; however, if you set the mouse color of a frame,
that also updates its pointer shapes based on the current values of
-these variables. @xref{X Frame Parameters}.
+these variables. @xref{Window Frame Parameters}.
The values you can use, to specify either of these pointer shapes, are
-defined in the file @file{lisp/x-win.el}. Use @kbd{M-x apropos
+defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
@key{RET} x-pointer @key{RET}} to see a list of them.
-@node X Selections
-@section X Selections
+@node Window System Selections
+@section Window System Selections
@cindex selection (for X windows)
The X server records a set of @dfn{selections} which permit transfer of
cons of two markers pointing to the same buffer. An overlay or a pair
of markers stands for text in the overlay or between the markers.
-The data may also be a vector of valid non-vector selection values.
+The argument @var{data} may also be a vector of valid non-vector
+selection values.
Each possible @var{type} has its own selection value, which changes
independently. The usual values of @var{type} are @code{PRIMARY} and
This function returns the contents of cut buffer number @var{n}.
@end defun
-@defun x-set-cut-buffer string
+@defun x-set-cut-buffer string &optional push
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 X Connections
-@section X Connections
-
-You can close the connection with the X server with the function
-@code{x-close-current-connection}, and open a new one with
-@code{x-open-connection} (perhaps with a different server and display).
+@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}, which converts to
+the text representation that X11 normally uses.
+@end defvar
-@defun x-close-current-connection
-This function closes the connection to the X server. It deletes all
-frames, making Emacs effectively inaccessible to the user; therefore, a
-Lisp program that closes the connection should open another one.
-@end defun
+@cindex clipboard support (for MS-Windows)
+When Emacs runs on MS-Windows, it does not implement X selections in
+general, but it 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
-@defun x-open-connection display &optional resource-string
-This function opens a connection to an X server, for use of display
-@var{display}.
+@node Color Names
+@section Color Names
-The optional argument @var{resource-string} 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. Here's an example of what this string might look
-like:
+ These functions provide a way to determine which color names are
+valid, and what they look like.
-@example
-"*BorderWidth: 3\n*InternalBorder: 2\n"
-@end example
+@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.
-@xref{Resources}.
+Note that this does not tell you whether the display you are using
+really supports that color. When using X, you can ask for any defined
+color on any kind of display, and you will get some result---typically,
+the closest it can do. To determine whether a frame can really display
+a certain color, use @code{color-supported-p} (see below).
+
+@findex x-color-defined-p
+This function used to be called @code{x-color-defined-p},
+and that name is still supported as an alias.
@end defun
-@defun x-display-color-p
-This returns @code{t} if the connected X display has color, and
-@code{nil} otherwise.
+@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 x-color-defined-p color
-This function reports whether a color name is meaningful. It returns
-@code{t} if so; otherwise, @code{nil}.
+@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.
-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}:
+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.
-@example
-(defun x-color-supported-p (color)
- (and (x-color-defined-p color)
- (or (x-display-color-p)
- (member color '("black" "white"))
- (and (> (x-display-planes) 1)
- (equal color "gray")))))
-@end example
+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
+@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 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
-@defun x-synchronize flag
-The function @code{x-synchronize} enables or disables synchronous
-communication with the X server. It enables synchronous communication
-if @var{flag} is non-@code{nil}, and disables it if @var{flag} is
-@code{nil}.
+@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 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.
+
+@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). 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}.
-In synchronous mode, Emacs waits for a response to each X protocol
-command before doing anything else. This is useful for debugging Emacs,
-because protocol errors are reported right away, which helps you find
-the erroneous command. Synchronous mode is not the default because it
-is much slower.
+@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
@section X Resources
-@defun x-get-resource attribute &optional component subclass
+@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.
Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
This function searches using a key of the form
@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
-under which Emacs was invoked), and using @samp{Emacs} as the class.
+under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
+the class.
The optional arguments @var{component} and @var{subclass} add to the key
and the class, respectively. You must specify both of them or neither.
If you specify them, the key is
@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
-@samp{Emacs.@var{subclass}}.
+@samp{Emacs.@var{class}.@var{subclass}}.
@end defun
- @xref{Resources X, X Resources,, emacs, The GNU Emacs Manual}.
+@defvar x-resource-class
+This variable specifies the application name that @code{x-get-resource}
+should look up. The default value is @code{"Emacs"}. You can examine X
+resources for application names other than ``Emacs'' by binding this
+variable to some other string, around a call to @code{x-get-resource}.
+@end defvar
-@node Server Data
-@section Data about the X Server
+ @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
- This section describes functions and a variable that 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, 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 ordinarly 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).
+
+ @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 x-display-pixel-height &optional display
+@defun display-selections-p &optional display
+@tindex display-selections-p
+This function returns @code{t} if @var{display} supports selections.
+Windowed displays normally support selections, but they may also be
+supported in some other cases.
+@end defun
+
+@defun display-screens &optional display
+@tindex display-screens
+This function returns the number of screens associated with the display.
+@end defun
+
+@defun display-pixel-height &optional display
+@tindex display-pixel-height
This function returns the height of the screen in pixels.
@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.
@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
HCoop / bpt / emacs.git / blobdiff