@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.
@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar.
-The default is 1. @xref{Menu Bar}.
+The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
+toolkit, there is only one menu bar line; all that matters about the
+number you specify is whether it is greater than zero.)
@item parent-id
@c ??? Not yet working.
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).
-
-@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
+@node Color Names
+@section Color Names
-@defun x-open-connection display &optional resource-string
-This function opens a connection to an X server, for use of display
-@var{display}.
+@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}. 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.
-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:
+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}:
@example
-"*BorderWidth: 3\n*InternalBorder: 2\n"
+(defun x-color-supported-p (color &optional frame)
+ (and (x-color-defined-p color frame)
+ (or (x-display-color-p frame)
+ (member color '("black" "white"))
+ (and (> (x-display-planes frame) 1)
+ (equal color "gray")))))
@end example
-
-@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-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
+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}.
-@defun x-color-defined-p color
-This function reports whether a color name is meaningful and supported
-on the X display Emacs is using. It returns @code{t} if the display
-supports that color; otherwise, @code{nil}.
-
-Black-and-white displays support just two colors, @code{"black"} or
-@code{"white"}. Color displays support many other colors.
-@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}.
+@example
+(x-color-values "black")
+ @result{} (0 0 0)
+(x-color-values "white")
+ @result{} (65280 65280 65280)
+(x-color-values "red")
+ @result{} (65280 0 0)
+(x-color-values "pink")
+ @result{} (65280 49152 51968)
+(x-color-values "hungry")
+ @result{} nil
+@end example
-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