@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002@c Free Software Foundation, Inc.@c See the file elisp.texi for copying conditions.@setfilename ../info/frames@node Frames, Positions, Windows, Top@chapter Frames@cindex frame A @dfn{frame} is a rectangle on the screen that contains one or moreEmacs windows. A frame initially contains a single main window (plusperhaps a minibuffer window), which you can subdivide vertically orhorizontally into smaller windows.@cindex terminal frame When Emacs runs on a text-only terminal, it starts with one@dfn{terminal frame}. If you create additional ones, Emacs displaysone and only one at any given time---on the terminal screen, of course.@cindex window frame When Emacs communicates directly with a supported window system, suchas X, it does not have a terminal frame; instead, it starts witha single @dfn{window frame}, but you can create more, and Emacs candisplay several such frames at once as is usual for window systems.@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 macThe frame is displayed on a Macintosh.@item w32The frame is displayed on MS-Windows 9X/NT.@item pcThe frame is displayed on an MS-DOS terminal.@end table@end defun@menu* Creating Frames:: Creating additional frames.* Multiple Displays:: Creating frames on other displays.* Frame Parameters:: Controlling frame size, position, font, etc.* Frame Titles:: Automatic updating of frame titles.* Deleting Frames:: Frames last until explicitly deleted.* 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 Shapes:: Specifying the shape of the mouse pointer.* Window System Selections:: Transferring text to and from other X clients.* Color Names:: Getting the definitions of color names.* Text Terminal Colors:: Defining colors for text-only terminals.* Resources:: Getting resource values from the server.* Display Feature Testing:: Determining the features of a terminal.@end menu @xref{Display}, for information about the related topic ofcontrolling Emacs redisplay.@node Creating Frames@section Creating FramesTo create a new frame, call the function @code{make-frame}.@defun make-frame &optional alistThis function creates a new frame. If you are using a supported windowsystem, it makes a window frame; otherwise, it makes a terminal frame.The argument is an alist specifying frame parameters. Any parametersnot mentioned in @var{alist} default according to the value of thevariable @code{default-frame-alist}; parameters not specified even theredefault from the standard X resources or whatever is used instead onyour system.The set of possible parameters depends in principle on what kind ofwindow system Emacs uses to display its frames. @xref{Window FrameParameters}, for documentation of individual parameters you can specify.@end defun@defvar before-make-frame-hookA normal hook run by @code{make-frame} before it actually creates theframe.@end defvar@defvar after-make-frame-functions@tindex 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@node Multiple Displays@section Multiple Displays@cindex multiple X displays@cindex displays, multiple A single Emacs can talk to more than one X display.Initially, Emacs uses just one display---the one chosen with the@code{DISPLAY} environment variable or with the @samp{--display} option(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect toanother display, use the command @code{make-frame-on-display} or specifythe @code{display} frame parameter when you create the frame. Emacs treats each X server as a separate terminal, giving each one itsown selected frame and its own minibuffer windows. However, only one ofthose frames is ``@emph{the} selected frame'' at any given moment, see@ref{Input Focus}. A few Lisp variables are @dfn{terminal-local}; that is, they have 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 can neverbe buffer-local (@pxref{Buffer-Local Variables}) or frame-local. A single X server can handle more than one screen. A display name@samp{@var{host}:@var{server}.@var{screen}} has three parts; the lastpart specifies the screen number for a given server. When you use twoscreens belonging to one server, Emacs knows by the similarity in theirnames that they share a single keyboard, and it treats them as a singleterminal.@deffn Command make-frame-on-display display &optional parametersThis creates a new frame on display @var{display}, taking the otherframe parameters from @var{parameters}. Aside from the @var{display}argument, it is like @code{make-frame} (@pxref{Creating Frames}).@end deffn@defun x-display-listThis returns a list that indicates which X displays Emacs has aconnection to. The elements of the list are strings, and each one isa display name.@end defun@defun x-open-connection display &optional xrm-string must-succeedThis function opens a connection to the X display @var{display}. Itdoes not create a frame on that display, but it permits you to checkthat communication can be established with that display.The optional argument @var{xrm-string}, if not @code{nil}, is astring of resource names and values, in the same format used in the@file{.Xresources} file. The values you specify override the resourcevalues recorded in the X server itself; they apply to all Emacs framescreated on this display. Here's an example of what this string mightlook like:@example"*BorderWidth: 3\n*InternalBorder: 2\n"@end example@xref{Resources}.If @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 open onthat display (@pxref{Deleting Frames}).@end defun@node Frame Parameters@section 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.@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.@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 parameter@tindex frame-parameterThis function returns the value of the parameter named @var{parameter}of @var{frame}. If @var{frame} is @code{nil}, it returns theselected frame's parameter.@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.@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}to apply the same parameter values to frames that will be createdhenceforth.@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}).@defvar 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 defvarIf these parameters specify a separate minibuffer-only frame with@code{(minibuffer . nil)}, and you have not created one, Emacs createsone for you.@defvar minibuffer-frame-alistThis variable's value is an alist of parameter values used when creatingan initial minibuffer-only frame---if such a frame is needed, accordingto the parameters for the main initial frame.@end defvar@defvar 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.@end defvarSee also @code{special-display-frame-alist}, in @ref{Choosing Window}.If you use options that specify window appearance when you invoke Emacs,they take effect by adding elements to @code{default-frame-alist}. Oneexception is @samp{-geometry}, which adds the specified position to@code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,The GNU Emacs Manual}.@node Window Frame Parameters@subsection Window Frame ParametersJust what parameters a frame has depends on what display mechanism ituses. Here is a table of the parameters that have special meanings in awindow frame; of these, @code{name}, @code{title}, @code{height},@code{width}, @code{buffer-list} and @code{buffer-predicate} providemeaningful information in terminal frames, and @code{tty-color-mode}is meaningful @emph{only} in terminal frames.@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 titleIf a frame has a non-@code{nil} title, it appears in the window system'sborder for the frame, and also in the mode line of windows in that frameif @code{mode-line-frame-identification} uses @samp{%F}(@pxref{%-Constructs}). This is normally the case when Emacs is notusing a window system, and can only display one frame at a 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.@item leftThe screen position of the left edge, in pixels, with respect to theleft edge of the screen. The value may be a positive number @var{pos},or a list of the form @code{(+ @var{pos})} which permits specifying anegative @var{pos} value.A negative number @minus{}@var{pos}, or a list of the form @code{(-@var{pos})}, actually specifies the position of the right edge of thewindow with respect to the right edge of the screen. A positive valueof @var{pos} counts toward the left. @strong{Reminder:} if theparameter is a negative integer @minus{}@var{pos}, then @var{pos} ispositive.Some 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 edge, in pixels, with respect to thetop edge of the screen. The value may be a positive number @var{pos},or a list of the form @code{(+ @var{pos})} which permits specifying anegative @var{pos} value.A negative number @minus{}@var{pos}, or a list of the form @code{(-@var{pos})}, actually specifies the position of the bottom edge of thewindow with respect to the bottom edge of the screen. A positive valueof @var{pos} counts toward the top. @strong{Reminder:} if theparameter is a negative integer @minus{}@var{pos}, then @var{pos} ispositive.Some 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 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.@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}.@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 height inpixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)@item fullscreenSpecify that width, height or both shall be set to the size of the screen.The value @code{fullwidth} specifies that width shall be the size of thescreen. The value @code{fullheight} specifies that height shall be thesize of the screen. The value @code{fullboth} specifies that both thewidth and the height shall be set to the size of the screen.@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 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 other frame),the new frame uses that minibuffer.@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 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 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.@item horizontal-scroll-barsWhether the frame has scroll bars for horizontal scrolling(non-@code{nil} means yes). (Horizontal scroll bars are not currentlyimplemented.)@item scroll-bar-widthThe width of the vertical scroll bar, in pixels,or @code{nil} meaning to use the default width.@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 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)} forces Emacs to usethe ANSI escape sequences for 8 standard text colors; and a value of-1 means Emacs should turn off color support. If the parameter'svalue is a symbol, that symbol is looked up in the alist@code{tty-color-mode-alist}, and if found, the associated number isused as the color support mode.@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 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 (bar . @var{width})Display a horizontal bar @var{width} pixels high.@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.@item border-widthThe width in pixels of the window border.@item internal-border-widthThe distance in pixels between text and border.@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 frame or the other to a precisewidth by specifying that width a negative integer. If both widths arenegative, only the left fringe gets the specified width.@item unsplittableIf non-@code{nil}, this frame's window is never split automatically.@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 menu-bar-linesThe number of lines to allocate at the top of the frame for a menu bar.The default is 1. @xref{Menu Bar}. (In Emacs versions that use the Xtoolkit or GTK, there is only one menu bar line; all that matters about thenumber you specify is whether it is greater than zero.)@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 they 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 tool-bar-linesThe number of lines to use for the toolbar. A value of @code{nil} meansdon't display a tool bar. (In Emacs versions that use GTK, there isonly one tool bar line; all that matters about the number you specifyis whether it is greater than zero.)@item line-spacingAdditional space put below text lines in pixels (a positive integer).@ignore@item parent-id@c ??? Not yet working.The X window number of the window that should be the parent of this one.Specifying this lets you create an Emacs window inside some otherapplication's window. (It is not certain this will be implemented; tryit and see if it works.)@end ignore@end table@defvar 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}), Emacs uses@var{off-state} to specify what the cursor looks like when it blinks``off''. Both @var{on-state} and @var{off-state} should be suitablevalues for the @code{cursor-type} frame parameter.There are various defaults for how to blink each type of cursor,if the type is not mentioned as an @var{on-state} here. Changesin this variable do not take effect immediately, because the variableis examined only when you specify a cursor type for a frame.@end defvarThese frame parameters are semi-obsolete in that they are automaticallyequivalent to particular face attributes of particular faces.@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.@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.@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 screen-height@defunx screen-widthThese functions are old aliases for @code{frame-height} and@code{frame-width}. When you are using a non-window terminal, the sizeof the frame is normally the same as the size of the terminal screen.@end defun@defun frame-pixel-height &optional frame@defunx frame-pixel-width &optional frameThese functions return the height and width of @var{frame}, measured inpixels. If you don't supply @var{frame}, they use the selected frame.@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.@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. These are the @var{value} possibilities for the positionparameters:@table @asis@item an integerA positive integer relates the left edge or top edge of the window tothe left or top edge of the screen. A negative integer relates theright or bottom edge of the window to the right or bottom edge of thescreen.@item @code{(+ @var{position})}This specifies the position of the left or top edge of the windowrelative to the left or top edge of the screen. The integer@var{position} may be positive or negative; a negative value specifies aposition outside the screen.@item @code{(- @var{position})}This specifies the position of the right or bottom edge of the windowrelative to the right or bottom edge of the screen. The integer@var{position} may be positive or negative; a negative value specifies aposition outside the screen.@end tableHere is an example:@example(x-parse-geometry "35x70+0-0") @result{} ((height . 70) (width . 35) (top - 0) (left . 0))@end example@end defun@node Frame Titles@section Frame Titles 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}. @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.@end defvar@node Deleting Frames@section Deleting Frames@cindex deletion of 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. There is noway to cancel the deletion of a frame aside from restoring a saved frameconfiguration (@pxref{Frame Configurations}); this is similar to theway windows behave.@deffn Command delete-frame &optional frame force@vindex delete-frame-functionsThis function deletes the frame @var{frame} after running the hook@code{delete-frame-functions} (each function gets one argument,@var{frame}). By default, @var{frame} is the selected frame.A frame cannot be deleted if its minibuffer is used by other frames.Normally, you cannot delete a frame if all other frames are invisible,but if the @var{force} is non-@code{nil}, then you are allowed to do so.@end deffn@defun frame-live-p frameThe function @code{frame-live-p} returns non-@code{nil} if the frame@var{frame} has not been deleted.@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@defun frame-listThe function @code{frame-list} returns a list of all the frames thathave not been deleted. It is analogous to @code{buffer-list} forbuffers, and includes frames on all terminals. The list that you get isnewly created, so modifying the list doesn't have any effect on theinternals 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 the 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. You can get the frame's currentselected window with @code{frame-selected-window}.@defun frame-selected-window &optional frameThis function returns the window on @var{frame} that is selected within@var{frame}. If omitted or @code{nil}, @var{frame} defaults to the selected frame.@end defun@defun set-frame-selected-window frame windowThis 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.@end defun Conversely, selecting a window for Emacs with @code{select-window} alsomakes that window selected within its frame. @xref{Selecting Windows}. Another function that (usually) returns one of the windows in a givenframe is @code{minibuffer-window}. @xref{Minibuffer Misc}.@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{Minibuffer Misc}).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 is always local to the current terminal and cannot bebuffer-local. @xref{Multiple Displays}.@end defvar@node Input Focus@section Input Focus@cindex input focus@cindex 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{MultipleDisplays}), each terminal has its own selected frame. But only one ofthese is ``@emph{the} selected frame'': it's the frame that belongs tothe terminal from which the most recent input came. That is, when Emacsruns a command that came from a certain terminal, the selected frame isthe one of that terminal. Since Emacs runs only a single command at anygiven time, it needs to consider only one selected frame at a time; thisframe is what we call @dfn{the selected frame} in this manual. Thedisplay on which the selected frame is displayed is the @dfn{selectedframe'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.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 the selected terminal frame isactually displayed on the terminal. @code{switch-frame} is the only wayto switch frames, and the change lasts until overridden by a subsequentcall to @code{switch-frame}. Each terminal screen except for theinitial one has a number, and the number of the selected frame appearsin the mode line before the buffer name (@pxref{Mode Line Variables}).@c ??? This is not yet implemented properly.@defun select-frame frameThis 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. The specified @var{frame}becomes the selected frame, as explained above, and the terminal that@var{frame} is on becomes the selected terminal.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. If it isiconified, the frame's contents do not appear on the screen, but an icondoes. If the frame is invisible, it doesn't show on the screen, noteven 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.@end deffn@deffn Command make-frame-invisible &optional frameThis function makes frame @var{frame} invisible. If you omit@var{frame}, it makes the selected frame 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.@end defun The visibility status of a frame is also available as a frameparameter. You can read or change it as such. @xref{Window FrameParameters}. 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.@cindex raising a 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. You can raise and lower Emacs frame Windows with these functions:@deffn Command raise-frame &optional frameThis function raises frame @var{frame} (default, the selected frame).@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{Window Frame 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}.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@cindex tracking the mouseSometimes 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 themenu. It can be either a mouse button event (which says to put the menuwhere the user actuated the button) or a list 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}'s 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}). Alternatively, itcan 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{line} . @var{item})...)@end exampleEach @var{line} should be a string, and each @var{item} should be thevalue to return if that @var{line} is chosen.@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 pane. The main use of dialog boxes is for askingquestions that the user can answer with ``yes'', ``no'', and a few otheralternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} usedialog boxes instead of the keyboard, when called from commands invokedby mouse clicks.@defun x-popup-dialog position contentsThis 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.An element of the list may be just a string instead of a cons cell@code{(@var{string} . @var{value})}. That makes a box that cannotbe 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 don't matter; only theframe matters.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.@end defun@node Pointer Shapes@section Pointer Shapes@cindex pointer shape@cindex mouse pointer shape These variables specify which shape to use for the mouse pointer invarious situations, when using the X Window System:@table @code@item x-pointer-shape@vindex x-pointer-shapeThis variable specifies the pointer shape to use ordinarily in the Emacsframe.@item x-sensitive-text-pointer-shape@vindex x-sensitive-text-pointer-shapeThis variable specifies the pointer shape to use when the mouseis over mouse-sensitive text.@end table These variables affect newly created frames. They do not normallyaffect existing frames; however, if you set the mouse color of a frame,that also updates its pointer shapes based on the current values ofthese variables. @xref{Window Frame 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.@defun 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. The default is@code{PRIMARY}.@end defun@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{LINE_NUMBER}, @code{COLUMN_NUMBER},@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},@code{NAME}, @code{ATOM}, and @code{INTEGER}. (These are symbols withupper-case names in accord with 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@defvar selection-coding-systemThis variable specifies the coding system to use when reading andwriting selections, the clipboard, or a cut buffer. @xref{CodingSystems}. The default is @code{compound-text-with-extensions}, whichconverts to the text representation that X11 normally uses.@end defvar@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 Color Names@section Color Names 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''.@defun color-defined-p color &optional frame@tindex color-defined-pThis 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 frame@tindex defined-colorsThis function returns a list of the color names that are definedand supported on frame @var{frame} (default, the selected frame).@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-p@tindex color-supported-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 frame@tindex color-gray-pThis 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. The argument @var{color} mustbe a valid color name.@end defun@defun color-values color &optional frame@tindex color-valuesThis function returns a value that describes what @var{color} shouldideally look like. If @var{color} is defined, the value is a list ofthree integers, which give the amount of red, the amount of green, andthe amount of blue. Each integer ranges in principle from 0 to 65535,but in practice no value seems to be above 65280. This kindof three-element list is called an @dfn{rgb value}.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 for the selectedframe's display.@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 Emacs can display color on text-only terminals, starting with version21. These terminals usually support only a small number of colors, andthe computer uses small integers to select colors on the terminal. Thismeans that the computer cannot reliably tell what the selected colorlooks like; instead, you have to inform your application which smallintegers correspond to which colors. However, Emacs does know thestandard set of colors and will try to use them automatically. The functions described in this section control how terminal colorsare used by Emacs.@cindex rgb value Several of these functions use or return @dfn{rgb values}. An rgbvalue 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 in practice the largest value used is65280. These functions accept a display (either a frame or the name of aterminal) as an optional argument. We hope in the future to make Emacssupport more than one text-only terminal at one time; then this argumentwill specify which terminal to operate on (the default being theselected frame's terminal; @pxref{Input Focus}). At present, though,the @var{display} argument has no effect.@defun tty-color-define name number &optional rgb display@tindex tty-color-defineThis 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; it sayswhat the color actually looks like. If you do not specify @var{rgb},then this color cannot be used by @code{tty-color-approximate} toapproximate other colors, because Emacs does not know what it lookslike.@end defun@defun tty-color-clear &optional display@tindex tty-color-clearThis function clears the table of defined colors for a text-only terminal.@end defun@defun tty-color-alist &optional display@tindex tty-color-alistThis 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 an rgb value that says what the coloractually looks like.@end defun@defun tty-color-approximate rgb &optional display@tindex tty-color-approximateThis function finds the closest color, among the known colors supportedfor @var{display}, to that described by the rgb value @var{rgb}.@end defun@defun tty-color-translate color &optional display@tindex tty-color-translateThis function finds the closest color to @var{color} among the knowncolors supported for @var{display}. If the name @var{color} is notdefined, the value is @code{nil}.@var{color} can be an X-style @code{"#@var{xxxyyyzzz}"} specificationinstead of an actual name. The format@code{"RGB:@var{xx}/@var{yy}/@var{zz}"} is also supported.@end defun@node Resources@section X Resources@defun x-get-resource attribute 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 defvar @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 display@tindex display-popup-menus-pThis 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 display@tindex display-graphic-p@cindex frames, more than one on display@cindex fonts, more than one on 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@tindex display-mouse-p@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@tindex display-color-p@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 display@tindex display-grayscale-pThis function returns @code{t} if the screen can display shades of gray.(All color displays can do this.)@end defun@defun display-supports-face-attributes-p attributes &optional display@anchor{Display Face Attribute Testing}@tindex display-supports-face-attributes-pThis 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 display@tindex display-selections-pThis 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 display@tindex display-screensThis function returns the number of screens associated with the display.@end defun@defun display-pixel-height &optional display@tindex display-pixel-heightThis function returns the height of the screen in pixels.@end defun@defun display-mm-height &optional display@tindex display-mm-heightThis function returns the height of the screen in millimeters,or @code{nil} if Emacs cannot get that information.@end defun@defun display-pixel-width &optional display@tindex display-pixel-widthThis function returns the width of the screen in pixels.@end defun@defun display-mm-width &optional display@tindex display-mm-widthThis function returns the width of the screen in millimeters,or @code{nil} if Emacs cannot get that information.@end defun@defun display-backing-store &optional display@tindex display-backing-storeThis 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 display@tindex display-save-underThis 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 display@tindex display-planesThis function returns the number of planes the display supports.This is typically the number of bits per pixel.For a tty display, it is log to base two of the number of colours supported.@end defun@defun display-visual-class &optional display@tindex display-visual-classThis 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 display@tindex display-color-cellsThis 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.@end defun@defun x-server-vendor &optional displayThis function returns the vendor that provided the X server software.@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