2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/frames
6 @node Frames, Positions, Windows, Top
10 A @dfn{frame} is a rectangle on the screen that contains one or more
11 Emacs windows. A frame initially contains a single main window (plus
12 perhaps a minibuffer window), which you can subdivide vertically or
13 horizontally into smaller windows.
15 @cindex terminal frame
16 @cindex X window frame
17 When Emacs runs on a text-only terminal, it starts with one
18 @dfn{terminal frame}. If you create additional ones, Emacs displays
19 one and only one at any given time---on the terminal screen, of course.
21 When Emacs communicates directly with a supported window system, such
22 as X Windows, it does not have a terminal frame; instead, it starts with
23 a single @dfn{window frame}, but you can create more, and Emacs can
24 display several such frames at once as is usual for window systems.
27 This predicate returns @code{t} if @var{object} is a frame, and
32 * Creating Frames:: Creating additional frames.
33 * Multiple Displays:: Creating frames on other displays.
34 * Frame Parameters:: Controlling frame size, position, font, etc.
35 * Frame Titles:: Automatic updating of frame titles.
36 * Deleting Frames:: Frames last until explicitly deleted.
37 * Finding All Frames:: How to examine all existing frames.
38 * Frames and Windows:: A frame contains windows;
39 display of text always works through windows.
40 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
41 * Input Focus:: Specifying the selected frame.
42 * Visibility of Frames:: Frames may be visible or invisible, or icons.
43 * Raising and Lowering:: Raising a frame makes it hide other windows;
44 lowering it makes the others hide them.
45 * Frame Configurations:: Saving the state of all frames.
46 * Mouse Tracking:: Getting events that say when the mouse moves.
47 * Mouse Position:: Asking where the mouse is, or moving it.
48 * Pop-Up Menus:: Displaying a menu for the user to select from.
49 * Dialog Boxes:: Displaying a box to ask yes or no.
50 * Pointer Shapes:: Specifying the shape of the mouse pointer.
51 * Window System Selections:: Transferring text to and from other X clients.
52 * Font Names:: Looking up font names.
53 * Color Names:: Getting the definitions of color names.
54 * Resources:: Getting resource values from the server.
55 * Server Data:: Getting info about the X server.
58 @xref{Display}, for related information.
61 @section Creating Frames
63 To create a new frame, call the function @code{make-frame}.
65 @defun make-frame &optional alist
66 This function creates a new frame. If you are using a supported window
67 system, it makes a window frame; otherwise, it makes a terminal frame.
69 The argument is an alist specifying frame parameters. Any parameters
70 not mentioned in @var{alist} default according to the value of the
71 variable @code{default-frame-alist}; parameters not specified even there
72 default from the standard X resources or whatever is used instead on
75 The set of possible parameters depends in principle on what kind of
76 window system Emacs uses to display its frames. @xref{Window Frame
77 Parameters}, for documentation of individual parameters you can specify.
80 @tindex before-make-frame-hook
81 @defvar before-make-frame-hook
82 A normal hook run by @code{make-frame} before it actually creates the
86 @tindex after-make-frame-hook
87 @defvar after-make-frame-hook
88 An abnormal hook run by @code{make-frame} after it creates the frame.
89 Each function in @code{after-make-frame-hook} receives one argument, the
93 @node Multiple Displays
94 @section Multiple Displays
95 @cindex multiple displays
96 @cindex multiple X terminals
97 @cindex displays, multiple
99 A single Emacs can talk to more than one X Window display.
100 Initially, Emacs uses just one display---the one chosen with the
101 @code{DISPLAY} environment variable or with the @samp{--display} option
102 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
103 another display, use the command @code{make-frame-on-display} or specify
104 the @code{display} frame parameter when you create the frame.
106 Emacs treats each X server as a separate terminal, giving each one its
107 own selected frame and its own minibuffer windows. A few Lisp variables
108 have values local to the current terminal (that is, the terminal
109 corresponding to the currently selected frame): these are
110 @code{default-minibuffer-frame}, @code{defining-kbd-macro},
111 @code{last-kbd-macro}, and @code{system-key-alist}. These variables are
112 always terminal-local and can never be buffer-local or frame-local
113 (@pxref{Buffer-Local Variables}).
115 A single X server can handle more than one screen. A display name
116 @samp{@var{host}.@var{server}.@var{screen}} has three parts; the last
117 part specifies the screen number for a given server. When you use two
118 screens belonging to one server, Emacs knows by the similarity in their
119 names that they share a single keyboard, and it treats them as a single
122 @deffn Command make-frame-on-display display &optional parameters
123 This creates a new frame on display @var{display}, taking the other
124 frame parameters from @var{parameters}. Aside from the @var{display}
125 argument, it is like @code{make-frame} (@pxref{Creating Frames}).
128 @defun x-display-list
129 This returns a list that indicates which X displays Emacs has a
130 connection to. The elements of the list are strings, and each one is
134 @defun x-open-connection display &optional xrm-string
135 This function opens a connection to the X display @var{display}. It
136 does not create a frame on that display, but it permits you to check
137 that communication can be established with that display.
139 The optional argument @var{xrm-string}, if not @code{nil}, is a
140 string of resource names and values, in the same format used in the
141 @file{.Xresources} file. The values you specify override the resource
142 values recorded in the X server itself; they apply to all Emacs frames
143 created on this display. Here's an example of what this string might
147 "*BorderWidth: 3\n*InternalBorder: 2\n"
153 @defun x-close-connection display
154 This function closes the connection to display @var{display}. Before
155 you can do this, you must first delete all the frames that were open on
156 that display (@pxref{Deleting Frames}).
159 @node Frame Parameters
160 @section Frame Parameters
162 A frame has many parameters that control its appearance and behavior.
163 Just what parameters a frame has depends on what display mechanism it
166 Frame parameters exist for the sake of window systems. A terminal frame
167 has a few parameters, mostly for compatibility's sake; only the height,
168 width, @code{name}, @code{title}, @code{buffer-list} and
169 @code{buffer-predicate} parameters do something special.
172 * Parameter Access:: How to change a frame's parameters.
173 * Initial Parameters:: Specifying frame parameters when you make a frame.
174 * Window Frame Parameters:: List of frame parameters for window systems.
175 * Size and Position:: Changing the size and position of a frame.
178 @node Parameter Access
179 @subsection Access to Frame Parameters
181 These functions let you read and change the parameter values of a
184 @defun frame-parameters frame
185 The function @code{frame-parameters} returns an alist listing all the
186 parameters of @var{frame} and their values.
189 @defun modify-frame-parameters frame alist
190 This function alters the parameters of frame @var{frame} based on the
191 elements of @var{alist}. Each element of @var{alist} has the form
192 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
193 parameter. If you don't mention a parameter in @var{alist}, its value
197 @node Initial Parameters
198 @subsection Initial Frame Parameters
200 You can specify the parameters for the initial startup frame
201 by setting @code{initial-frame-alist} in your @file{.emacs} file.
203 @defvar initial-frame-alist
204 This variable's value is an alist of parameter values used when creating
205 the initial window frame. You can set this variable to specify the
206 appearance of the initial frame without altering subsequent frames.
207 Each element has the form:
210 (@var{parameter} . @var{value})
213 Emacs creates the initial frame before it reads your @file{~/.emacs}
214 file. After reading that file, Emacs checks @code{initial-frame-alist},
215 and applies the parameter settings in the altered value to the already
216 created initial frame.
218 If these settings affect the frame geometry and appearance, you'll see
219 the frame appear with the wrong ones and then change to the specified
220 ones. If that bothers you, you can specify the same geometry and
221 appearance with X resources; those do take affect before the frame is
222 created. @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
224 X resource settings typically apply to all frames. If you want to
225 specify some X resources solely for the sake of the initial frame, and
226 you don't want them to apply to subsequent frames, here's how to achieve
227 this. Specify parameters in @code{default-frame-alist} to override the
228 X resources for subsequent frames; then, to prevent these from affecting
229 the initial frame, specify the same parameters in
230 @code{initial-frame-alist} with values that match the X resources.
233 If these parameters specify a separate minibuffer-only frame with
234 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
237 @defvar minibuffer-frame-alist
238 This variable's value is an alist of parameter values used when creating
239 an initial minibuffer-only frame---if such a frame is needed, according
240 to the parameters for the main initial frame.
243 @defvar default-frame-alist
244 This is an alist specifying default values of frame parameters for all
245 Emacs frames---the first frame, and subsequent frames. When using the X
246 Window System, you can get the same results by means of X resources
250 See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
252 If you use options that specify window appearance when you invoke Emacs,
253 they take effect by adding elements to @code{default-frame-alist}. One
254 exception is @samp{-geometry}, which adds the specified position to
255 @code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
256 The GNU Emacs Manual}.
258 @node Window Frame Parameters
259 @subsection Window Frame Parameters
261 Just what parameters a frame has depends on what display mechanism it
262 uses. Here is a table of the parameters that have special meanings in a
263 window frame; of these, @code{name}, @code{title}, @code{height},
264 @code{width}, @code{buffer-list} and @code{buffer-predicate} provide
265 meaningful information in terminal frames.
269 If a frame has a non-@code{nil} title, it appears in the window system's
270 border for the frame, and also in the mode line of windows in that frame
271 if @code{mode-line-frame-identification} uses @samp{%F}
272 (@pxref{%-Constructs}). This is normally the case when Emacs is not
273 using a window system, and can only display one frame at a time.
277 The name of the frame. The frame name serves as a default for the frame
278 title, if the @code{title} parameter is unspecified or @code{nil}. If
279 you don't specify a name, Emacs sets the frame name automatically
280 (@pxref{Frame Titles}).
282 If you specify the frame name explicitly when you create the frame, the
283 name is also used (instead of the name of the Emacs executable) when
284 looking up X resources for the frame.
287 The display on which to open this frame. It should be a string of the
288 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
289 @code{DISPLAY} environment variable.
292 The screen position of the left edge, in pixels, with respect to the
293 left edge of the screen. The value may be a positive number @var{pos},
294 or a list of the form @code{(+ @var{pos})} which permits specifying a
295 negative @var{pos} value.
297 A negative number @minus{}@var{pos}, or a list of the form @code{(-
298 @var{pos})}, actually specifies the position of the right edge of the
299 window with respect to the right edge of the screen. A positive value
300 of @var{pos} counts toward the left. @strong{Reminder:} if the
301 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
304 Some window managers ignore program-specified positions. If you want to
305 be sure the position you specify is not ignored, specify a
306 non-@code{nil} value for the @code{user-position} parameter as well.
309 The screen position of the top edge, in pixels, with respect to the
310 top edge of the screen. The value may be a positive number @var{pos},
311 or a list of the form @code{(+ @var{pos})} which permits specifying a
312 negative @var{pos} value.
314 A negative number @minus{}@var{pos}, or a list of the form @code{(-
315 @var{pos})}, actually specifies the position of the bottom edge of the
316 window with respect to the bottom edge of the screen. A positive value
317 of @var{pos} counts toward the top. @strong{Reminder:} if the
318 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
321 Some window managers ignore program-specified positions. If you want to
322 be sure the position you specify is not ignored, specify a
323 non-@code{nil} value for the @code{user-position} parameter as well.
326 The screen position of the left edge @emph{of the frame's icon}, in
327 pixels, counting from the left edge of the screen. This takes effect if
328 and when the frame is iconified.
331 The screen position of the top edge @emph{of the frame's icon}, in
332 pixels, counting from the top edge of the screen. This takes effect if
333 and when the frame is iconified.
336 When you create a frame and specify its screen position with the
337 @code{left} and @code{top} parameters, use this parameter to say whether
338 the specified position was user-specified (explicitly requested in some
339 way by a human user) or merely program-specified (chosen by a program).
340 A non-@code{nil} value says the position was user-specified.
342 Window managers generally heed user-specified positions, and some heed
343 program-specified positions too. But many ignore program-specified
344 positions, placing the window in a default fashion or letting the user
345 place it with the mouse. Some window managers, including @code{twm},
346 let the user specify whether to obey program-specified positions or
349 When you call @code{make-frame}, you should specify a non-@code{nil}
350 value for this parameter if the values of the @code{left} and @code{top}
351 parameters represent the user's stated preference; otherwise, use
355 The height of the frame contents, in characters. (To get the height in
356 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
359 The width of the frame contents, in characters. (To get the height in
360 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
363 The number of the window-system window used by the frame.
366 Whether this frame has its own minibuffer. The value @code{t} means
367 yes, @code{nil} means no, @code{only} means this frame is just a
368 minibuffer. If the value is a minibuffer window (in some other frame),
369 the new frame uses that minibuffer.
371 @item buffer-predicate
372 The buffer-predicate function for this frame. The function
373 @code{other-buffer} uses this predicate (from the selected frame) to
374 decide which buffers it should consider, if the predicate is not
375 @code{nil}. It calls the predicate with one argument, a buffer, once for
376 each buffer; if the predicate returns a non-@code{nil} value, it
377 considers that buffer.
380 A list of buffers that have been selected in this frame,
381 ordered most-recently-selected first.
384 The name of the font for displaying text in the frame. This is a
388 Whether selecting the frame raises it (non-@code{nil} means yes).
391 Whether deselecting the frame lowers it (non-@code{nil} means yes).
393 @item vertical-scroll-bars
394 Whether the frame has scroll bars for vertical scrolling, and which side
395 of the frame they should be on. The possible values are @code{left},
396 @code{right}, and @code{nil} for no scroll bars.
398 @item horizontal-scroll-bars
399 Whether the frame has scroll bars for horizontal scrolling
400 (non-@code{nil} means yes). (Horizontal scroll bars are not currently
403 @item scroll-bar-width
404 The width of the vertical scroll bar, in pixels.
407 The type of icon to use for this frame when it is iconified. If the
408 value is a string, that specifies a file containing a bitmap to use.
409 Any other non-@code{nil} value specifies the default bitmap icon (a
410 picture of a gnu); @code{nil} specifies a text icon.
413 The name to use in the icon for this frame, when and if the icon
414 appears. If this is @code{nil}, the frame's title is used.
416 @item foreground-color
417 The color to use for the image of a character. This is a string; the
418 window system defines the meaningful color names.
420 @item background-color
421 The color to use for the background of characters.
424 The color for the mouse pointer.
427 The color for the cursor that shows point.
430 The color for the border of the frame.
433 The way to display the cursor. The legitimate values are @code{bar},
434 @code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
435 specifies an ordinary black box overlaying the character after point;
436 that is the default. The symbol @code{bar} specifies a vertical bar
437 between characters as the cursor. @code{(bar . @var{width})} specifies
438 a bar @var{width} pixels wide.
441 The width in pixels of the window border.
443 @item internal-border-width
444 The distance in pixels between text and border.
447 If non-@code{nil}, this frame's window is never split automatically.
450 The state of visibility of the frame. There are three possibilities:
451 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
452 iconified. @xref{Visibility of Frames}.
455 The number of lines to allocate at the top of the frame for a menu bar.
456 The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
457 toolkit, there is only one menu bar line; all that matters about the
458 number you specify is whether it is greater than zero.)
461 @c ??? Not yet working.
462 The X window number of the window that should be the parent of this one.
463 Specifying this lets you create an Emacs window inside some other
464 application's window. (It is not certain this will be implemented; try
465 it and see if it works.)
468 @node Size and Position
469 @subsection Frame Size And Position
471 You can read or change the size and position of a frame using the
472 frame parameters @code{left}, @code{top}, @code{height}, and
473 @code{width}. Whatever geometry parameters you don't specify are chosen
474 by the window manager in its usual fashion.
476 Here are some special features for working with sizes and positions:
478 @defun set-frame-position frame left top
479 This function sets the position of the top left corner of @var{frame} to
480 @var{left} and @var{top}. These arguments are measured in pixels, and
481 count from the top left corner of the screen. Negative parameter values
482 count up or rightward from the top left corner of the screen.
485 @defun frame-height &optional frame
486 @defunx frame-width &optional frame
487 These functions return the height and width of @var{frame}, measured in
488 characters. If you don't supply @var{frame}, they use the selected
492 @defun frame-pixel-height &optional frame
493 @defunx frame-pixel-width &optional frame
494 These functions return the height and width of @var{frame}, measured in
495 pixels. If you don't supply @var{frame}, they use the selected frame.
498 @defun frame-char-height &optional frame
499 @defunx frame-char-width &optional frame
500 These functions return the height and width of a character in
501 @var{frame}, measured in pixels. The values depend on the choice of
502 font. If you don't supply @var{frame}, these functions use the selected
506 @defun set-frame-size frame cols rows
507 This function sets the size of @var{frame}, measured in characters;
508 @var{cols} and @var{rows} specify the new width and height.
510 To set the size based on values measured in pixels, use
511 @code{frame-char-height} and @code{frame-char-width} to convert
512 them to units of characters.
515 The old-fashioned functions @code{set-screen-height} and
516 @code{set-screen-width}, which were used to specify the height and width
517 of the screen in Emacs versions that did not support multiple frames,
518 are still usable. They apply to the selected frame. @xref{Screen
521 @defun x-parse-geometry geom
522 @cindex geometry specification
523 The function @code{x-parse-geometry} converts a standard X Windows
524 geometry string to an alist that you can use as part of the argument to
527 The alist describes which parameters were specified in @var{geom}, and
528 gives the values specified for them. Each element looks like
529 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
530 values are @code{left}, @code{top}, @code{width}, and @code{height}.
532 For the size parameters, the value must be an integer. The position
533 parameter names @code{left} and @code{top} are not totally accurate,
534 because some values indicate the position of the right or bottom edges
535 instead. These are the @var{value} possibilities for the position
540 A positive integer relates the left edge or top edge of the window to
541 the left or top edge of the screen. A negative integer relates the
542 right or bottom edge of the window to the right or bottom edge of the
545 @item @code{(+ @var{position})}
546 This specifies the position of the left or top edge of the window
547 relative to the left or top edge of the screen. The integer
548 @var{position} may be positive or negative; a negative value specifies a
549 position outside the screen.
551 @item @code{(- @var{position})}
552 This specifies the position of the right or bottom edge of the window
553 relative to the right or bottom edge of the screen. The integer
554 @var{position} may be positive or negative; a negative value specifies a
555 position outside the screen.
561 (x-parse-geometry "35x70+0-0")
562 @result{} ((width . 35) (height . 70)
563 (left . 0) (top - 0))
568 New functions @code{set-frame-height} and @code{set-frame-width} set the
569 size of a specified frame. The frame is the first argument; the size is
574 @section Frame Titles
576 Every frame has a @code{name} parameter; this serves as the default
577 for the frame title which window systems typically display at the top of
578 the frame. You can specify a name explicitly by setting the @code{name}
581 Normally you don't specify the name explicitly, and Emacs computes the
582 frame name automatically based on a template stored in the variable
583 @code{frame-title-format}. Emacs recomputes the name each time the
584 frame is redisplayed.
586 @defvar frame-title-format
587 This variable specifies how to compute a name for a frame when you have
588 not explicitly specified one. The variable's value is actually a mode
589 line construct, just like @code{mode-line-format}. @xref{Mode Line
593 @defvar icon-title-format
594 This variable specifies how to compute the name for an iconified frame,
595 when you have not explicitly specified the frame title. This title
596 appears in the icon itself.
599 @defvar multiple-frames
600 This variable is set automatically by Emacs. Its value is @code{t} when
601 there are two or more frames (not counting minibuffer-only frames or
602 invisible frames). The default value of @code{frame-title-format} uses
603 @code{multiple-frames} so as to put the buffer name in the frame title
604 only when there is more than one frame.
607 @node Deleting Frames
608 @section Deleting Frames
609 @cindex deletion of frames
611 Frames remain potentially visible until you explicitly @dfn{delete}
612 them. A deleted frame cannot appear on the screen, but continues to
613 exist as a Lisp object until there are no references to it. There is no
614 way to cancel the deletion of a frame aside from restoring a saved frame
615 configuration (@pxref{Frame Configurations}); this is similar to the
618 @deffn Command delete-frame &optional frame
619 This function deletes the frame @var{frame}. By default, @var{frame} is
623 @defun frame-live-p frame
624 The function @code{frame-live-p} returns non-@code{nil} if the frame
625 @var{frame} has not been deleted.
628 Some window managers provide a command to delete a window. These work
629 by sending a special message to the program that operates the window.
630 When Emacs gets one of these commands, it generates a
631 @code{delete-frame} event, whose normal definition is a command that
632 calls the function @code{delete-frame}. @xref{Misc Events}.
634 @node Finding All Frames
635 @section Finding All Frames
638 The function @code{frame-list} returns a list of all the frames that
639 have not been deleted. It is analogous to @code{buffer-list} for
640 buffers. The list that you get is newly created, so modifying the list
641 doesn't have any effect on the internals of Emacs.
644 @defun visible-frame-list
645 This function returns a list of just the currently visible frames.
646 @xref{Visibility of Frames}. (Terminal frames always count as
647 ``visible'', even though only the selected one is actually displayed.)
650 @defun next-frame &optional frame minibuf
651 The function @code{next-frame} lets you cycle conveniently through all
652 the frames from an arbitrary starting point. It returns the ``next''
653 frame after @var{frame} in the cycle. If @var{frame} is omitted or
654 @code{nil}, it defaults to the selected frame.
656 The second argument, @var{minibuf}, says which frames to consider:
660 Exclude minibuffer-only frames.
662 Consider all visible frames.
664 Consider all visible or iconified frames.
666 Consider only the frames using that particular window as their
673 @defun previous-frame &optional frame minibuf
674 Like @code{next-frame}, but cycles through all frames in the opposite
678 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
681 @node Frames and Windows
682 @section Frames and Windows
684 Each window is part of one and only one frame; you can get the frame
685 with @code{window-frame}.
687 @defun window-frame window
688 This function returns the frame that @var{window} is on.
691 All the non-minibuffer windows in a frame are arranged in a cyclic
692 order. The order runs from the frame's top window, which is at the
693 upper left corner, down and to the right, until it reaches the window at
694 the lower right corner (always the minibuffer window, if the frame has
695 one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
697 @defun frame-top-window frame
698 This returns the topmost, leftmost window of frame @var{frame}.
701 At any time, exactly one window on any frame is @dfn{selected within the
702 frame}. The significance of this designation is that selecting the
703 frame also selects this window. You can get the frame's current
704 selected window with @code{frame-selected-window}.
706 @defun frame-selected-window frame
707 This function returns the window on @var{frame} that is selected within
711 Conversely, selecting a window for Emacs with @code{select-window} also
712 makes that window selected within its frame. @xref{Selecting Windows}.
714 Another function that (usually) returns one of the windows in a given
715 frame is @code{minibuffer-window}. @xref{Minibuffer Misc}.
717 @node Minibuffers and Frames
718 @section Minibuffers and Frames
720 Normally, each frame has its own minibuffer window at the bottom, which
721 is used whenever that frame is selected. If the frame has a minibuffer,
722 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
724 However, you can also create a frame with no minibuffer. Such a frame
725 must use the minibuffer window of some other frame. When you create the
726 frame, you can specify explicitly the minibuffer window to use (in some
727 other frame). If you don't, then the minibuffer is found in the frame
728 which is the value of the variable @code{default-minibuffer-frame}. Its
729 value should be a frame that does have a minibuffer.
731 If you use a minibuffer-only frame, you might want that frame to raise
732 when you enter the minibuffer. If so, set the variable
733 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
735 @defvar default-minibuffer-frame
736 This variable specifies the frame to use for the minibuffer window, by
737 default. It is always local to the current terminal and cannot be
738 buffer-local. @xref{Multiple Displays}.
744 @cindex selected frame
746 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
747 window always resides on the selected frame.
749 @defun selected-frame
750 This function returns the selected frame.
753 Some window systems and window managers direct keyboard input to the
754 window object that the mouse is in; others require explicit clicks or
755 commands to @dfn{shift the focus} to various window objects. Either
756 way, Emacs automatically keeps track of which frame has the focus.
758 Lisp programs can also switch frames ``temporarily'' by calling the
759 function @code{select-frame}. This does not alter the window system's
760 concept of focus; rather, it escapes from the window manager's control
761 until that control is somehow reasserted.
763 When using a text-only terminal, only the selected terminal frame is
764 actually displayed on the terminal. @code{switch-frame} is the only way
765 to switch frames, and the change lasts until overridden by a subsequent
766 call to @code{switch-frame}. Each terminal screen except for the
767 initial one has a number, and the number of the selected frame appears
768 in the mode line after the word @samp{Emacs} (@pxref{Mode Line
771 @c ??? This is not yet implemented properly.
772 @defun select-frame frame
773 This function selects frame @var{frame}, temporarily disregarding the
774 focus of the X server if any. The selection of @var{frame} lasts until
775 the next time the user does something to select a different frame, or
776 until the next time this function is called.
779 Emacs cooperates with the window system by arranging to select frames as
780 the server and window manager request. It does so by generating a
781 special kind of input event, called a @dfn{focus} event, when
782 appropriate. The command loop handles a focus event by calling
783 @code{handle-switch-frame}. @xref{Focus Events}.
785 @deffn Command handle-switch-frame frame
786 This function handles a focus event by selecting frame @var{frame}.
788 Focus events normally do their job by invoking this command.
789 Don't call it for any other reason.
792 @defun redirect-frame-focus frame focus-frame
793 This function redirects focus from @var{frame} to @var{focus-frame}.
794 This means that @var{focus-frame} will receive subsequent keystrokes and
795 events intended for @var{frame}. After such an event, the value of
796 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
797 events specifying @var{frame} will instead select @var{focus-frame}.
799 If @var{focus-frame} is @code{nil}, that cancels any existing
800 redirection for @var{frame}, which therefore once again receives its own
803 One use of focus redirection is for frames that don't have minibuffers.
804 These frames use minibuffers on other frames. Activating a minibuffer
805 on another frame redirects focus to that frame. This puts the focus on
806 the minibuffer's frame, where it belongs, even though the mouse remains
807 in the frame that activated the minibuffer.
809 Selecting a frame can also change focus redirections. Selecting frame
810 @code{bar}, when @code{foo} had been selected, changes any redirections
811 pointing to @code{foo} so that they point to @code{bar} instead. This
812 allows focus redirection to work properly when the user switches from
813 one frame to another using @code{select-window}.
815 This means that a frame whose focus is redirected to itself is treated
816 differently from a frame whose focus is not redirected.
817 @code{select-frame} affects the former but not the latter.
819 The redirection lasts until @code{redirect-frame-focus} is called to
823 @tindex focus-follows-mouse
824 @defopt focus-follows-mouse
825 This option is how you inform Emacs whether the window manager transfers
826 focus when the user moves the mouse. Non-@code{nil} says that it does.
827 When this is so, the command @code{other-frame} moves the mouse to a
828 position consistent with the new selected frame.
831 @node Visibility of Frames
832 @section Visibility of Frames
833 @cindex visible frame
834 @cindex invisible frame
835 @cindex iconified frame
836 @cindex frame visibility
838 A window frame may be @dfn{visible}, @dfn{invisible}, or
839 @dfn{iconified}. If it is visible, you can see its contents. If it is
840 iconified, the frame's contents do not appear on the screen, but an icon
841 does. If the frame is invisible, it doesn't show on the screen, not
844 Visibility is meaningless for terminal frames, since only the selected
845 one is actually displayed in any case.
847 @deffn Command make-frame-visible &optional frame
848 This function makes frame @var{frame} visible. If you omit @var{frame},
849 it makes the selected frame visible.
852 @deffn Command make-frame-invisible &optional frame
853 This function makes frame @var{frame} invisible. If you omit
854 @var{frame}, it makes the selected frame invisible.
857 @deffn Command iconify-frame &optional frame
858 This function iconifies frame @var{frame}. If you omit @var{frame}, it
859 iconifies the selected frame.
862 @defun frame-visible-p frame
863 This returns the visibility status of frame @var{frame}. The value is
864 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
865 @code{icon} if it is iconified.
868 The visibility status of a frame is also available as a frame
869 parameter. You can read or change it as such. @xref{Window Frame
872 The user can iconify and deiconify frames with the window manager.
873 This happens below the level at which Emacs can exert any control, but
874 Emacs does provide events that you can use to keep track of such
875 changes. @xref{Misc Events}.
877 @node Raising and Lowering
878 @section Raising and Lowering Frames
880 Most window systems use a desktop metaphor. Part of this metaphor is
881 the idea that windows are stacked in a notional third dimension
882 perpendicular to the screen surface, and thus ordered from ``highest''
883 to ``lowest''. Where two windows overlap, the one higher up covers
884 the one underneath. Even a window at the bottom of the stack can be
885 seen if no other window overlaps it.
887 @cindex raising a frame
888 @cindex lowering a frame
889 A window's place in this ordering is not fixed; in fact, users tend
890 to change the order frequently. @dfn{Raising} a window means moving
891 it ``up'', to the top of the stack. @dfn{Lowering} a window means
892 moving it to the bottom of the stack. This motion is in the notional
893 third dimension only, and does not change the position of the window
896 You can raise and lower Emacs frame Windows with these functions:
898 @deffn Command raise-frame frame
899 This function raises frame @var{frame}.
902 @deffn Command lower-frame frame
903 This function lowers frame @var{frame}.
906 @defopt minibuffer-auto-raise
907 If this is non-@code{nil}, activation of the minibuffer raises the frame
908 that the minibuffer window is in.
911 You can also enable auto-raise (raising automatically when a frame is
912 selected) or auto-lower (lowering automatically when it is deselected)
913 for any frame using frame parameters. @xref{Window Frame Parameters}.
915 @node Frame Configurations
916 @section Frame Configurations
917 @cindex frame configuration
919 A @dfn{frame configuration} records the current arrangement of frames,
920 all their properties, and the window configuration of each one.
921 (@xref{Window Configurations}.)
923 @defun current-frame-configuration
924 This function returns a frame configuration list that describes
925 the current arrangement of frames and their contents.
928 @defun set-frame-configuration configuration
929 This function restores the state of frames described in
934 @section Mouse Tracking
935 @cindex mouse tracking
936 @cindex tracking the mouse
938 Sometimes it is useful to @dfn{track} the mouse, which means to display
939 something to indicate where the mouse is and move the indicator as the
940 mouse moves. For efficient mouse tracking, you need a way to wait until
941 the mouse actually moves.
943 The convenient way to track the mouse is to ask for events to represent
944 mouse motion. Then you can wait for motion by waiting for an event. In
945 addition, you can easily handle any other sorts of events that may
946 occur. That is useful, because normally you don't want to track the
947 mouse forever---only until some other event, such as the release of a
950 @defspec track-mouse body@dots{}
951 This special form executes @var{body}, with generation of mouse motion
952 events enabled. Typically @var{body} would use @code{read-event} to
953 read the motion events and modify the display accordingly. @xref{Motion
954 Events}, for the format of mouse motion events.
956 The value of @code{track-mouse} is that of the last form in @var{body}.
957 You should design @var{body} to return when it sees the up-event that
958 indicates the release of the button, or whatever kind of event means
959 it is time to stop tracking.
962 The usual purpose of tracking mouse motion is to indicate on the screen
963 the consequences of pushing or releasing a button at the current
966 In many cases, you can avoid the need to track the mouse by using
967 the @code{mouse-face} text property (@pxref{Special Properties}).
968 That works at a much lower level and runs more smoothly than
969 Lisp-level mouse tracking.
972 @c These are not implemented yet.
974 These functions change the screen appearance instantaneously. The
975 effect is transient, only until the next ordinary Emacs redisplay. That
976 is OK for mouse tracking, since it doesn't make sense for mouse tracking
977 to change the text, and the body of @code{track-mouse} normally reads
978 the events itself and does not do redisplay.
980 @defun x-contour-region window beg end
981 This function draws lines to make a box around the text from @var{beg}
982 to @var{end}, in window @var{window}.
985 @defun x-uncontour-region window beg end
986 This function erases the lines that would make a box around the text
987 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
988 a contour that you previously made by calling @code{x-contour-region}.
991 @defun x-draw-rectangle frame left top right bottom
992 This function draws a hollow rectangle on frame @var{frame} with the
993 specified edge coordinates, all measured in pixels from the inside top
994 left corner. It uses the cursor color, the one used for indicating the
998 @defun x-erase-rectangle frame left top right bottom
999 This function erases a hollow rectangle on frame @var{frame} with the
1000 specified edge coordinates, all measured in pixels from the inside top
1001 left corner. Erasure means redrawing the text and background that
1002 normally belong in the specified rectangle.
1006 @node Mouse Position
1007 @section Mouse Position
1008 @cindex mouse position
1009 @cindex position of mouse
1011 The functions @code{mouse-position} and @code{set-mouse-position}
1012 give access to the current position of the mouse.
1014 @defun mouse-position
1015 This function returns a description of the position of the mouse. The
1016 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1017 and @var{y} are integers giving the position in characters relative to
1018 the top left corner of the inside of @var{frame}.
1021 @defun set-mouse-position frame x y
1022 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1023 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1024 giving the position in characters relative to the top left corner of the
1025 inside of @var{frame}.
1028 @defun mouse-pixel-position
1029 This function is like @code{mouse-position} except that it returns
1030 coordinates in units of pixels rather than units of characters.
1033 @defun set-mouse-pixel-position frame x y
1034 This function warps the mouse like @code{set-mouse-position} except that
1035 @var{x} and @var{y} are in units of pixels rather than units of
1036 characters. These coordinates are not required to be within the frame.
1042 @section Pop-Up Menus
1044 When using a window system, a Lisp program can pop up a menu so that
1045 the user can choose an alternative with the mouse.
1047 @defun x-popup-menu position menu
1048 This function displays a pop-up menu and returns an indication of
1049 what selection the user makes.
1051 The argument @var{position} specifies where on the screen to put the
1052 menu. It can be either a mouse button event (which says to put the menu
1053 where the user actuated the button) or a list of this form:
1056 ((@var{xoffset} @var{yoffset}) @var{window})
1060 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1061 pixels, counting from the top left corner of @var{window}'s frame.
1063 If @var{position} is @code{t}, it means to use the current mouse
1064 position. If @var{position} is @code{nil}, it means to precompute the
1065 key binding equivalents for the keymaps specified in @var{menu},
1066 without actually displaying or popping up the menu.
1068 The argument @var{menu} says what to display in the menu. It can be a
1069 keymap or a list of keymaps (@pxref{Menu Keymaps}). Alternatively, it
1070 can have the following form:
1073 (@var{title} @var{pane1} @var{pane2}...)
1077 where each pane is a list of form
1080 (@var{title} (@var{line} . @var{item})...)
1083 Each @var{line} should be a string, and each @var{item} should be the
1084 value to return if that @var{line} is chosen.
1087 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1088 if you could do the job with a prefix key defined with a menu keymap.
1089 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1090 a} can see the individual items in that menu and provide help for them.
1091 If instead you implement the menu by defining a command that calls
1092 @code{x-popup-menu}, the help facilities cannot know what happens inside
1093 that command, so they cannot give any help for the menu's items.
1095 The menu bar mechanism, which lets you switch between submenus by
1096 moving the mouse, cannot look within the definition of a command to see
1097 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1098 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1099 an integrated fashion. This is why all menu bar submenus are
1100 implemented with menu keymaps within the parent menu, and never with
1101 @code{x-popup-menu}. @xref{Menu Bar},
1103 If you want a menu bar submenu to have contents that vary, you should
1104 still use a menu keymap to implement it. To make the contents vary, add
1105 a hook function to @code{menu-bar-update-hook} to update the contents of
1106 the menu keymap as necessary.
1109 @section Dialog Boxes
1110 @cindex dialog boxes
1112 A dialog box is a variant of a pop-up menu---it looks a little
1113 different, it always appears in the center of a frame, and it has just
1114 one level and one pane. The main use of dialog boxes is for asking
1115 questions that the user can answer with ``yes'', ``no'', and a few other
1116 alternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} use
1117 dialog boxes instead of the keyboard, when called from commands invoked
1120 @defun x-popup-dialog position contents
1121 This function displays a pop-up dialog box and returns an indication of
1122 what selection the user makes. The argument @var{contents} specifies
1123 the alternatives to offer; it has this format:
1126 (@var{title} (@var{string} . @var{value})@dots{})
1130 which looks like the list that specifies a single pane for
1131 @code{x-popup-menu}.
1133 The return value is @var{value} from the chosen alternative.
1135 An element of the list may be just a string instead of a cons cell
1136 @code{(@var{string} . @var{value})}. That makes a box that cannot
1139 If @code{nil} appears in the list, it separates the left-hand items from
1140 the right-hand items; items that precede the @code{nil} appear on the
1141 left, and items that follow the @code{nil} appear on the right. If you
1142 don't include a @code{nil} in the list, then approximately half the
1143 items appear on each side.
1145 Dialog boxes always appear in the center of a frame; the argument
1146 @var{position} specifies which frame. The possible values are as in
1147 @code{x-popup-menu}, but the precise coordinates don't matter; only the
1150 In some configurations, Emacs cannot display a real dialog box; so
1151 instead it displays the same items in a pop-up menu in the center of the
1155 @node Pointer Shapes
1156 @section Pointer Shapes
1157 @cindex pointer shape
1158 @cindex mouse pointer shape
1160 These variables specify which shape to use for the mouse pointer in
1161 various situations, when using the X Window System:
1164 @item x-pointer-shape
1165 @vindex x-pointer-shape
1166 This variable specifies the pointer shape to use ordinarily in the Emacs
1169 @item x-sensitive-text-pointer-shape
1170 @vindex x-sensitive-text-pointer-shape
1171 This variable specifies the pointer shape to use when the mouse
1172 is over mouse-sensitive text.
1175 These variables affect newly created frames. They do not normally
1176 affect existing frames; however, if you set the mouse color of a frame,
1177 that also updates its pointer shapes based on the current values of
1178 these variables. @xref{Window Frame Parameters}.
1180 The values you can use, to specify either of these pointer shapes, are
1181 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1182 @key{RET} x-pointer @key{RET}} to see a list of them.
1184 @node Window System Selections
1185 @section Window System Selections
1186 @cindex selection (for X windows)
1188 The X server records a set of @dfn{selections} which permit transfer of
1189 data between application programs. The various selections are
1190 distinguished by @dfn{selection types}, represented in Emacs by
1191 symbols. X clients including Emacs can read or set the selection for
1194 @defun x-set-selection type data
1195 This function sets a ``selection'' in the X server. It takes two
1196 arguments: a selection type @var{type}, and the value to assign to it,
1197 @var{data}. If @var{data} is @code{nil}, it means to clear out the
1198 selection. Otherwise, @var{data} may be a string, a symbol, an integer
1199 (or a cons of two integers or list of two integers), an overlay, or a
1200 cons of two markers pointing to the same buffer. An overlay or a pair
1201 of markers stands for text in the overlay or between the markers.
1203 The argument @var{data} may also be a vector of valid non-vector
1206 Each possible @var{type} has its own selection value, which changes
1207 independently. The usual values of @var{type} are @code{PRIMARY} and
1208 @code{SECONDARY}; these are symbols with upper-case names, in accord
1209 with X Window System conventions. The default is @code{PRIMARY}.
1212 @defun x-get-selection &optional type data-type
1213 This function accesses selections set up by Emacs or by other X
1214 clients. It takes two optional arguments, @var{type} and
1215 @var{data-type}. The default for @var{type}, the selection type, is
1218 The @var{data-type} argument specifies the form of data conversion to
1219 use, to convert the raw data obtained from another X client into Lisp
1220 data. Meaningful values include @code{TEXT}, @code{STRING},
1221 @code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
1222 @code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
1223 @code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
1224 @code{NAME}, @code{ATOM}, and @code{INTEGER}. (These are symbols with
1225 upper-case names in accord with X conventions.) The default for
1226 @var{data-type} is @code{STRING}.
1230 The X server also has a set of numbered @dfn{cut buffers} which can
1231 store text or other data being moved between applications. Cut buffers
1232 are considered obsolete, but Emacs supports them for the sake of X
1233 clients that still use them.
1235 @defun x-get-cut-buffer n
1236 This function returns the contents of cut buffer number @var{n}.
1239 @defun x-set-cut-buffer string
1240 This function stores @var{string} into the first cut buffer (cut buffer
1241 0), moving the other values down through the series of cut buffers, much
1242 like the way successive kills in Emacs move down the kill ring.
1246 @section Looking up Font Names
1248 @defun x-list-font pattern &optional face frame maximum
1249 This function returns a list of available font names that match
1250 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
1251 specified, then the list is limited to fonts that are the same size as
1252 @var{face} currently is on @var{frame}.
1254 The argument @var{pattern} should be a string, perhaps with wildcard
1255 characters: the @samp{*} character matches any substring, and the
1256 @samp{?} character matches any single character. Pattern matching
1257 of font names ignores case.
1259 If you specify @var{face} and @var{frame}, @var{face} should be a face name
1260 (a symbol) and @var{frame} should be a frame.
1262 The optional argument @var{maximum} sets a limit on how many fonts to
1263 return. If this is non-@code{nil}, then the return value is truncated
1264 after the first @var{maximum} matching fonts. Specifying a small value
1265 for @var{maximum} can make this function much faster, in cases where
1266 many fonts match the pattern.
1270 @section Color Names
1272 @defun x-color-defined-p color &optional frame
1273 This function reports whether a color name is meaningful. It returns
1274 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
1275 which frame's display to ask about; if @var{frame} is omitted or
1276 @code{nil}, the selected frame is used.
1278 Note that this does not tell you whether the display you are using
1279 really supports that color. You can ask for any defined color on any
1280 kind of display, and you will get some result---that is how the X server
1281 works. Here's an approximate way to test whether your display supports
1282 the color @var{color}:
1285 (defun x-color-supported-p (color &optional frame)
1286 (and (x-color-defined-p color frame)
1287 (or (x-display-color-p frame)
1288 (member color '("black" "white"))
1289 (and (> (x-display-planes frame) 1)
1290 (equal color "gray")))))
1294 @defun x-color-values color &optional frame
1295 This function returns a value that describes what @var{color} should
1296 ideally look like. If @var{color} is defined, the value is a list of
1297 three integers, which give the amount of red, the amount of green, and
1298 the amount of blue. Each integer ranges in principle from 0 to 65535,
1299 but in practice no value seems to be above 65280. If @var{color} is not
1300 defined, the value is @code{nil}.
1303 (x-color-values "black")
1305 (x-color-values "white")
1306 @result{} (65280 65280 65280)
1307 (x-color-values "red")
1308 @result{} (65280 0 0)
1309 (x-color-values "pink")
1310 @result{} (65280 49152 51968)
1311 (x-color-values "hungry")
1315 The color values are returned for @var{frame}'s display. If @var{frame}
1316 is omitted or @code{nil}, the information is return for the selected
1321 @section X Resources
1323 @defun x-get-resource attribute class &optional component subclass
1324 The function @code{x-get-resource} retrieves a resource value from the X
1325 Windows defaults database.
1327 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
1328 This function searches using a key of the form
1329 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
1330 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
1333 The optional arguments @var{component} and @var{subclass} add to the key
1334 and the class, respectively. You must specify both of them or neither.
1335 If you specify them, the key is
1336 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
1337 @samp{Emacs.@var{class}.@var{subclass}}.
1340 @defvar x-resource-class
1341 This variable specifies the application name that @code{x-get-resource}
1342 should look up. The default value is @code{"Emacs"}. You can examine X
1343 resources for application names other than ``Emacs'' by binding this
1344 variable to some other string, around a call to @code{x-get-resource}.
1347 @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
1350 @section Data about the X Server
1352 This section describes functions you can use to get information about
1353 the capabilities and origin of an X display that Emacs is using. Each
1354 of these functions lets you specify the display you are interested in:
1355 the @var{display} argument can be either a display name, or a frame
1356 (meaning use the display that frame is on). If you omit the
1357 @var{display} argument, or specify @code{nil}, that means to use the
1358 selected frame's display.
1360 @defun x-display-screens &optional display
1361 This function returns the number of screens associated with the display.
1364 @defun x-server-version &optional display
1365 This function returns the list of version numbers of the X server
1366 running the display.
1369 @defun x-server-vendor &optional display
1370 This function returns the vendor that provided the X server software.
1373 @defun x-display-pixel-height &optional display
1374 This function returns the height of the screen in pixels.
1377 @defun x-display-mm-height &optional display
1378 This function returns the height of the screen in millimeters.
1381 @defun x-display-pixel-width &optional display
1382 This function returns the width of the screen in pixels.
1385 @defun x-display-mm-width &optional display
1386 This function returns the width of the screen in millimeters.
1389 @defun x-display-backing-store &optional display
1390 This function returns the backing store capability of the screen.
1391 Values can be the symbols @code{always}, @code{when-mapped}, or
1395 @defun x-display-save-under &optional display
1396 This function returns non-@code{nil} if the display supports the
1400 @defun x-display-planes &optional display
1401 This function returns the number of planes the display supports.
1404 @defun x-display-visual-class &optional display
1405 This function returns the visual class for the screen. The value is one
1406 of the symbols @code{static-gray}, @code{gray-scale},
1407 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
1408 @code{direct-color}.
1411 @defun x-display-grayscale-p &optional display
1412 This function returns @code{t} if the screen can display shades of gray.
1415 @defun x-display-color-p &optional display
1416 This function returns @code{t} if the screen is a color screen.
1419 @defun x-display-color-cells &optional display
1420 This function returns the number of color cells the screen supports.
1424 @defvar x-no-window-manager
1425 This variable's value is is @code{t} if no X window manager is in use.
1431 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
1432 width and height of an X Window frame, measured in pixels.