@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 has just one frame, a
-@dfn{terminal frame}. There is no way to create another terminal frame
-after startup. If Emacs has an X display, it does not have a terminal
-frame; instead, it starts with a single @dfn{X window frame}. You can
-create more; see @ref{Creating Frames}.
+ 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.
+
+ When Emacs communicates directly with an X server, 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.
@defun framep object
This predicate returns @code{t} if @var{object} is a frame, and
@end defun
@menu
-* Creating Frames:: Creating additional X Window frames.
+* Creating Frames:: Creating additional frames.
+* Multiple Displays:: Creating frames on other X displays.
* Frame Parameters:: Controlling frame size, position, font, etc.
+* Frame Titles:: Automatic updating of frame titles.
* Deleting Frames:: Frames last until explicitly deleted.
* Finding All Frames:: How to examine all existing frames.
* Frames and Windows:: A frame contains windows;
* 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.
+* Color Names:: Getting the definitions of color names.
* Resources:: Getting resource values from the server.
* Server Data:: Getting info about the X server.
@end menu
To create a new frame, call the function @code{make-frame}.
-@defun make-frame alist
-This function creates a new frame, if the display mechanism permits
-creation of frames. (An X server does; an ordinary terminal does not.)
+@defun make-frame &optional alist
+This function creates a new frame. If you are using X, it makes
+an X 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 defaults file and X resources.
The set of possible parameters depends in principle on what kind of
window system Emacs uses to display its frames. @xref{X Frame
-Parameters}, for documentation of individual parameters you can specify
-when creating an X window frame.
+Parameters}, for documentation of individual parameters you can specify.
@end defun
@defvar before-make-frame-hook
A normal hook run by @code{make-frame} after it creates the frame.
@end defvar
+@node Multiple Displays
+@section Multiple Displays
+@cindex multiple displays
+@cindex multiple X terminals
+@cindex displays, multiple
+
+ A single Emacs can talk to more than one X Windows display.
+Initially, Emacs uses just one display---the one chosen with the
+@code{DISPLAY} environment variable or with the @samp{--display} option
+(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
+another display, use the command @code{make-frame-on-display} or specify
+the @code{display} frame parameter when you create the frame.
+
+ Emacs treats each X server as a separate terminal, giving each one its
+own selected frame and its own minibuffer windows. 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.
+
+ A single X server can handle more than one screen. A display name
+@samp{@var{host}.@var{server}.@var{screen}} has three parts; the last
+part specifies the screen number for a given server. When you use two
+screens belonging to one server, Emacs knows by the similarity in their
+names that they share a single keyboard, and it treats them as a single
+terminal.
+
+@deffn Command make-frame-on-display display &optional parameters
+This creates a new frame on display @var{display}, taking the other
+frame parameters from @var{parameters}. Aside from the @var{display}
+argument, it is like @code{make-frame} (@pxref{Creating Frames}).
+@end deffn
+
+@defun x-display-list
+This returns a list that indicates which X displays Emacs has a
+connection to. The elements of the list are strings, and each one is
+a display name.
+@end defun
+
+@defun x-open-connection display &optional xrm-string
+This function opens a connection to the X display @var{display}. It
+does not create a frame on that display, but it permits you to check
+that communication can be established with that display.
+
+The optional argument @var{resource-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}.
+@end defun
+
+@defun x-close-connection display
+This function closes the connection to display @var{display}. Before
+you can do this, you must first delete all the frames that were open on
+that display (@pxref{Deleting Frames}).
+@end defun
+
@node Frame Parameters
@section Frame Parameters
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.
+has a few parameters, mostly for compatibility's sake; only the height,
+width and @code{buffer-predicate} parameters really do something.
@menu
* Parameter Access:: How to change a frame's parameters.
* Initial Parameters:: Specifying frame parameters when you make a frame.
-* X Frame Parameters:: Individual parameters documented.
+* X Frame Parameters:: List of frame parameters.
* Size and Position:: Changing the size and position of a frame.
@end menu
@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 X 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})
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 affect 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. In many cases,
+you can get the same results by means of X resources.
@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
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:
+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.
@table @code
@item name
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. The value may be
-@code{-} instead of a number; that represents @samp{-0} in a geometry
-specification.
+The screen position of the left edge, in pixels, with respect to the
+left edge of the screen. The value may be a positive number @var{pos},
+or a list of the form @code{(+ @var{pos})} which permits specifying a
+negative @var{pos} value.
+
+A negative number @minus{}@var{pos}, or a list of the form @code{(-
+@var{pos})}, actually specifies the position of the right edge of the
+window with respect to the right edge of the screen. A positive value
+of @var{pos} counts toward the left. 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. The value may be
-@code{-} instead of a number; that represents @samp{-0} in a geometry
-specification.
+The screen position of the top edge, in pixels, with respect to the
+top edge of the screen. The value may be a positive number @var{pos},
+or a list of the form @code{(+ @var{pos})} which permits specifying a
+negative @var{pos} value.
+
+A negative number @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. A positive value
+of @var{pos} counts toward the top. 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
+pixels, counting from the left edge of the screen. This takes effect if
+and when the frame is iconified.
+
+@item icon-top
+The screen position of the top edge @emph{of the frame's icon}, in
+pixels, counting from the top edge of the screen. This takes effect if
+and when the frame is iconified.
@item user-position
-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
@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
+each buffer; if the predicate returns a non-@code{nil} value, it
+considers that buffer.
@item font
The name of the font for displaying text in the frame. This is a
(non-@code{nil} means yes). (Horizontal scroll bars are not currently
implemented.)
+@item scroll-bar-width
+The width of the vertical scroll bar, in pixels.
+
@item icon-type
-The type of icon to use for this frame when it is iconified.
-Non-@code{nil} specifies a bitmap icon, @code{nil} a text icon.
+The type of icon to use for this frame when it is iconified. If the
+value is a string, that specifies a file containing a bitmap to use.
+Any other non-@code{nil} value specifies the default bitmap icon (a
+picture of a gnu); @code{nil} specifies a text icon.
+
+@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
The color for the border of the frame.
@item cursor-type
-The way to display the cursor. There are two legitimate values:
-@code{bar} and @code{box}. The symbol @code{bar} specifies a vertical
-bar between characters as the cursor. The symbol @code{box} specifies
-an ordinary black box overlaying the character after point; that is the
-default.
+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.
@item border-width
The width in pixels of the window border.
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
+count from the top left corner of the screen. Negative parameter values
+count up or rightward from the top left corner of the screen.
@end defun
@defun frame-height &optional frame
@code{(@var{parameter} . @var{value})}. The possible @var{parameter}
values are @code{left}, @code{top}, @code{width}, and @code{height}.
-@smallexample
+For the size parameters, the value must be an integer. The position
+parameter names @code{left} and @code{top} are not totally accurate,
+because some values indicate the position of the right or bottom edges
+instead. These are the @var{value} possibilities for the position
+parameters:
+
+@table @asis
+@item an integer
+A positive integer relates the left edge or top edge of the window to
+the left or top edge of the screen. A negative integer relates the
+right or bottom edge of the window to the right or bottom edge of the
+screen.
+
+@item @code{(+ @var{position})}
+This specifies the position of the left or top edge of the window
+relative to the left or top edge of the screen. The integer
+@var{position} may be positive or negative; a negative value specifies a
+position outside the screen.
+
+@item @code{(- @var{position})}
+This specifies the position of the right or bottom edge of the window
+relative to the right or bottom edge of the screen. The integer
+@var{position} may be positive or negative; a negative value specifies a
+position outside the screen.
+@end table
+
+Here is an example:
+
+@example
(x-parse-geometry "35x70+0-0")
- @result{} ((width . 35) (height . 70) (left . 0) (top . -1))
-@end smallexample
+ @result{} ((width . 35) (height . 70)
+ (left . 0) (top - 0))
+@end example
@end defun
@ignore
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.
+
+Emacs computes the frame title based on a template stored in the
+variable @code{frame-title-format}.
+
+@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}.
+@end defvar
+
+@defvar icon-title-format
+This variable specifies how to compute the title for an iconified frame,
+when you have not explicitly specified the frame title. This title
+appears in the icon itself.
+@end defvar
+
+@defvar multiple-frames
+This variable is set automatically by Emacs. Its value is @code{t} when
+there are two or more frames (not counting minibuffer-only frames or
+invisible frames). The default value of @code{frame-title-format} uses
+@code{multiple-frames} so as to put the buffer name in the frame title
+only when there is more than one frame.
+@end defvar
+
@node Deleting Frames
@section Deleting Frames
@cindex deletion of frames
@var{frame} has not been deleted.
@end defun
+ Some window managers provide a command to delete a window. These work
+by sending a special message to the program that operates the window.
+When Emacs gets one of these commands, it generates a
+@code{delete-frame} event, whose normal definition is a command that
+calls the function @code{delete-frame}. @xref{Misc Events}.
+
@node Finding All Frames
@section Finding All Frames
@defun visible-frame-list
This function returns a list of just the currently visible frames.
-@xref{Visibility of Frames}.
+@xref{Visibility of Frames}. (Terminal frames always count as
+``visible'', even though only the selected one is actually displayed.)
@end defun
@defun next-frame &optional frame minibuf
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
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 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
@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
+@defvar default-minibuffer-frame
+This variable specifies the frame to use for the minibuffer window, by
+default. It is always local to the current terminal and cannot be
+buffer-local. @xref{Multiple Displays}.
+@end defvar
+
@node Input Focus
@section Input Focus
@cindex input focus
manager; 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} (@pxref{Mode Line Variables}).
+
@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. 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.
+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.
@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}.
+@code{handle-switch-frame}. @xref{Focus Events}.
@deffn Command handle-switch-frame frame
This function handles a focus event by selecting frame @var{frame}.
@cindex iconified frame
@cindex frame visibility
-A frame may be @dfn{visible}, @dfn{invisible}, or @dfn{iconified}. If
-it is visible, you can see its contents. If it is iconified, the
-frame's contents do not appear on the screen, but an icon does. If the
-frame is invisible, it doesn't show on the screen, not even as an icon.
+An X window frame may be @dfn{visible}, @dfn{invisible}, or
+@dfn{iconified}. If it is visible, you can see its contents. If it is
+iconified, the frame's contents do not appear on the screen, but an icon
+does. If the frame is invisible, it doesn't show on the screen, not
+even as an icon.
+
+Visibility is meaningless for terminal frames, since only the selected
+one is actually displayed in any case.
@deffn Command make-frame-visible &optional frame
This function makes frame @var{frame} visible. If you omit @var{frame},
parameter. You can read or change it as such. @xref{X Frame
Parameters}.
+ The user can iconify and deiconify frames with the window manager.
+This happens below the level at which Emacs can exert any control, but
+Emacs does provide events that you can use to keep track of such
+changes. @xref{Misc Events}.
+
@node Raising and Lowering
@section Raising and Lowering Frames
You can raise and lower Emacs's X windows with these functions:
-@defun raise-frame frame
+@deffn Command raise-frame frame
This function raises frame @var{frame}.
-@end defun
+@end deffn
-@defun lower-frame frame
+@deffn Command lower-frame frame
This function lowers frame @var{frame}.
-@end defun
+@end deffn
@defopt minibuffer-auto-raise
If this is non-@code{nil}, activation of the minibuffer raises the frame
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.
@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.
+
@defun x-popup-menu position menu
This function displays a pop-up menu and returns an indication of
what selection the user makes.
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
+ @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}).
+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 pointer shape
@cindex mouse pointer shape
- These variables specify which mouse pointer shape to use in various
-situations:
+ These variables specify which shape to use for the mouse pointer in
+various situations:
@table @code
@item x-pointer-shape
these variables. @xref{X 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
like the way successive kills in Emacs move down the kill ring.
@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).
+@node Color Names
+@section Color Names
-@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
-
-@defun x-open-connection display &optional resource-string
-This function opens a connection to an X server, for use of display
-@var{display}.
-
-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:
-
-@example
-"*BorderWidth: 3\n*InternalBorder: 2\n"
-@end example
-
-@xref{Resources}.
-@end defun
-
-@defun x-display-color-p
-This returns @code{t} if the connected X display has color, and
-@code{nil} otherwise.
-@end defun
-
-@defun x-color-defined-p color
+@defun x-color-defined-p color &optional frame
This function reports whether a color name is meaningful. It returns
-@code{t} if so; otherwise, @code{nil}.
+@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
the color @var{color}:
@example
-(defun x-color-supported-p (color)
- (and (x-color-defined-p color)
- (or (x-display-color-p)
+(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) 1)
+ (and (> (x-display-planes frame) 1)
(equal color "gray")))))
@end example
@end defun
-@defun x-color-values color
+@defun x-color-values color &optional frame
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
(x-color-values "hungry")
@result{} nil
@end example
-@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}.
-
-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.
+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
+frame's display.
@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}.
+ @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
@node Server Data
@section Data about the X Server
- This section describes functions and a variable that you can use to
-get information about the capabilities and origin of the X server that
-Emacs is displaying its frames on.
+ 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.
-@defun x-display-screens
-This function returns the number of screens associated with the current
-display.
+@defun x-display-screens &optional display
+This function returns the number of screens associated with the display.
@end defun
-@defun x-server-version
-This function returns the list of version numbers of the X server in
-use.
+@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-server-vendor
-This function returns the vendor supporting the X server in use.
+@defun x-server-vendor &optional display
+This function returns the vendor that provided the X server software.
@end defun
-@defun x-display-pixel-height
-This function returns the height of this X screen in pixels.
+@defun x-display-pixel-height &optional display
+This function returns the height of the screen in pixels.
@end defun
-@defun x-display-mm-height
-This function returns the height of this X screen in millimeters.
+@defun x-display-mm-height &optional display
+This function returns the height of the screen in millimeters.
@end defun
-@defun x-display-pixel-width
-This function returns the width of this X screen in pixels.
+@defun x-display-pixel-width &optional display
+This function returns the width of the screen in pixels.
@end defun
-@defun x-display-mm-width
-This function returns the width of this X screen in millimeters.
+@defun x-display-mm-width &optional display
+This function returns the width of the screen in millimeters.
@end defun
-@defun x-display-backing-store
-This function returns the backing store capability of this screen.
+@defun x-display-backing-store &optional display
+This function returns the backing store capability of the screen.
Values can be the symbols @code{always}, @code{when-mapped}, or
@code{not-useful}.
@end defun
-@defun x-display-save-under
-This function returns non-@code{nil} if this X screen supports the
+@defun x-display-save-under &optional display
+This function returns non-@code{nil} if the display supports the
SaveUnder feature.
@end defun
-@defun x-display-planes
-This function returns the number of planes this display supports.
+@defun x-display-planes &optional display
+This function returns the number of planes the display supports.
@end defun
-@defun x-display-visual-class
-This function returns the visual class for this X screen. The value is
-one of the symbols @code{static-gray}, @code{gray-scale},
+@defun x-display-visual-class &optional display
+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-color-p
-This function returns @code{t} if the X screen in use is a color
-screen.
+@defun x-display-grayscale-p &optional display
+This function returns @code{t} if the screen can display shades of gray.
+@end defun
+
+@defun x-display-color-p &optional display
+This function returns @code{t} if the screen is a color screen.
@end defun
-@defun x-display-color-cells
-This function returns the number of color cells this X screen supports.
+@defun x-display-color-cells &optional display
+This function returns the number of color cells the screen supports.
@end defun
@ignore
HCoop / bpt / emacs.git / blobdiff