@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions.@setfilename ../info/frames@node Frames, Positions, Windows, Top@chapter Frames@cindex frame A @var{frame} is a rectangle on the screen that contains one or 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@cindex X window frame When Emacs runs on a text-only terminal, it has just one frame, a@dfn{terminal frame}. There is no way to create another terminal frameafter startup. If Emacs has an X display, it does not have a terminalframe; instead, it starts with a single @dfn{X window frame}. You cancreate more; see @ref{Creating Frames}.@defun framep objectThis predicate returns @code{t} if @var{object} is a frame, and@code{nil} otherwise.@end defun@menu* Creating Frames:: Creating additional X Window frames.* Frame Parameters:: Controlling frame size, position, font, etc.* 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 X windows; lowering it makes the others hide them.* Frame Configurations:: Saving the state of all frames.* Mouse Tracking:: Getting events that say when the mouse moves.* 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.* X Selections:: Transferring text to and from other X clients.* X Connections:: Opening and closing the X server connection.* Resources:: Getting resource values from the server.* Server Data:: Getting info about the X server.@end menu @xref{Display}, for related information.@node Creating Frames@section Creating FramesTo create a new frame, call the function @code{make-frame}.@defun make-frame alistThis function creates a new frame, if the display mechanism permitscreation of frames. (An X server does; an ordinary terminal does not.)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 thereeither default from the standard X defaults file and X resources.The set of possible parameters depends in principle on what kind ofwindow system Emacs uses to display its frames. @xref{X FrameParameters}, for documentation of individual parameters you can specifywhen creating an X window frame.@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-hookA normal hook run by @code{make-frame} after it creates the frame.@end defvar@node Frame Parameters@section Frame ParametersA 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 for the sake of window systems. A terminal framehas a few parameters, for compatibility's sake only. You can't changethese parameters directly; the only ones that ever change are the heightand width.@menu* Parameter Access:: How to change a frame's parameters.* Initial Parameters:: Specifying frame parameters when you make a frame.* X Frame Parameters:: Individual parameters documented.* 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-parameters frameThe function @code{frame-parameters} returns an alist listing all theparameters of @var{frame} and their values.@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.@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 @file{.emacs} file.@defvar initial-frame-alistThis variable's value is an alist of parameter values used when creatingthe initial X window frame. Each element has the form:@example(@var{parameter} . @var{value})@end exampleEmacs creates the initial frame before it reads your @file{~/.emacs}file. 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, you'll see the frame appearwith the wrong geometry and then change to the specified one. If youlike, you can specify the same geometry with X resources; those do takeaffect before the frame is created. @xref{Resources X,, X Resources,emacs, The GNU Emacs Manual}.X resource settings typically apply to all frames. If you want 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,and you have not created one, Emacs creates one 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 special-display-frame-alistThe variable @code{special-display-frame-alist} specifies the frameparameters for special display frames.@end defvar@defvar default-frame-alistThis is an alist specifying default values of frame parameters forsubsequent Emacs frames (not the initial ones).@end defvarIf 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 to @code{initial-frame-alist}instead. @xref{Command Arguments,,, emacs, The GNU Emacs Manual}.@node X Frame Parameters@subsection X Window Frame ParametersJust what parameters a frame has depends on what display mechanism ituses. Here is a table of the parameters of an X window frame:@table @code@item nameThe name of the frame. Most window managers display the frame's name inthe frame's border, at the top of the frame. If you don't specify aname, and you have more than one frame, Emacs sets the frame name basedon the buffer displayed in the frame's selected window.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. The value may be@code{-} instead of a number; that represents @samp{-0} in a geometryspecification.@item topThe screen position of the top edge, in pixels. The value may be@code{-} instead of a number; that represents @samp{-0} in a geometryspecification.@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-positionNon-@code{nil} if the screen position of the frame was explicitlyrequested by the user (for example, with the @samp{-geometry} option).Nothing automatically makes this parameter non-@code{nil}; it is up toLisp programs that call @code{make-frame} to specify this parameter aswell as specifying the @code{left} and @code{top} parameters.@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 window-idThe number of the X window for the 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, a minibuffer window (in some other frame) means the newframe uses that minibuffer.@item fontThe name of the font for displaying text in the frame. This is astring.@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(non-@code{nil} means yes).@item horizontal-scroll-barsWhether the frame has scroll bars for horizontal scrolling(non-@code{nil} means yes). (Horizontal scroll bars are not currentlyimplemented.)@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 foreground-colorThe color to use for the image of a character. This is a string; the Xserver defines the meaningful color names.@item background-colorThe color to use for the background of characters.@item mouse-colorThe color for the mouse pointer.@item cursor-colorThe color for the cursor that shows point.@item border-colorThe color for the border of the frame.@item cursor-typeThe way to display the cursor. There are two legitimate values:@code{bar} and @code{box}. The symbol @code{bar} specifies a verticalbar between characters as the cursor. The symbol @code{box} specifiesan ordinary black box overlaying the character after point; that is thedefault.@item border-widthThe width in pixels of the window border.@item internal-border-widthThe distance in pixels between text and border.@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, there is only one menu bar line; all that matters about thenumber you specify is whether it is greater than zero.)@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 table@node Size and Position@subsection Frame Size And Position 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:@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 measuredin pixels, counting from the top left corner of the screen.@end defun@defun frame-height &optional frame@defunx frame-width &optional frameThese functions return the height and width of @var{frame}, measured incharacters. If you don't supply @var{frame}, they use the selectedframe.@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 The old-fashioned functions @code{set-screen-height} and@code{set-screen-width}, which were used to specify the height and widthof the screen in Emacs versions that did not support multiple frames,are still usable. They apply to the selected frame. @xref{ScreenSize}.@defun x-parse-geometry geom@cindex geometry specificationThe function @code{x-parse-geometry} converts a standard X windowsgeometry 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}.@smallexample(x-parse-geometry "35x70+0-0") @result{} ((width . 35) (height . 70) (left . 0) (top . -1))@end smallexample@end defun@ignoreNew functions @code{set-frame-height} and @code{set-frame-width} set thesize of a specified frame. The frame is the first argument; the size isthe second.@end ignore@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 frameThis function deletes the frame @var{frame}. By default, @var{frame} isthe selected frame.@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@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. The list that you get is newly created, so modifying the listdoesn't have 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}.@end defun@defun next-frame &optional frame minibufThe function @code{next-frame} lets you cycle conveniently through allthe frames from an arbitrary starting point. It returns the ``next''frame after @var{frame} in the cycle. If @var{frame} is omitted or@code{nil}, it defaults to the selected frame.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 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@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.@defun frame-top-window frameThis returns the topmost, leftmost window of frame @var{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 frameThis function returns the window on @var{frame} that is selected within@var{frame}.@end defunConversely, selecting a window for Emacs with @code{select-window} alsomakes that window selected within its frame. @xref{Selecting Windows}.@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 frame on which to find theminibuffer to use. If you don't, then the minibuffer is found in theframe which is the value of the variable@code{default-minibuffer-frame}. Its value should be a frame that doeshave 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}.@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.@defun selected-frameThis function returns the selected frame.@end defunThe X server normally directs keyboard input to the X window that themouse is in. Some window managers use mouse clicks or keyboard eventsto @dfn{shift the focus} to various X windows, overriding the normalbehavior of the server.Lisp programs can switch frames ``temporarily'' by callingthe function @code{select-frame}. This does not override the windowmanager; rather, it escapes from the window manager's control untilthat control is somehow reasserted.@c ??? This is not yet implemented properly.@defun select-frame frameThis function selects frame @var{frame}, temporarily disregarding thefocus of the X server. The selection of @var{frame} lasts until thenext time the user does something to select a different frame, or untilthe next time this function is called.@end defunEmacs cooperates with the X server and the window managers by arrangingto select frames according to what the server and window manager askfor. It does so by generating a special kind of input event, called a@dfn{focus} event. The command loop handles a focus event by calling@code{handle-select-frame}. @xref{Focus Events}.@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 focus-frameThis function redirects focus from @var{frame} to @var{focus-frame}.This means that @var{focus-frame} will receive subsequent keystrokesintended 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 @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@node Visibility of Frames@section Visibility of Frames@cindex visible frame@cindex invisible frame@cindex iconified frame@cindex frame visibilityA frame may be @dfn{visible}, @dfn{invisible}, or @dfn{iconified}. Ifit is visible, you can see its contents. If it is iconified, theframe's contents do not appear on the screen, but an icon does. If theframe is invisible, it doesn't show on the screen, not even as an icon.@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{X FrameParameters}.@node Raising and Lowering@section Raising and Lowering FramesThe X Window System uses 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 covers theone underneath. Even a window at the bottom of the stack can be seen ifno other window overlaps it.@cindex raising a frame@cindex lowering a frameA window's place in this ordering is not fixed; in fact, users tend tochange the order frequently. @dfn{Raising} a window means moving it``up'', to the top of the stack. @dfn{Lowering} a window means movingit to the bottom of the stack. This motion is in the notional thirddimension only, and does not change the position of the window on thescreen.You can raise and lower Emacs's X windows with these functions:@defun raise-frame frameThis function raises frame @var{frame}.@end defun@defun lower-frame frameThis function lowers frame @var{frame}.@end defun@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{X 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.@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 configurationThis function restores the state of frames described in@var{configuration}.@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{}Execute @var{body}, meanwhile generating input events for mouse motion.The code in @var{body} can read these events with @code{read-event} or@code{read-key-sequence}. @xref{Motion Events}, for the format of mousemotion events.The value of @code{track-mouse} is that of the last form in @var{body}.@end defspecThe usual purpose of tracking mouse motion is to indicate on the screenthe consequences of pushing or releasing a button at the currentposition.@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@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}.@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.@end defun@need 3000@node Pop-Up Menus@section Pop-Up Menus@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 menu ifa prefix key with a menu keymap would do the job. If you use a menukeymap to implement a menu, @kbd{C-h c} and @kbd{C-h a} can see theindividual items in that menu and provide help for them. If instead youimplement the menu by defining a command that calls @code{x-popup-menu},the help facilities cannot know what happens inside that command, sothey cannot give any help for the menu's items. This is the reason whyall the menu bar items except @samp{Buffers} are implemented with menukeymaps (@pxref{Menu Keymaps}).@node Dialog Boxes@section Dialog Boxes@cindex dialog boxes A dialog box is a variant of a pop-up menu. It looks a littledifferent (if Emacs uses an X toolkit), it always appears in the centerof a frame, and it has just one level and one pane. The main use ofdialog boxes is for asking questions that the user can answer with``yes'', ``no'', and a few other alternatives. The functions@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of thekeyboard, when called from commands invoked by 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.If your Emacs executable does not use an X toolkit, then it cannotdisplay a real dialog box; so instead it displays the same items in apop-up menu in the center of the frame.@end defun@node Pointer Shapes@section Pointer Shapes@cindex pointer shape@cindex mouse pointer shape These variables specify which mouse pointer shape to use in varioussituations:@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{X Frame Parameters}. The values you can use, to specify either of these pointer shapes, aredefined in the file @file{lisp/x-win.el}. Use @kbd{M-x apropos@key{RET} x-pointer @key{RET}} to see a list of them.@node X Selections@section X Selections@cindex selection (for X windows)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 data may also be a vector of valid non-vector selection values.Each possible @var{type} has its own selection value, which changesindependently. The usual values of @var{type} are @code{PRIMARY} and@code{SECONDARY}; these are symbols with upper-case names, in accordwith 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{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 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.@defun x-get-cut-buffer nThis function returns the contents of cut buffer number @var{n}.@end defun@defun x-set-cut-buffer stringThis function stores @var{string} into the first cut buffer (cut buffer0), moving the other values down through the series of cut buffers, muchlike the way successive kills in Emacs move down the kill ring.@end defun@node X Connections@section X ConnectionsYou can close the connection with the X server with the function@code{x-close-current-connection}, and open a new one with@code{x-open-connection} (perhaps with a different server and display).@defun x-close-current-connectionThis function closes the connection to the X server. It deletes allframes, making Emacs effectively inaccessible to the user; therefore, aLisp program that closes the connection should open another one.@end defun@defun x-open-connection display &optional resource-stringThis function opens a connection to an X server, for use of display@var{display}.The optional argument @var{resource-string} is a string of resourcenames and values, in the same format used in the @file{.Xresources}file. The values you specify override the resource values recorded inthe X server itself. Here's an example of what this string might looklike:@example"*BorderWidth: 3\n*InternalBorder: 2\n"@end example@xref{Resources}.@end defun@defun x-display-color-pThis returns @code{t} if the connected X display has color, and@code{nil} otherwise.@end defun@defun x-color-defined-p colorThis function reports whether a color name is meaningful. It returns@code{t} if so; otherwise, @code{nil}.Note that this does not tell you whether the display you are usingreally supports that color. You can ask for any defined color on anykind of display, and you will get some result---that is how the X serverworks. Here's an approximate way to test whether your display supportsthe color @var{color}:@example(defun x-color-supported-p (color) (and (x-color-defined-p color) (or (x-display-color-p) (member color '("black" "white")) (and (> (x-display-planes) 1) (equal color "gray")))))@end example@end defun@defun x-color-values colorThis 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. If @var{color} is notdefined, the value is @code{nil}.@example(x-color-values "black") @result{} (0 0 0)(x-color-values "white") @result{} (65280 65280 65280)(x-color-values "red") @result{} (65280 0 0)(x-color-values "pink") @result{} (65280 49152 51968)(x-color-values "hungry") @result{} nil@end example@end defun@defun x-synchronize flagThe function @code{x-synchronize} enables or disables synchronouscommunication with the X server. It enables synchronous communicationif @var{flag} is non-@code{nil}, and disables it if @var{flag} is@code{nil}.In synchronous mode, Emacs waits for a response to each X protocolcommand before doing anything else. This is useful for debugging Emacs,because protocol errors are reported right away, which helps you findthe erroneous command. Synchronous mode is not the default because itis much slower.@end defun@node Resources@section X Resources@defun x-get-resource attribute &optional component subclassThe function @code{x-get-resource} retrieves a resource value from the XWindows 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} as the 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{subclass}}.@end defun @xref{Resources X, X Resources,, emacs, The GNU Emacs Manual}.@node Server Data@section Data about the X Server This section describes functions and a variable that you can use toget information about the capabilities and origin of the X server thatEmacs is displaying its frames on.@defun x-display-screensThis function returns the number of screens associated with the currentdisplay.@end defun@defun x-server-versionThis function returns the list of version numbers of the X server inuse.@end defun@defun x-server-vendorThis function returns the vendor supporting the X server in use.@end defun@defun x-display-pixel-heightThis function returns the height of this X screen in pixels.@end defun@defun x-display-mm-heightThis function returns the height of this X screen in millimeters.@end defun@defun x-display-pixel-widthThis function returns the width of this X screen in pixels.@end defun@defun x-display-mm-widthThis function returns the width of this X screen in millimeters.@end defun@defun x-display-backing-storeThis function returns the backing store capability of this screen.Values can be the symbols @code{always}, @code{when-mapped}, or@code{not-useful}.@end defun@defun x-display-save-underThis function returns non-@code{nil} if this X screen supports theSaveUnder feature.@end defun@defun x-display-planesThis function returns the number of planes this display supports.@end defun@defun x-display-visual-classThis function returns the visual class for this X screen. The value isone of the symbols @code{static-gray}, @code{gray-scale},@code{static-color}, @code{pseudo-color}, @code{true-color}, and@code{direct-color}.@end defun@defun x-display-color-pThis function returns @code{t} if the X screen in use is a colorscreen.@end defun@defun x-display-color-cellsThis function returns the number of color cells this X screen supports.@end defun@ignore@defvar x-no-window-managerThis variable's value is 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