@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.@c See the file elisp.texi for copying conditions.@setfilename ../../info/frames@node Frames, Positions, Windows, Top@chapter Frames@cindex frame A @dfn{frame} is a screen object that contains one or more Emacswindows (@pxref{Windows}). It is the kind of object called a``window'' in the terminology of graphical environments; but we can'tcall it a ``window'' here, because Emacs uses that word in a differentway. In Emacs Lisp, a @dfn{frame object} is a Lisp object thatrepresents a frame on the screen. @xref{Frame Type}. A frame initially contains a single main window and/or a minibufferwindow; you can subdivide the main window vertically or horizontallyinto smaller windows. @xref{Splitting Windows}.@cindex terminal A @dfn{terminal} is a display device capable of displaying one ormore Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lispobject that represents a terminal. @xref{Terminal Type}.@cindex terminal frame@cindex window frame There are two classes of terminals: text-only terminals andgraphical terminals. Text-only terminals are non-graphics-capabledisplay devices, including ``terminal emulators'' such as xterm. Ontext-only terminals, each frame occupies the entire terminal screen;although you can create additional frames and switch between them,only one frame can be shown at any given time. We refer to frames ontext-only terminals as @dfn{terminal frames}. Graphical terminals, onthe other hand, are graphics-capable windowing systems, such as the XWindow System. On a graphical terminal, Emacs can display multipleframes simultaneously. We refer to such frames as @dfn{windowframes}. On GNU and Unix systems, you can create additional frames on anyavailable terminal, within a single Emacs session, regardless ofwhether Emacs was started on a text-only or graphical terminal. Emacscan display on both graphical and text-only terminals simultaneously.This comes in handy, for instance, when you connect to the samesession from several remote locations. @xref{Multiple Terminals}.@defun framep objectThis predicate returns a non-@code{nil} value if @var{object} is aframe, and @code{nil} otherwise. For a frame, the value indicates whichkind of display the frame uses:@table @code@item xThe frame is displayed in an X window.@item tA terminal frame on a character display.@item w32The frame is displayed on MS-Windows 9X/NT.@item nsThe frame is displayed on a GNUstep or Macintosh Cocoa display.@item pcThe frame is displayed on an MS-DOS terminal.@end table@end defun@defun frame-terminal &optional frameThis function returns the terminal object that displays @var{frame}.If @var{frame} is @code{nil} or unspecified, it defaults to theselected frame.@end defun@defun terminal-live-p objectThis predicate returns a non-@code{nil} value if @var{object} is aterminal that is alive (i.e.@: was not deleted), and @code{nil}otherwise. For live terminals, the return value indicates what kindof frames are displayed on that terminal; the list of possible valuesis the same as for @code{framep} above.@end defun@menu* Creating Frames:: Creating additional frames.* Multiple Terminals:: Displaying on several different devices.* Frame Parameters:: Controlling frame size, position, font, etc.* Terminal Parameters:: Parameters common for all frames on terminal.* Frame Titles:: Automatic updating of frame titles.* Deleting Frames:: Frames last until explicitly deleted.* Finding All Frames:: How to examine all existing frames.* Frames and Windows:: A frame contains windows; display of text always works through windows.* 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 windows; lowering it makes the others hide it.* Frame Configurations:: Saving the state of all frames.* Mouse Tracking:: Getting events that say when the mouse moves.* Mouse Position:: Asking where the mouse is, or moving it.* Pop-Up Menus:: Displaying a menu for the user to select from.* Dialog Boxes:: Displaying a box to ask yes or no.* Pointer Shape:: Specifying the shape of the mouse pointer.* Window System Selections:: Transferring text to and from other X clients.* Drag and Drop:: Internals of Drag-and-Drop implementation.* Color Names:: Getting the definitions of color names.* Text Terminal Colors:: Defining colors for text-only terminals.* Resources:: Getting resource values from the server.* Display Feature Testing:: Determining the features of a terminal.@end menu@node Creating Frames@section Creating FramesTo create a new frame, call the function @code{make-frame}.@defun make-frame &optional alistThis function creates and returns a new frame, displaying the currentbuffer.The @var{alist} argument is an alist that specifies frame parametersfor the new frame. @xref{Frame Parameters}. If you specify the@code{terminal} parameter in @var{alist}, the new frame is created onthat terminal. Otherwise, if you specify the @code{window-system}frame parameter in @var{alist}, that determines whether the frameshould be displayed on a text-only or graphical terminal.@xref{Window Systems}. If neither is specified, the new frame iscreated in the same terminal as the selected frame.Any parameters not mentioned in @var{alist} default to the values inthe alist @code{default-frame-alist} (@pxref{Initial Parameters});parameters not specified there default from the X resources or itsequivalent on your operating system (@pxref{X Resources,, X Resources,emacs, The GNU Emacs Manual}). After the frame is created, Emacsapplies any parameters listed in @code{frame-inherited-parameters}(see below) and not present in the argument, taking the values fromthe frame that was selected when @code{make-frame} was called.This function itself does not make the new frame the selected frame.@xref{Input Focus}. The previously selected frame remains selected.On graphical terminals, however, the windowing system may select thenew frame for its own reasons.@end defun@defvar before-make-frame-hookA normal hook run by @code{make-frame} before it creates the frame.@end defvar@defvar after-make-frame-functionsAn abnormal hook run by @code{make-frame} after it creates the frame.Each function in @code{after-make-frame-functions} receives one argument, theframe just created.@end defvar@defvar frame-inherited-parametersThis variable specifies the list of frame parameters that a newlycreated frame inherits from the currently selected frame. For eachparameter (a symbol) that is an element in the list and is not presentin the argument to @code{make-frame}, the function sets the value ofthat parameter in the created frame to its value in the selectedframe.@end defvar@node Multiple Terminals@section Multiple Terminals@cindex multiple terminals@cindex multi-tty@cindex multiple X displays@cindex displays, multiple Emacs represents each terminal, whether graphical or text-only, as a@dfn{terminal object} data type (@pxref{Terminal Type}). On GNU andUnix systems, Emacs can use multiple terminals simultaneously in eachsession. On other systems, it can only use a single terminal. Eachterminal object has the following attributes:@itemize @bullet@itemThe name of the device used by the terminal (e.g., @samp{:0.0} or@file{/dev/tty}).@itemThe terminal and keyboard coding systems used on the terminal.@xref{Terminal I/O Encoding}.@itemThe kind of display associated with the terminal. This is the symbolreturned by the function @code{terminal-live-p} (i.e., @code{x},@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.@itemA list of terminal parameters. @xref{Terminal Parameters}.@end itemize There is no primitive for creating terminal objects. Emacs createsthem as needed, such as when you call @code{make-frame-on-display}(which is described below).@defun terminal-name &optional terminalThis function returns the file name of the device used by@var{terminal}. If @var{terminal} is omitted or @code{nil}, itdefaults to the selected frame's terminal. @var{terminal} can also bea frame, meaning that frame's terminal.@end defun@defun terminal-listThis function returns a list of all terminal objects currently in use.@end defun@defun get-device-terminal deviceThis function returns a terminal whose device name is given by@var{device}. If @var{device} is a string, it can be either the filename of a terminal device, or the name of an X display of the form@samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is aframe, this function returns that frame's terminal; @code{nil} meansthe selected frame. Finally, if @var{device} is a terminal objectthat represents a live terminal, that terminal is returned. Thefunction signals an error if its argument is none of the above.@end defun@defun delete-terminal &optional terminal forceThis function deletes all frames on @var{terminal} and frees theresources used by it. It runs the abnormal hook@code{delete-terminal-functions}, passing @var{terminal} as theargument to each function.If @var{terminal} is omitted or @code{nil}, it defaults to theselected frame's terminal. @var{terminal} can also be a frame,meaning that frame's terminal.Normally, this function signals an error if you attempt to delete thesole active terminal, but if @var{force} is non-@code{nil}, you areallowed to do so. Emacs automatically calls this function when thelast frame on a terminal is deleted (@pxref{Deleting Frames}).@end defun@defvar delete-terminal-functionsAn abnormal hook run by @code{delete-terminal}. Each functionreceives one argument, the @var{terminal} argument passed to@code{delete-terminal}. Due to technical details, the functions maybe called either just before the terminal is deleted, or justafterwards.@end defvar@cindex terminal-local variables A few Lisp variables are @dfn{terminal-local}; that is, they have aseparate binding for each terminal. The binding in effect at any timeis the one for the terminal that the currently selected frame belongsto. 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 cannever be buffer-local (@pxref{Buffer-Local Variables}). On GNU and Unix systems, each X display is a separate graphicalterminal. When Emacs is started from within the X window system, ituses the X display chosen with the @code{DISPLAY} environmentvariable, or with the @samp{--display} option. @xref{InitialOptions,,, emacs, The GNU Emacs Manual}. Emacs can connect to other Xdisplays via the command @code{make-frame-on-display}. Each X displayhas its own selected frame and its own minibuffer windows; however,only one of those frames is ``@emph{the} selected frame'' at any givenmoment (@pxref{Input Focus}). Emacs can even connect to othertext-only terminals, by interacting with the @command{emacsclient}program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}. A single X server can handle more than one display. Each X displayhas a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.The first two parts, @var{host} and @var{server}, identify the Xserver; the third part, @var{screen}, identifies a screen number onthat X server. When you use two or more screens belonging to oneserver, Emacs knows by the similarity in their names that they share asingle keyboard. On some ``multi-monitor'' setups, a single X display outputs to morethan one monitor. Currently, there is no way for Emacs to distinguishbetween the different physical monitors.@deffn Command make-frame-on-display display &optional parametersThis function creates and returns a new frame on @var{display}, takingthe other frame parameters from the alist @var{parameters}.@var{display} should be the name of an X display (a string).Before creating the frame, this function ensures that Emacs is ``setup'' to display graphics. For instance, if Emacs has not processed Xresources (e.g., if it was started on a text-only terminal), it doesso at this time. In all other respects, this function behaves like@code{make-frame} (@pxref{Creating Frames}).@end deffn@defun x-display-listThis function returns a list that indicates which X displays Emacs hasa connection to. The elements of the list are strings, and each oneis a display name.@end defun@defun x-open-connection display &optional xrm-string must-succeedThis function opens a connection to the X display @var{display},without creating a frame on that display. Normally, Emacs Lispprograms need not call this function, as @code{make-frame-on-display}calls it automatically. The only reason for calling it is to checkwhether communication can be established with a given X display.The optional argument @var{xrm-string}, if not @code{nil}, is a stringof resource names and values, in the same format used in the@file{.Xresources} file. @xref{X Resources,, X Resources, emacs, TheGNU Emacs Manual}. These values apply to all Emacs frames created onthis display, overriding the resource values recorded in the X server.Here's an example of what this string might look like:@example"*BorderWidth: 3\n*InternalBorder: 2\n"@end exampleIf @var{must-succeed} is non-@code{nil}, failure to open the connectionterminates Emacs. Otherwise, it is an ordinary Lisp error.@end defun@defun x-close-connection displayThis function closes the connection to display @var{display}. Beforeyou can do this, you must first delete all the frames that were openon that display (@pxref{Deleting Frames}).@end defun@node Frame Parameters@section Frame Parameters@cindex frame parameters A frame has many parameters that control its appearance and behavior.Just what parameters a frame has depends on what display mechanism ituses. Frame parameters exist mostly for the sake of window systems. Aterminal 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, theparameters @code{foreground-color}, @code{background-color},@code{background-mode} and @code{display-type} are also meaningful.If the terminal supports frame transparency, the parameter@code{alpha} is also meaningful. You can use frame parameters to define frame-local bindings forvariables. @xref{Frame-Local Variables}.@menu* Parameter Access:: How to change a frame's parameters.* Initial Parameters:: Specifying frame parameters when you make a frame.* Window Frame Parameters:: List of frame parameters for window systems.* Size and Position:: Changing the size and position of a frame.* Geometry:: Parsing geometry specifications.@end menu@node Parameter Access@subsection Access to Frame ParametersThese functions let you read and change the parameter values of aframe.@defun frame-parameter frame parameterThis function returns the value of the parameter @var{parameter} (asymbol) of @var{frame}. If @var{frame} is @code{nil}, it returns theselected frame's parameter. If @var{frame} has no setting for@var{parameter}, this function returns @code{nil}.@end defun@defun frame-parameters &optional frameThe function @code{frame-parameters} returns an alist listing all theparameters of @var{frame} and their values. If @var{frame} is@code{nil} or omitted, this returns the selected frame's parameters@end defun@defun modify-frame-parameters frame alistThis function alters the parameters of frame @var{frame} based on theelements of @var{alist}. Each element of @var{alist} has the form@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming aparameter. If you don't mention a parameter in @var{alist}, its valuedoesn't change. If @var{frame} is @code{nil}, it defaults to the selectedframe.You can use this function to define frame-local bindings forvariables, see @ref{Frame-Local Variables}.@end defun@defun set-frame-parameter frame parm valueThis function sets the frame parameter @var{parm} to the specified@var{value}. If @var{frame} is @code{nil}, it defaults to theselected frame.@end defun@defun modify-all-frames-parameters alistThis function alters the frame parameters of all existing framesaccording to @var{alist}, then modifies @code{default-frame-alist}(and, if necessary, @code{initial-frame-alist}) to apply the sameparameter values to frames that will be created henceforth.@end defun@node Initial Parameters@subsection Initial Frame ParametersYou can specify the parameters for the initial startup frameby setting @code{initial-frame-alist} in your init file (@pxref{Init File}).@defopt initial-frame-alistThis variable's value is an alist of parameter values used when creatingthe initial window frame. You can set this variable to specify theappearance of the initial frame without altering subsequent frames.Each element has the form:@example(@var{parameter} . @var{value})@end exampleEmacs creates the initial frame before it reads your initfile. After reading that file, Emacs checks @code{initial-frame-alist},and applies the parameter settings in the altered value to the alreadycreated initial frame.If these settings affect the frame geometry and appearance, you'll seethe frame appear with the wrong ones and then change to the specifiedones. If that bothers you, you can specify the same geometry andappearance with X resources; those do take effect before the frame iscreated. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.X resource settings typically apply to all frames. If you want tospecify some X resources solely for the sake of the initial frame, andyou don't want them to apply to subsequent frames, here's how to achievethis. Specify parameters in @code{default-frame-alist} to override theX resources for subsequent frames; then, to prevent these from affectingthe initial frame, specify the same parameters in@code{initial-frame-alist} with values that match the X resources.@end defoptIf these parameters specify a separate minibuffer-only frame with@code{(minibuffer . nil)}, and you have not created one, Emacs createsone for you.@defopt minibuffer-frame-alistThis variable's value is an alist of parameter values used whencreating an initial minibuffer-only frame. This is theminibuffer-only frame that Emacs creates if @code{initial-frame-alist}specifies a frame with no minibuffer.@end defopt@defopt default-frame-alistThis is an alist specifying default values of frame parameters for allEmacs frames---the first frame, and subsequent frames. When using the XWindow System, you can get the same results by means of X resourcesin many cases.Setting this variable does not affect existing frames.@end defoptFunctions that display a buffer in a separate frame can override thedefault parameters by supplying their own parameters. @xref{Definitionof special-display-frame-alist}.If you use options that specify window appearance when you invoke Emacs,they take effect by adding elements to @code{default-frame-alist}. Oneexception is @samp{-geometry}, which adds the specified position to@code{initial-frame-alist} instead. @xref{Emacs Invocation,, CommandLine Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.@node Window Frame Parameters@subsection Window Frame Parameters Just what parameters a frame has depends on what display mechanismit uses. This section describes the parameters that have specialmeanings on some or all kinds of terminals. Of these, @code{name},@code{title}, @code{height}, @code{width}, @code{buffer-list} and@code{buffer-predicate} provide meaningful information in terminalframes, and @code{tty-color-mode} is meaningful @emph{only} interminal frames.@menu* Basic Parameters:: Parameters that are fundamental.* Position Parameters:: The position of the frame on the screen.* Size Parameters:: Frame's size.* Layout Parameters:: Size of parts of the frame, and enabling or disabling some parts.* Buffer Parameters:: Which buffers have been or should be shown.* Management Parameters:: Communicating with the window manager.* Cursor Parameters:: Controlling the cursor appearance.* Font and Color Parameters:: Fonts and colors for the frame text.@end menu@node Basic Parameters@subsubsection Basic Parameters These frame parameters give the most basic information about theframe. @code{title} and @code{name} are meaningful on all terminals.@table @code@item displayThe display on which to open this frame. It should be a string of theform @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the@code{DISPLAY} environment variable.@item display-typeThis parameter describes the range of possible colors that can be usedin this frame. Its value is @code{color}, @code{grayscale} or@code{mono}.@item titleIf a frame has a non-@code{nil} title, it appears in the windowsystem's title bar at the top of the frame, and also in the mode lineof windows in that frame if @code{mode-line-frame-identification} uses@samp{%F} (@pxref{%-Constructs}). This is normally the case whenEmacs is not using a window system, and can only display one frame ata time. @xref{Frame Titles}.@item nameThe name of the frame. The frame name serves as a default for the frametitle, if the @code{title} parameter is unspecified or @code{nil}. Ifyou 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, thename is also used (instead of the name of the Emacs executable) whenlooking up X resources for the frame.@end table@node Position Parameters@subsubsection Position Parameters Position parameters' values are normally measured in pixels, but ontext-only terminals they count characters or lines instead.@table @code@item leftThe position, in pixels, of the left (or right) edge of the frame withrespect to the left (or right) edge of the screen. The value may be:@table @asis@item an integerA positive integer relates the left edge of the frame to the left edgeof the screen. A negative integer relates the right frame edge to theright screen edge.@item @code{(+ @var{pos})}This specifies the position of the left frame edge relative to the leftscreen edge. The integer @var{pos} may be positive or negative; anegative value specifies a position outside the screen.@item @code{(- @var{pos})}This specifies the position of the right frame edge relative to the rightscreen edge. The integer @var{pos} may be positive or negative; anegative value specifies a position outside the screen.@end tableSome window managers ignore program-specified positions. If you want tobe sure the position you specify is not ignored, specify anon-@code{nil} value for the @code{user-position} parameter as well.@item topThe screen position of the top (or bottom) edge, in pixels, with respectto the top (or bottom) edge of the screen. It works just like@code{left}, except vertically instead of horizontally.@item icon-leftThe screen position of the left edge @emph{of the frame's icon}, inpixels, counting from the left edge of the screen. This takes effect ifand when the frame is iconified.If you specify a value for this parameter, then you must also specifya value for @code{icon-top} and vice versa. The window manager mayignore these two parameters.@item icon-topThe screen position of the top edge @emph{of the frame's icon}, inpixels, counting from the top edge of the screen. This takes effect ifand when the frame is iconified.@item user-positionWhen you create a frame and specify its screen position with the@code{left} and @code{top} parameters, use this parameter to say whetherthe specified position was user-specified (explicitly requested in someway 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 heedprogram-specified positions too. But many ignore program-specifiedpositions, placing the window in a default fashion or letting the userplace it with the mouse. Some window managers, including @code{twm},let the user specify whether to obey program-specified positions orignore 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}.@end table@node Size Parameters@subsubsection Size Parameters Size parameters' values are normally measured in pixels, but ontext-only terminals they count characters or lines instead.@table @code@item heightThe height of the frame contents, in characters. (To get the height inpixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)@item widthThe width of the frame contents, in characters. (To get the width inpixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)@item user-sizeThis does for the size parameters @code{height} and @code{width} whatthe @code{user-position} parameter (see above) does for the positionparameters @code{top} and @code{left}.@item fullscreenSpecify that width, height or both shall be maximized.The value @code{fullwidth} specifies that width shall be as wide as possible.The value @code{fullheight} specifies that height shall be as tall aspossible. The value @code{fullboth} specifies that both thewidth and the height shall be set to the size of the screen.The value @code{maximized} specifies that the frame shall be maximized.The difference between @code{maximized} and @code{fullboth} is thatthe first does have window manager decorations but the second does notand thus really covers the whole screen.@end table@node Layout Parameters@subsubsection Layout Parameters These frame parameters enable or disable various parts of theframe, or control their sizes.@table @code@item border-widthThe width in pixels of the frame's border.@item internal-border-widthThe distance in pixels between text (or fringe) and the frame's border.@item vertical-scroll-barsWhether the frame has scroll bars for vertical scrolling, and which sideof the frame they should be on. The possible values are @code{left},@code{right}, and @code{nil} for no scroll bars.@ignore@item horizontal-scroll-barsWhether the frame has scroll bars for horizontal scrolling(non-@code{nil} means yes). Horizontal scroll bars are not currentlyimplemented.@end ignore@item scroll-bar-widthThe width of vertical scroll bars, in pixels, or @code{nil} meaning touse the default width.@item left-fringe@itemx right-fringeThe default width of the left and right fringes of windows in thisframe (@pxref{Fringes}). If either of these is zero, that effectivelyremoves the corresponding fringe. A value of @code{nil} stands forthe standard fringe width, which is the width needed to display thefringe bitmaps.The combined fringe widths must add up to an integral number ofcolumns, so the actual default fringe widths for the frame may belarger than the specified values. The extra width needed to reach anacceptable total is distributed evenly between the left and rightfringe. However, you can force one fringe or the other to a precisewidth by specifying that width as a negative integer. If both widths arenegative, only the left fringe gets the specified width.@item menu-bar-linesThe number of lines to allocate at the top of the frame for a menubar. The default is 1. A value of @code{nil} means don't display amenu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most onemenu bar line; they treat larger values as 1.)@item tool-bar-linesThe number of lines to use for the tool bar. A value of @code{nil}means don't display a tool bar. (GTK and Nextstep allow at most onetool bar line; they treat larger values as 1.)@item line-spacingAdditional space to leave below each text line, in pixels (a positiveinteger). @xref{Line Height}, for more information.@end table@node Buffer Parameters@subsubsection Buffer Parameters These frame parameters, meaningful on all kinds of terminals, dealwith which buffers have been, or should, be displayed in the frame.@table @code@item minibufferWhether this frame has its own minibuffer. The value @code{t} meansyes, @code{nil} means no, @code{only} means this frame is just aminibuffer. If the value is a minibuffer window (in some otherframe), the frame uses that minibuffer.This frame parameter takes effect when the frame is created, and cannot be changed afterwards.@item buffer-predicateThe buffer-predicate function for this frame. The function@code{other-buffer} uses this predicate (from the selected frame) todecide which buffers it should consider, if the predicate is not@code{nil}. It calls the predicate with one argument, a buffer, once foreach buffer; if the predicate returns a non-@code{nil} value, itconsiders that buffer.@item buffer-listA list of buffers that have been selected in this frame,ordered most-recently-selected first.@item unsplittableIf non-@code{nil}, this frame's window is never split automatically.@end table@node Management Parameters@subsubsection Window Management Parameters@cindex window manager, and frame parameters These frame parameters, meaningful only on window system displays,interact with the window manager.@table @code@item visibilityThe state of visibility of the frame. There are three possibilities:@code{nil} for invisible, @code{t} for visible, and @code{icon} foriconified. @xref{Visibility of Frames}.@item auto-raiseWhether selecting the frame raises it (non-@code{nil} means yes).@item auto-lowerWhether deselecting the frame lowers it (non-@code{nil} means yes).@item icon-typeThe type of icon to use for this frame when it is iconified. If thevalue is a string, that specifies a file containing a bitmap to use.Any other non-@code{nil} value specifies the default bitmap icon (apicture of a gnu); @code{nil} specifies a text icon.@item icon-nameThe name to use in the icon for this frame, when and if the iconappears. If this is @code{nil}, the frame's title is used.@item window-idThe number of the window-system window used by the frameto contain the actual Emacs windows.@item outer-window-idThe number of the outermost window-system window used for the whole frame.@item wait-for-wmIf non-@code{nil}, tell Xt to wait for the window manager to confirmgeometry changes. Some window managers, including versions of Fvwm2and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} toprevent hanging with those window managers.@item stickyIf non-@code{nil}, the frame is visible on all virtual desktops on systemswith virtual desktops.@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 otherapplication's window. (It is not certain this will be implemented; tryit and see if it works.)@end ignore@end table@node Cursor Parameters@subsubsection Cursor Parameters This frame parameter controls the way the cursor looks.@table @code@item cursor-typeHow to display the cursor. Legitimate values are:@table @code@item boxDisplay a filled box. (This is the default.)@item hollowDisplay a hollow box.@item nilDon't display a cursor.@item barDisplay a vertical bar between characters.@item (bar . @var{width})Display a vertical bar @var{width} pixels wide between characters.@item hbarDisplay a horizontal bar.@item (hbar . @var{height})Display a horizontal bar @var{height} pixels high.@end table@end table@vindex cursor-typeThe buffer-local variable @code{cursor-type} overrides the value ofthe @code{cursor-type} frame parameter, but if it is @code{t}, thatmeans to use the cursor specified for the frame.@defopt blink-cursor-alistThis variable specifies how to blink the cursor. Each element has theform @code{(@var{on-state} . @var{off-state})}. Whenever the cursortype equals @var{on-state} (comparing using @code{equal}), thecorresponding @var{off-state} specifies what the cursor looks likewhen it blinks ``off.'' Both @var{on-state} and @var{off-state}should be suitable values for the @code{cursor-type} frame parameter.There are various defaults for how to blink each type of cursor, ifthe type is not mentioned as an @var{on-state} here. Changes in thisvariable do not take effect immediately, only when you specify the@code{cursor-type} frame parameter.@end defopt@defopt cursor-in-non-selected-windowsThis variable controls how the cursor looks in a window that is notselected. It supports the same values as the @code{cursor-type} frameparameter; also, @code{nil} means don't display a cursor innonselected windows, and @code{t} (the default) means use a standardmodificatoin of the usual cursor type (solid box becomes hollow box,and bar becomes a narrower bar).@end defopt@node Font and Color Parameters@subsubsection Font and Color Parameters These frame parameters control the use of fonts and colors.@table @code@item font-backendA list of symbols, specifying the @dfn{font backends} to use fordrawing fonts in the frame, in order of priority. On X, there arecurrently two available font backends: @code{x} (the X core fontdriver) and @code{xft} (the Xft font driver). On other systems, thereis only one available font backend, so it does not make sense tomodify this frame parameter.@item background-modeThis parameter is either @code{dark} or @code{light}, accordingto whether the background color is a light one or a dark one.@item tty-color-mode@cindex standard colors for character terminalsThis parameter overrides the terminal's color support as given by thesystem's terminal capabilities database in that this parameter's valuespecifies the color mode to use in terminal frames. The value can beeither a symbol or a number. A number specifies the number of colorsto use (and, indirectly, what commands to issue to produce eachcolor). For example, @code{(tty-color-mode . 8)} specifies use of theANSI escape sequences for 8 standard text colors. A value of -1 turnsoff color support.If the parameter's value is a symbol, it specifies a number throughthe value of @code{tty-color-mode-alist}, and the associated number isused instead.@item screen-gamma@cindex gamma correctionIf this is a number, Emacs performs ``gamma correction'' which adjuststhe brightness of all colors. The value should be the screen gamma ofyour display, a floating point number.Usual PC monitors have a screen gamma of 2.2, so color values inEmacs, and in X windows generally, are calibrated to display properlyon a monitor with that gamma value. If you specify 2.2 for@code{screen-gamma}, that means no correction is needed. Other valuesrequest correction, designed to make the corrected colors appear onyour screen the way they would have appeared without correction on anordinary monitor with a gamma value of 2.2.If your monitor displays colors too light, you should specify a@code{screen-gamma} value smaller than 2.2. This requests correctionthat makes colors darker. A screen gamma value of 1.5 may give goodresults for LCD color displays.@item alpha@cindex opacity, frame@cindex transparency, frame@vindex frame-alpha-lower-limitThis parameter specifies the opacity of the frame, on graphicaldisplays that support variable opacity. It should be an integerbetween 0 and 100, where 0 means completely transparent and 100 meanscompletely opaque. It can also have a @code{nil} value, which tellsEmacs not to set the frame opacity (leaving it to the window manager).To prevent the frame from disappearing completely from view, thevariable @code{frame-alpha-lower-limit} defines a lower opacity limit.If the value of the frame parameter is less than the value of thisvariable, Emacs uses the latter. By default,@code{frame-alpha-lower-limit} is 20.The @code{alpha} frame parameter can also be a cons cell@code{(@samp{active} . @samp{inactive})}, where @samp{active} is theopacity of the frame when it is selected, and @samp{inactive} is theopactity when it is not selected.@end tableThe following frame parameters are semi-obsolete in that they areautomatically equivalent to particular face attributes of particularfaces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):@table @code@item fontThe name of the font for displaying text in the frame. This is astring, either a valid font name for your system or the name of an Emacsfontset (@pxref{Fontsets}). It is equivalent to the @code{font}attribute of the @code{default} face.@item foreground-colorThe color to use for the image of a character. It is equivalent tothe @code{:foreground} attribute of the @code{default} face.@item background-colorThe color to use for the background of characters. It is equivalent tothe @code{:background} attribute of the @code{default} face.@item mouse-colorThe color for the mouse pointer. It is equivalent to the @code{:background}attribute of the @code{mouse} face.@item cursor-colorThe color for the cursor that shows point. It is equivalent to the@code{:background} attribute of the @code{cursor} face.@item border-colorThe color for the border of the frame. It is equivalent to the@code{:background} attribute of the @code{border} face.@item scroll-bar-foregroundIf non-@code{nil}, the color for the foreground of scroll bars. It isequivalent to the @code{:foreground} attribute of the@code{scroll-bar} face.@item scroll-bar-backgroundIf non-@code{nil}, the color for the background of scroll bars. It isequivalent to the @code{:background} attribute of the@code{scroll-bar} face.@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 theframe parameters @code{left}, @code{top}, @code{height}, and@code{width}. Whatever geometry parameters you don't specify are chosenby the window manager in its usual fashion. Here are some special features for working with sizes and positions.(For the precise meaning of ``selected frame'' used by these functions,see @ref{Input Focus}.)@defun set-frame-position frame left topThis function sets the position of the top left corner of @var{frame} to@var{left} and @var{top}. These arguments are measured in pixels, andnormally count from the top left corner of the screen.Negative parameter values position the bottom edge of the window up fromthe bottom edge of the screen, or the right window edge to the left ofthe right edge of the screen. It would probably be better if the valueswere always counted from the left and top, so that negative argumentswould 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 frameThese functions return the height and width of @var{frame}, measured inlines and columns. If you don't supply @var{frame}, they use theselected frame.@end defun@defun frame-pixel-height &optional frame@defunx frame-pixel-width &optional frameThese functions return the height and width of the main display areaof @var{frame}, measured in pixels. If you don't supply @var{frame},they use the selected frame.These values include the internal borders, and windows' scroll barsand fringes (which belong to individual windows, not to the frameitself), but do not include menu bars or tool bars (except when usingX without an X toolkit).@end defun@defun frame-char-height &optional frame@defunx frame-char-width &optional frameThese functions return the height and width of a character in@var{frame}, measured in pixels. The values depend on the choice offont. If you don't supply @var{frame}, these functions use the selectedframe.@end defun@defun set-frame-size frame cols rowsThis function sets the size of @var{frame}, measured in characters;@var{cols} and @var{rows} specify the new width and height.To set the size based on values measured in pixels, use@code{frame-char-height} and @code{frame-char-width} to convertthem to units of characters.@end defun@defun set-frame-height frame lines &optional pretendThis function resizes @var{frame} to a height of @var{lines} lines. Thesizes of existing windows in @var{frame} are altered proportionally tofit.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 theactual height of the frame. This is only useful for a terminal frame.Using a smaller height than the terminal actually implements may beuseful to reproduce behavior observed on a smaller screen, or if theterminal malfunctions when using its whole screen. Setting the frameheight ``for real'' does not always work, because knowing the correctactual size may be necessary for correct cursor positioning on aterminal frame.@end defun@defun set-frame-width frame width &optional pretendThis 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 thescreen, in Emacs versions that did not support multiple frames. Theyare semi-obsolete, but still work; they apply to the selected frame.@node Geometry@subsection Geometry Here's how to examine the data in an X-style window geometryspecification:@defun x-parse-geometry geom@cindex geometry specificationThe function @code{x-parse-geometry} converts a standard X windowgeometry string to an alist that you can use as part of the argument to@code{make-frame}.The alist describes which parameters were specified in @var{geom}, andgives the values specified for them. Each element looks like@code{(@var{parameter} . @var{value})}. The possible @var{parameter}values are @code{left}, @code{top}, @code{width}, and @code{height}.For the size parameters, the value must be an integer. The positionparameter names @code{left} and @code{top} are not totally accurate,because some values indicate the position of the right or bottom edgesinstead. The @var{value} possibilities for the position parameters are:an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};as previously described (@pxref{Position Parameters}).Here is an example:@example(x-parse-geometry "35x70+0-0") @result{} ((height . 70) (width . 35) (top - 0) (left . 0))@end example@end defun@node Terminal Parameters@section Terminal Parameters@cindex terminal parameters Each terminal has a list of associated parameters. These@dfn{terminal parameters} are mostly a convenient way of storage forterminal-local variables, but some terminal parameters have a specialmeaning. This section describes functions to read and change the parameter valuesof a terminal. They all accept as their argument either a terminal ora frame; the latter means use that frame's terminal. An argument of@code{nil} means the selected frame's terminal.@defun terminal-parameters &optional terminalThis function returns an alist listing all the parameters of@var{terminal} and their values.@end defun@defun terminal-parameter terminal parameterThis function returns the value of the parameter @var{parameter} (asymbol) of @var{terminal}. If @var{terminal} has no setting for@var{parameter}, this function returns @code{nil}.@end defun@defun set-terminal-parameter terminal parameter valueThis function sets the parameter @var{parm} of @var{terminal} to thespecified @var{value}, and returns the previous value of thatparameter.@end defunHere's a list of a few terminal parameters that have a specialmeaning:@table @code@item background-modeThe classification of the terminal's background color, either@code{light} or @code{dark}.@item normal-erase-is-backspaceValue is either 1 or 0, depending on whether@code{normal-erase-is-backspace-mode} is turned on or off on thisterminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.@item terminal-inittedAfter the terminal is initialized, this is set to theterminal-specific initialization function.@end table@node Frame Titles@section Frame Titles@cindex frame title Every frame has a @code{name} parameter; this serves as the defaultfor the frame title which window systems typically display at the top ofthe frame. You can specify a name explicitly by setting the @code{name}frame property. Normally you don't specify the name explicitly, and Emacs computes theframe name automatically based on a template stored in the variable@code{frame-title-format}. Emacs recomputes the name each time theframe is redisplayed.@defvar frame-title-formatThis variable specifies how to compute a name for a frame when you havenot explicitly specified one. The variable's value is actually a modeline construct, just like @code{mode-line-format}, except that the@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode LineData}.@end defvar@defvar icon-title-formatThis variable specifies how to compute the name for an iconified frame,when you have not explicitly specified the frame title. This titleappears in the icon itself.@end defvar@defvar multiple-framesThis variable is set automatically by Emacs. Its value is @code{t} whenthere are two or more frames (not counting minibuffer-only frames orinvisible frames). The default value of @code{frame-title-format} uses@code{multiple-frames} so as to put the buffer name in the frame titleonly when there is more than one frame.The value of this variable is not guaranteed to be accurate exceptwhile processing @code{frame-title-format} or@code{icon-title-format}.@end defvar@node Deleting Frames@section Deleting Frames@cindex deleting framesFrames remain potentially visible until you explicitly @dfn{delete}them. A deleted frame cannot appear on the screen, but continues toexist as a Lisp object until there are no references to it.@deffn Command delete-frame &optional frame force@vindex delete-frame-functionsThis function deletes the frame @var{frame}. Unless @var{frame} is atooltip, it first runs the hook @code{delete-frame-functions} (eachfunction gets one argument, @var{frame}). By default, @var{frame} isthe 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 @var{force} is non-@code{nil}, then you are allowed to do so.@end deffn@defun frame-live-p frameThe function @code{frame-live-p} returns non-@code{nil} if the frame@var{frame} has not been deleted. The possible non-@code{nil} returnvalues are like those of @code{framep}. @xref{Frames}.@end defun Some window managers provide a command to delete a window. These workby 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 thatcalls the function @code{delete-frame}. @xref{Misc Events}.@node Finding All Frames@section Finding All Frames@cindex frames, scanning all@defun frame-listThe function @code{frame-list} returns a list of all the live frames,i.e.@: those that have not been deleted. It is analogous to@code{buffer-list} for buffers, and includes frames on all terminals.The list that you get is newly created, so modifying the list doesn'thave any effect on the internals of Emacs.@end defun@defun visible-frame-listThis function returns a list of just the currently visible 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 minibufThe function @code{next-frame} lets you cycle conveniently through allthe frames on the current display from an arbitrary starting point. Itreturns the ``next'' frame after @var{frame} in the cycle. If@var{frame} is omitted or @code{nil}, it defaults to the selected frame(@pxref{Input Focus}).The second argument, @var{minibuf}, says which frames to consider:@table @asis@item @code{nil}Exclude minibuffer-only frames.@item @code{visible}Consider all visible frames.@item 0Consider all visible or iconified frames.@item a windowConsider only the frames using that particular window as theirminibuffer.@item anything elseConsider all frames.@end table@end defun@defun previous-frame &optional frame minibufLike @code{next-frame}, but cycles through all frames in the oppositedirection.@end defun See also @code{next-window} and @code{previous-window}, in @ref{CyclicWindow Ordering}.@node Frames and Windows@section Frames and Windows Each window is part of one and only one frame; you can get that framewith @code{window-frame}.@defun window-frame windowThis function returns the frame that @var{window} is on.@end defun All the non-minibuffer windows in a frame are arranged in a cyclicorder. The order runs from the frame's top window, which is at theupper left corner, down and to the right, until it reaches the window atthe lower right corner (always the minibuffer window, if the frame hasone), and then it moves back to the top. @xref{Cyclic Window Ordering}.@defun frame-first-window &optional frameThis returns the topmost, leftmost window of frame @var{frame}.If omitted or @code{nil}, @var{frame} defaults to the selected frame.@end defunAt any time, exactly one window on any frame is @dfn{selected within theframe}. The significance of this designation is that selecting theframe also selects this window. Conversely, selecting a window forEmacs with @code{select-window} also makes that window selected withinits frame. @xref{Selecting Windows}.@defun frame-selected-window &optional frameThis function returns the window on @var{frame} that is selectedwithin @var{frame}. If omitted or @code{nil}, @var{frame} defaults tothe selected frame.@end defun@defun set-frame-selected-window frame window &optional norecordThis sets the selected window of frame @var{frame} to @var{window}.If @var{frame} is @code{nil}, it operates on the selected frame. If@var{frame} is the selected frame, this makes @var{window} theselected window. This function returns @var{window}.Optional argument @var{norecord} non-@code{nil} means to neither changethe order of recently selected windows nor the buffer list (@pxref{TheBuffer List}).@end defun Another function that (usually) returns one of the windows in a givenframe is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.@node Minibuffers and Frames@section Minibuffers and FramesNormally, each frame has its own minibuffer window at the bottom, whichis used whenever that frame is selected. If the frame has a minibuffer,you can get it with @code{minibuffer-window} (@pxref{Definition ofminibuffer-window}).However, you can also create a frame with no minibuffer. Such a framemust use the minibuffer window of some other frame. When you create theframe, you can specify explicitly the minibuffer window to use (in someother frame). If you don't, then the minibuffer is found in the framewhich is the value of the variable @code{default-minibuffer-frame}. Itsvalue should be a frame that does have a minibuffer.If you use a minibuffer-only frame, you might want that frame to raisewhen you enter the minibuffer. If so, set the variable@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.@defvar default-minibuffer-frameThis variable specifies the frame to use for the minibuffer window, bydefault. It does not affect existing frames. It is always local tothe current terminal and cannot be buffer-local. @xref{MultipleTerminals}.@end defvar@node Input Focus@section Input Focus@cindex input focus@c @cindex selected frame Duplicates selected-frameAt any time, one frame in Emacs is the @dfn{selected frame}. The selectedwindow always resides on the selected frame.When Emacs displays its frames on several terminals (@pxref{MultipleTerminals}), each terminal has its own selected frame. But only oneof these is ``@emph{the} selected frame'': it's the frame that belongsto the terminal from which the most recent input came. That is, whenEmacs runs a command that came from a certain terminal, the selectedframe is the one of that terminal. Since Emacs runs only a singlecommand at any given time, it needs to consider only one selectedframe at a time; this frame is what we call @dfn{the selected frame}in this manual. The display on which the selected frame is shown isthe @dfn{selected frame's display}.@defun selected-frameThis function returns the selected frame.@end defunSome window systems and window managers direct keyboard input to thewindow object that the mouse is in; others require explicit clicks orcommands to @dfn{shift the focus} to various window objects. Eitherway, Emacs automatically keeps track of which frame has the focus. Toexplicitly switch to a different frame from a Lisp function, call@code{select-frame-set-input-focus}.Lisp programs can also switch frames ``temporarily'' by calling thefunction @code{select-frame}. This does not alter the window system'sconcept of focus; rather, it escapes from the window manager's controluntil that control is somehow reasserted.When using a text-only terminal, only one frame can be displayed at atime on the terminal, so after a call to @code{select-frame}, the nextredisplay actually displays the newly selected frame. This frameremains selected until a subsequent call to @code{select-frame}. Eachterminal frame has a number which appears in the mode line before thebuffer name (@pxref{Mode Line Variables}).@defun select-frame-set-input-focus frameThis function selects @var{frame}, raises it (should it happen to beobscured by other frames) and tries to give it the X server's focus. Ona text-only terminal, the next redisplay displays the new frame on theentire terminal screen. The return value of this function is notsignificant.@end defun@c ??? This is not yet implemented properly.@defun select-frame frame &optional norecordThis function selects frame @var{frame}, temporarily disregarding thefocus of the X server if any. The selection of @var{frame} lasts untilthe next time the user does something to select a different frame, oruntil the next time this function is called. (If you are using awindow system, the previously selected frame may be restored as theselected frame after return to the command loop, because it still mayhave the window system's input focus.)The specified @var{frame} becomes the selected frame, as explainedabove, and the terminal that @var{frame} is on becomes the selectedterminal. The window selected within @var{frame} becomes the selectedwindow. This function returns @var{frame}, or @code{nil} if @var{frame}has been deleted.Optional argument @var{norecord} non-@code{nil} means to neither changethe order of recently selected windows nor the buffer list. @xref{TheBuffer List}.In general, you should never use @code{select-frame} in a way that couldswitch to a different terminal without switching back when you're done.@end defunEmacs cooperates with the window system by arranging to select frames asthe server and window manager request. It does so by generating aspecial kind of input event, called a @dfn{focus} event, whenappropriate. The command loop handles a focus event by calling@code{handle-switch-frame}. @xref{Focus Events}.@deffn Command handle-switch-frame frameThis function handles a focus event by selecting frame @var{frame}.Focus events normally do their job by invoking this command.Don't call it for any other reason.@end deffn@defun redirect-frame-focus frame &optional focus-frameThis function redirects focus from @var{frame} to @var{focus-frame}.This means that @var{focus-frame} will receive subsequent keystrokes andevents intended for @var{frame}. After such an event, the value of@code{last-event-frame} will be @var{focus-frame}. Also, switch-frameevents specifying @var{frame} will instead select @var{focus-frame}.If @var{focus-frame} is omitted or @code{nil}, that cancels any existingredirection for @var{frame}, which therefore once again receives its ownevents.One use of focus redirection is for frames that don't have minibuffers.These frames use minibuffers on other frames. Activating a minibufferon another frame redirects focus to that frame. This puts the focus onthe minibuffer's frame, where it belongs, even though the mouse remainsin the frame that activated the minibuffer.Selecting a frame can also change focus redirections. Selecting frame@code{bar}, when @code{foo} had been selected, changes any redirectionspointing to @code{foo} so that they point to @code{bar} instead. Thisallows focus redirection to work properly when the user switches fromone frame to another using @code{select-window}.This means that a frame whose focus is redirected to itself is treateddifferently from a frame whose focus is not redirected.@code{select-frame} affects the former but not the latter.The redirection lasts until @code{redirect-frame-focus} is called tochange it.@end defun@defopt focus-follows-mouseThis option is how you inform Emacs whether the window manager transfersfocus 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 aposition consistent with the new selected frame.@end defopt@node Visibility of Frames@section Visibility of Frames@cindex visible frame@cindex invisible frame@cindex iconified frame@cindex frame visibilityA window frame may be @dfn{visible}, @dfn{invisible}, or@dfn{iconified}. If it is visible, you can see its contents, unlessother windows cover it. If it is iconified, the frame's contents donot appear on the screen, but an icon does. (Note: because of theway in which some window managers implement the concept of multipleworkspaces, or desktops, all frames on other workspaces may appear toEmacs to be iconified.) If the frame is invisible, it doesn't show onthe screen, not even as an icon.Visibility is meaningless for terminal frames, since only the selectedone is actually displayed in any case.@deffn Command make-frame-visible &optional frameThis function makes frame @var{frame} visible. If you omit@var{frame}, it makes the selected frame visible. This does not raisethe frame, but you can do that with @code{raise-frame} if you wish(@pxref{Raising and Lowering}).@end deffn@deffn Command make-frame-invisible &optional frame forceThis function makes frame @var{frame} invisible. If you omit@var{frame}, it makes the selected frame invisible.Unless @var{force} is non-@code{nil}, this function refuses to make@var{frame} invisible if all other frames are invisible..@end deffn@deffn Command iconify-frame &optional frameThis function iconifies frame @var{frame}. If you omit @var{frame}, iticonifies the selected frame.@end deffn@defun frame-visible-p frameThis returns the visibility status of frame @var{frame}. The value is@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and@code{icon} if it is iconified.On a text-only terminal, all frames are considered visible, whetherthey are currently being displayed or not, and this function returns@code{t} for all frames.@end defun The visibility status of a frame is also available as a frameparameter. You can read or change it as such. @xref{ManagementParameters}. The user can iconify and deiconify frames with the window manager.This happens below the level at which Emacs can exert any control, butEmacs does provide events that you can use to keep track of suchchanges. @xref{Misc Events}.@node Raising and Lowering@section Raising and Lowering Frames Most window systems use a desktop metaphor. Part of this metaphor isthe idea that windows are stacked in a notional third dimensionperpendicular to the screen surface, and thus ordered from ``highest''to ``lowest.'' Where two windows overlap, the one higher up coversthe one underneath. Even a window at the bottom of the stack can beseen if no other window overlaps it.@c @cindex raising a frame redundant with raise-frame@cindex lowering a frame A window's place in this ordering is not fixed; in fact, users tendto change the order frequently. @dfn{Raising} a window means movingit ``up,'' to the top of the stack. @dfn{Lowering} a window meansmoving it to the bottom of the stack. This motion is in the notionalthird dimension only, and does not change the position of the windowon the screen. With Emacs, frames constitute the windows in the metaphor sketchedabove. You can raise and lower frames using these functions:@deffn Command raise-frame &optional frameThis function raises frame @var{frame} (default, the selected frame).If @var{frame} is invisible or iconified, this makes it visible.@end deffn@deffn Command lower-frame &optional frameThis function lowers frame @var{frame} (default, the selected frame).@end deffn@defopt minibuffer-auto-raiseIf this is non-@code{nil}, activation of the minibuffer raises the framethat the minibuffer window is in.@end defoptYou can also enable auto-raise (raising automatically when a frame isselected) or auto-lower (lowering automatically when it is deselected)for any frame using frame parameters. @xref{Management Parameters}.@node Frame Configurations@section Frame Configurations@cindex frame configuration 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-configurationThis function returns a frame configuration list that describesthe current arrangement of frames and their contents.@end defun@defun set-frame-configuration configuration &optional nodeleteThis function restores the state of frames described in@var{configuration}. However, this function does not restore deletedframes.Ordinarily, this function deletes all existing frames not listed in@var{configuration}. But if @var{nodelete} is non-@code{nil}, theunwanted frames are iconified instead.@end defun@node Mouse Tracking@section Mouse Tracking@cindex mouse tracking@c @cindex tracking the mouse Duplicates track-mouse Sometimes it is useful to @dfn{track} the mouse, which means to displaysomething to indicate where the mouse is and move the indicator as themouse moves. For efficient mouse tracking, you need a way to wait untilthe mouse actually moves. The convenient way to track the mouse is to ask for events to representmouse motion. Then you can wait for motion by waiting for an event. Inaddition, you can easily handle any other sorts of events that mayoccur. That is useful, because normally you don't want to track themouse forever---only until some other event, such as the release of abutton.@defspec track-mouse body@dots{}This special form executes @var{body}, with generation of mouse motionevents enabled. Typically, @var{body} would use @code{read-event} toread the motion events and modify the display accordingly. @xref{MotionEvents}, 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 thatindicates the release of the button, or whatever kind of event meansit is time to stop tracking.@end defspecThe usual purpose of tracking mouse motion is to indicate on the screenthe consequences of pushing or releasing a button at the currentposition.In many cases, you can avoid the need to track the mouse by usingthe @code{mouse-face} text property (@pxref{Special Properties}).That works at a much lower level and runs more smoothly thanLisp-level mouse tracking.@ignore@c These are not implemented yet.These functions change the screen appearance instantaneously. Theeffect is transient, only until the next ordinary Emacs redisplay. Thatis OK for mouse tracking, since it doesn't make sense for mouse trackingto change the text, and the body of @code{track-mouse} normally readsthe events itself and does not do redisplay.@defun x-contour-region window beg endThis function draws lines to make a box around the text from @var{beg}to @var{end}, in window @var{window}.@end defun@defun x-uncontour-region window beg endThis function erases the lines that would make a box around the textfrom @var{beg} to @var{end}, in window @var{window}. Use it to removea contour that you previously made by calling @code{x-contour-region}.@end defun@defun x-draw-rectangle frame left top right bottomThis function draws a hollow rectangle on frame @var{frame} with thespecified edge coordinates, all measured in pixels from the inside topleft corner. It uses the cursor color, the one used for indicating thelocation of point.@end defun@defun x-erase-rectangle frame left top right bottomThis function erases a hollow rectangle on frame @var{frame} with thespecified edge coordinates, all measured in pixels from the inside topleft corner. Erasure means redrawing the text and background thatnormally belong in the specified rectangle.@end defun@end ignore@node Mouse Position@section Mouse Position@cindex mouse position@cindex position of mouse The functions @code{mouse-position} and @code{set-mouse-position}give access to the current position of the mouse.@defun mouse-positionThis function returns a description of the position of the mouse. Thevalue looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}and @var{y} are integers giving the position in characters relative tothe top left corner of the inside of @var{frame}.@end defun@defvar mouse-position-functionIf non-@code{nil}, the value of this variable is a function for@code{mouse-position} to call. @code{mouse-position} calls thisfunction just before returning, with its normal return value as thesole argument, and it returns whatever this function returns to it.This abnormal hook exists for the benefit of packages like@file{xt-mouse.el} that need to do mouse handling at the Lisp level.@end defvar@defun set-mouse-position frame x yThis function @dfn{warps the mouse} to position @var{x}, @var{y} inframe @var{frame}. The arguments @var{x} and @var{y} are integers,giving the position in characters relative to the top left corner of theinside of @var{frame}. If @var{frame} is not visible, this functiondoes nothing. The return value is not significant.@end defun@defun mouse-pixel-positionThis function is like @code{mouse-position} except that it returnscoordinates in units of pixels rather than units of characters.@end defun@defun set-mouse-pixel-position frame x yThis function warps the mouse like @code{set-mouse-position} except that@var{x} and @var{y} are in units of pixels rather than units ofcharacters. These coordinates are not required to be within the frame.If @var{frame} is not visible, this function does nothing. The returnvalue is not significant.@end defun@need 3000@node Pop-Up Menus@section Pop-Up Menus When using a window system, a Lisp program can pop up a menu so thatthe user can choose an alternative with the mouse.@defun x-popup-menu position menuThis function displays a pop-up menu and returns an indication ofwhat selection the user makes.The argument @var{position} specifies where on the screen to put thetop left corner of the menu. It can be either a mouse button event(which says to put the menu where the user actuated the button) or alist of this form:@example((@var{xoffset} @var{yoffset}) @var{window})@end example@noindentwhere @var{xoffset} and @var{yoffset} are coordinates, measured inpixels, counting from the top left corner of @var{window}. @var{window}may be a window or a frame.If @var{position} is @code{t}, it means to use the current mouseposition. If @var{position} is @code{nil}, it means to precompute thekey binding equivalents for the keymaps specified in @var{menu},without actually displaying or popping up the menu.The argument @var{menu} says what to display in the menu. It can be akeymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, thereturn value is the list of events corresponding to the user's choice.(This list has more than one element if the choice occurred in asubmenu.) Note that @code{x-popup-menu} does not actually execute thecommand bound to that sequence of events.Alternatively, @var{menu} can have the following form:@example(@var{title} @var{pane1} @var{pane2}...)@end example@noindentwhere each pane is a list of form@example(@var{title} @var{item1} @var{item2}...)@end exampleEach item should normally be a cons cell @code{(@var{line} . @var{value})},where @var{line} is a string, and @var{value} is the value to return ifthat @var{line} is chosen. An item can also be a string; this makes anon-selectable line in the menu.If the user gets rid of the menu without making a valid choice, forinstance by clicking the mouse away from a valid choice or by typingkeyboard input, then this normally results in a quit and@code{x-popup-menu} does not return. But if @var{position} is a mousebutton event (indicating that the user invoked the menu with themouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.@end defun @strong{Usage note:} Don't use @code{x-popup-menu} to display a menuif 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-ha} 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 insidethat command, so they cannot give any help for the menu's items. The menu bar mechanism, which lets you switch between submenus bymoving the mouse, cannot look within the definition of a command to seethat it calls @code{x-popup-menu}. Therefore, if you try to implement asubmenu using @code{x-popup-menu}, it cannot work with the menu bar inan integrated fashion. This is why all menu bar submenus areimplemented 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 shouldstill use a menu keymap to implement it. To make the contents vary, adda hook function to @code{menu-bar-update-hook} to update the contents ofthe 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 littledifferent, it always appears in the center of a frame, and it has justone level and one or more buttons. The main use of dialog boxes isfor asking questions that the user can answer with ``yes,'' ``no,''and a few other alternatives. With a single button, they can alsoforce the user to acknowledge important information. The functions@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of thekeyboard, when called from commands invoked by mouse clicks.@defun x-popup-dialog position contents &optional headerThis function displays a pop-up dialog box and returns an indication ofwhat selection the user makes. The argument @var{contents} specifiesthe alternatives to offer; it has this format:@example(@var{title} (@var{string} . @var{value})@dots{})@end example@noindentwhich looks like the list that specifies a single pane for@code{x-popup-menu}.The return value is @var{value} from the chosen alternative.As for @code{x-popup-menu}, an element of the list may be just astring instead of a cons cell @code{(@var{string} . @var{value})}.That makes a box that cannot be selected.If @code{nil} appears in the list, it separates the left-hand items fromthe right-hand items; items that precede the @code{nil} appear on theleft, and items that follow the @code{nil} appear on the right. If youdon't include a @code{nil} in the list, then approximately half theitems appear on each side.Dialog boxes always appear in the center of a frame; the argument@var{position} specifies which frame. The possible values are as in@code{x-popup-menu}, but the precise coordinates or the individualwindow don't matter; only the frame matters.If @var{header} is non-@code{nil}, the frame title for the box is@samp{Information}, otherwise it is @samp{Question}. The former is usedfor @code{message-box} (@pxref{message-box}).In some configurations, Emacs cannot display a real dialog box; soinstead it displays the same items in a pop-up menu in the center of theframe.If the user gets rid of the dialog box without making a valid choice,for instance using the window manager, then this produces a quit and@code{x-popup-dialog} does not return.@end defun@node Pointer Shape@section Pointer Shape@cindex pointer shape@cindex mouse pointer shape You can specify the mouse pointer style for particular text orimages using the @code{pointer} text property, and for images with the@code{:pointer} and @code{:map} image properties. The values you canuse in these properties are @code{text} (or @code{nil}), @code{arrow},@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and@code{hourglass}. @code{text} stands for the usual mouse pointerstyle used over text. Over void parts of the window (parts that do not correspond to anyof the buffer contents), the mouse pointer usually uses the@code{arrow} style, but you can specify a different style (one ofthose above) by setting @code{void-text-area-pointer}.@defvar void-text-area-pointerThis variable specifies the mouse pointer style for void text areas.These include the areas after the end of a line or below the last linein the buffer. The default is to use the @code{arrow} (non-text)pointer style.@end defvar When using X, you can specify what the @code{text} pointer stylereally looks like by setting the variable @code{x-pointer-shape}.@defvar x-pointer-shapeThis variable specifies the pointer shape to use ordinarily in theEmacs frame, for the @code{text} pointer style.@end defvar@defvar x-sensitive-text-pointer-shapeThis variable specifies the pointer shape to use when the mouseis over mouse-sensitive text.@end defvar These variables affect newly created frames. They do not normallyaffect existing frames; however, if you set the mouse color of aframe, that also installs the current value of those two variables.@xref{Font and Color Parameters}. The values you can use, to specify either of these pointer shapes, aredefined 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 Window System Selections@section Window System Selections@cindex selection (for window systems)The X server records a set of @dfn{selections} which permit transfer ofdata between application programs. The various selections aredistinguished by @dfn{selection types}, represented in Emacs bysymbols. X clients including Emacs can read or set the selection forany given type.@deffn Command x-set-selection type dataThis function sets a ``selection'' in the X server. It takes twoarguments: a selection type @var{type}, and the value to assign to it,@var{data}. If @var{data} is @code{nil}, it means to clear out theselection. Otherwise, @var{data} may be a string, a symbol, an integer(or a cons of two integers or list of two integers), an overlay, or acons of two markers pointing to the same buffer. An overlay or a pairof markers stands for text in the overlay or between the markers.The argument @var{data} may also be a vector of valid non-vectorselection values.Each possible @var{type} has its own selection value, which changesindependently. The usual values of @var{type} are @code{PRIMARY},@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-casenames, in accord with X Window System conventions. If @var{type} is@code{nil}, that stands for @code{PRIMARY}.This function returns @var{data}.@end deffn@defun x-get-selection &optional type data-typeThis function accesses selections set up by Emacs or by other Xclients. It takes two optional arguments, @var{type} and@var{data-type}. The default for @var{type}, the selection type, is@code{PRIMARY}.The @var{data-type} argument specifies the form of data conversion touse, to convert the raw data obtained from another X client into Lispdata. Meaningful values include @code{TEXT}, @code{STRING},@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and@code{INTEGER}. (These are symbols with upper-case names in accordwith X conventions.) The default for @var{data-type} is@code{STRING}.@end defun@cindex cut bufferThe X server also has a set of eight numbered @dfn{cut buffers} which canstore text or other data being moved between applications. Cut buffersare considered obsolete, but Emacs supports them for the sake of Xclients that still use them. Cut buffers are numbered from 0 to 7.@defun x-get-cut-buffer &optional nThis function returns the contents of cut buffer number @var{n}.If omitted @var{n} defaults to 0.@end defun@defun x-set-cut-buffer string &optional push@anchor{Definition of x-set-cut-buffer}This function stores @var{string} into the first cut buffer (cut buffer0). 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 downthrough the series of cut buffers, much like the way successive kills inEmacs move down the kill ring. In other words, the previous value ofthe first cut buffer moves into the second cut buffer, and the second tothe third, and so on through all eight cut buffers.@end defun@defopt selection-coding-systemThis variable specifies the coding system to use when reading andwriting selections or the clipboard. @xref{CodingSystems}. The default is @code{compound-text-with-extensions}, whichconverts to the text representation that X11 normally uses.@end defopt@cindex clipboard support (for MS-Windows)When Emacs runs on MS-Windows, it does not implement X selections ingeneral, but it does support the clipboard. @code{x-get-selection}and @code{x-set-selection} on MS-Windows support the text data typeonly; if the clipboard holds other types of data, Emacs treats theclipboard as empty.@defopt x-select-enable-clipboardIf this is non-@code{nil}, the Emacs yank functions consult theclipboard before the primary selection, and the kill functions store inthe clipboard as well as the primary selection. Otherwise they do notaccess the clipboard at all. The default is @code{nil} on most systems,but @code{t} on MS-Windows.@end defopt@node Drag and Drop@section Drag and Drop@vindex x-dnd-test-function@vindex x-dnd-known-types When a user drags something from another application over Emacs, that otherapplication expects Emacs to tell it if Emacs can handle the data that isdragged. The variable @code{x-dnd-test-function} is used by Emacs to determinewhat to reply. The default value is @code{x-dnd-default-test-function}which accepts drops if the type of the data to be dropped is present in@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or@code{x-dnd-known-types} if you want Emacs to accept or reject drops basedon some other criteria.@vindex x-dnd-types-alist If you want to change the way Emacs handles drop of different typesor add a new type, customize @code{x-dnd-types-alist}. This requiresdetailed knowledge of what types other applications use for drag anddrop.@vindex dnd-protocol-alist When an URL is dropped on Emacs it may be a file, but it may also beanother URL type (ftp, http, etc.). Emacs first checks@code{dnd-protocol-alist} to determine what to do with the URL. Ifthere is no match there and if @code{browse-url-browser-function} isan alist, Emacs looks for a match there. If no match is found thetext for the URL is inserted. If you want to alter Emacs behavior,you can customize these variables.@node Color Names@section Color Names@cindex color names@cindex specify color@cindex numerical RGB color specification A color name is text (usually in a string) that specifies a color.Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,are allowed; use @kbd{M-x list-colors-display} to see a list ofdefined names. You can also specify colors numerically in forms suchas @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where@var{r} specifies the red level, @var{g} specifies the green level,and @var{b} specifies the blue level. You can use either one, two,three, or four hex digits for @var{r}; then you must use the samenumber of hex digits for all @var{g} and @var{b} as well, makingeither 3, 6, 9 or 12 hex digits in all. (See the documentation of theX Window System for more details about numerical RGB specification ofcolors.) These functions provide a way to determine which color names arevalid, and what they look like. In some cases, the value depends on the@dfn{selected frame}, as described below; see @ref{Input Focus}, for themeaning of the term ``selected frame.'' To read user input of color names with completion, use@code{read-color} (@pxref{High-Level Completion, read-color}).@defun color-defined-p color &optional frameThis function reports whether a color name is meaningful. It returns@code{t} if so; otherwise, @code{nil}. The argument @var{frame} sayswhich 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 usingreally supports that color. When using X, you can ask for any definedcolor on any kind of display, and you will get some result---typically,the closest it can do. To determine whether a frame can really displaya certain color, use @code{color-supported-p} (see below).@findex x-color-defined-pThis function used to be called @code{x-color-defined-p},and that name is still supported as an alias.@end defun@defun defined-colors &optional frameThis function returns a list of the color names that are definedand supported on frame @var{frame} (default, the selected frame).If @var{frame} does not support colors, the value is @code{nil}.@findex x-defined-colorsThis function used to be called @code{x-defined-colors},and that name is still supported as an alias.@end defun@defun color-supported-p color &optional frame background-pThis returns @code{t} if @var{frame} can really display the color@var{color} (or at least something close to it). If @var{frame} isomitted or @code{nil}, the question applies to the selected frame.Some terminals support a different set of colors for foreground andbackground. If @var{background-p} is non-@code{nil}, that means you areasking whether @var{color} can be used as a background; otherwise youare asking whether it can be used as a foreground.The argument @var{color} must be a valid color name.@end defun@defun color-gray-p color &optional frameThis 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}, thequestion applies to the selected frame. If @var{color} is not a validcolor name, this function returns @code{nil}.@end defun@defun color-values color &optional frame@cindex rgb valueThis function returns a value that describes what @var{color} shouldideally look like on @var{frame}. If @var{color} is defined, thevalue is a list of three integers, which give the amount of red, theamount of green, and the amount of blue. Each integer ranges inprinciple from 0 to 65535, but some displays may not use the fullrange. This three-element list is called the @dfn{rgb values} of thecolor.If @var{color} is not defined, the value is @code{nil}.@example(color-values "black") @result{} (0 0 0)(color-values "white") @result{} (65280 65280 65280)(color-values "red") @result{} (65280 0 0)(color-values "pink") @result{} (65280 49152 51968)(color-values "hungry") @result{} nil@end exampleThe color values are returned for @var{frame}'s display. If@var{frame} is omitted or @code{nil}, the information is returned forthe selected frame's display. If the frame cannot display colors, thevalue is @code{nil}.@findex x-color-valuesThis function used to be called @code{x-color-values},and that name is still supported as an alias.@end defun@node Text Terminal Colors@section Text Terminal Colors@cindex colors on text-only terminals Text-only terminals usually support only a small number of colors,and the computer uses small integers to select colors on the terminal.This means that the computer cannot reliably tell what the selectedcolor looks like; instead, you have to inform your application whichsmall integers correspond to which colors. However, Emacs does knowthe standard set of colors and will try to use them automatically. The functions described in this section control how terminal colorsare used by Emacs. Several of these functions use or return @dfn{rgb values}, describedin @ref{Color Names}. These functions accept a display (either a frame or the name of aterminal) as an optional argument. We hope in the future to makeEmacs support different colors on different text-only terminals; thenthis argument will specify which terminal to operate on (the defaultbeing the selected frame's terminal; @pxref{Input Focus}). Atpresent, though, the @var{frame} argument has no effect.@defun tty-color-define name number &optional rgb frameThis function associates the color name @var{name} withcolor number @var{number} on the terminal.The optional argument @var{rgb}, if specified, is an rgb value, a listof three numbers that specify 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, becauseEmacs will not know what it looks like.@end defun@defun tty-color-clear &optional frameThis function clears the table of defined colors for a text-only terminal.@end defun@defun tty-color-alist &optional frameThis function returns an alist recording the known colors supported by atext-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 colorname, @var{number} is the number used to specify it to the terminal.If present, @var{rgb} is a list of three color values (for red, green,and blue) that says what the color actually looks like.@end defun@defun tty-color-approximate rgb &optional frameThis function finds the closest color, among the known colorssupported for @var{display}, to that described by the rgb value@var{rgb} (a list of color values). The return value is an element of@code{tty-color-alist}.@end defun@defun tty-color-translate color &optional frameThis function finds the closest color to @var{color} among the knowncolors supported for @var{display} and returns its index (an integer).If the name @var{color} is not defined, the value is @code{nil}.@end defun@node Resources@section X Resources@defun x-get-resource attribute class &optional component subclassThe function @code{x-get-resource} retrieves a resource value from the XWindow 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 nameunder which Emacs was invoked), and using @samp{Emacs.@var{class}} asthe class.The optional arguments @var{component} and @var{subclass} add to the keyand 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{class}.@var{subclass}}.@end defun@defvar x-resource-classThis variable specifies the application name that @code{x-get-resource}should look up. The default value is @code{"Emacs"}. You can examine Xresources for application names other than ``Emacs'' by binding thisvariable to some other string, around a call to @code{x-get-resource}.@end defvar@defvar x-resource-nameThis variable specifies the instance name that @code{x-get-resource}should look up. The default value is the name Emacs was invoked with,or the value specified with the @samp{-name} or @samp{-rn} switches.@end defvarTo illustrate some of the above, suppose that you have the line:@examplexterm.vt100.background: yellow@end example@noindentin your X resources file (whose name is usually @file{~/.Xdefaults}or @file{~/.Xresources}). Then:@example@group(let ((x-resource-class "XTerm") (x-resource-name "xterm")) (x-get-resource "vt100.background" "VT100.Background")) @result{} "yellow"@end group@group(let ((x-resource-class "XTerm") (x-resource-name "xterm")) (x-get-resource "background" "VT100" "vt100" "Background")) @result{} "yellow"@end group@end example @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.@node Display Feature Testing@section Display Feature Testing@cindex display feature testing The functions in this section describe the basic capabilities of aparticular display. Lisp programs can use them to adapt their behaviorto what the display can do. For example, a program that ordinarily usesa popup menu could use the minibuffer if popup menus are not supported. The optional argument @var{display} in these functions specifies whichdisplay to ask the question about. It can be a display name, a frame(which designates the display that frame is on), or @code{nil} (whichrefers to the selected frame's display, @pxref{Input Focus}). @xref{Color Names}, @ref{Text Terminal Colors}, for other functions toobtain information about displays.@defun display-popup-menus-p &optional displayThis function returns @code{t} if popup menus are supported on@var{display}, @code{nil} if not. Support for popup menus requires thatthe mouse be available, since the user cannot choose menu items withouta mouse.@end defun@defun display-graphic-p &optional displayThis function returns @code{t} if @var{display} is a graphic displaycapable of displaying several frames and several different fonts atonce. This is true for displays that use a window system such as X, andfalse for text-only terminals.@end defun@defun display-mouse-p &optional display@cindex mouse, availabilityThis function returns @code{t} if @var{display} has a mouse available,@code{nil} if not.@end defun@defun display-color-p &optional display@findex x-display-color-pThis function returns @code{t} if the screen is a color screen.It used to be called @code{x-display-color-p}, and that nameis still supported as an alias.@end defun@defun display-grayscale-p &optional displayThis function returns @code{t} if the screen can display shades of gray.(All color displays can do this.)@end defun@defun display-supports-face-attributes-p attributes &optional display@anchor{Display Face Attribute Testing}This function returns non-@code{nil} if all the face attributes in@var{attributes} are supported (@pxref{Face Attributes}).The definition of `supported' is somewhat heuristic, but basicallymeans that a face containing all the attributes in @var{attributes},when merged with the default face for display, can be represented in away that's@enumerate@itemdifferent in appearance than the default face, and@item`close in spirit' to what the attributes specify, if not exact.@end enumeratePoint (2) implies that a @code{:weight black} attribute will besatisfied by any display that can display bold, as will@code{:foreground "yellow"} as long as some yellowish color can bedisplayed, but @code{:slant italic} will @emph{not} be satisfied bythe tty display code's automatic substitution of a `dim' face foritalic.@end defun@defun display-selections-p &optional displayThis function returns @code{t} if @var{display} supports selections.Windowed displays normally support selections, but they may also besupported in some other cases.@end defun@defun display-images-p &optional displayThis function returns @code{t} if @var{display} can display images.Windowed displays ought in principle to handle images, but somesystems lack the support for that. On a display that does not supportimages, Emacs cannot display a tool bar.@end defun@defun display-screens &optional displayThis function returns the number of screens associated with the display.@end defun@defun display-pixel-height &optional displayThis function returns the height of the screen in pixels.On a character terminal, it gives the height in characters.For graphical terminals, note that on ``multi-monitor'' setups thisrefers to the pixel width for all physical monitors associated with@var{display}. @xref{Multiple Terminals}.@end defun@defun display-pixel-width &optional displayThis function returns the width of the screen in pixels.On a character terminal, it gives the width in characters.For graphical terminals, note that on ``multi-monitor'' setups thisrefers to the pixel width for all physical monitors associated with@var{display}. @xref{Multiple Terminals}.@end defun@defun display-mm-height &optional displayThis function returns the height of the screen in millimeters,or @code{nil} if Emacs cannot get that information.@end defun@defun display-mm-width &optional displayThis function returns the width of the screen in millimeters,or @code{nil} if Emacs cannot get that information.@end defun@defopt display-mm-dimensions-alistThis variable allows the user to specify the dimensions of graphicaldisplays returned by @code{display-mm-height} and@code{display-mm-width} in case the system provides incorrect values.@end defopt@defun display-backing-store &optional displayThis function returns the backing store capability of the display.Backing store means recording the pixels of windows (and parts ofwindows) that are not exposed, so that when exposed they can bedisplayed very quickly.Values can be the symbols @code{always}, @code{when-mapped}, or@code{not-useful}. The function can also return @code{nil}when the question is inapplicable to a certain kind of display.@end defun@defun display-save-under &optional displayThis function returns non-@code{nil} if the display supports theSaveUnder feature. That feature is used by pop-up windowsto save the pixels they obscure, so that they can pop downquickly.@end defun@defun display-planes &optional displayThis function returns the number of planes the display supports.This is typically the number of bits per pixel.For a tty display, it is log to base two of the number of colors supported.@end defun@defun display-visual-class &optional displayThis function returns the visual class for the screen. The value is oneof the symbols @code{static-gray}, @code{gray-scale},@code{static-color}, @code{pseudo-color}, @code{true-color}, and@code{direct-color}.@end defun@defun display-color-cells &optional displayThis function returns the number of color cells the screen supports.@end defun These functions obtain additional information specificallyabout X displays.@defun x-server-version &optional displayThis function returns the list of version numbers of the X serverrunning the display. The value is a list of three integers: the majorand minor version numbers of the X protocol, and thedistributor-specific release number of the X server software itself.@end defun@defun x-server-vendor &optional displayThis function returns the ``vendor'' that provided the X serversoftware (as a string). Really this means whoever distributes the Xserver.When the developers of X labelled software distributors as``vendors,'' they showed their false assumption that no system couldever be developed and distributed noncommercially.@end defun@ignore@defvar x-no-window-managerThis variable's value is @code{t} if no X window manager is in use.@end defvar@end ignore@ignore@itemThe functions @code{x-pixel-width} and @code{x-pixel-height} return thewidth and height of an X Window frame, measured in pixels.@end ignore@ignore arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba@end ignore