2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/frames
7 @node Frames, Positions, Windows, Top
11 In Emacs editing, a @dfn{frame} is a screen object that contains one
12 or more Emacs windows, see @ref{Windows}. It's the kind of object that
13 is called a ``window'' in the terminology of graphical environments; but
14 we can't call it a ``window'' here, because Emacs uses that word in a
15 different way. In Emacs Lisp, a @dfn{frame object} is a Lisp object
16 that represents a frame on the screen. @xref{Frame Type}.
18 A frame initially contains a single main window and/or a minibuffer
19 window; you can subdivide the main window vertically or horizontally
20 into smaller windows. @xref{Splitting Windows}.
22 A @dfn{terminal} is a display device capable of displaying one or
23 more Emacs frames. On GNU and Unix systems, Emacs supports any number
24 of different terminals in one session, and can mix GUI and text-only
25 frames in the same session.
27 Emacs represents each terminal on which it displays frames as a
28 special @dfn{terminal object} data type, see @ref{Terminal Type}.
30 @cindex terminal frame
31 When Emacs runs on a text-only terminal, it starts with one
32 @dfn{terminal frame}. If you create additional frames on the same
33 terminal, Emacs displays one and only one at any given time---on that
34 terminal screen, of course. You can create additional frames, either
35 text-only or GUI, on other terminals from the same Emacs session.
36 (This comes in handy when you connect to the same session from several
37 remote locations.) @xref{Multiple Terminals}.
40 When Emacs communicates directly with a supported window system, such
41 as X, it does not have a terminal frame; instead, it starts with
42 a single @dfn{window frame}, but you can create more, and Emacs can
43 display several such frames at once as is usual for window systems.
46 This predicate returns a non-@code{nil} value if @var{object} is a
47 frame, and @code{nil} otherwise. For a frame, the value indicates which
48 kind of display the frame uses:
52 The frame is displayed in an X window.
54 A terminal frame on a character display.
56 The frame is displayed on MS-Windows 9X/NT.
58 The frame is displayed on an MS-DOS terminal.
62 @defun frame-terminal &optional frame
63 This function returns the terminal object (@pxref{Terminal Type}) that
64 displays @var{frame}. If @var{frame} is @code{nil} or unspecified, it
65 defaults to the selected frame.
68 @defun terminal-live-p object
69 This predicate returns a non-@code{nil} value if @var{object} is a
70 terminal that is alive (i.e.@: was not deleted), and @code{nil}
71 otherwise. For live terminals, the return value indicates what kind
72 of frames are displayed on that terminal; the list of possible values
73 is the same as for @code{framep} above.
77 * Creating Frames:: Creating additional frames.
78 * Multiple Displays:: Creating frames on other displays.
79 * Multiple Terminals:: Displaying on several different devices.
80 * Frame Parameters:: Controlling frame size, position, font, etc.
81 * Terminal Parameters:: Parameters common for all frames on terminal.
82 * Frame Titles:: Automatic updating of frame titles.
83 * Deleting Frames:: Frames last until explicitly deleted.
84 * Finding All Frames:: How to examine all existing frames.
85 * Frames and Windows:: A frame contains windows;
86 display of text always works through windows.
87 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
88 * Input Focus:: Specifying the selected frame.
89 * Visibility of Frames:: Frames may be visible or invisible, or icons.
90 * Raising and Lowering:: Raising a frame makes it hide other windows;
91 lowering it makes the others hide it.
92 * Frame Configurations:: Saving the state of all frames.
93 * Mouse Tracking:: Getting events that say when the mouse moves.
94 * Mouse Position:: Asking where the mouse is, or moving it.
95 * Pop-Up Menus:: Displaying a menu for the user to select from.
96 * Dialog Boxes:: Displaying a box to ask yes or no.
97 * Pointer Shape:: Specifying the shape of the mouse pointer.
98 * Window System Selections:: Transferring text to and from other X clients.
99 * Drag and Drop:: Internals of Drag-and-Drop implementation.
100 * Color Names:: Getting the definitions of color names.
101 * Text Terminal Colors:: Defining colors for text-only terminals.
102 * Resources:: Getting resource values from the server.
103 * Display Feature Testing:: Determining the features of a terminal.
106 @xref{Display}, for information about the related topic of
107 controlling Emacs redisplay.
109 @node Creating Frames
110 @section Creating Frames
112 To create a new frame, call the function @code{make-frame}.
114 @defun make-frame &optional alist
115 This function creates and returns a new frame, displaying the current
116 buffer. If you are using a supported window system, it makes a window
117 frame; otherwise, it makes a terminal frame.
119 The argument is an alist specifying frame parameters. Any parameters
120 not mentioned in @var{alist} default according to the value of the
121 variable @code{default-frame-alist}; parameters not specified even there
122 default from the standard X resources or whatever is used instead on
125 After the frame is created, this function applies to it the
126 parameters, if any, listed in the value of
127 @code{frame-inherited-parameters} (see below) and not present in the
128 argument, taking the values from the frame that was selected when
129 @code{make-frame} was called.
131 The set of possible parameters depends in principle on what kind of
132 window system Emacs uses to display its frames. @xref{Window Frame
133 Parameters}, for documentation of individual parameters you can specify.
135 This function itself does not make the new frame the selected frame.
136 @xref{Input Focus}. The previously selected frame remains selected.
137 However, the window system may select the new frame for its own reasons,
138 for instance if the frame appears under the mouse pointer and your
139 setup is for focus to follow the pointer.
142 @defvar before-make-frame-hook
143 A normal hook run by @code{make-frame} before it actually creates the
147 @defvar after-make-frame-functions
148 An abnormal hook run by @code{make-frame} after it creates the frame.
149 Each function in @code{after-make-frame-functions} receives one argument, the
153 @defvar frame-inherited-parameters
154 This variable specifies the list of frame parameters that a newly
155 created frame inherits from the currently selected frame. For each
156 parameter (a symbol) that is an element in the list and is not present
157 in the argument to @code{make-frame}, the function sets the value of
158 that parameter in the created frame to its value in the selected
162 @node Multiple Displays
163 @section Multiple Displays
164 @cindex multiple X displays
165 @cindex displays, multiple
167 A single Emacs can talk to more than one X display.
168 Initially, Emacs uses just one display---the one chosen with the
169 @code{DISPLAY} environment variable or with the @samp{--display} option
170 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
171 another display, use the command @code{make-frame-on-display} or specify
172 the @code{display} frame parameter when you create the frame.
174 Emacs treats each X server as a separate terminal, giving each one its
175 own selected frame and its own minibuffer windows. However, only one of
176 those frames is ``@emph{the} selected frame'' at any given moment, see
179 A few Lisp variables are @dfn{terminal-local}; that is, they have a
180 separate binding for each terminal. The binding in effect at any time
181 is the one for the terminal that the currently selected frame belongs
182 to. These variables include @code{default-minibuffer-frame},
183 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
184 @code{system-key-alist}. They are always terminal-local, and can never
185 be buffer-local (@pxref{Buffer-Local Variables}).
187 A single X server can handle more than one screen. A display name
188 @samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
189 part specifies the screen number for a given server. When you use two
190 screens belonging to one server, Emacs knows by the similarity in their
191 names that they share a single keyboard, and it treats them as a single
194 Note that some graphical terminals can output to more than a one
195 monitor (or other output device) at the same time. On these
196 ``multi-monitor'' setups, a single @var{display} value controls the
197 output to all the physical monitors. In this situation, there is
198 currently no platform-independent way for Emacs to distinguish between
199 the different physical monitors.
201 @deffn Command make-frame-on-display display &optional parameters
202 This creates and returns a new frame on display @var{display}, taking
203 the other frame parameters from @var{parameters}. Aside from the
204 @var{display} argument, it is like @code{make-frame} (@pxref{Creating
208 @deffn Command make-frame-on-tty tty type &optional parameters
209 This command creates a text-only frame on another text terminal. The
210 argument @var{tty} identifies the terminal device by its file name,
211 e.g., @file{/dev/ttys2}, and @var{type} gives the device type as a
212 string, e.g., @code{"vt100"}, to use for searching the
213 termcap/terminfo database for the entry describing capabilities of the
214 device. Optional argument @var{parameters} specifies additional
215 parameters for the frame.
218 @defun x-display-list
219 This returns a list that indicates which X displays Emacs has a
220 connection to. The elements of the list are strings, and each one is
224 @defun x-open-connection display &optional xrm-string must-succeed
225 This function opens a connection to the X display @var{display}. It
226 does not create a frame on that display, but it permits you to check
227 that communication can be established with that display.
229 The optional argument @var{xrm-string}, if not @code{nil}, is a
230 string of resource names and values, in the same format used in the
231 @file{.Xresources} file. The values you specify override the resource
232 values recorded in the X server itself; they apply to all Emacs frames
233 created on this display. Here's an example of what this string might
237 "*BorderWidth: 3\n*InternalBorder: 2\n"
240 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
242 If @var{must-succeed} is non-@code{nil}, failure to open the connection
243 terminates Emacs. Otherwise, it is an ordinary Lisp error.
246 @defun x-close-connection display
247 This function closes the connection to display @var{display}. Before
248 you can do this, you must first delete all the frames that were open on
249 that display (@pxref{Deleting Frames}).
252 @node Multiple Terminals
253 @section Multiple Terminals
254 @cindex multiple terminals
257 Emacs represents each terminal on which it displays frames as a
258 special @dfn{terminal object} data type, see @ref{Terminal Type}. The
259 terminal object has the following attributes:
263 The name of the device used by the terminal (e.g., @file{/dev/tty}).
266 The terminal and keyboard coding systems (@pxref{Terminal I/O
267 Encoding}) used on the terminal.
270 The kind of frames (@pxref{Frames}) the terminal is displaying.
273 A list of the terminal parameters (@pxref{Terminal Parameters}).
276 There's no primitive for creating terminal objects; Emacs creates
277 them as needed when you call one of the primitives, such as
278 @code{make-frame-on-tty} (@pxref{Multiple Displays}), that start
279 displaying on a new terminal.
282 This function return the list of all the terminal objects used by
283 Emacs to display frames in this session.
286 @defun delete-terminal &optional terminal force
287 This function deletes all frames on @var{terminal} and frees the
288 resources used by it. @var{terminal} can be a terminal object, a
289 frame (meaning that frame's terminal), or @code{nil} (meaning the
290 selected frame's terminal). Normally, the function signals an error
291 if you attempt to delete the sole active terminal, but if @var{force}
292 is non-@code{nil}, you are allowed to do so. This function runs the
293 hook @code{delete-terminal-functions}, passing each function a single
294 argument, @var{terminal}.
297 @defun terminal-name &optional terminal
298 This function returns the file name of the device used by
299 @var{terminal}. If @var{terminal} is omitted or @code{nil}, it
300 defaults to the selected frame's terminal. @var{terminal} can also be
301 a frame, meaning that frame's terminal.
304 @defun get-device-terminal device
305 This function is in a sense the opposite of @code{terminal-name}: it
306 returns a terminal whose device name is given by @var{device}. If
307 @var{device} is a string, it can be either the file name of a terminal
308 device or the name of an X display of the form
309 @samp{@var{host}:@var{server}.@var{screen}} (@pxref{Multiple
310 Displays}). If @var{device} is a frame, this function returns that
311 frame's terminal; @code{nil} means the selected frame. Finally, if
312 @var{device} is a terminal object that represents a live terminal,
313 that terminal is returned. The function signals an error if its
314 argument is none of the above.
317 @node Frame Parameters
318 @section Frame Parameters
319 @cindex frame parameters
321 A frame has many parameters that control its appearance and behavior.
322 Just what parameters a frame has depends on what display mechanism it
325 Frame parameters exist mostly for the sake of window systems. A
326 terminal frame has a few parameters, mostly for compatibility's sake;
327 only the @code{height}, @code{width}, @code{name}, @code{title},
328 @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
329 parameters do something special. If the terminal supports colors, the
330 parameters @code{foreground-color}, @code{background-color},
331 @code{background-mode} and @code{display-type} are also meaningful.
332 If the terminal supports frame transparency, the parameter
333 @code{alpha} is also meaningful.
335 You can use frame parameters to define frame-local bindings for
336 variables. @xref{Frame-Local Variables}.
339 * Parameter Access:: How to change a frame's parameters.
340 * Initial Parameters:: Specifying frame parameters when you make a frame.
341 * Window Frame Parameters:: List of frame parameters for window systems.
342 * Size and Position:: Changing the size and position of a frame.
343 * Geometry:: Parsing geometry specifications.
346 @node Parameter Access
347 @subsection Access to Frame Parameters
349 These functions let you read and change the parameter values of a
352 @defun frame-parameter frame parameter
353 This function returns the value of the parameter @var{parameter} (a
354 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
355 selected frame's parameter. If @var{frame} has no setting for
356 @var{parameter}, this function returns @code{nil}.
359 @defun frame-parameters &optional frame
360 The function @code{frame-parameters} returns an alist listing all the
361 parameters of @var{frame} and their values. If @var{frame} is
362 @code{nil} or omitted, this returns the selected frame's parameters
365 @defun modify-frame-parameters frame alist
366 This function alters the parameters of frame @var{frame} based on the
367 elements of @var{alist}. Each element of @var{alist} has the form
368 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
369 parameter. If you don't mention a parameter in @var{alist}, its value
370 doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
373 You can use this function to define frame-local bindings for
374 variables, see @ref{Frame-Local Variables}.
377 @defun set-frame-parameter frame parm value
378 This function sets the frame parameter @var{parm} to the specified
379 @var{value}. If @var{frame} is @code{nil}, it defaults to the
383 @defun modify-all-frames-parameters alist
384 This function alters the frame parameters of all existing frames
385 according to @var{alist}, then modifies @code{default-frame-alist}
386 (and, if necessary, @code{initial-frame-alist}) to apply the same
387 parameter values to frames that will be created henceforth.
390 @node Initial Parameters
391 @subsection Initial Frame Parameters
393 You can specify the parameters for the initial startup frame
394 by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
396 @defvar initial-frame-alist
397 This variable's value is an alist of parameter values used when creating
398 the initial window frame. You can set this variable to specify the
399 appearance of the initial frame without altering subsequent frames.
400 Each element has the form:
403 (@var{parameter} . @var{value})
406 Emacs creates the initial frame before it reads your init
407 file. After reading that file, Emacs checks @code{initial-frame-alist},
408 and applies the parameter settings in the altered value to the already
409 created initial frame.
411 If these settings affect the frame geometry and appearance, you'll see
412 the frame appear with the wrong ones and then change to the specified
413 ones. If that bothers you, you can specify the same geometry and
414 appearance with X resources; those do take effect before the frame is
415 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
417 X resource settings typically apply to all frames. If you want to
418 specify some X resources solely for the sake of the initial frame, and
419 you don't want them to apply to subsequent frames, here's how to achieve
420 this. Specify parameters in @code{default-frame-alist} to override the
421 X resources for subsequent frames; then, to prevent these from affecting
422 the initial frame, specify the same parameters in
423 @code{initial-frame-alist} with values that match the X resources.
426 If these parameters specify a separate minibuffer-only frame with
427 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
430 @defvar minibuffer-frame-alist
431 This variable's value is an alist of parameter values used when creating
432 an initial minibuffer-only frame---if such a frame is needed, according
433 to the parameters for the main initial frame.
436 @defvar default-frame-alist
437 This is an alist specifying default values of frame parameters for all
438 Emacs frames---the first frame, and subsequent frames. When using the X
439 Window System, you can get the same results by means of X resources
442 Setting this variable does not affect existing frames.
445 Functions that display a buffer in a separate frame can override the
446 default parameters by supplying their own parameters. @xref{Definition
447 of special-display-frame-alist}.
449 If you use options that specify window appearance when you invoke Emacs,
450 they take effect by adding elements to @code{default-frame-alist}. One
451 exception is @samp{-geometry}, which adds the specified position to
452 @code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command
453 Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
455 @node Window Frame Parameters
456 @subsection Window Frame Parameters
458 Just what parameters a frame has depends on what display mechanism
459 it uses. This section describes the parameters that have special
460 meanings on some or all kinds of terminals. Of these, @code{name},
461 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
462 @code{buffer-predicate} provide meaningful information in terminal
463 frames, and @code{tty-color-mode} is meaningful @emph{only} in
467 * Basic Parameters:: Parameters that are fundamental.
468 * Position Parameters:: The position of the frame on the screen.
469 * Size Parameters:: Frame's size.
470 * Layout Parameters:: Size of parts of the frame, and
471 enabling or disabling some parts.
472 * Buffer Parameters:: Which buffers have been or should be shown.
473 * Management Parameters:: Communicating with the window manager.
474 * Cursor Parameters:: Controlling the cursor appearance.
475 * Color Parameters:: Colors of various parts of the frame.
478 @node Basic Parameters
479 @subsubsection Basic Parameters
481 These frame parameters give the most basic information about the
482 frame. @code{title} and @code{name} are meaningful on all terminals.
486 The display on which to open this frame. It should be a string of the
487 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
488 @code{DISPLAY} environment variable.
491 This parameter describes the range of possible colors that can be used
492 in this frame. Its value is @code{color}, @code{grayscale} or
496 If a frame has a non-@code{nil} title, it appears in the window
497 system's title bar at the top of the frame, and also in the mode line
498 of windows in that frame if @code{mode-line-frame-identification} uses
499 @samp{%F} (@pxref{%-Constructs}). This is normally the case when
500 Emacs is not using a window system, and can only display one frame at
501 a time. @xref{Frame Titles}.
504 The name of the frame. The frame name serves as a default for the frame
505 title, if the @code{title} parameter is unspecified or @code{nil}. If
506 you don't specify a name, Emacs sets the frame name automatically
507 (@pxref{Frame Titles}).
509 If you specify the frame name explicitly when you create the frame, the
510 name is also used (instead of the name of the Emacs executable) when
511 looking up X resources for the frame.
514 @node Position Parameters
515 @subsubsection Position Parameters
517 Position parameters' values are normally measured in pixels, but on
518 text-only terminals they count characters or lines instead.
522 The position, in pixels, of the left (or right) edge of the frame with
523 respect to the left (or right) edge of the screen. The value may be:
527 A positive integer relates the left edge of the frame to the left edge
528 of the screen. A negative integer relates the right frame edge to the
531 @item @code{(+ @var{pos})}
532 This specifies the position of the left frame edge relative to the left
533 screen edge. The integer @var{pos} may be positive or negative; a
534 negative value specifies a position outside the screen.
536 @item @code{(- @var{pos})}
537 This specifies the position of the right frame edge relative to the right
538 screen edge. The integer @var{pos} may be positive or negative; a
539 negative value specifies a position outside the screen.
542 Some window managers ignore program-specified positions. If you want to
543 be sure the position you specify is not ignored, specify a
544 non-@code{nil} value for the @code{user-position} parameter as well.
547 The screen position of the top (or bottom) edge, in pixels, with respect
548 to the top (or bottom) edge of the screen. It works just like
549 @code{left}, except vertically instead of horizontally.
552 The screen position of the left edge @emph{of the frame's icon}, in
553 pixels, counting from the left edge of the screen. This takes effect if
554 and when the frame is iconified.
556 If you specify a value for this parameter, then you must also specify
557 a value for @code{icon-top} and vice versa. The window manager may
558 ignore these two parameters.
561 The screen position of the top edge @emph{of the frame's icon}, in
562 pixels, counting from the top edge of the screen. This takes effect if
563 and when the frame is iconified.
566 When you create a frame and specify its screen position with the
567 @code{left} and @code{top} parameters, use this parameter to say whether
568 the specified position was user-specified (explicitly requested in some
569 way by a human user) or merely program-specified (chosen by a program).
570 A non-@code{nil} value says the position was user-specified.
572 Window managers generally heed user-specified positions, and some heed
573 program-specified positions too. But many ignore program-specified
574 positions, placing the window in a default fashion or letting the user
575 place it with the mouse. Some window managers, including @code{twm},
576 let the user specify whether to obey program-specified positions or
579 When you call @code{make-frame}, you should specify a non-@code{nil}
580 value for this parameter if the values of the @code{left} and @code{top}
581 parameters represent the user's stated preference; otherwise, use
585 @node Size Parameters
586 @subsubsection Size Parameters
588 Size parameters' values are normally measured in pixels, but on
589 text-only terminals they count characters or lines instead.
593 The height of the frame contents, in characters. (To get the height in
594 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
597 The width of the frame contents, in characters. (To get the width in
598 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
601 This does for the size parameters @code{height} and @code{width} what
602 the @code{user-position} parameter (see above) does for the position
603 parameters @code{top} and @code{left}.
606 Specify that width, height or both shall be set to the size of the screen.
607 The value @code{fullwidth} specifies that width shall be the size of the
608 screen. The value @code{fullheight} specifies that height shall be the
609 size of the screen. The value @code{fullboth} specifies that both the
610 width and the height shall be set to the size of the screen.
613 @node Layout Parameters
614 @subsubsection Layout Parameters
616 These frame parameters enable or disable various parts of the
617 frame, or control their sizes.
621 The width in pixels of the frame's border.
623 @item internal-border-width
624 The distance in pixels between text (or fringe) and the frame's border.
626 @item vertical-scroll-bars
627 Whether the frame has scroll bars for vertical scrolling, and which side
628 of the frame they should be on. The possible values are @code{left},
629 @code{right}, and @code{nil} for no scroll bars.
632 @item horizontal-scroll-bars
633 Whether the frame has scroll bars for horizontal scrolling
634 (non-@code{nil} means yes). Horizontal scroll bars are not currently
638 @item scroll-bar-width
639 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
640 use the default width.
644 The default width of the left and right fringes of windows in this
645 frame (@pxref{Fringes}). If either of these is zero, that effectively
646 removes the corresponding fringe. A value of @code{nil} stands for
647 the standard fringe width, which is the width needed to display the
650 The combined fringe widths must add up to an integral number of
651 columns, so the actual default fringe widths for the frame may be
652 larger than the specified values. The extra width needed to reach an
653 acceptable total is distributed evenly between the left and right
654 fringe. However, you can force one fringe or the other to a precise
655 width by specifying that width as a negative integer. If both widths are
656 negative, only the left fringe gets the specified width.
659 The number of lines to allocate at the top of the frame for a menu
660 bar. The default is 1. A value of @code{nil} means don't display a
661 menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one
662 menu bar line; they treat larger values as 1.)
665 The number of lines to use for the tool bar. A value of @code{nil}
666 means don't display a tool bar. (GTK allows at most one tool bar line;
667 it treats larger values as 1.)
670 Additional space to leave below each text line, in pixels (a positive
671 integer). @xref{Line Height}, for more information.
674 @node Buffer Parameters
675 @subsubsection Buffer Parameters
677 These frame parameters, meaningful on all kinds of terminals, deal
678 with which buffers have been, or should, be displayed in the frame.
682 Whether this frame has its own minibuffer. The value @code{t} means
683 yes, @code{nil} means no, @code{only} means this frame is just a
684 minibuffer. If the value is a minibuffer window (in some other frame),
685 the new frame uses that minibuffer.
687 @item buffer-predicate
688 The buffer-predicate function for this frame. The function
689 @code{other-buffer} uses this predicate (from the selected frame) to
690 decide which buffers it should consider, if the predicate is not
691 @code{nil}. It calls the predicate with one argument, a buffer, once for
692 each buffer; if the predicate returns a non-@code{nil} value, it
693 considers that buffer.
696 A list of buffers that have been selected in this frame,
697 ordered most-recently-selected first.
700 If non-@code{nil}, this frame's window is never split automatically.
703 @node Management Parameters
704 @subsubsection Window Management Parameters
705 @cindex window manager, and frame parameters
707 These frame parameters, meaningful only on window system displays,
708 interact with the window manager.
712 The state of visibility of the frame. There are three possibilities:
713 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
714 iconified. @xref{Visibility of Frames}.
717 Whether selecting the frame raises it (non-@code{nil} means yes).
720 Whether deselecting the frame lowers it (non-@code{nil} means yes).
723 The type of icon to use for this frame when it is iconified. If the
724 value is a string, that specifies a file containing a bitmap to use.
725 Any other non-@code{nil} value specifies the default bitmap icon (a
726 picture of a gnu); @code{nil} specifies a text icon.
729 The name to use in the icon for this frame, when and if the icon
730 appears. If this is @code{nil}, the frame's title is used.
733 The number of the window-system window used by the frame
734 to contain the actual Emacs windows.
736 @item outer-window-id
737 The number of the outermost window-system window used for the whole frame.
740 If non-@code{nil}, tell Xt to wait for the window manager to confirm
741 geometry changes. Some window managers, including versions of Fvwm2
742 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
743 prevent hanging with those window managers.
747 @c ??? Not yet working.
748 The X window number of the window that should be the parent of this one.
749 Specifying this lets you create an Emacs window inside some other
750 application's window. (It is not certain this will be implemented; try
751 it and see if it works.)
755 @node Cursor Parameters
756 @subsubsection Cursor Parameters
758 This frame parameter controls the way the cursor looks.
762 How to display the cursor. Legitimate values are:
766 Display a filled box. (This is the default.)
768 Display a hollow box.
770 Don't display a cursor.
772 Display a vertical bar between characters.
773 @item (bar . @var{width})
774 Display a vertical bar @var{width} pixels wide between characters.
776 Display a horizontal bar.
777 @item (hbar . @var{height})
778 Display a horizontal bar @var{height} pixels high.
783 The buffer-local variable @code{cursor-type} overrides the value of
784 the @code{cursor-type} frame parameter, but if it is @code{t}, that
785 means to use the cursor specified for the frame.
787 @defvar blink-cursor-alist
788 This variable specifies how to blink the cursor. Each element has the
789 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
790 type equals @var{on-state} (comparing using @code{equal}), the
791 corresponding @var{off-state} specifies what the cursor looks like
792 when it blinks ``off.'' Both @var{on-state} and @var{off-state}
793 should be suitable values for the @code{cursor-type} frame parameter.
795 There are various defaults for how to blink each type of cursor, if
796 the type is not mentioned as an @var{on-state} here. Changes in this
797 variable do not take effect immediately, only when you specify the
798 @code{cursor-type} frame parameter.
801 @defvar cursor-in-non-selected-windows
802 This variable controls how the cursor looks in a window that is not
803 selected. It supports the same values as the @code{cursor-type} frame
804 parameter; also, @code{nil} means don't display a cursor in
805 nonselected windows, and @code{t} (the default) means use a standard
806 modificatoin of the usual cursor type (solid box becomes hollow box,
807 and bar becomes a narrower bar).
810 @node Color Parameters
811 @subsubsection Color Parameters
813 These frame parameters control the use of colors.
816 @item background-mode
817 This parameter is either @code{dark} or @code{light}, according
818 to whether the background color is a light one or a dark one.
821 @cindex standard colors for character terminals
822 This parameter overrides the terminal's color support as given by the
823 system's terminal capabilities database in that this parameter's value
824 specifies the color mode to use in terminal frames. The value can be
825 either a symbol or a number. A number specifies the number of colors
826 to use (and, indirectly, what commands to issue to produce each
827 color). For example, @code{(tty-color-mode . 8)} specifies use of the
828 ANSI escape sequences for 8 standard text colors. A value of -1 turns
831 If the parameter's value is a symbol, it specifies a number through
832 the value of @code{tty-color-mode-alist}, and the associated number is
836 @cindex gamma correction
837 If this is a number, Emacs performs ``gamma correction'' which adjusts
838 the brightness of all colors. The value should be the screen gamma of
839 your display, a floating point number.
841 Usual PC monitors have a screen gamma of 2.2, so color values in
842 Emacs, and in X windows generally, are calibrated to display properly
843 on a monitor with that gamma value. If you specify 2.2 for
844 @code{screen-gamma}, that means no correction is needed. Other values
845 request correction, designed to make the corrected colors appear on
846 your screen the way they would have appeared without correction on an
847 ordinary monitor with a gamma value of 2.2.
849 If your monitor displays colors too light, you should specify a
850 @code{screen-gamma} value smaller than 2.2. This requests correction
851 that makes colors darker. A screen gamma value of 1.5 may give good
852 results for LCD color displays.
855 @cindex opacity, frame
856 @cindex transparency, frame
857 @vindex frame-alpha-lower-limit
858 This parameter specifies the opacity of the frame, on graphical
859 displays that support variable opacity. It should be an integer
860 between 0 and 100, where 0 means completely transparent and 100 means
861 completely opaque. It can also have a @code{nil} value, which tells
862 Emacs not to set the frame opacity (leaving it to the window manager).
864 To prevent the frame from disappearing completely from view, the
865 variable @var{frame-alpha-lower-limit} defines a lower opacity limit.
866 If the value of the frame parameter is less than the value of this
867 variable, Emacs uses the latter. By default,
868 @var{frame-alpha-lower-limit} is 20.
870 The @code{alpha} frame parameter can also be a cons cell
871 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
872 opacity of the frame when it is selected, and @samp{inactive} is the
873 opactity when it is not selected.
876 The following frame parameters are semi-obsolete in that they are
877 automatically equivalent to particular face attributes of particular
878 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
882 The name of the font for displaying text in the frame. This is a
883 string, either a valid font name for your system or the name of an Emacs
884 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
885 attribute of the @code{default} face.
887 @item foreground-color
888 The color to use for the image of a character. It is equivalent to
889 the @code{:foreground} attribute of the @code{default} face.
891 @item background-color
892 The color to use for the background of characters. It is equivalent to
893 the @code{:background} attribute of the @code{default} face.
896 The color for the mouse pointer. It is equivalent to the @code{:background}
897 attribute of the @code{mouse} face.
900 The color for the cursor that shows point. It is equivalent to the
901 @code{:background} attribute of the @code{cursor} face.
904 The color for the border of the frame. It is equivalent to the
905 @code{:background} attribute of the @code{border} face.
907 @item scroll-bar-foreground
908 If non-@code{nil}, the color for the foreground of scroll bars. It is
909 equivalent to the @code{:foreground} attribute of the
910 @code{scroll-bar} face.
912 @item scroll-bar-background
913 If non-@code{nil}, the color for the background of scroll bars. It is
914 equivalent to the @code{:background} attribute of the
915 @code{scroll-bar} face.
918 @node Size and Position
919 @subsection Frame Size And Position
920 @cindex size of frame
925 You can read or change the size and position of a frame using the
926 frame parameters @code{left}, @code{top}, @code{height}, and
927 @code{width}. Whatever geometry parameters you don't specify are chosen
928 by the window manager in its usual fashion.
930 Here are some special features for working with sizes and positions.
931 (For the precise meaning of ``selected frame'' used by these functions,
932 see @ref{Input Focus}.)
934 @defun set-frame-position frame left top
935 This function sets the position of the top left corner of @var{frame} to
936 @var{left} and @var{top}. These arguments are measured in pixels, and
937 normally count from the top left corner of the screen.
939 Negative parameter values position the bottom edge of the window up from
940 the bottom edge of the screen, or the right window edge to the left of
941 the right edge of the screen. It would probably be better if the values
942 were always counted from the left and top, so that negative arguments
943 would position the frame partly off the top or left edge of the screen,
944 but it seems inadvisable to change that now.
947 @defun frame-height &optional frame
948 @defunx frame-width &optional frame
949 These functions return the height and width of @var{frame}, measured in
950 lines and columns. If you don't supply @var{frame}, they use the
956 These functions are old aliases for @code{frame-height} and
957 @code{frame-width}. When you are using a non-window terminal, the size
958 of the frame is normally the same as the size of the terminal screen.
961 @defun frame-pixel-height &optional frame
962 @defunx frame-pixel-width &optional frame
963 These functions return the height and width of the main display area
964 of @var{frame}, measured in pixels. If you don't supply @var{frame},
965 they use the selected frame.
967 These values include the internal borders, and windows' scroll bars
968 and fringes (which belong to individual windows, not to the frame
969 itself), but do not include menu bars or tool bars (except when using
970 X without an X toolkit).
973 @defun frame-char-height &optional frame
974 @defunx frame-char-width &optional frame
975 These functions return the height and width of a character in
976 @var{frame}, measured in pixels. The values depend on the choice of
977 font. If you don't supply @var{frame}, these functions use the selected
981 @defun set-frame-size frame cols rows
982 This function sets the size of @var{frame}, measured in characters;
983 @var{cols} and @var{rows} specify the new width and height.
985 To set the size based on values measured in pixels, use
986 @code{frame-char-height} and @code{frame-char-width} to convert
987 them to units of characters.
990 @defun set-frame-height frame lines &optional pretend
991 This function resizes @var{frame} to a height of @var{lines} lines. The
992 sizes of existing windows in @var{frame} are altered proportionally to
995 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
996 lines of output in @var{frame}, but does not change its value for the
997 actual height of the frame. This is only useful for a terminal frame.
998 Using a smaller height than the terminal actually implements may be
999 useful to reproduce behavior observed on a smaller screen, or if the
1000 terminal malfunctions when using its whole screen. Setting the frame
1001 height ``for real'' does not always work, because knowing the correct
1002 actual size may be necessary for correct cursor positioning on a
1006 @defun set-frame-width frame width &optional pretend
1007 This function sets the width of @var{frame}, measured in characters.
1008 The argument @var{pretend} has the same meaning as in
1009 @code{set-frame-height}.
1012 @findex set-screen-height
1013 @findex set-screen-width
1014 The older functions @code{set-screen-height} and
1015 @code{set-screen-width} were used to specify the height and width of the
1016 screen, in Emacs versions that did not support multiple frames. They
1017 are semi-obsolete, but still work; they apply to the selected frame.
1020 @subsection Geometry
1022 Here's how to examine the data in an X-style window geometry
1025 @defun x-parse-geometry geom
1026 @cindex geometry specification
1027 The function @code{x-parse-geometry} converts a standard X window
1028 geometry string to an alist that you can use as part of the argument to
1031 The alist describes which parameters were specified in @var{geom}, and
1032 gives the values specified for them. Each element looks like
1033 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
1034 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1036 For the size parameters, the value must be an integer. The position
1037 parameter names @code{left} and @code{top} are not totally accurate,
1038 because some values indicate the position of the right or bottom edges
1039 instead. The @var{value} possibilities for the position parameters are:
1040 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1041 as previously described (@pxref{Position Parameters}).
1046 (x-parse-geometry "35x70+0-0")
1047 @result{} ((height . 70) (width . 35)
1048 (top - 0) (left . 0))
1052 @node Terminal Parameters
1053 @section Terminal Parameters
1054 @cindex terminal parameters
1056 Each terminal has a list of associated parameters. These
1057 @dfn{terminal parameters} are mostly a convenient way of storage for
1058 terminal-local variables, but some terminal parameters have a special
1061 This section describes functions to read and change the parameter values
1062 of a terminal. They all accept as their argument either a terminal or
1063 a frame; the latter means use that frame's terminal. An argument of
1064 @code{nil} means the selected frame's terminal.
1066 @defun terminal-parameters &optional terminal
1067 This function returns an alist listing all the parameters of
1068 @var{terminal} and their values.
1071 @defun terminal-parameter terminal parameter
1072 This function returns the value of the parameter @var{parameter} (a
1073 symbol) of @var{terminal}. If @var{terminal} has no setting for
1074 @var{parameter}, this function returns @code{nil}.
1077 @defun set-terminal-parameter terminal parameter value
1078 This function sets the parameter @var{parm} of @var{terminal} to the
1079 specified @var{value}, and returns the previous value of that
1083 Here's a list of a few terminal parameters that have a special
1087 @item background-mode
1088 The classification of the terminal's background color, either
1089 @code{light} or @code{dark}.
1090 @item normal-erase-is-backspace
1091 Value is either 1 or 0, depending on whether
1092 @code{normal-erase-is-backspace-mode} is turned on or off on this
1093 terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1094 @item terminal-initted
1095 After the terminal is initialized, this is set to the
1096 terminal-specific initialization function.
1100 @section Frame Titles
1103 Every frame has a @code{name} parameter; this serves as the default
1104 for the frame title which window systems typically display at the top of
1105 the frame. You can specify a name explicitly by setting the @code{name}
1108 Normally you don't specify the name explicitly, and Emacs computes the
1109 frame name automatically based on a template stored in the variable
1110 @code{frame-title-format}. Emacs recomputes the name each time the
1111 frame is redisplayed.
1113 @defvar frame-title-format
1114 This variable specifies how to compute a name for a frame when you have
1115 not explicitly specified one. The variable's value is actually a mode
1116 line construct, just like @code{mode-line-format}, except that the
1117 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
1121 @defvar icon-title-format
1122 This variable specifies how to compute the name for an iconified frame,
1123 when you have not explicitly specified the frame title. This title
1124 appears in the icon itself.
1127 @defvar multiple-frames
1128 This variable is set automatically by Emacs. Its value is @code{t} when
1129 there are two or more frames (not counting minibuffer-only frames or
1130 invisible frames). The default value of @code{frame-title-format} uses
1131 @code{multiple-frames} so as to put the buffer name in the frame title
1132 only when there is more than one frame.
1134 The value of this variable is not guaranteed to be accurate except
1135 while processing @code{frame-title-format} or
1136 @code{icon-title-format}.
1139 @node Deleting Frames
1140 @section Deleting Frames
1141 @cindex deleting frames
1143 Frames remain potentially visible until you explicitly @dfn{delete}
1144 them. A deleted frame cannot appear on the screen, but continues to
1145 exist as a Lisp object until there are no references to it.
1147 @deffn Command delete-frame &optional frame force
1148 @vindex delete-frame-functions
1149 This function deletes the frame @var{frame}. Unless @var{frame} is a
1150 tooltip, it first runs the hook @code{delete-frame-functions} (each
1151 function gets one argument, @var{frame}). By default, @var{frame} is
1154 A frame cannot be deleted if its minibuffer is used by other frames.
1155 Normally, you cannot delete a frame if all other frames are invisible,
1156 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1159 @defun frame-live-p frame
1160 The function @code{frame-live-p} returns non-@code{nil} if the frame
1161 @var{frame} has not been deleted. The possible non-@code{nil} return
1162 values are like those of @code{framep}. @xref{Frames}.
1165 Some window managers provide a command to delete a window. These work
1166 by sending a special message to the program that operates the window.
1167 When Emacs gets one of these commands, it generates a
1168 @code{delete-frame} event, whose normal definition is a command that
1169 calls the function @code{delete-frame}. @xref{Misc Events}.
1171 @node Finding All Frames
1172 @section Finding All Frames
1173 @cindex frames, scanning all
1176 The function @code{frame-list} returns a list of all the frames that
1177 have not been deleted. It is analogous to @code{buffer-list} for
1178 buffers, and includes frames on all terminals. The list that you get is
1179 newly created, so modifying the list doesn't have any effect on the
1183 @defun visible-frame-list
1184 This function returns a list of just the currently visible frames.
1185 @xref{Visibility of Frames}. (Terminal frames always count as
1186 ``visible,'' even though only the selected one is actually displayed.)
1189 @defun next-frame &optional frame minibuf
1190 The function @code{next-frame} lets you cycle conveniently through all
1191 the frames on the current display from an arbitrary starting point. It
1192 returns the ``next'' frame after @var{frame} in the cycle. If
1193 @var{frame} is omitted or @code{nil}, it defaults to the selected frame
1194 (@pxref{Input Focus}).
1196 The second argument, @var{minibuf}, says which frames to consider:
1200 Exclude minibuffer-only frames.
1201 @item @code{visible}
1202 Consider all visible frames.
1204 Consider all visible or iconified frames.
1206 Consider only the frames using that particular window as their
1209 Consider all frames.
1213 @defun previous-frame &optional frame minibuf
1214 Like @code{next-frame}, but cycles through all frames in the opposite
1218 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1221 @node Frames and Windows
1222 @section Frames and Windows
1224 Each window is part of one and only one frame; you can get that frame
1225 with @code{window-frame}.
1227 @defun window-frame window
1228 This function returns the frame that @var{window} is on.
1231 All the non-minibuffer windows in a frame are arranged in a cyclic
1232 order. The order runs from the frame's top window, which is at the
1233 upper left corner, down and to the right, until it reaches the window at
1234 the lower right corner (always the minibuffer window, if the frame has
1235 one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
1237 @defun frame-first-window &optional frame
1238 This returns the topmost, leftmost window of frame @var{frame}.
1239 If omitted or @code{nil}, @var{frame} defaults to the selected frame.
1242 At any time, exactly one window on any frame is @dfn{selected within the
1243 frame}. The significance of this designation is that selecting the
1244 frame also selects this window. Conversely, selecting a window for
1245 Emacs with @code{select-window} also makes that window selected within
1246 its frame. @xref{Selecting Windows}.
1248 @defun frame-selected-window &optional frame
1249 This function returns the window on @var{frame} that is selected
1250 within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to
1254 @defun set-frame-selected-window frame window &optional norecord
1255 This sets the selected window of frame @var{frame} to @var{window}.
1256 If @var{frame} is @code{nil}, it operates on the selected frame. If
1257 @var{frame} is the selected frame, this makes @var{window} the
1258 selected window. This function returns @var{window}.
1260 Optional argument @var{norecord} non-@code{nil} means to neither change
1261 the order of recently selected windows nor the buffer list (@pxref{The
1265 Another function that (usually) returns one of the windows in a given
1266 frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
1268 @node Minibuffers and Frames
1269 @section Minibuffers and Frames
1271 Normally, each frame has its own minibuffer window at the bottom, which
1272 is used whenever that frame is selected. If the frame has a minibuffer,
1273 you can get it with @code{minibuffer-window} (@pxref{Definition of
1274 minibuffer-window}).
1276 However, you can also create a frame with no minibuffer. Such a frame
1277 must use the minibuffer window of some other frame. When you create the
1278 frame, you can specify explicitly the minibuffer window to use (in some
1279 other frame). If you don't, then the minibuffer is found in the frame
1280 which is the value of the variable @code{default-minibuffer-frame}. Its
1281 value should be a frame that does have a minibuffer.
1283 If you use a minibuffer-only frame, you might want that frame to raise
1284 when you enter the minibuffer. If so, set the variable
1285 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
1287 @defvar default-minibuffer-frame
1288 This variable specifies the frame to use for the minibuffer window, by
1289 default. It does not affect existing frames. It is always local to
1290 the current terminal and cannot be buffer-local. @xref{Multiple
1295 @section Input Focus
1297 @c @cindex selected frame Duplicates selected-frame
1299 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
1300 window always resides on the selected frame.
1302 When Emacs displays its frames on several terminals (@pxref{Multiple
1303 Displays}), each terminal has its own selected frame. But only one of
1304 these is ``@emph{the} selected frame'': it's the frame that belongs to
1305 the terminal from which the most recent input came. That is, when Emacs
1306 runs a command that came from a certain terminal, the selected frame is
1307 the one of that terminal. Since Emacs runs only a single command at any
1308 given time, it needs to consider only one selected frame at a time; this
1309 frame is what we call @dfn{the selected frame} in this manual. The
1310 display on which the selected frame is shown is the @dfn{selected
1313 @defun selected-frame
1314 This function returns the selected frame.
1317 Some window systems and window managers direct keyboard input to the
1318 window object that the mouse is in; others require explicit clicks or
1319 commands to @dfn{shift the focus} to various window objects. Either
1320 way, Emacs automatically keeps track of which frame has the focus. To
1321 explicitly switch to a different frame from a Lisp function, call
1322 @code{select-frame-set-input-focus}.
1324 Lisp programs can also switch frames ``temporarily'' by calling the
1325 function @code{select-frame}. This does not alter the window system's
1326 concept of focus; rather, it escapes from the window manager's control
1327 until that control is somehow reasserted.
1329 When using a text-only terminal, only one frame can be displayed at a
1330 time on the terminal, so after a call to @code{select-frame}, the next
1331 redisplay actually displays the newly selected frame. This frame
1332 remains selected until a subsequent call to @code{select-frame}. Each
1333 terminal frame has a number which appears in the mode line before the
1334 buffer name (@pxref{Mode Line Variables}).
1336 @defun select-frame-set-input-focus frame
1337 This function selects @var{frame}, raises it (should it happen to be
1338 obscured by other frames) and tries to give it the X server's focus. On
1339 a text-only terminal, the next redisplay displays the new frame on the
1340 entire terminal screen. The return value of this function is not
1344 @c ??? This is not yet implemented properly.
1345 @defun select-frame frame &optional norecord
1346 This function selects frame @var{frame}, temporarily disregarding the
1347 focus of the X server if any. The selection of @var{frame} lasts until
1348 the next time the user does something to select a different frame, or
1349 until the next time this function is called. (If you are using a
1350 window system, the previously selected frame may be restored as the
1351 selected frame after return to the command loop, because it still may
1352 have the window system's input focus.)
1354 The specified @var{frame} becomes the selected frame, as explained
1355 above, and the terminal that @var{frame} is on becomes the selected
1356 terminal. The window selected within @var{frame} becomes the selected
1357 window. This function returns @var{frame}, or @code{nil} if @var{frame}
1360 Optional argument @var{norecord} non-@code{nil} means to neither change
1361 the order of recently selected windows nor the buffer list. @xref{The
1364 In general, you should never use @code{select-frame} in a way that could
1365 switch to a different terminal without switching back when you're done.
1368 Emacs cooperates with the window system by arranging to select frames as
1369 the server and window manager request. It does so by generating a
1370 special kind of input event, called a @dfn{focus} event, when
1371 appropriate. The command loop handles a focus event by calling
1372 @code{handle-switch-frame}. @xref{Focus Events}.
1374 @deffn Command handle-switch-frame frame
1375 This function handles a focus event by selecting frame @var{frame}.
1377 Focus events normally do their job by invoking this command.
1378 Don't call it for any other reason.
1381 @defun redirect-frame-focus frame &optional focus-frame
1382 This function redirects focus from @var{frame} to @var{focus-frame}.
1383 This means that @var{focus-frame} will receive subsequent keystrokes and
1384 events intended for @var{frame}. After such an event, the value of
1385 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1386 events specifying @var{frame} will instead select @var{focus-frame}.
1388 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1389 redirection for @var{frame}, which therefore once again receives its own
1392 One use of focus redirection is for frames that don't have minibuffers.
1393 These frames use minibuffers on other frames. Activating a minibuffer
1394 on another frame redirects focus to that frame. This puts the focus on
1395 the minibuffer's frame, where it belongs, even though the mouse remains
1396 in the frame that activated the minibuffer.
1398 Selecting a frame can also change focus redirections. Selecting frame
1399 @code{bar}, when @code{foo} had been selected, changes any redirections
1400 pointing to @code{foo} so that they point to @code{bar} instead. This
1401 allows focus redirection to work properly when the user switches from
1402 one frame to another using @code{select-window}.
1404 This means that a frame whose focus is redirected to itself is treated
1405 differently from a frame whose focus is not redirected.
1406 @code{select-frame} affects the former but not the latter.
1408 The redirection lasts until @code{redirect-frame-focus} is called to
1412 @defopt focus-follows-mouse
1413 This option is how you inform Emacs whether the window manager transfers
1414 focus when the user moves the mouse. Non-@code{nil} says that it does.
1415 When this is so, the command @code{other-frame} moves the mouse to a
1416 position consistent with the new selected frame.
1419 @node Visibility of Frames
1420 @section Visibility of Frames
1421 @cindex visible frame
1422 @cindex invisible frame
1423 @cindex iconified frame
1424 @cindex frame visibility
1426 A window frame may be @dfn{visible}, @dfn{invisible}, or
1427 @dfn{iconified}. If it is visible, you can see its contents, unless
1428 other windows cover it. If it is iconified, the frame's contents do
1429 not appear on the screen, but an icon does. If the frame is
1430 invisible, it doesn't show on the screen, not even as an icon.
1432 Visibility is meaningless for terminal frames, since only the selected
1433 one is actually displayed in any case.
1435 @deffn Command make-frame-visible &optional frame
1436 This function makes frame @var{frame} visible. If you omit
1437 @var{frame}, it makes the selected frame visible. This does not raise
1438 the frame, but you can do that with @code{raise-frame} if you wish
1439 (@pxref{Raising and Lowering}).
1442 @deffn Command make-frame-invisible &optional frame force
1443 This function makes frame @var{frame} invisible. If you omit
1444 @var{frame}, it makes the selected frame invisible.
1446 Unless @var{force} is non-@code{nil}, this function refuses to make
1447 @var{frame} invisible if all other frames are invisible..
1450 @deffn Command iconify-frame &optional frame
1451 This function iconifies frame @var{frame}. If you omit @var{frame}, it
1452 iconifies the selected frame.
1455 @defun frame-visible-p frame
1456 This returns the visibility status of frame @var{frame}. The value is
1457 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
1458 @code{icon} if it is iconified.
1460 On a text-only terminal, all frames are considered visible, whether
1461 they are currently being displayed or not, and this function returns
1462 @code{t} for all frames.
1465 The visibility status of a frame is also available as a frame
1466 parameter. You can read or change it as such. @xref{Management
1469 The user can iconify and deiconify frames with the window manager.
1470 This happens below the level at which Emacs can exert any control, but
1471 Emacs does provide events that you can use to keep track of such
1472 changes. @xref{Misc Events}.
1474 @node Raising and Lowering
1475 @section Raising and Lowering Frames
1477 Most window systems use a desktop metaphor. Part of this metaphor is
1478 the idea that windows are stacked in a notional third dimension
1479 perpendicular to the screen surface, and thus ordered from ``highest''
1480 to ``lowest.'' Where two windows overlap, the one higher up covers
1481 the one underneath. Even a window at the bottom of the stack can be
1482 seen if no other window overlaps it.
1484 @c @cindex raising a frame redundant with raise-frame
1485 @cindex lowering a frame
1486 A window's place in this ordering is not fixed; in fact, users tend
1487 to change the order frequently. @dfn{Raising} a window means moving
1488 it ``up,'' to the top of the stack. @dfn{Lowering} a window means
1489 moving it to the bottom of the stack. This motion is in the notional
1490 third dimension only, and does not change the position of the window
1493 With Emacs, frames constitute the windows in the metaphor sketched
1494 above. You can raise and lower frames using these functions:
1496 @deffn Command raise-frame &optional frame
1497 This function raises frame @var{frame} (default, the selected frame).
1498 If @var{frame} is invisible or iconified, this makes it visible.
1501 @deffn Command lower-frame &optional frame
1502 This function lowers frame @var{frame} (default, the selected frame).
1505 @defopt minibuffer-auto-raise
1506 If this is non-@code{nil}, activation of the minibuffer raises the frame
1507 that the minibuffer window is in.
1510 You can also enable auto-raise (raising automatically when a frame is
1511 selected) or auto-lower (lowering automatically when it is deselected)
1512 for any frame using frame parameters. @xref{Management Parameters}.
1514 @node Frame Configurations
1515 @section Frame Configurations
1516 @cindex frame configuration
1518 A @dfn{frame configuration} records the current arrangement of frames,
1519 all their properties, and the window configuration of each one.
1520 (@xref{Window Configurations}.)
1522 @defun current-frame-configuration
1523 This function returns a frame configuration list that describes
1524 the current arrangement of frames and their contents.
1527 @defun set-frame-configuration configuration &optional nodelete
1528 This function restores the state of frames described in
1529 @var{configuration}. However, this function does not restore deleted
1532 Ordinarily, this function deletes all existing frames not listed in
1533 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1534 unwanted frames are iconified instead.
1537 @node Mouse Tracking
1538 @section Mouse Tracking
1539 @cindex mouse tracking
1540 @c @cindex tracking the mouse Duplicates track-mouse
1542 Sometimes it is useful to @dfn{track} the mouse, which means to display
1543 something to indicate where the mouse is and move the indicator as the
1544 mouse moves. For efficient mouse tracking, you need a way to wait until
1545 the mouse actually moves.
1547 The convenient way to track the mouse is to ask for events to represent
1548 mouse motion. Then you can wait for motion by waiting for an event. In
1549 addition, you can easily handle any other sorts of events that may
1550 occur. That is useful, because normally you don't want to track the
1551 mouse forever---only until some other event, such as the release of a
1554 @defspec track-mouse body@dots{}
1555 This special form executes @var{body}, with generation of mouse motion
1556 events enabled. Typically, @var{body} would use @code{read-event} to
1557 read the motion events and modify the display accordingly. @xref{Motion
1558 Events}, for the format of mouse motion events.
1560 The value of @code{track-mouse} is that of the last form in @var{body}.
1561 You should design @var{body} to return when it sees the up-event that
1562 indicates the release of the button, or whatever kind of event means
1563 it is time to stop tracking.
1566 The usual purpose of tracking mouse motion is to indicate on the screen
1567 the consequences of pushing or releasing a button at the current
1570 In many cases, you can avoid the need to track the mouse by using
1571 the @code{mouse-face} text property (@pxref{Special Properties}).
1572 That works at a much lower level and runs more smoothly than
1573 Lisp-level mouse tracking.
1576 @c These are not implemented yet.
1578 These functions change the screen appearance instantaneously. The
1579 effect is transient, only until the next ordinary Emacs redisplay. That
1580 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1581 to change the text, and the body of @code{track-mouse} normally reads
1582 the events itself and does not do redisplay.
1584 @defun x-contour-region window beg end
1585 This function draws lines to make a box around the text from @var{beg}
1586 to @var{end}, in window @var{window}.
1589 @defun x-uncontour-region window beg end
1590 This function erases the lines that would make a box around the text
1591 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1592 a contour that you previously made by calling @code{x-contour-region}.
1595 @defun x-draw-rectangle frame left top right bottom
1596 This function draws a hollow rectangle on frame @var{frame} with the
1597 specified edge coordinates, all measured in pixels from the inside top
1598 left corner. It uses the cursor color, the one used for indicating the
1602 @defun x-erase-rectangle frame left top right bottom
1603 This function erases a hollow rectangle on frame @var{frame} with the
1604 specified edge coordinates, all measured in pixels from the inside top
1605 left corner. Erasure means redrawing the text and background that
1606 normally belong in the specified rectangle.
1610 @node Mouse Position
1611 @section Mouse Position
1612 @cindex mouse position
1613 @cindex position of mouse
1615 The functions @code{mouse-position} and @code{set-mouse-position}
1616 give access to the current position of the mouse.
1618 @defun mouse-position
1619 This function returns a description of the position of the mouse. The
1620 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1621 and @var{y} are integers giving the position in characters relative to
1622 the top left corner of the inside of @var{frame}.
1625 @defvar mouse-position-function
1626 If non-@code{nil}, the value of this variable is a function for
1627 @code{mouse-position} to call. @code{mouse-position} calls this
1628 function just before returning, with its normal return value as the
1629 sole argument, and it returns whatever this function returns to it.
1631 This abnormal hook exists for the benefit of packages like
1632 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1635 @defun set-mouse-position frame x y
1636 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1637 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1638 giving the position in characters relative to the top left corner of the
1639 inside of @var{frame}. If @var{frame} is not visible, this function
1640 does nothing. The return value is not significant.
1643 @defun mouse-pixel-position
1644 This function is like @code{mouse-position} except that it returns
1645 coordinates in units of pixels rather than units of characters.
1648 @defun set-mouse-pixel-position frame x y
1649 This function warps the mouse like @code{set-mouse-position} except that
1650 @var{x} and @var{y} are in units of pixels rather than units of
1651 characters. These coordinates are not required to be within the frame.
1653 If @var{frame} is not visible, this function does nothing. The return
1654 value is not significant.
1660 @section Pop-Up Menus
1662 When using a window system, a Lisp program can pop up a menu so that
1663 the user can choose an alternative with the mouse.
1665 @defun x-popup-menu position menu
1666 This function displays a pop-up menu and returns an indication of
1667 what selection the user makes.
1669 The argument @var{position} specifies where on the screen to put the
1670 top left corner of the menu. It can be either a mouse button event
1671 (which says to put the menu where the user actuated the button) or a
1675 ((@var{xoffset} @var{yoffset}) @var{window})
1679 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1680 pixels, counting from the top left corner of @var{window}. @var{window}
1681 may be a window or a frame.
1683 If @var{position} is @code{t}, it means to use the current mouse
1684 position. If @var{position} is @code{nil}, it means to precompute the
1685 key binding equivalents for the keymaps specified in @var{menu},
1686 without actually displaying or popping up the menu.
1688 The argument @var{menu} says what to display in the menu. It can be a
1689 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
1690 return value is the list of events corresponding to the user's choice.
1691 (This list has more than one element if the choice occurred in a
1692 submenu.) Note that @code{x-popup-menu} does not actually execute the
1693 command bound to that sequence of events.
1695 Alternatively, @var{menu} can have the following form:
1698 (@var{title} @var{pane1} @var{pane2}...)
1702 where each pane is a list of form
1705 (@var{title} @var{item1} @var{item2}...)
1708 Each item should normally be a cons cell @code{(@var{line} . @var{value})},
1709 where @var{line} is a string, and @var{value} is the value to return if
1710 that @var{line} is chosen. An item can also be a string; this makes a
1711 non-selectable line in the menu.
1713 If the user gets rid of the menu without making a valid choice, for
1714 instance by clicking the mouse away from a valid choice or by typing
1715 keyboard input, then this normally results in a quit and
1716 @code{x-popup-menu} does not return. But if @var{position} is a mouse
1717 button event (indicating that the user invoked the menu with the
1718 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1721 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1722 if you could do the job with a prefix key defined with a menu keymap.
1723 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1724 a} can see the individual items in that menu and provide help for them.
1725 If instead you implement the menu by defining a command that calls
1726 @code{x-popup-menu}, the help facilities cannot know what happens inside
1727 that command, so they cannot give any help for the menu's items.
1729 The menu bar mechanism, which lets you switch between submenus by
1730 moving the mouse, cannot look within the definition of a command to see
1731 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1732 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1733 an integrated fashion. This is why all menu bar submenus are
1734 implemented with menu keymaps within the parent menu, and never with
1735 @code{x-popup-menu}. @xref{Menu Bar}.
1737 If you want a menu bar submenu to have contents that vary, you should
1738 still use a menu keymap to implement it. To make the contents vary, add
1739 a hook function to @code{menu-bar-update-hook} to update the contents of
1740 the menu keymap as necessary.
1743 @section Dialog Boxes
1744 @cindex dialog boxes
1746 A dialog box is a variant of a pop-up menu---it looks a little
1747 different, it always appears in the center of a frame, and it has just
1748 one level and one or more buttons. The main use of dialog boxes is
1749 for asking questions that the user can answer with ``yes,'' ``no,''
1750 and a few other alternatives. With a single button, they can also
1751 force the user to acknowledge important information. The functions
1752 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1753 keyboard, when called from commands invoked by mouse clicks.
1755 @defun x-popup-dialog position contents &optional header
1756 This function displays a pop-up dialog box and returns an indication of
1757 what selection the user makes. The argument @var{contents} specifies
1758 the alternatives to offer; it has this format:
1761 (@var{title} (@var{string} . @var{value})@dots{})
1765 which looks like the list that specifies a single pane for
1766 @code{x-popup-menu}.
1768 The return value is @var{value} from the chosen alternative.
1770 As for @code{x-popup-menu}, an element of the list may be just a
1771 string instead of a cons cell @code{(@var{string} . @var{value})}.
1772 That makes a box that cannot be selected.
1774 If @code{nil} appears in the list, it separates the left-hand items from
1775 the right-hand items; items that precede the @code{nil} appear on the
1776 left, and items that follow the @code{nil} appear on the right. If you
1777 don't include a @code{nil} in the list, then approximately half the
1778 items appear on each side.
1780 Dialog boxes always appear in the center of a frame; the argument
1781 @var{position} specifies which frame. The possible values are as in
1782 @code{x-popup-menu}, but the precise coordinates or the individual
1783 window don't matter; only the frame matters.
1785 If @var{header} is non-@code{nil}, the frame title for the box is
1786 @samp{Information}, otherwise it is @samp{Question}. The former is used
1787 for @code{message-box} (@pxref{message-box}).
1789 In some configurations, Emacs cannot display a real dialog box; so
1790 instead it displays the same items in a pop-up menu in the center of the
1793 If the user gets rid of the dialog box without making a valid choice,
1794 for instance using the window manager, then this produces a quit and
1795 @code{x-popup-dialog} does not return.
1799 @section Pointer Shape
1800 @cindex pointer shape
1801 @cindex mouse pointer shape
1803 You can specify the mouse pointer style for particular text or
1804 images using the @code{pointer} text property, and for images with the
1805 @code{:pointer} and @code{:map} image properties. The values you can
1806 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1807 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1808 @code{hourglass}. @code{text} stands for the usual mouse pointer
1809 style used over text.
1811 Over void parts of the window (parts that do not correspond to any
1812 of the buffer contents), the mouse pointer usually uses the
1813 @code{arrow} style, but you can specify a different style (one of
1814 those above) by setting @code{void-text-area-pointer}.
1816 @defvar void-text-area-pointer
1817 This variable specifies the mouse pointer style for void text areas.
1818 These include the areas after the end of a line or below the last line
1819 in the buffer. The default is to use the @code{arrow} (non-text)
1823 When using X, you can specify what the @code{text} pointer style
1824 really looks like by setting the variable @code{x-pointer-shape}.
1826 @defvar x-pointer-shape
1827 This variable specifies the pointer shape to use ordinarily in the
1828 Emacs frame, for the @code{text} pointer style.
1831 @defvar x-sensitive-text-pointer-shape
1832 This variable specifies the pointer shape to use when the mouse
1833 is over mouse-sensitive text.
1836 These variables affect newly created frames. They do not normally
1837 affect existing frames; however, if you set the mouse color of a
1838 frame, that also installs the current value of those two variables.
1839 @xref{Color Parameters}.
1841 The values you can use, to specify either of these pointer shapes, are
1842 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1843 @key{RET} x-pointer @key{RET}} to see a list of them.
1845 @node Window System Selections
1846 @section Window System Selections
1847 @cindex selection (for window systems)
1849 The X server records a set of @dfn{selections} which permit transfer of
1850 data between application programs. The various selections are
1851 distinguished by @dfn{selection types}, represented in Emacs by
1852 symbols. X clients including Emacs can read or set the selection for
1855 @deffn Command x-set-selection type data
1856 This function sets a ``selection'' in the X server. It takes two
1857 arguments: a selection type @var{type}, and the value to assign to it,
1858 @var{data}. If @var{data} is @code{nil}, it means to clear out the
1859 selection. Otherwise, @var{data} may be a string, a symbol, an integer
1860 (or a cons of two integers or list of two integers), an overlay, or a
1861 cons of two markers pointing to the same buffer. An overlay or a pair
1862 of markers stands for text in the overlay or between the markers.
1864 The argument @var{data} may also be a vector of valid non-vector
1867 Each possible @var{type} has its own selection value, which changes
1868 independently. The usual values of @var{type} are @code{PRIMARY},
1869 @code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
1870 names, in accord with X Window System conventions. If @var{type} is
1871 @code{nil}, that stands for @code{PRIMARY}.
1873 This function returns @var{data}.
1876 @defun x-get-selection &optional type data-type
1877 This function accesses selections set up by Emacs or by other X
1878 clients. It takes two optional arguments, @var{type} and
1879 @var{data-type}. The default for @var{type}, the selection type, is
1882 The @var{data-type} argument specifies the form of data conversion to
1883 use, to convert the raw data obtained from another X client into Lisp
1884 data. Meaningful values include @code{TEXT}, @code{STRING},
1885 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1886 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1887 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1888 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
1889 @code{INTEGER}. (These are symbols with upper-case names in accord
1890 with X conventions.) The default for @var{data-type} is
1895 The X server also has a set of eight numbered @dfn{cut buffers} which can
1896 store text or other data being moved between applications. Cut buffers
1897 are considered obsolete, but Emacs supports them for the sake of X
1898 clients that still use them. Cut buffers are numbered from 0 to 7.
1900 @defun x-get-cut-buffer &optional n
1901 This function returns the contents of cut buffer number @var{n}.
1902 If omitted @var{n} defaults to 0.
1905 @defun x-set-cut-buffer string &optional push
1906 @anchor{Definition of x-set-cut-buffer}
1907 This function stores @var{string} into the first cut buffer (cut buffer
1908 0). If @var{push} is @code{nil}, only the first cut buffer is changed.
1909 If @var{push} is non-@code{nil}, that says to move the values down
1910 through the series of cut buffers, much like the way successive kills in
1911 Emacs move down the kill ring. In other words, the previous value of
1912 the first cut buffer moves into the second cut buffer, and the second to
1913 the third, and so on through all eight cut buffers.
1916 @defvar selection-coding-system
1917 This variable specifies the coding system to use when reading and
1918 writing selections or the clipboard. @xref{Coding
1919 Systems}. The default is @code{compound-text-with-extensions}, which
1920 converts to the text representation that X11 normally uses.
1923 @cindex clipboard support (for MS-Windows)
1924 When Emacs runs on MS-Windows, it does not implement X selections in
1925 general, but it does support the clipboard. @code{x-get-selection}
1926 and @code{x-set-selection} on MS-Windows support the text data type
1927 only; if the clipboard holds other types of data, Emacs treats the
1930 @defopt x-select-enable-clipboard
1931 If this is non-@code{nil}, the Emacs yank functions consult the
1932 clipboard before the primary selection, and the kill functions store in
1933 the clipboard as well as the primary selection. Otherwise they do not
1934 access the clipboard at all. The default is @code{nil} on most systems,
1935 but @code{t} on MS-Windows.
1939 @section Drag and Drop
1941 @vindex x-dnd-test-function
1942 @vindex x-dnd-known-types
1943 When a user drags something from another application over Emacs, that other
1944 application expects Emacs to tell it if Emacs can handle the data that is
1945 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
1946 what to reply. The default value is @code{x-dnd-default-test-function}
1947 which accepts drops if the type of the data to be dropped is present in
1948 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
1949 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
1950 on some other criteria.
1952 @vindex x-dnd-types-alist
1953 If you want to change the way Emacs handles drop of different types
1954 or add a new type, customize @code{x-dnd-types-alist}. This requires
1955 detailed knowledge of what types other applications use for drag and
1958 @vindex dnd-protocol-alist
1959 When an URL is dropped on Emacs it may be a file, but it may also be
1960 another URL type (ftp, http, etc.). Emacs first checks
1961 @code{dnd-protocol-alist} to determine what to do with the URL. If
1962 there is no match there and if @code{browse-url-browser-function} is
1963 an alist, Emacs looks for a match there. If no match is found the
1964 text for the URL is inserted. If you want to alter Emacs behavior,
1965 you can customize these variables.
1968 @section Color Names
1971 @cindex specify color
1972 @cindex numerical RGB color specification
1973 A color name is text (usually in a string) that specifies a color.
1974 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
1975 are allowed; use @kbd{M-x list-colors-display} to see a list of
1976 defined names. You can also specify colors numerically in forms such
1977 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
1978 @var{r} specifies the red level, @var{g} specifies the green level,
1979 and @var{b} specifies the blue level. You can use either one, two,
1980 three, or four hex digits for @var{r}; then you must use the same
1981 number of hex digits for all @var{g} and @var{b} as well, making
1982 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
1983 X Window System for more details about numerical RGB specification of
1986 These functions provide a way to determine which color names are
1987 valid, and what they look like. In some cases, the value depends on the
1988 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
1989 meaning of the term ``selected frame.''
1991 To read user input of color names with completion, use
1992 @code{read-color} (@pxref{High-Level Completion, read-color}).
1994 @defun color-defined-p color &optional frame
1995 This function reports whether a color name is meaningful. It returns
1996 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
1997 which frame's display to ask about; if @var{frame} is omitted or
1998 @code{nil}, the selected frame is used.
2000 Note that this does not tell you whether the display you are using
2001 really supports that color. When using X, you can ask for any defined
2002 color on any kind of display, and you will get some result---typically,
2003 the closest it can do. To determine whether a frame can really display
2004 a certain color, use @code{color-supported-p} (see below).
2006 @findex x-color-defined-p
2007 This function used to be called @code{x-color-defined-p},
2008 and that name is still supported as an alias.
2011 @defun defined-colors &optional frame
2012 This function returns a list of the color names that are defined
2013 and supported on frame @var{frame} (default, the selected frame).
2014 If @var{frame} does not support colors, the value is @code{nil}.
2016 @findex x-defined-colors
2017 This function used to be called @code{x-defined-colors},
2018 and that name is still supported as an alias.
2021 @defun color-supported-p color &optional frame background-p
2022 This returns @code{t} if @var{frame} can really display the color
2023 @var{color} (or at least something close to it). If @var{frame} is
2024 omitted or @code{nil}, the question applies to the selected frame.
2026 Some terminals support a different set of colors for foreground and
2027 background. If @var{background-p} is non-@code{nil}, that means you are
2028 asking whether @var{color} can be used as a background; otherwise you
2029 are asking whether it can be used as a foreground.
2031 The argument @var{color} must be a valid color name.
2034 @defun color-gray-p color &optional frame
2035 This returns @code{t} if @var{color} is a shade of gray, as defined on
2036 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
2037 question applies to the selected frame. If @var{color} is not a valid
2038 color name, this function returns @code{nil}.
2041 @defun color-values color &optional frame
2043 This function returns a value that describes what @var{color} should
2044 ideally look like on @var{frame}. If @var{color} is defined, the
2045 value is a list of three integers, which give the amount of red, the
2046 amount of green, and the amount of blue. Each integer ranges in
2047 principle from 0 to 65535, but some displays may not use the full
2048 range. This three-element list is called the @dfn{rgb values} of the
2051 If @var{color} is not defined, the value is @code{nil}.
2054 (color-values "black")
2056 (color-values "white")
2057 @result{} (65280 65280 65280)
2058 (color-values "red")
2059 @result{} (65280 0 0)
2060 (color-values "pink")
2061 @result{} (65280 49152 51968)
2062 (color-values "hungry")
2066 The color values are returned for @var{frame}'s display. If
2067 @var{frame} is omitted or @code{nil}, the information is returned for
2068 the selected frame's display. If the frame cannot display colors, the
2069 value is @code{nil}.
2071 @findex x-color-values
2072 This function used to be called @code{x-color-values},
2073 and that name is still supported as an alias.
2076 @node Text Terminal Colors
2077 @section Text Terminal Colors
2078 @cindex colors on text-only terminals
2080 Text-only terminals usually support only a small number of colors,
2081 and the computer uses small integers to select colors on the terminal.
2082 This means that the computer cannot reliably tell what the selected
2083 color looks like; instead, you have to inform your application which
2084 small integers correspond to which colors. However, Emacs does know
2085 the standard set of colors and will try to use them automatically.
2087 The functions described in this section control how terminal colors
2090 Several of these functions use or return @dfn{rgb values}, described
2091 in @ref{Color Names}.
2093 These functions accept a display (either a frame or the name of a
2094 terminal) as an optional argument. We hope in the future to make Emacs
2095 support more than one text-only terminal at one time; then this argument
2096 will specify which terminal to operate on (the default being the
2097 selected frame's terminal; @pxref{Input Focus}). At present, though,
2098 the @var{frame} argument has no effect.
2100 @defun tty-color-define name number &optional rgb frame
2101 This function associates the color name @var{name} with
2102 color number @var{number} on the terminal.
2104 The optional argument @var{rgb}, if specified, is an rgb value, a list
2105 of three numbers that specify what the color actually looks like.
2106 If you do not specify @var{rgb}, then this color cannot be used by
2107 @code{tty-color-approximate} to approximate other colors, because
2108 Emacs will not know what it looks like.
2111 @defun tty-color-clear &optional frame
2112 This function clears the table of defined colors for a text-only terminal.
2115 @defun tty-color-alist &optional frame
2116 This function returns an alist recording the known colors supported by a
2119 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2120 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
2121 name, @var{number} is the number used to specify it to the terminal.
2122 If present, @var{rgb} is a list of three color values (for red, green,
2123 and blue) that says what the color actually looks like.
2126 @defun tty-color-approximate rgb &optional frame
2127 This function finds the closest color, among the known colors
2128 supported for @var{display}, to that described by the rgb value
2129 @var{rgb} (a list of color values). The return value is an element of
2130 @code{tty-color-alist}.
2133 @defun tty-color-translate color &optional frame
2134 This function finds the closest color to @var{color} among the known
2135 colors supported for @var{display} and returns its index (an integer).
2136 If the name @var{color} is not defined, the value is @code{nil}.
2140 @section X Resources
2142 @defun x-get-resource attribute class &optional component subclass
2143 The function @code{x-get-resource} retrieves a resource value from the X
2144 Window defaults database.
2146 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2147 This function searches using a key of the form
2148 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2149 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2152 The optional arguments @var{component} and @var{subclass} add to the key
2153 and the class, respectively. You must specify both of them or neither.
2154 If you specify them, the key is
2155 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2156 @samp{Emacs.@var{class}.@var{subclass}}.
2159 @defvar x-resource-class
2160 This variable specifies the application name that @code{x-get-resource}
2161 should look up. The default value is @code{"Emacs"}. You can examine X
2162 resources for application names other than ``Emacs'' by binding this
2163 variable to some other string, around a call to @code{x-get-resource}.
2166 @defvar x-resource-name
2167 This variable specifies the instance name that @code{x-get-resource}
2168 should look up. The default value is the name Emacs was invoked with,
2169 or the value specified with the @samp{-name} or @samp{-rn} switches.
2172 To illustrate some of the above, suppose that you have the line:
2175 xterm.vt100.background: yellow
2179 in your X resources file (whose name is usually @file{~/.Xdefaults}
2180 or @file{~/.Xresources}). Then:
2184 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2185 (x-get-resource "vt100.background" "VT100.Background"))
2189 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2190 (x-get-resource "background" "VT100" "vt100" "Background"))
2195 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
2197 @node Display Feature Testing
2198 @section Display Feature Testing
2199 @cindex display feature testing
2201 The functions in this section describe the basic capabilities of a
2202 particular display. Lisp programs can use them to adapt their behavior
2203 to what the display can do. For example, a program that ordinarily uses
2204 a popup menu could use the minibuffer if popup menus are not supported.
2206 The optional argument @var{display} in these functions specifies which
2207 display to ask the question about. It can be a display name, a frame
2208 (which designates the display that frame is on), or @code{nil} (which
2209 refers to the selected frame's display, @pxref{Input Focus}).
2211 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2212 obtain information about displays.
2214 @defun display-popup-menus-p &optional display
2215 This function returns @code{t} if popup menus are supported on
2216 @var{display}, @code{nil} if not. Support for popup menus requires that
2217 the mouse be available, since the user cannot choose menu items without
2221 @defun display-graphic-p &optional display
2222 This function returns @code{t} if @var{display} is a graphic display
2223 capable of displaying several frames and several different fonts at
2224 once. This is true for displays that use a window system such as X, and
2225 false for text-only terminals.
2228 @defun display-mouse-p &optional display
2229 @cindex mouse, availability
2230 This function returns @code{t} if @var{display} has a mouse available,
2234 @defun display-color-p &optional display
2235 @findex x-display-color-p
2236 This function returns @code{t} if the screen is a color screen.
2237 It used to be called @code{x-display-color-p}, and that name
2238 is still supported as an alias.
2241 @defun display-grayscale-p &optional display
2242 This function returns @code{t} if the screen can display shades of gray.
2243 (All color displays can do this.)
2246 @defun display-supports-face-attributes-p attributes &optional display
2247 @anchor{Display Face Attribute Testing}
2248 This function returns non-@code{nil} if all the face attributes in
2249 @var{attributes} are supported (@pxref{Face Attributes}).
2251 The definition of `supported' is somewhat heuristic, but basically
2252 means that a face containing all the attributes in @var{attributes},
2253 when merged with the default face for display, can be represented in a
2258 different in appearance than the default face, and
2261 `close in spirit' to what the attributes specify, if not exact.
2264 Point (2) implies that a @code{:weight black} attribute will be
2265 satisfied by any display that can display bold, as will
2266 @code{:foreground "yellow"} as long as some yellowish color can be
2267 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2268 the tty display code's automatic substitution of a `dim' face for
2272 @defun display-selections-p &optional display
2273 This function returns @code{t} if @var{display} supports selections.
2274 Windowed displays normally support selections, but they may also be
2275 supported in some other cases.
2278 @defun display-images-p &optional display
2279 This function returns @code{t} if @var{display} can display images.
2280 Windowed displays ought in principle to handle images, but some
2281 systems lack the support for that. On a display that does not support
2282 images, Emacs cannot display a tool bar.
2285 @defun display-screens &optional display
2286 This function returns the number of screens associated with the display.
2289 @defun display-pixel-height &optional display
2290 This function returns the height of the screen in pixels.
2291 On a character terminal, it gives the height in characters.
2293 For graphical terminals, note that on ``multi-monitor'' setups this
2294 refers to the pixel width for all physical monitors associated with
2295 @var{display}. @xref{Multiple Displays}.
2298 @defun display-pixel-width &optional display
2299 This function returns the width of the screen in pixels.
2300 On a character terminal, it gives the width in characters.
2302 For graphical terminals, note that on ``multi-monitor'' setups this
2303 refers to the pixel width for all physical monitors associated with
2304 @var{display}. @xref{Multiple Displays}.
2307 @defun display-mm-height &optional display
2308 This function returns the height of the screen in millimeters,
2309 or @code{nil} if Emacs cannot get that information.
2312 @defun display-mm-width &optional display
2313 This function returns the width of the screen in millimeters,
2314 or @code{nil} if Emacs cannot get that information.
2317 @defvar display-mm-dimensions-alist
2318 This variable allows the user to specify the dimensions of graphical
2319 displays returned by @code{display-mm-height} and
2320 @code{display-mm-width} in case the system provides incorrect values.
2323 @defun display-backing-store &optional display
2324 This function returns the backing store capability of the display.
2325 Backing store means recording the pixels of windows (and parts of
2326 windows) that are not exposed, so that when exposed they can be
2327 displayed very quickly.
2329 Values can be the symbols @code{always}, @code{when-mapped}, or
2330 @code{not-useful}. The function can also return @code{nil}
2331 when the question is inapplicable to a certain kind of display.
2334 @defun display-save-under &optional display
2335 This function returns non-@code{nil} if the display supports the
2336 SaveUnder feature. That feature is used by pop-up windows
2337 to save the pixels they obscure, so that they can pop down
2341 @defun display-planes &optional display
2342 This function returns the number of planes the display supports.
2343 This is typically the number of bits per pixel.
2344 For a tty display, it is log to base two of the number of colors supported.
2347 @defun display-visual-class &optional display
2348 This function returns the visual class for the screen. The value is one
2349 of the symbols @code{static-gray}, @code{gray-scale},
2350 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
2351 @code{direct-color}.
2354 @defun display-color-cells &optional display
2355 This function returns the number of color cells the screen supports.
2358 These functions obtain additional information specifically
2361 @defun x-server-version &optional display
2362 This function returns the list of version numbers of the X server
2363 running the display. The value is a list of three integers: the major
2364 and minor version numbers of the X protocol, and the
2365 distributor-specific release number of the X server software itself.
2368 @defun x-server-vendor &optional display
2369 This function returns the ``vendor'' that provided the X server
2370 software (as a string). Really this means whoever distributes the X
2373 When the developers of X labelled software distributors as
2374 ``vendors,'' they showed their false assumption that no system could
2375 ever be developed and distributed noncommercially.
2379 @defvar x-no-window-manager
2380 This variable's value is @code{t} if no X window manager is in use.
2386 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2387 width and height of an X Window frame, measured in pixels.
2392 arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba