2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 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 @var{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 frames}. 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 an X server, it does not have a
22 terminal frame; instead, it starts with a single @dfn{X window frame}.
23 It can display multiple X window frames at the same time, each in its
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 X 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 X 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 * X Selections:: Transferring text to and from other X clients.
52 * Color Names:: Getting the definitions of color names.
53 * Resources:: Getting resource values from the server.
54 * Server Data:: Getting info about the X server.
57 @xref{Display}, for related information.
60 @section Creating Frames
62 To create a new frame, call the function @code{make-frame}.
64 @defun make-frame alist
65 This function creates a new frame. If you are using X, it makes
66 an X window frame; otherwise, it makes a terminal frame.
68 The argument is an alist specifying frame parameters. Any parameters
69 not mentioned in @var{alist} default according to the value of the
70 variable @code{default-frame-alist}; parameters not specified even there
71 default from the standard X defaults file and X resources.
73 The set of possible parameters depends in principle on what kind of
74 window system Emacs uses to display its frames. @xref{X Frame
75 Parameters}, for documentation of individual parameters you can specify.
78 @defvar before-make-frame-hook
79 A normal hook run by @code{make-frame} before it actually creates the
83 @defvar after-make-frame-hook
84 A normal hook run by @code{make-frame} after it creates the frame.
87 @node Multiple Displays
88 @section Multiple Displays
89 @cindex multiple displays
90 @cindex multiple X terminals
91 @cindex displays, multiple
93 A single Emacs can talk to more than one X Windows display.
94 Initially, Emacs uses just one display---the one chosen with the
95 @code{DISPLAY} environment variable or with the @samp{--display} option
96 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
97 another display, use the command @code{make-frame-on-display} or specify
98 the @code{display} frame parameter when you create the frame.
100 Emacs treats each X server as a separate terminal, giving each one its
101 own selected frame and its own minibuffer windows. A few Lisp variables
102 have values local to the current terminal (that is, the terminal
103 corresponding to the currently selected frame): these are
104 @code{default-minibuffer-frame}, @code{defining-kbd-macro},
105 @code{last-kbd-macro}, @code{multiple-frames} and
106 @code{system-key-alist}. These variables are always terminal-local and
107 can never be buffer-local.
109 A single X server can handle more than one screen. A display name
110 @samp{@var{host}.@var{server}.@var{screen}} has three parts; the last
111 part specifies the screen number for a given server. When you use two
112 screens belonging to one server, Emacs knows by the similarity in their
113 names that they share a single keyboard, and it treats them as a single
116 @deffn Command make-frame-on-display display &optional parameters
117 This creates a new frame on display @var{display}, taking the other
118 frame parameters from @var{parameters}. Aside from the @var{display}
119 argument, it is like @code{make-frame} (@pxref{Creating Frames}).
122 @defun x-display-list
123 This returns a list that indicates which X displays Emacs has a
124 connection to. The elements of the list are strings, and each one is
128 @defun x-open-connection display &optional xrm-string
129 This function opens a connection to the X display @var{display}. It
130 does not create a frame on that display, but it permits you to check
131 that communication can be established with that display.
133 The optional argument @var{resource-string}, if not @code{nil}, is a
134 string of resource names and values, in the same format used in the
135 @file{.Xresources} file. The values you specify override the resource
136 values recorded in the X server itself; they apply to all Emacs frames
137 created on this display. Here's an example of what this string might
141 "*BorderWidth: 3\n*InternalBorder: 2\n"
147 @defun x-close-connection display
148 This function closes the connection to display @var{display}. Before
149 you can do this, you must first delete all the frames that were open on
150 that display (@pxref{Deleting Frames}).
153 @node Frame Parameters
154 @section Frame Parameters
156 A frame has many parameters that control its appearance and behavior.
157 Just what parameters a frame has depends on what display mechanism it
160 Frame parameters exist for the sake of window systems. A terminal frame
161 has a few parameters, mostly for compatibility's sake; only the height,
162 width and @code{buffer-predicate} parameters really do something.
165 * Parameter Access:: How to change a frame's parameters.
166 * Initial Parameters:: Specifying frame parameters when you make a frame.
167 * X Frame Parameters:: List of frame parameters.
168 * Size and Position:: Changing the size and position of a frame.
171 @node Parameter Access
172 @subsection Access to Frame Parameters
174 These functions let you read and change the parameter values of a
177 @defun frame-parameters frame
178 The function @code{frame-parameters} returns an alist listing all the
179 parameters of @var{frame} and their values.
182 @defun modify-frame-parameters frame alist
183 This function alters the parameters of frame @var{frame} based on the
184 elements of @var{alist}. Each element of @var{alist} has the form
185 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
186 parameter. If you don't mention a parameter in @var{alist}, its value
190 @node Initial Parameters
191 @subsection Initial Frame Parameters
193 You can specify the parameters for the initial startup frame
194 by setting @code{initial-frame-alist} in your @file{.emacs} file.
196 @defvar initial-frame-alist
197 This variable's value is an alist of parameter values used when creating
198 the initial X window frame. Each element has the form:
201 (@var{parameter} . @var{value})
204 Emacs creates the initial frame before it reads your @file{~/.emacs}
205 file. After reading that file, Emacs checks @code{initial-frame-alist},
206 and applies the parameter settings in the altered value to the already
207 created initial frame.
209 If these settings affect the frame geometry and appearance, you'll see
210 the frame appear with the wrong ones and then change to the specified
211 ones. If that bothers you, you can specify the same geometry and
212 appearance with X resources; those do take affect before the frame is
213 created. @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
215 X resource settings typically apply to all frames. If you want to
216 specify some X resources solely for the sake of the initial frame, and
217 you don't want them to apply to subsequent frames, here's how to achieve
218 this. Specify parameters in @code{default-frame-alist} to override the
219 X resources for subsequent frames; then, to prevent these from affecting
220 the initial frame, specify the same parameters in
221 @code{initial-frame-alist} with values that match the X resources.
224 If these parameters specify a separate minibuffer-only frame with
225 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
228 @defvar minibuffer-frame-alist
229 This variable's value is an alist of parameter values used when creating
230 an initial minibuffer-only frame---if such a frame is needed, according
231 to the parameters for the main initial frame.
234 @defvar default-frame-alist
235 This is an alist specifying default values of frame parameters for
236 subsequent Emacs frames (not the initial ones).
239 See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
241 If you use options that specify window appearance when you invoke Emacs,
242 they take effect by adding elements to @code{default-frame-alist}. One
243 exception is @samp{-geometry}, which adds the specified position to
244 @code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
245 The GNU Emacs Manual}.
247 @node X Frame Parameters
248 @subsection X Window Frame Parameters
250 Just what parameters a frame has depends on what display mechanism it
251 uses. Here is a table of the parameters of an X window frame; of these,
252 @code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
253 provide meaningful information in non-X frames.
257 The name of the frame. Most window managers display the frame's name in
258 the frame's border, at the top of the frame. If you don't specify a
259 name, and you have more than one frame, Emacs sets the frame name based
260 on the buffer displayed in the frame's selected window.
262 If you specify the frame name explicitly when you create the frame, the
263 name is also used (instead of the name of the Emacs executable) when
264 looking up X resources for the frame.
267 The display on which to open this frame. It should be a string of the
268 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
269 @code{DISPLAY} environment variable.
272 The screen position of the left edge, in pixels, with respect to the
273 left edge of the screen. The value may be a positive number @var{pos},
274 or a list of the form @code{(+ @var{pos})} which permits specifying a
275 negative @var{pos} value.
277 A negative number @minus{}@var{pos}, or a list of the form @code{(-
278 @var{pos})}, actually specifies the position of the right edge of the
279 window with respect to the right edge of the screen. A positive value
280 of @var{pos} counts toward the left. If the parameter is a negative
281 integer @minus{}@var{pos} then @var{pos} is positive!
284 The screen position of the top edge, in pixels, with respect to the
285 top edge of the screen. The value may be a positive number @var{pos},
286 or a list of the form @code{(+ @var{pos})} which permits specifying a
287 negative @var{pos} value.
289 A negative number @minus{}@var{pos}, or a list of the form @code{(-
290 @var{pos})}, actually specifies the position of the bottom edge of the
291 window with respect to the bottom edge of the screen. A positive value
292 of @var{pos} counts toward the top. If the parameter is a negative
293 integer @minus{}@var{pos} then @var{pos} is positive!
296 The screen position of the left edge @emph{of the frame's icon}, in
297 pixels, counting from the left edge of the screen. This takes effect if
298 and when the frame is iconified.
301 The screen position of the top edge @emph{of the frame's icon}, in
302 pixels, counting from the top edge of the screen. This takes effect if
303 and when the frame is iconified.
306 Non-@code{nil} if the screen position of the frame was explicitly
307 requested by the user (for example, with the @samp{-geometry} option).
308 Nothing automatically makes this parameter non-@code{nil}; it is up to
309 Lisp programs that call @code{make-frame} to specify this parameter as
310 well as specifying the @code{left} and @code{top} parameters.
313 The height of the frame contents, in characters. (To get the height in
314 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
317 The width of the frame contents, in characters. (To get the height in
318 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
321 The number of the X window for the frame.
324 Whether this frame has its own minibuffer. The value @code{t} means
325 yes, @code{nil} means no, @code{only} means this frame is just a
326 minibuffer. If the value is a minibuffer window (in some other frame),
327 the new frame uses that minibuffer.
329 @item buffer-predicate
330 The buffer-predicate function for this frame. The function
331 @code{other-buffer} uses this predicate (from the selected frame) to
332 decide which buffers it should consider, if the predicate is not
333 @code{nil}. It calls the predicate with one arg, a buffer, once for
334 each buffer; if the predicate returns a non-@code{nil} value, it
335 considers that buffer.
338 The name of the font for displaying text in the frame. This is a
342 Whether selecting the frame raises it (non-@code{nil} means yes).
345 Whether deselecting the frame lowers it (non-@code{nil} means yes).
347 @item vertical-scroll-bars
348 Whether the frame has scroll bars for vertical scrolling
349 (non-@code{nil} means yes).
351 @item horizontal-scroll-bars
352 Whether the frame has scroll bars for horizontal scrolling
353 (non-@code{nil} means yes). (Horizontal scroll bars are not currently
356 @item scroll-bar-width
357 The width of the vertical scroll bar, in pixels.
360 The type of icon to use for this frame when it is iconified. If the
361 value is a string, that specifies a file containing a bitmap to use.
362 Any other non-@code{nil} value specifies the default bitmap icon (a
363 picture of a gnu); @code{nil} specifies a text icon.
366 The name to use in the icon for this frame, when and if the icon
367 appears. If this is @code{nil}, the frame's title is used.
369 @item foreground-color
370 The color to use for the image of a character. This is a string; the X
371 server defines the meaningful color names.
373 @item background-color
374 The color to use for the background of characters.
377 The color for the mouse pointer.
380 The color for the cursor that shows point.
383 The color for the border of the frame.
386 The way to display the cursor. The legitimate values are @code{bar},
387 @code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
388 specifies an ordinary black box overlaying the character after point;
389 that is the default. The symbol @code{bar} specifies a vertical bar
390 between characters as the cursor. @code{(bar . @var{width})} specifies
391 a bar @var{width} pixels wide.
394 The width in pixels of the window border.
396 @item internal-border-width
397 The distance in pixels between text and border.
400 If non-@code{nil}, this frame's window is never split automatically.
403 The state of visibility of the frame. There are three possibilities:
404 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
405 iconified. @xref{Visibility of Frames}.
408 The number of lines to allocate at the top of the frame for a menu bar.
409 The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
410 toolkit, there is only one menu bar line; all that matters about the
411 number you specify is whether it is greater than zero.)
414 @c ??? Not yet working.
415 The X window number of the window that should be the parent of this one.
416 Specifying this lets you create an Emacs window inside some other
417 application's window. (It is not certain this will be implemented; try
418 it and see if it works.)
421 @node Size and Position
422 @subsection Frame Size And Position
424 You can read or change the size and position of a frame using the
425 frame parameters @code{left}, @code{top}, @code{height}, and
426 @code{width}. Whatever geometry parameters you don't specify are chosen
427 by the window manager in its usual fashion.
429 Here are some special features for working with sizes and positions:
431 @defun set-frame-position frame left top
432 This function sets the position of the top left corner of @var{frame} to
433 @var{left} and @var{top}. These arguments are measured in pixels, and
434 count from the top left corner of the screen. Negative parameter values
435 count up or rightward from the top left corner of the screen.
438 @defun frame-height &optional frame
439 @defunx frame-width &optional frame
440 These functions return the height and width of @var{frame}, measured in
441 characters. If you don't supply @var{frame}, they use the selected
445 @defun frame-pixel-height &optional frame
446 @defunx frame-pixel-width &optional frame
447 These functions return the height and width of @var{frame}, measured in
448 pixels. If you don't supply @var{frame}, they use the selected frame.
451 @defun frame-char-height &optional frame
452 @defunx frame-char-width &optional frame
453 These functions return the height and width of a character in
454 @var{frame}, measured in pixels. The values depend on the choice of
455 font. If you don't supply @var{frame}, these functions use the selected
459 @defun set-frame-size frame cols rows
460 This function sets the size of @var{frame}, measured in characters;
461 @var{cols} and @var{rows} specify the new width and height.
463 To set the size based on values measured in pixels, use
464 @code{frame-char-height} and @code{frame-char-width} to convert
465 them to units of characters.
468 The old-fashioned functions @code{set-screen-height} and
469 @code{set-screen-width}, which were used to specify the height and width
470 of the screen in Emacs versions that did not support multiple frames,
471 are still usable. They apply to the selected frame. @xref{Screen
474 @defun x-parse-geometry geom
475 @cindex geometry specification
476 The function @code{x-parse-geometry} converts a standard X windows
477 geometry string to an alist that you can use as part of the argument to
480 The alist describes which parameters were specified in @var{geom}, and
481 gives the values specified for them. Each element looks like
482 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
483 values are @code{left}, @code{top}, @code{width}, and @code{height}.
485 For the size parameters, the value must be an integer. The position
486 parameter names @code{left} and @code{top} are not totally accurate,
487 because some values indicate the position of the right or bottom edges
488 instead. These are the @var{value} possibilities for the position
493 A positive integer relates the left edge or top edge of the window to
494 the left or top edge of the screen. A negative integer relates the
495 right or bottom edge of the window to the right or bottom edge of the
498 @item @code{(+ @var{position})}
499 This specifies the position of the left or top edge of the window
500 relative to the left or top edge of the screen. The integer
501 @var{position} may be positive or negative; a negative value specifies a
502 position outside the screen.
504 @item @code{(- @var{position})}
505 This specifies the position of the right or bottom edge of the window
506 relative to the right or bottom edge of the screen. The integer
507 @var{position} may be positive or negative; a negative value specifies a
508 position outside the screen.
514 (x-parse-geometry "35x70+0-0")
515 @result{} ((width . 35) (height . 70)
516 (left . 0) (top - 0))
521 New functions @code{set-frame-height} and @code{set-frame-width} set the
522 size of a specified frame. The frame is the first argument; the size is
527 @section Frame Titles
529 Every frame has a title; most window managers display the frame title at
530 the top of the frame. You can specify an explicit title with the
531 @code{name} frame property. But normally you don't specify this
532 explicitly, and Emacs computes the title automatically.
534 Emacs computes the frame title based on a template stored in the
535 variable @code{frame-title-format}.
537 @defvar frame-title-format
538 This variable specifies how to compute a title for a frame
539 when you have not explicitly specified one.
541 The variable's value is actually a mode line construct, just like
542 @code{mode-line-format}. @xref{Mode Line Data}.
545 @defvar icon-title-format
546 This variable specifies how to compute the title for an iconified frame,
547 when you have not explicitly specified the frame title. This title
548 appears in the icon itself.
551 @defvar multiple-frames
552 This variable is set automatically by Emacs. Its value is @code{t} when
553 there are two or more frames (not counting minibuffer-only frames or
554 invisible frames). The default value of @code{frame-title-format} uses
555 @code{multiple-frames} so as to put the buffer name in the frame title
556 only when there is more than one frame.
558 The variable is always local to the current terminal and cannot be
559 buffer-local. @xref{Multiple Displays}.
562 @node Deleting Frames
563 @section Deleting Frames
564 @cindex deletion of frames
566 Frames remain potentially visible until you explicitly @dfn{delete}
567 them. A deleted frame cannot appear on the screen, but continues to
568 exist as a Lisp object until there are no references to it. There is no
569 way to cancel the deletion of a frame aside from restoring a saved frame
570 configuration (@pxref{Frame Configurations}); this is similar to the
573 @deffn Command delete-frame &optional frame
574 This function deletes the frame @var{frame}. By default, @var{frame} is
578 @defun frame-live-p frame
579 The function @code{frame-live-p} returns non-@code{nil} if the frame
580 @var{frame} has not been deleted.
583 Some window managers provide a command to delete a window. These work
584 by sending a special message to the program than operates the window.
585 When Emacs gets one of these commands, it generates a
586 @code{delete-frame} event, whose normal definition is a command that
587 calls the function @code{delete-frame}. @xref{Misc Events}.
589 @node Finding All Frames
590 @section Finding All Frames
593 The function @code{frame-list} returns a list of all the frames that
594 have not been deleted. It is analogous to @code{buffer-list} for
595 buffers. The list that you get is newly created, so modifying the list
596 doesn't have any effect on the internals of Emacs.
599 @defun visible-frame-list
600 This function returns a list of just the currently visible frames.
601 @xref{Visibility of Frames}. (Terminal frames always count as
602 ``visible'', even though only the selected one is actually displayed.)
605 @defun next-frame &optional frame minibuf
606 The function @code{next-frame} lets you cycle conveniently through all
607 the frames from an arbitrary starting point. It returns the ``next''
608 frame after @var{frame} in the cycle. If @var{frame} is omitted or
609 @code{nil}, it defaults to the selected frame.
611 The second argument, @var{minibuf}, says which frames to consider:
615 Exclude minibuffer-only frames.
617 Consider all visible frames.
619 Consider all visible or iconified frames.
621 Consider only the frames using that particular window as their
628 @defun previous-frame &optional frame minibuf
629 Like @code{next-frame}, but cycles through all frames in the opposite
633 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
636 @node Frames and Windows
637 @section Frames and Windows
639 Each window is part of one and only one frame; you can get the frame
640 with @code{window-frame}.
642 @defun window-frame window
643 This function returns the frame that @var{window} is on.
646 All the non-minibuffer windows in a frame are arranged in a cyclic
647 order. The order runs from the frame's top window, which is at the
648 upper left corner, down and to the right, until it reaches the window at
649 the lower right corner (always the minibuffer window, if the frame has
650 one), and then it moves back to the top.
652 @defun frame-top-window frame
653 This returns the topmost, leftmost window of frame @var{frame}.
656 At any time, exactly one window on any frame is @dfn{selected within the
657 frame}. The significance of this designation is that selecting the
658 frame also selects this window. You can get the frame's current
659 selected window with @code{frame-selected-window}.
661 @defun frame-selected-window frame
662 This function returns the window on @var{frame} that is selected within
666 Conversely, selecting a window for Emacs with @code{select-window} also
667 makes that window selected within its frame. @xref{Selecting Windows}.
669 Another function that (usually) returns one of the windows in a frame is
670 @code{minibuffer-window}. @xref{Minibuffer Misc}.
672 @node Minibuffers and Frames
673 @section Minibuffers and Frames
675 Normally, each frame has its own minibuffer window at the bottom, which
676 is used whenever that frame is selected. If the frame has a minibuffer,
677 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
679 However, you can also create a frame with no minibuffer. Such a frame
680 must use the minibuffer window of some other frame. When you create the
681 frame, you can specify explicitly the minibuffer window to use (in some
682 other frame). If you don't, then the minibuffer is found in the frame
683 which is the value of the variable @code{default-minibuffer-frame}. Its
684 value should be a frame that does have a minibuffer.
686 If you use a minibuffer-only frame, you might want that frame to raise
687 when you enter the minibuffer. If so, set the variable
688 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
690 @defvar default-minibuffer-frame
691 This variable specifies the frame to use for the minibuffer window, by
692 default. It is always local to the current terminal and cannot be
693 buffer-local. @xref{Multiple Displays}.
699 @cindex selected frame
701 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
702 window always resides on the selected frame.
704 @defun selected-frame
705 This function returns the selected frame.
708 The X server normally directs keyboard input to the X window that the
709 mouse is in. Some window managers use mouse clicks or keyboard events
710 to @dfn{shift the focus} to various X windows, overriding the normal
711 behavior of the server.
713 Lisp programs can switch frames ``temporarily'' by calling
714 the function @code{select-frame}. This does not override the window
715 manager; rather, it escapes from the window manager's control until
716 that control is somehow reasserted.
718 When using a text-only terminal, there is no window manager; therefore,
719 @code{switch-frame} is the only way to switch frames, and the effect
720 lasts until overridden by a subsequent call to @code{switch-frame}.
721 Only the selected terminal frame is actually displayed on the terminal.
722 Each terminal screen except for the initial one has a number, and the
723 number of the selected frame appears in the mode line after the word
724 @samp{Emacs} (@pxref{Mode Line Variables}).
726 @c ??? This is not yet implemented properly.
727 @defun select-frame frame
728 This function selects frame @var{frame}, temporarily disregarding the
729 focus of the X server if any. The selection of @var{frame} lasts until
730 the next time the user does something to select a different frame, or
731 until the next time this function is called.
734 Emacs cooperates with the X server and the window managers by arranging
735 to select frames according to what the server and window manager ask
736 for. It does so by generating a special kind of input event, called a
737 @dfn{focus} event. The command loop handles a focus event by calling
738 @code{handle-select-frame}. @xref{Focus Events}.
740 @deffn Command handle-switch-frame frame
741 This function handles a focus event by selecting frame @var{frame}.
743 Focus events normally do their job by invoking this command.
744 Don't call it for any other reason.
747 @defun redirect-frame-focus frame focus-frame
748 This function redirects focus from @var{frame} to @var{focus-frame}.
749 This means that @var{focus-frame} will receive subsequent keystrokes
750 intended for @var{frame}. After such an event, the value of
751 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
752 events specifying @var{frame} will instead select @var{focus-frame}.
754 If @var{focus-frame} is @code{nil}, that cancels any existing
755 redirection for @var{frame}, which therefore once again receives its own
758 One use of focus redirection is for frames that don't have minibuffers.
759 These frames use minibuffers on other frames. Activating a minibuffer
760 on another frame redirects focus to that frame. This puts the focus on
761 the minibuffer's frame, where it belongs, even though the mouse remains
762 in the frame that activated the minibuffer.
764 Selecting a frame can also change focus redirections. Selecting frame
765 @code{bar}, when @code{foo} had been selected, changes any redirections
766 pointing to @code{foo} so that they point to @code{bar} instead. This
767 allows focus redirection to work properly when the user switches from
768 one frame to another using @code{select-window}.
770 This means that a frame whose focus is redirected to itself is treated
771 differently from a frame whose focus is not redirected.
772 @code{select-frame} affects the former but not the latter.
774 The redirection lasts until @code{redirect-frame-focus} is called to
778 @node Visibility of Frames
779 @section Visibility of Frames
780 @cindex visible frame
781 @cindex invisible frame
782 @cindex iconified frame
783 @cindex frame visibility
785 An X window frame may be @dfn{visible}, @dfn{invisible}, or
786 @dfn{iconified}. If it is visible, you can see its contents. If it is
787 iconified, the frame's contents do not appear on the screen, but an icon
788 does. If the frame is invisible, it doesn't show on the screen, not
791 Visibility is meaningless for terminal frames, since only the selected
792 one is actually displayed in any case.
794 @deffn Command make-frame-visible &optional frame
795 This function makes frame @var{frame} visible. If you omit @var{frame},
796 it makes the selected frame visible.
799 @deffn Command make-frame-invisible &optional frame
800 This function makes frame @var{frame} invisible. If you omit
801 @var{frame}, it makes the selected frame invisible.
804 @deffn Command iconify-frame &optional frame
805 This function iconifies frame @var{frame}. If you omit @var{frame}, it
806 iconifies the selected frame.
809 @defun frame-visible-p frame
810 This returns the visibility status of frame @var{frame}. The value is
811 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
812 @code{icon} if it is iconified.
815 The visibility status of a frame is also available as a frame
816 parameter. You can read or change it as such. @xref{X Frame
819 The user can iconify and deiconify frames with the window manager.
820 This happens below the level at which Emacs can exert any control, but
821 Emacs does provide events that you can use to keep track of such
822 changes. @xref{Misc Events}.
824 @node Raising and Lowering
825 @section Raising and Lowering Frames
827 The X Window System uses a desktop metaphor. Part of this metaphor is
828 the idea that windows are stacked in a notional third dimension
829 perpendicular to the screen surface, and thus ordered from ``highest''
830 to ``lowest''. Where two windows overlap, the one higher up covers the
831 one underneath. Even a window at the bottom of the stack can be seen if
832 no other window overlaps it.
834 @cindex raising a frame
835 @cindex lowering a frame
836 A window's place in this ordering is not fixed; in fact, users tend to
837 change the order frequently. @dfn{Raising} a window means moving it
838 ``up'', to the top of the stack. @dfn{Lowering} a window means moving
839 it to the bottom of the stack. This motion is in the notional third
840 dimension only, and does not change the position of the window on the
843 You can raise and lower Emacs's X windows with these functions:
845 @deffn Command raise-frame frame
846 This function raises frame @var{frame}.
849 @deffn Command lower-frame frame
850 This function lowers frame @var{frame}.
853 @defopt minibuffer-auto-raise
854 If this is non-@code{nil}, activation of the minibuffer raises the frame
855 that the minibuffer window is in.
858 You can also enable auto-raise (raising automatically when a frame is
859 selected) or auto-lower (lowering automatically when it is deselected)
860 for any frame using frame parameters. @xref{X Frame Parameters}.
862 @node Frame Configurations
863 @section Frame Configurations
864 @cindex frame configuration
866 A @dfn{frame configuration} records the current arrangement of frames,
867 all their properties, and the window configuration of each one.
869 @defun current-frame-configuration
870 This function returns a frame configuration list that describes
871 the current arrangement of frames and their contents.
874 @defun set-frame-configuration configuration
875 This function restores the state of frames described in
880 @section Mouse Tracking
881 @cindex mouse tracking
882 @cindex tracking the mouse
884 Sometimes it is useful to @dfn{track} the mouse, which means to display
885 something to indicate where the mouse is and move the indicator as the
886 mouse moves. For efficient mouse tracking, you need a way to wait until
887 the mouse actually moves.
889 The convenient way to track the mouse is to ask for events to represent
890 mouse motion. Then you can wait for motion by waiting for an event. In
891 addition, you can easily handle any other sorts of events that may
892 occur. That is useful, because normally you don't want to track the
893 mouse forever---only until some other event, such as the release of a
896 @defspec track-mouse body@dots{}
897 Execute @var{body}, meanwhile generating input events for mouse motion.
898 The code in @var{body} can read these events with @code{read-event} or
899 @code{read-key-sequence}. @xref{Motion Events}, for the format of mouse
902 The value of @code{track-mouse} is that of the last form in @var{body}.
905 The usual purpose of tracking mouse motion is to indicate on the screen
906 the consequences of pushing or releasing a button at the current
909 In many cases, you can avoid the need to track the mouse by using
910 the @code{mouse-face} text property (@pxref{Special Properties}).
911 That works at a much lower level and runs more smoothly than
912 Lisp-level mouse tracking.
915 @c These are not implemented yet.
917 These functions change the screen appearance instantaneously. The
918 effect is transient, only until the next ordinary Emacs redisplay. That
919 is ok for mouse tracking, since it doesn't make sense for mouse tracking
920 to change the text, and the body of @code{track-mouse} normally reads
921 the events itself and does not do redisplay.
923 @defun x-contour-region window beg end
924 This function draws lines to make a box around the text from @var{beg}
925 to @var{end}, in window @var{window}.
928 @defun x-uncontour-region window beg end
929 This function erases the lines that would make a box around the text
930 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
931 a contour that you previously made by calling @code{x-contour-region}.
934 @defun x-draw-rectangle frame left top right bottom
935 This function draws a hollow rectangle on frame @var{frame} with the
936 specified edge coordinates, all measured in pixels from the inside top
937 left corner. It uses the cursor color, the one used for indicating the
941 @defun x-erase-rectangle frame left top right bottom
942 This function erases a hollow rectangle on frame @var{frame} with the
943 specified edge coordinates, all measured in pixels from the inside top
944 left corner. Erasure means redrawing the text and background that
945 normally belong in the specified rectangle.
950 @section Mouse Position
951 @cindex mouse position
952 @cindex position of mouse
954 The functions @code{mouse-position} and @code{set-mouse-position}
955 give access to the current position of the mouse.
957 @defun mouse-position
958 This function returns a description of the position of the mouse. The
959 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
960 and @var{y} are integers giving the position in characters relative to
961 the top left corner of the inside of @var{frame}.
964 @defun set-mouse-position frame x y
965 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
966 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
967 giving the position in characters relative to the top left corner of the
968 inside of @var{frame}.
971 @defun mouse-pixel-position
972 This function is like @code{mouse-position} except that it returns
973 coordinates in units of pixels rather than units of characters.
976 @defun set-mouse-pixel-position frame x y
977 This function warps the mouse like @code{set-mouse-position} except that
978 @var{x} and @var{y} are in units of pixels rather than units of
979 characters. These coordinates are not required to be within the frame.
985 @section Pop-Up Menus
987 When using X windows, a Lisp program can pop up a menu which the
988 user can choose from with the mouse.
990 @defun x-popup-menu position menu
991 This function displays a pop-up menu and returns an indication of
992 what selection the user makes.
994 The argument @var{position} specifies where on the screen to put the
995 menu. It can be either a mouse button event (which says to put the menu
996 where the user actuated the button) or a list of this form:
999 ((@var{xoffset} @var{yoffset}) @var{window})
1003 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1004 pixels, counting from the top left corner of @var{window}'s frame.
1006 If @var{position} is @code{t}, it means to use the current mouse
1007 position. If @var{position} is @code{nil}, it means to precompute the
1008 key binding equivalents for the keymaps specified in @var{menu},
1009 without actually displaying or popping up the menu.
1011 The argument @var{menu} says what to display in the menu. It can be a
1012 keymap or a list of keymaps (@pxref{Menu Keymaps}). Alternatively, it
1013 can have the following form:
1016 (@var{title} @var{pane1} @var{pane2}...)
1020 where each pane is a list of form
1023 (@var{title} (@var{line} . @var{item})...)
1026 Each @var{line} should be a string, and each @var{item} should be the
1027 value to return if that @var{line} is chosen.
1030 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu if
1031 a prefix key with a menu keymap would do the job. If you use a menu
1032 keymap to implement a menu, @kbd{C-h c} and @kbd{C-h a} can see the
1033 individual items in that menu and provide help for them. If instead you
1034 implement the menu by defining a command that calls @code{x-popup-menu},
1035 the help facilities cannot know what happens inside that command, so
1036 they cannot give any help for the menu's items. This is the reason why
1037 all the menu bar items are normally implemented with menu keymaps
1038 (@pxref{Menu Keymaps}).
1041 @section Dialog Boxes
1042 @cindex dialog boxes
1044 A dialog box is a variant of a pop-up menu. It looks a little
1045 different (if Emacs uses an X toolkit), it always appears in the center
1046 of a frame, and it has just one level and one pane. The main use of
1047 dialog boxes is for asking questions that the user can answer with
1048 ``yes'', ``no'', and a few other alternatives. The functions
1049 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1050 keyboard, when called from commands invoked by mouse clicks.
1052 @defun x-popup-dialog position contents
1053 This function displays a pop-up dialog box and returns an indication of
1054 what selection the user makes. The argument @var{contents} specifies
1055 the alternatives to offer; it has this format:
1058 (@var{title} (@var{string} . @var{value})@dots{})
1062 which looks like the list that specifies a single pane for
1063 @code{x-popup-menu}.
1065 The return value is @var{value} from the chosen alternative.
1067 An element of the list may be just a string instead of a cons cell
1068 @code{(@var{string} . @var{value})}. That makes a box that cannot
1071 If @code{nil} appears in the list, it separates the left-hand items from
1072 the right-hand items; items that precede the @code{nil} appear on the
1073 left, and items that follow the @code{nil} appear on the right. If you
1074 don't include a @code{nil} in the list, then approximately half the
1075 items appear on each side.
1077 Dialog boxes always appear in the center of a frame; the argument
1078 @var{position} specifies which frame. The possible values are as in
1079 @code{x-popup-menu}, but the precise coordinates don't matter; only the
1082 If your Emacs executable does not use an X toolkit, then it cannot
1083 display a real dialog box; so instead it displays the same items in a
1084 pop-up menu in the center of the frame.
1087 @node Pointer Shapes
1088 @section Pointer Shapes
1089 @cindex pointer shape
1090 @cindex mouse pointer shape
1092 These variables specify which shape to use for the mouse pointer in
1096 @item x-pointer-shape
1097 @vindex x-pointer-shape
1098 This variable specifies the pointer shape to use ordinarily in the Emacs
1101 @item x-sensitive-text-pointer-shape
1102 @vindex x-sensitive-text-pointer-shape
1103 This variable specifies the pointer shape to use when the mouse
1104 is over mouse-sensitive text.
1107 These variables affect newly created frames. They do not normally
1108 affect existing frames; however, if you set the mouse color of a frame,
1109 that also updates its pointer shapes based on the current values of
1110 these variables. @xref{X Frame Parameters}.
1112 The values you can use, to specify either of these pointer shapes, are
1113 defined in the file @file{lisp/x-win.el}. Use @kbd{M-x apropos
1114 @key{RET} x-pointer @key{RET}} to see a list of them.
1117 @section X Selections
1118 @cindex selection (for X windows)
1120 The X server records a set of @dfn{selections} which permit transfer of
1121 data between application programs. The various selections are
1122 distinguished by @dfn{selection types}, represented in Emacs by
1123 symbols. X clients including Emacs can read or set the selection for
1126 @defun x-set-selection type data
1127 This function sets a ``selection'' in the X server. It takes two
1128 arguments: a selection type @var{type}, and the value to assign to it,
1129 @var{data}. If @var{data} is @code{nil}, it means to clear out the
1130 selection. Otherwise, @var{data} may be a string, a symbol, an integer
1131 (or a cons of two integers or list of two integers), an overlay, or a
1132 cons of two markers pointing to the same buffer. An overlay or a pair
1133 of markers stands for text in the overlay or between the markers.
1135 The data may also be a vector of valid non-vector selection values.
1137 Each possible @var{type} has its own selection value, which changes
1138 independently. The usual values of @var{type} are @code{PRIMARY} and
1139 @code{SECONDARY}; these are symbols with upper-case names, in accord
1140 with X Window System conventions. The default is @code{PRIMARY}.
1143 @defun x-get-selection &optional type data-type
1144 This function accesses selections set up by Emacs or by other X
1145 clients. It takes two optional arguments, @var{type} and
1146 @var{data-type}. The default for @var{type}, the selection type, is
1149 The @var{data-type} argument specifies the form of data conversion to
1150 use, to convert the raw data obtained from another X client into Lisp
1151 data. Meaningful values include @code{TEXT}, @code{STRING},
1152 @code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
1153 @code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
1154 @code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
1155 @code{NAME}, @code{ATOM}, and @code{INTEGER}. (These are symbols with
1156 upper-case names in accord with X conventions.) The default for
1157 @var{data-type} is @code{STRING}.
1161 The X server also has a set of numbered @dfn{cut buffers} which can
1162 store text or other data being moved between applications. Cut buffers
1163 are considered obsolete, but Emacs supports them for the sake of X
1164 clients that still use them.
1166 @defun x-get-cut-buffer n
1167 This function returns the contents of cut buffer number @var{n}.
1170 @defun x-set-cut-buffer string
1171 This function stores @var{string} into the first cut buffer (cut buffer
1172 0), moving the other values down through the series of cut buffers, much
1173 like the way successive kills in Emacs move down the kill ring.
1177 @section Color Names
1179 @defun x-color-defined-p color
1180 This function reports whether a color name is meaningful. It returns
1181 @code{t} if so; otherwise, @code{nil}.
1183 Note that this does not tell you whether the display you are using
1184 really supports that color. You can ask for any defined color on any
1185 kind of display, and you will get some result---that is how the X server
1186 works. Here's an approximate way to test whether your display supports
1187 the color @var{color}:
1190 (defun x-color-supported-p (color)
1191 (and (x-color-defined-p color)
1192 (or (x-display-color-p)
1193 (member color '("black" "white"))
1194 (and (> (x-display-planes) 1)
1195 (equal color "gray")))))
1199 @defun x-color-values color
1200 This function returns a value that describes what @var{color} should
1201 ideally look like. If @var{color} is defined, the value is a list of
1202 three integers, which give the amount of red, the amount of green, and
1203 the amount of blue. Each integer ranges in principle from 0 to 65535,
1204 but in practice no value seems to be above 65280. If @var{color} is not
1205 defined, the value is @code{nil}.
1208 (x-color-values "black")
1210 (x-color-values "white")
1211 @result{} (65280 65280 65280)
1212 (x-color-values "red")
1213 @result{} (65280 0 0)
1214 (x-color-values "pink")
1215 @result{} (65280 49152 51968)
1216 (x-color-values "hungry")
1222 @section X Resources
1224 @defun x-get-resource attribute class &optional component subclass
1225 The function @code{x-get-resource} retrieves a resource value from the X
1226 Windows defaults database.
1228 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
1229 This function searches using a key of the form
1230 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
1231 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
1234 The optional arguments @var{component} and @var{subclass} add to the key
1235 and the class, respectively. You must specify both of them or neither.
1236 If you specify them, the key is
1237 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
1238 @samp{Emacs.@var{class}.@var{subclass}}.
1241 @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
1244 @section Data about the X Server
1246 This section describes functions and a variable that you can use to
1247 get information about the capabilities and origin of an X display that
1248 Emacs is using. Each of these functions lets you specify the display
1249 you are interested in: the @var{display} argument can be either a
1250 display name, or a frame (meaning use the display that frame is on). If
1251 you omit the @var{display} argument, or specify @code{nil}, that means
1252 to use the selected frame's display.
1254 @defun x-display-screens &optional display
1255 This function returns the number of screens associated with the display.
1258 @defun x-server-version &optional display
1259 This function returns the list of version numbers of the X server
1260 running the display.
1263 @defun x-server-vendor &optional display
1264 This function returns the vendor that provided the X server software.
1267 @defun x-display-pixel-height &optional display
1268 This function returns the height of the screen in pixels.
1271 @defun x-display-mm-height &optional display
1272 This function returns the height of the screen in millimeters.
1275 @defun x-display-pixel-width &optional display
1276 This function returns the width of the screen in pixels.
1279 @defun x-display-mm-width &optional display
1280 This function returns the width of the screen in millimeters.
1283 @defun x-display-backing-store &optional display
1284 This function returns the backing store capability of the screen.
1285 Values can be the symbols @code{always}, @code{when-mapped}, or
1289 @defun x-display-save-under &optional display
1290 This function returns non-@code{nil} if the display supports the
1294 @defun x-display-planes &optional display
1295 This function returns the number of planes the display supports.
1298 @defun x-display-visual-class &optional display
1299 This function returns the visual class for the screen. The value is one
1300 of the symbols @code{static-gray}, @code{gray-scale},
1301 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
1302 @code{direct-color}.
1305 @defun x-display-grayscale-p &optional display
1306 This function returns @code{t} if the screen can display shades of gray.
1309 @defun x-display-color-p &optional display
1310 This function returns @code{t} if the screen is a color screen.
1313 @defun x-display-color-cells &optional display
1314 This function returns the number of color cells the screen supports.
1318 @defvar x-no-window-manager
1319 This variable's value is is @code{t} if no X window manager is in use.
1325 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
1326 width and height of an X Window frame, measured in pixels.