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, 2010, 2011
5 @c Free Software Foundation, Inc.
6 @c See the file elisp.texi for copying conditions.
7 @setfilename ../../info/frames
8 @node Frames, Positions, Windows, Top
12 A @dfn{frame} is a screen object that contains one or more Emacs
13 windows (@pxref{Windows}). It is the kind of object called a
14 ``window'' in the terminology of graphical environments; but we can't
15 call it a ``window'' here, because Emacs uses that word in a different
16 way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that
17 represents a frame on the screen. @xref{Frame Type}.
19 A frame initially contains a single main window and/or a minibuffer
20 window; you can subdivide the main window vertically or horizontally
21 into smaller windows. @xref{Splitting Windows}.
24 A @dfn{terminal} is a display device capable of displaying one or
25 more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp
26 object that represents a terminal. @xref{Terminal Type}.
28 @cindex terminal frame
30 There are two classes of terminals: text-only terminals and
31 graphical terminals. Text-only terminals are non-graphics-capable
32 display devices, including ``terminal emulators'' such as xterm. On
33 text-only terminals, each frame occupies the entire terminal screen;
34 although you can create additional frames and switch between them,
35 only one frame can be shown at any given time. We refer to frames on
36 text-only terminals as @dfn{terminal frames}. Graphical terminals, on
37 the other hand, are graphics-capable windowing systems, such as the X
38 Window System. On a graphical terminal, Emacs can display multiple
39 frames simultaneously. We refer to such frames as @dfn{window
42 On GNU and Unix systems, you can create additional frames on any
43 available terminal, within a single Emacs session, regardless of
44 whether Emacs was started on a text-only or graphical terminal. Emacs
45 can display on both graphical and text-only terminals simultaneously.
46 This comes in handy, for instance, when you connect to the same
47 session from several remote locations. @xref{Multiple Terminals}.
50 This predicate returns a non-@code{nil} value if @var{object} is a
51 frame, and @code{nil} otherwise. For a frame, the value indicates which
52 kind of display the frame uses:
56 The frame is displayed in an X window.
58 A terminal frame on a character display.
60 The frame is displayed on MS-Windows 9X/NT.
62 The frame is displayed on a GNUstep or Macintosh Cocoa display.
64 The frame is displayed on an MS-DOS terminal.
68 @defun frame-terminal &optional frame
69 This function returns the terminal object that displays @var{frame}.
70 If @var{frame} is @code{nil} or unspecified, it defaults to the
74 @defun terminal-live-p object
75 This predicate returns a non-@code{nil} value if @var{object} is a
76 terminal that is alive (i.e.@: was not deleted), and @code{nil}
77 otherwise. For live terminals, the return value indicates what kind
78 of frames are displayed on that terminal; the list of possible values
79 is the same as for @code{framep} above.
83 * Creating Frames:: Creating additional frames.
84 * Multiple Terminals:: Displaying on several different devices.
85 * Frame Parameters:: Controlling frame size, position, font, etc.
86 * Terminal Parameters:: Parameters common for all frames on terminal.
87 * Frame Titles:: Automatic updating of frame titles.
88 * Deleting Frames:: Frames last until explicitly deleted.
89 * Finding All Frames:: How to examine all existing frames.
90 * Frames and Windows:: A frame contains windows;
91 display of text always works through windows.
92 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
93 * Input Focus:: Specifying the selected frame.
94 * Visibility of Frames:: Frames may be visible or invisible, or icons.
95 * Raising and Lowering:: Raising a frame makes it hide other windows;
96 lowering it makes the others hide it.
97 * Frame Configurations:: Saving the state of all frames.
98 * Mouse Tracking:: Getting events that say when the mouse moves.
99 * Mouse Position:: Asking where the mouse is, or moving it.
100 * Pop-Up Menus:: Displaying a menu for the user to select from.
101 * Dialog Boxes:: Displaying a box to ask yes or no.
102 * Pointer Shape:: Specifying the shape of the mouse pointer.
103 * Window System Selections:: Transferring text to and from other X clients.
104 * Drag and Drop:: Internals of Drag-and-Drop implementation.
105 * Color Names:: Getting the definitions of color names.
106 * Text Terminal Colors:: Defining colors for text-only terminals.
107 * Resources:: Getting resource values from the server.
108 * Display Feature Testing:: Determining the features of a terminal.
111 @node Creating Frames
112 @section Creating Frames
114 To create a new frame, call the function @code{make-frame}.
116 @defun make-frame &optional alist
117 This function creates and returns a new frame, displaying the current
120 The @var{alist} argument is an alist that specifies frame parameters
121 for the new frame. @xref{Frame Parameters}. If you specify the
122 @code{terminal} parameter in @var{alist}, the new frame is created on
123 that terminal. Otherwise, if you specify the @code{window-system}
124 frame parameter in @var{alist}, that determines whether the frame
125 should be displayed on a text-only or graphical terminal.
126 @xref{Window Systems}. If neither is specified, the new frame is
127 created in the same terminal as the selected frame.
129 Any parameters not mentioned in @var{alist} default to the values in
130 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
131 parameters not specified there default from the X resources or its
132 equivalent on your operating system (@pxref{X Resources,, X Resources,
133 emacs, The GNU Emacs Manual}). After the frame is created, Emacs
134 applies any parameters listed in @code{frame-inherited-parameters}
135 (see below) and not present in the argument, taking the values from
136 the frame that was selected when @code{make-frame} was called.
138 This function itself does not make the new frame the selected frame.
139 @xref{Input Focus}. The previously selected frame remains selected.
140 On graphical terminals, however, the windowing system may select the
141 new frame for its own reasons.
144 @defvar before-make-frame-hook
145 A normal hook run by @code{make-frame} before it creates the frame.
148 @defvar after-make-frame-functions
149 An abnormal hook run by @code{make-frame} after it creates the frame.
150 Each function in @code{after-make-frame-functions} receives one argument, the
154 @defvar frame-inherited-parameters
155 This variable specifies the list of frame parameters that a newly
156 created frame inherits from the currently selected frame. For each
157 parameter (a symbol) that is an element in the list and is not present
158 in the argument to @code{make-frame}, the function sets the value of
159 that parameter in the created frame to its value in the selected
163 @node Multiple Terminals
164 @section Multiple Terminals
165 @cindex multiple terminals
167 @cindex multiple X displays
168 @cindex displays, multiple
170 Emacs represents each terminal, whether graphical or text-only, as a
171 @dfn{terminal object} data type (@pxref{Terminal Type}). On GNU and
172 Unix systems, Emacs can use multiple terminals simultaneously in each
173 session. On other systems, it can only use a single terminal. Each
174 terminal object has the following attributes:
178 The name of the device used by the terminal (e.g., @samp{:0.0} or
182 The terminal and keyboard coding systems used on the terminal.
183 @xref{Terminal I/O Encoding}.
186 The kind of display associated with the terminal. This is the symbol
187 returned by the function @code{terminal-live-p} (i.e., @code{x},
188 @code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.
191 A list of terminal parameters. @xref{Terminal Parameters}.
194 There is no primitive for creating terminal objects. Emacs creates
195 them as needed, such as when you call @code{make-frame-on-display}
196 (which is described below).
198 @defun terminal-name &optional terminal
199 This function returns the file name of the device used by
200 @var{terminal}. If @var{terminal} is omitted or @code{nil}, it
201 defaults to the selected frame's terminal. @var{terminal} can also be
202 a frame, meaning that frame's terminal.
206 This function returns a list of all terminal objects currently in use.
209 @defun get-device-terminal device
210 This function returns a terminal whose device name is given by
211 @var{device}. If @var{device} is a string, it can be either the file
212 name of a terminal device, or the name of an X display of the form
213 @samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a
214 frame, this function returns that frame's terminal; @code{nil} means
215 the selected frame. Finally, if @var{device} is a terminal object
216 that represents a live terminal, that terminal is returned. The
217 function signals an error if its argument is none of the above.
220 @defun delete-terminal &optional terminal force
221 This function deletes all frames on @var{terminal} and frees the
222 resources used by it. It runs the abnormal hook
223 @code{delete-terminal-functions}, passing @var{terminal} as the
224 argument to each function.
226 If @var{terminal} is omitted or @code{nil}, it defaults to the
227 selected frame's terminal. @var{terminal} can also be a frame,
228 meaning that frame's terminal.
230 Normally, this function signals an error if you attempt to delete the
231 sole active terminal, but if @var{force} is non-@code{nil}, you are
232 allowed to do so. Emacs automatically calls this function when the
233 last frame on a terminal is deleted (@pxref{Deleting Frames}).
236 @defvar delete-terminal-functions
237 An abnormal hook run by @code{delete-terminal}. Each function
238 receives one argument, the @var{terminal} argument passed to
239 @code{delete-terminal}. Due to technical details, the functions may
240 be called either just before the terminal is deleted, or just
244 @cindex terminal-local variables
245 A few Lisp variables are @dfn{terminal-local}; that is, they have a
246 separate binding for each terminal. The binding in effect at any time
247 is the one for the terminal that the currently selected frame belongs
248 to. These variables include @code{default-minibuffer-frame},
249 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
250 @code{system-key-alist}. They are always terminal-local, and can
251 never be buffer-local (@pxref{Buffer-Local Variables}).
253 On GNU and Unix systems, each X display is a separate graphical
254 terminal. When Emacs is started from within the X window system, it
255 uses the X display chosen with the @code{DISPLAY} environment
256 variable, or with the @samp{--display} option. @xref{Initial
257 Options,,, emacs, The GNU Emacs Manual}. Emacs can connect to other X
258 displays via the command @code{make-frame-on-display}. Each X display
259 has its own selected frame and its own minibuffer windows; however,
260 only one of those frames is ``@emph{the} selected frame'' at any given
261 moment (@pxref{Input Focus}). Emacs can even connect to other
262 text-only terminals, by interacting with the @command{emacsclient}
263 program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
265 A single X server can handle more than one display. Each X display
266 has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
267 The first two parts, @var{host} and @var{server}, identify the X
268 server; the third part, @var{screen}, identifies a screen number on
269 that X server. When you use two or more screens belonging to one
270 server, Emacs knows by the similarity in their names that they share a
273 On some ``multi-monitor'' setups, a single X display outputs to more
274 than one monitor. Currently, there is no way for Emacs to distinguish
275 between the different physical monitors.
277 @deffn Command make-frame-on-display display &optional parameters
278 This function creates and returns a new frame on @var{display}, taking
279 the other frame parameters from the alist @var{parameters}.
280 @var{display} should be the name of an X display (a string).
282 Before creating the frame, this function ensures that Emacs is ``set
283 up'' to display graphics. For instance, if Emacs has not processed X
284 resources (e.g., if it was started on a text-only terminal), it does
285 so at this time. In all other respects, this function behaves like
286 @code{make-frame} (@pxref{Creating Frames}).
289 @defun x-display-list
290 This function returns a list that indicates which X displays Emacs has
291 a connection to. The elements of the list are strings, and each one
295 @defun x-open-connection display &optional xrm-string must-succeed
296 This function opens a connection to the X display @var{display},
297 without creating a frame on that display. Normally, Emacs Lisp
298 programs need not call this function, as @code{make-frame-on-display}
299 calls it automatically. The only reason for calling it is to check
300 whether communication can be established with a given X display.
302 The optional argument @var{xrm-string}, if not @code{nil}, is a string
303 of resource names and values, in the same format used in the
304 @file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The
305 GNU Emacs Manual}. These values apply to all Emacs frames created on
306 this display, overriding the resource values recorded in the X server.
307 Here's an example of what this string might look like:
310 "*BorderWidth: 3\n*InternalBorder: 2\n"
313 If @var{must-succeed} is non-@code{nil}, failure to open the connection
314 terminates Emacs. Otherwise, it is an ordinary Lisp error.
317 @defun x-close-connection display
318 This function closes the connection to display @var{display}. Before
319 you can do this, you must first delete all the frames that were open
320 on that display (@pxref{Deleting Frames}).
323 @node Frame Parameters
324 @section Frame Parameters
325 @cindex frame parameters
327 A frame has many parameters that control its appearance and behavior.
328 Just what parameters a frame has depends on what display mechanism it
331 Frame parameters exist mostly for the sake of window systems. A
332 terminal frame has a few parameters, mostly for compatibility's sake;
333 only the @code{height}, @code{width}, @code{name}, @code{title},
334 @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
335 parameters do something special. If the terminal supports colors, the
336 parameters @code{foreground-color}, @code{background-color},
337 @code{background-mode} and @code{display-type} are also meaningful.
338 If the terminal supports frame transparency, the parameter
339 @code{alpha} is also meaningful.
341 You can use frame parameters to define frame-local bindings for
342 variables. @xref{Frame-Local Variables}.
345 * Parameter Access:: How to change a frame's parameters.
346 * Initial Parameters:: Specifying frame parameters when you make a frame.
347 * Window Frame Parameters:: List of frame parameters for window systems.
348 * Size and Position:: Changing the size and position of a frame.
349 * Geometry:: Parsing geometry specifications.
352 @node Parameter Access
353 @subsection Access to Frame Parameters
355 These functions let you read and change the parameter values of a
358 @defun frame-parameter frame parameter
359 This function returns the value of the parameter @var{parameter} (a
360 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
361 selected frame's parameter. If @var{frame} has no setting for
362 @var{parameter}, this function returns @code{nil}.
365 @defun frame-parameters &optional frame
366 The function @code{frame-parameters} returns an alist listing all the
367 parameters of @var{frame} and their values. If @var{frame} is
368 @code{nil} or omitted, this returns the selected frame's parameters
371 @defun modify-frame-parameters frame alist
372 This function alters the parameters of frame @var{frame} based on the
373 elements of @var{alist}. Each element of @var{alist} has the form
374 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
375 parameter. If you don't mention a parameter in @var{alist}, its value
376 doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
379 You can use this function to define frame-local bindings for
380 variables, see @ref{Frame-Local Variables}.
383 @defun set-frame-parameter frame parm value
384 This function sets the frame parameter @var{parm} to the specified
385 @var{value}. If @var{frame} is @code{nil}, it defaults to the
389 @defun modify-all-frames-parameters alist
390 This function alters the frame parameters of all existing frames
391 according to @var{alist}, then modifies @code{default-frame-alist}
392 (and, if necessary, @code{initial-frame-alist}) to apply the same
393 parameter values to frames that will be created henceforth.
396 @node Initial Parameters
397 @subsection Initial Frame Parameters
399 You can specify the parameters for the initial startup frame
400 by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
402 @defopt initial-frame-alist
403 This variable's value is an alist of parameter values used when creating
404 the initial window frame. You can set this variable to specify the
405 appearance of the initial frame without altering subsequent frames.
406 Each element has the form:
409 (@var{parameter} . @var{value})
412 Emacs creates the initial frame before it reads your init
413 file. After reading that file, Emacs checks @code{initial-frame-alist},
414 and applies the parameter settings in the altered value to the already
415 created initial frame.
417 If these settings affect the frame geometry and appearance, you'll see
418 the frame appear with the wrong ones and then change to the specified
419 ones. If that bothers you, you can specify the same geometry and
420 appearance with X resources; those do take effect before the frame is
421 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
423 X resource settings typically apply to all frames. If you want to
424 specify some X resources solely for the sake of the initial frame, and
425 you don't want them to apply to subsequent frames, here's how to achieve
426 this. Specify parameters in @code{default-frame-alist} to override the
427 X resources for subsequent frames; then, to prevent these from affecting
428 the initial frame, specify the same parameters in
429 @code{initial-frame-alist} with values that match the X resources.
432 If these parameters specify a separate minibuffer-only frame with
433 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
436 @defopt minibuffer-frame-alist
437 This variable's value is an alist of parameter values used when
438 creating an initial minibuffer-only frame. This is the
439 minibuffer-only frame that Emacs creates if @code{initial-frame-alist}
440 specifies a frame with no minibuffer.
443 @defopt default-frame-alist
444 This is an alist specifying default values of frame parameters for all
445 Emacs frames---the first frame, and subsequent frames. When using the X
446 Window System, you can get the same results by means of X resources
449 Setting this variable does not affect existing frames.
452 Functions that display a buffer in a separate frame can override the
453 default parameters by supplying their own parameters. @xref{Definition
454 of special-display-frame-alist}.
456 If you use options that specify window appearance when you invoke Emacs,
457 they take effect by adding elements to @code{default-frame-alist}. One
458 exception is @samp{-geometry}, which adds the specified position to
459 @code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command
460 Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
462 @node Window Frame Parameters
463 @subsection Window Frame Parameters
465 Just what parameters a frame has depends on what display mechanism
466 it uses. This section describes the parameters that have special
467 meanings on some or all kinds of terminals. Of these, @code{name},
468 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
469 @code{buffer-predicate} provide meaningful information in terminal
470 frames, and @code{tty-color-mode} is meaningful @emph{only} in
474 * Basic Parameters:: Parameters that are fundamental.
475 * Position Parameters:: The position of the frame on the screen.
476 * Size Parameters:: Frame's size.
477 * Layout Parameters:: Size of parts of the frame, and
478 enabling or disabling some parts.
479 * Buffer Parameters:: Which buffers have been or should be shown.
480 * Management Parameters:: Communicating with the window manager.
481 * Cursor Parameters:: Controlling the cursor appearance.
482 * Font and Color Parameters:: Fonts and colors for the frame text.
485 @node Basic Parameters
486 @subsubsection Basic Parameters
488 These frame parameters give the most basic information about the
489 frame. @code{title} and @code{name} are meaningful on all terminals.
493 The display on which to open this frame. It should be a string of the
494 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
495 @code{DISPLAY} environment variable.
498 This parameter describes the range of possible colors that can be used
499 in this frame. Its value is @code{color}, @code{grayscale} or
503 If a frame has a non-@code{nil} title, it appears in the window
504 system's title bar at the top of the frame, and also in the mode line
505 of windows in that frame if @code{mode-line-frame-identification} uses
506 @samp{%F} (@pxref{%-Constructs}). This is normally the case when
507 Emacs is not using a window system, and can only display one frame at
508 a time. @xref{Frame Titles}.
511 The name of the frame. The frame name serves as a default for the frame
512 title, if the @code{title} parameter is unspecified or @code{nil}. If
513 you don't specify a name, Emacs sets the frame name automatically
514 (@pxref{Frame Titles}).
516 If you specify the frame name explicitly when you create the frame, the
517 name is also used (instead of the name of the Emacs executable) when
518 looking up X resources for the frame.
521 @node Position Parameters
522 @subsubsection Position Parameters
524 Position parameters' values are normally measured in pixels, but on
525 text-only terminals they count characters or lines instead.
529 The position, in pixels, of the left (or right) edge of the frame with
530 respect to the left (or right) edge of the screen. The value may be:
534 A positive integer relates the left edge of the frame to the left edge
535 of the screen. A negative integer relates the right frame edge to the
538 @item @code{(+ @var{pos})}
539 This specifies the position of the left frame edge relative to the left
540 screen edge. The integer @var{pos} may be positive or negative; a
541 negative value specifies a position outside the screen.
543 @item @code{(- @var{pos})}
544 This specifies the position of the right frame edge relative to the right
545 screen edge. The integer @var{pos} may be positive or negative; a
546 negative value specifies a position outside the screen.
549 Some window managers ignore program-specified positions. If you want to
550 be sure the position you specify is not ignored, specify a
551 non-@code{nil} value for the @code{user-position} parameter as well.
554 The screen position of the top (or bottom) edge, in pixels, with respect
555 to the top (or bottom) edge of the screen. It works just like
556 @code{left}, except vertically instead of horizontally.
559 The screen position of the left edge @emph{of the frame's icon}, in
560 pixels, counting from the left edge of the screen. This takes effect if
561 and when the frame is iconified.
563 If you specify a value for this parameter, then you must also specify
564 a value for @code{icon-top} and vice versa. The window manager may
565 ignore these two parameters.
568 The screen position of the top edge @emph{of the frame's icon}, in
569 pixels, counting from the top edge of the screen. This takes effect if
570 and when the frame is iconified.
573 When you create a frame and specify its screen position with the
574 @code{left} and @code{top} parameters, use this parameter to say whether
575 the specified position was user-specified (explicitly requested in some
576 way by a human user) or merely program-specified (chosen by a program).
577 A non-@code{nil} value says the position was user-specified.
579 Window managers generally heed user-specified positions, and some heed
580 program-specified positions too. But many ignore program-specified
581 positions, placing the window in a default fashion or letting the user
582 place it with the mouse. Some window managers, including @code{twm},
583 let the user specify whether to obey program-specified positions or
586 When you call @code{make-frame}, you should specify a non-@code{nil}
587 value for this parameter if the values of the @code{left} and @code{top}
588 parameters represent the user's stated preference; otherwise, use
592 @node Size Parameters
593 @subsubsection Size Parameters
595 Size parameters' values are normally measured in pixels, but on
596 text-only terminals they count characters or lines instead.
600 The height of the frame contents, in characters. (To get the height in
601 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
604 The width of the frame contents, in characters. (To get the width in
605 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
608 This does for the size parameters @code{height} and @code{width} what
609 the @code{user-position} parameter (see above) does for the position
610 parameters @code{top} and @code{left}.
613 Specify that width, height or both shall be maximized. The value
614 @code{fullwidth} specifies that width shall be as wide as possible.
615 The value @code{fullheight} specifies that height shall be as tall as
616 possible. The value @code{fullboth} specifies that both the width and
617 the height shall be set to the size of the screen. The value
618 @code{maximized} specifies that the frame shall be maximized. The
619 difference between @code{maximized} and @code{fullboth} is that the
620 former still has window manager decorations while the latter really
621 covers the whole screen.
624 @node Layout Parameters
625 @subsubsection Layout Parameters
627 These frame parameters enable or disable various parts of the
628 frame, or control their sizes.
632 The width in pixels of the frame's border.
634 @item internal-border-width
635 The distance in pixels between text (or fringe) and the frame's border.
637 @item vertical-scroll-bars
638 Whether the frame has scroll bars for vertical scrolling, and which side
639 of the frame they should be on. The possible values are @code{left},
640 @code{right}, and @code{nil} for no scroll bars.
643 @item horizontal-scroll-bars
644 Whether the frame has scroll bars for horizontal scrolling
645 (non-@code{nil} means yes). Horizontal scroll bars are not currently
649 @item scroll-bar-width
650 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
651 use the default width.
655 The default width of the left and right fringes of windows in this
656 frame (@pxref{Fringes}). If either of these is zero, that effectively
657 removes the corresponding fringe.
659 When you use @code{frame-parameter} to query the value of either of
660 these two frame parameters, the return value is always an integer.
661 When using @code{set-frame-parameter}, passing a @code{nil} value
662 imposes an actual default value of 8 pixels.
664 The combined fringe widths must add up to an integral number of
665 columns, so the actual default fringe widths for the frame, as
666 reported by @code{frame-parameter}, may be larger than what you
667 specify. Any extra width is distributed evenly between the left and
668 right fringe. However, you can force one fringe or the other to a
669 precise width by specifying that width as a negative integer. If both
670 widths are negative, only the left fringe gets the specified width.
673 The number of lines to allocate at the top of the frame for a menu
674 bar. The default is 1. A value of @code{nil} means don't display a
675 menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one
676 menu bar line; they treat larger values as 1.)
679 The number of lines to use for the tool bar. A value of @code{nil}
680 means don't display a tool bar. (GTK and Nextstep allow at most one
681 tool bar line; they treat larger values as 1.)
684 Additional space to leave below each text line, in pixels (a positive
685 integer). @xref{Line Height}, for more information.
688 @node Buffer Parameters
689 @subsubsection Buffer Parameters
691 These frame parameters, meaningful on all kinds of terminals, deal
692 with which buffers have been, or should, be displayed in the frame.
696 Whether this frame has its own minibuffer. The value @code{t} means
697 yes, @code{nil} means no, @code{only} means this frame is just a
698 minibuffer. If the value is a minibuffer window (in some other
699 frame), the frame uses that minibuffer.
701 This frame parameter takes effect when the frame is created, and can
702 not be changed afterwards.
704 @item buffer-predicate
705 The buffer-predicate function for this frame. The function
706 @code{other-buffer} uses this predicate (from the selected frame) to
707 decide which buffers it should consider, if the predicate is not
708 @code{nil}. It calls the predicate with one argument, a buffer, once for
709 each buffer; if the predicate returns a non-@code{nil} value, it
710 considers that buffer.
713 A list of buffers that have been selected in this frame,
714 ordered most-recently-selected first.
717 If non-@code{nil}, this frame's window is never split automatically.
720 @node Management Parameters
721 @subsubsection Window Management Parameters
722 @cindex window manager, and frame parameters
724 These frame parameters, meaningful only on window system displays,
725 interact with the window manager.
729 The state of visibility of the frame. There are three possibilities:
730 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
731 iconified. @xref{Visibility of Frames}.
734 Whether selecting the frame raises it (non-@code{nil} means yes).
737 Whether deselecting the frame lowers it (non-@code{nil} means yes).
740 The type of icon to use for this frame when it is iconified. If the
741 value is a string, that specifies a file containing a bitmap to use.
742 Any other non-@code{nil} value specifies the default bitmap icon (a
743 picture of a gnu); @code{nil} specifies a text icon.
746 The name to use in the icon for this frame, when and if the icon
747 appears. If this is @code{nil}, the frame's title is used.
750 The number of the window-system window used by the frame
751 to contain the actual Emacs windows.
753 @item outer-window-id
754 The number of the outermost window-system window used for the whole frame.
757 If non-@code{nil}, tell Xt to wait for the window manager to confirm
758 geometry changes. Some window managers, including versions of Fvwm2
759 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
760 prevent hanging with those window managers.
763 If non-@code{nil}, the frame is visible on all virtual desktops on systems
764 with virtual desktops.
768 @c ??? Not yet working.
769 The X window number of the window that should be the parent of this one.
770 Specifying this lets you create an Emacs window inside some other
771 application's window. (It is not certain this will be implemented; try
772 it and see if it works.)
776 @node Cursor Parameters
777 @subsubsection Cursor Parameters
779 This frame parameter controls the way the cursor looks.
783 How to display the cursor. Legitimate values are:
787 Display a filled box. (This is the default.)
789 Display a hollow box.
791 Don't display a cursor.
793 Display a vertical bar between characters.
794 @item (bar . @var{width})
795 Display a vertical bar @var{width} pixels wide between characters.
797 Display a horizontal bar.
798 @item (hbar . @var{height})
799 Display a horizontal bar @var{height} pixels high.
804 The buffer-local variable @code{cursor-type} overrides the value of
805 the @code{cursor-type} frame parameter, but if it is @code{t}, that
806 means to use the cursor specified for the frame.
808 @defopt blink-cursor-alist
809 This variable specifies how to blink the cursor. Each element has the
810 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
811 type equals @var{on-state} (comparing using @code{equal}), the
812 corresponding @var{off-state} specifies what the cursor looks like
813 when it blinks ``off.'' Both @var{on-state} and @var{off-state}
814 should be suitable values for the @code{cursor-type} frame parameter.
816 There are various defaults for how to blink each type of cursor, if
817 the type is not mentioned as an @var{on-state} here. Changes in this
818 variable do not take effect immediately, only when you specify the
819 @code{cursor-type} frame parameter.
822 @defopt cursor-in-non-selected-windows
823 This variable controls how the cursor looks in a window that is not
824 selected. It supports the same values as the @code{cursor-type} frame
825 parameter; also, @code{nil} means don't display a cursor in
826 nonselected windows, and @code{t} (the default) means use a standard
827 modification of the usual cursor type (solid box becomes hollow box,
828 and bar becomes a narrower bar).
831 @node Font and Color Parameters
832 @subsubsection Font and Color Parameters
834 These frame parameters control the use of fonts and colors.
838 A list of symbols, specifying the @dfn{font backends} to use for
839 drawing fonts in the frame, in order of priority. On X, there are
840 currently two available font backends: @code{x} (the X core font
841 driver) and @code{xft} (the Xft font driver). On other systems, there
842 is only one available font backend, so it does not make sense to
843 modify this frame parameter.
845 @item background-mode
846 This parameter is either @code{dark} or @code{light}, according
847 to whether the background color is a light one or a dark one.
850 @cindex standard colors for character terminals
851 This parameter overrides the terminal's color support as given by the
852 system's terminal capabilities database in that this parameter's value
853 specifies the color mode to use in terminal frames. The value can be
854 either a symbol or a number. A number specifies the number of colors
855 to use (and, indirectly, what commands to issue to produce each
856 color). For example, @code{(tty-color-mode . 8)} specifies use of the
857 ANSI escape sequences for 8 standard text colors. A value of -1 turns
860 If the parameter's value is a symbol, it specifies a number through
861 the value of @code{tty-color-mode-alist}, and the associated number is
865 @cindex gamma correction
866 If this is a number, Emacs performs ``gamma correction'' which adjusts
867 the brightness of all colors. The value should be the screen gamma of
868 your display, a floating point number.
870 Usual PC monitors have a screen gamma of 2.2, so color values in
871 Emacs, and in X windows generally, are calibrated to display properly
872 on a monitor with that gamma value. If you specify 2.2 for
873 @code{screen-gamma}, that means no correction is needed. Other values
874 request correction, designed to make the corrected colors appear on
875 your screen the way they would have appeared without correction on an
876 ordinary monitor with a gamma value of 2.2.
878 If your monitor displays colors too light, you should specify a
879 @code{screen-gamma} value smaller than 2.2. This requests correction
880 that makes colors darker. A screen gamma value of 1.5 may give good
881 results for LCD color displays.
884 @cindex opacity, frame
885 @cindex transparency, frame
886 @vindex frame-alpha-lower-limit
887 This parameter specifies the opacity of the frame, on graphical
888 displays that support variable opacity. It should be an integer
889 between 0 and 100, where 0 means completely transparent and 100 means
890 completely opaque. It can also have a @code{nil} value, which tells
891 Emacs not to set the frame opacity (leaving it to the window manager).
893 To prevent the frame from disappearing completely from view, the
894 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
895 If the value of the frame parameter is less than the value of this
896 variable, Emacs uses the latter. By default,
897 @code{frame-alpha-lower-limit} is 20.
899 The @code{alpha} frame parameter can also be a cons cell
900 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
901 opacity of the frame when it is selected, and @samp{inactive} is the
902 opactity when it is not selected.
905 The following frame parameters are semi-obsolete in that they are
906 automatically equivalent to particular face attributes of particular
907 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
911 The name of the font for displaying text in the frame. This is a
912 string, either a valid font name for your system or the name of an Emacs
913 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
914 attribute of the @code{default} face.
916 @item foreground-color
917 The color to use for the image of a character. It is equivalent to
918 the @code{:foreground} attribute of the @code{default} face.
920 @item background-color
921 The color to use for the background of characters. It is equivalent to
922 the @code{:background} attribute of the @code{default} face.
925 The color for the mouse pointer. It is equivalent to the @code{:background}
926 attribute of the @code{mouse} face.
929 The color for the cursor that shows point. It is equivalent to the
930 @code{:background} attribute of the @code{cursor} face.
933 The color for the border of the frame. It is equivalent to the
934 @code{:background} attribute of the @code{border} face.
936 @item scroll-bar-foreground
937 If non-@code{nil}, the color for the foreground of scroll bars. It is
938 equivalent to the @code{:foreground} attribute of the
939 @code{scroll-bar} face.
941 @item scroll-bar-background
942 If non-@code{nil}, the color for the background of scroll bars. It is
943 equivalent to the @code{:background} attribute of the
944 @code{scroll-bar} face.
947 @node Size and Position
948 @subsection Frame Size And Position
949 @cindex size of frame
954 You can read or change the size and position of a frame using the
955 frame parameters @code{left}, @code{top}, @code{height}, and
956 @code{width}. Whatever geometry parameters you don't specify are chosen
957 by the window manager in its usual fashion.
959 Here are some special features for working with sizes and positions.
960 (For the precise meaning of ``selected frame'' used by these functions,
961 see @ref{Input Focus}.)
963 @defun set-frame-position frame left top
964 This function sets the position of the top left corner of @var{frame} to
965 @var{left} and @var{top}. These arguments are measured in pixels, and
966 normally count from the top left corner of the screen.
968 Negative parameter values position the bottom edge of the window up from
969 the bottom edge of the screen, or the right window edge to the left of
970 the right edge of the screen. It would probably be better if the values
971 were always counted from the left and top, so that negative arguments
972 would position the frame partly off the top or left edge of the screen,
973 but it seems inadvisable to change that now.
976 @defun frame-height &optional frame
977 @defunx frame-width &optional frame
978 These functions return the height and width of @var{frame}, measured in
979 lines and columns. If you don't supply @var{frame}, they use the
983 @defun frame-pixel-height &optional frame
984 @defunx frame-pixel-width &optional frame
985 These functions return the height and width of the main display area
986 of @var{frame}, measured in pixels. If you don't supply @var{frame},
987 they use the selected frame. For a text-only terminal, the results are
988 in characters rather than pixels.
990 These values include the internal borders, and windows' scroll bars and
991 fringes (which belong to individual windows, not to the frame itself).
992 The exact value of the heights depends on the window-system and toolkit
993 in use. With Gtk+, the height does not include any tool bar or menu
994 bar. With the Motif or Lucid toolkits, it includes the tool bar but
995 not the menu bar. In a graphical version with no toolkit, it includes
996 both the tool bar and menu bar. For a text-only terminal, the result
997 includes the menu bar.
1000 @defun frame-char-height &optional frame
1001 @defunx frame-char-width &optional frame
1002 These functions return the height and width of a character in
1003 @var{frame}, measured in pixels. The values depend on the choice of
1004 font. If you don't supply @var{frame}, these functions use the selected
1008 @defun set-frame-size frame cols rows
1009 This function sets the size of @var{frame}, measured in characters;
1010 @var{cols} and @var{rows} specify the new width and height.
1012 To set the size based on values measured in pixels, use
1013 @code{frame-char-height} and @code{frame-char-width} to convert
1014 them to units of characters.
1017 @defun set-frame-height frame lines &optional pretend
1018 This function resizes @var{frame} to a height of @var{lines} lines. The
1019 sizes of existing windows in @var{frame} are altered proportionally to
1022 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
1023 lines of output in @var{frame}, but does not change its value for the
1024 actual height of the frame. This is only useful for a terminal frame.
1025 Using a smaller height than the terminal actually implements may be
1026 useful to reproduce behavior observed on a smaller screen, or if the
1027 terminal malfunctions when using its whole screen. Setting the frame
1028 height ``for real'' does not always work, because knowing the correct
1029 actual size may be necessary for correct cursor positioning on a
1033 @defun set-frame-width frame width &optional pretend
1034 This function sets the width of @var{frame}, measured in characters.
1035 The argument @var{pretend} has the same meaning as in
1036 @code{set-frame-height}.
1039 @findex set-screen-height
1040 @findex set-screen-width
1041 The older functions @code{set-screen-height} and
1042 @code{set-screen-width} were used to specify the height and width of the
1043 screen, in Emacs versions that did not support multiple frames. They
1044 are semi-obsolete, but still work; they apply to the selected frame.
1047 @subsection Geometry
1049 Here's how to examine the data in an X-style window geometry
1052 @defun x-parse-geometry geom
1053 @cindex geometry specification
1054 The function @code{x-parse-geometry} converts a standard X window
1055 geometry string to an alist that you can use as part of the argument to
1058 The alist describes which parameters were specified in @var{geom}, and
1059 gives the values specified for them. Each element looks like
1060 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
1061 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1063 For the size parameters, the value must be an integer. The position
1064 parameter names @code{left} and @code{top} are not totally accurate,
1065 because some values indicate the position of the right or bottom edges
1066 instead. The @var{value} possibilities for the position parameters are:
1067 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1068 as previously described (@pxref{Position Parameters}).
1073 (x-parse-geometry "35x70+0-0")
1074 @result{} ((height . 70) (width . 35)
1075 (top - 0) (left . 0))
1079 @node Terminal Parameters
1080 @section Terminal Parameters
1081 @cindex terminal parameters
1083 Each terminal has a list of associated parameters. These
1084 @dfn{terminal parameters} are mostly a convenient way of storage for
1085 terminal-local variables, but some terminal parameters have a special
1088 This section describes functions to read and change the parameter values
1089 of a terminal. They all accept as their argument either a terminal or
1090 a frame; the latter means use that frame's terminal. An argument of
1091 @code{nil} means the selected frame's terminal.
1093 @defun terminal-parameters &optional terminal
1094 This function returns an alist listing all the parameters of
1095 @var{terminal} and their values.
1098 @defun terminal-parameter terminal parameter
1099 This function returns the value of the parameter @var{parameter} (a
1100 symbol) of @var{terminal}. If @var{terminal} has no setting for
1101 @var{parameter}, this function returns @code{nil}.
1104 @defun set-terminal-parameter terminal parameter value
1105 This function sets the parameter @var{parm} of @var{terminal} to the
1106 specified @var{value}, and returns the previous value of that
1110 Here's a list of a few terminal parameters that have a special
1114 @item background-mode
1115 The classification of the terminal's background color, either
1116 @code{light} or @code{dark}.
1117 @item normal-erase-is-backspace
1118 Value is either 1 or 0, depending on whether
1119 @code{normal-erase-is-backspace-mode} is turned on or off on this
1120 terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1121 @item terminal-initted
1122 After the terminal is initialized, this is set to the
1123 terminal-specific initialization function.
1127 @section Frame Titles
1130 Every frame has a @code{name} parameter; this serves as the default
1131 for the frame title which window systems typically display at the top of
1132 the frame. You can specify a name explicitly by setting the @code{name}
1135 Normally you don't specify the name explicitly, and Emacs computes the
1136 frame name automatically based on a template stored in the variable
1137 @code{frame-title-format}. Emacs recomputes the name each time the
1138 frame is redisplayed.
1140 @defvar frame-title-format
1141 This variable specifies how to compute a name for a frame when you have
1142 not explicitly specified one. The variable's value is actually a mode
1143 line construct, just like @code{mode-line-format}, except that the
1144 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
1148 @defvar icon-title-format
1149 This variable specifies how to compute the name for an iconified frame,
1150 when you have not explicitly specified the frame title. This title
1151 appears in the icon itself.
1154 @defvar multiple-frames
1155 This variable is set automatically by Emacs. Its value is @code{t} when
1156 there are two or more frames (not counting minibuffer-only frames or
1157 invisible frames). The default value of @code{frame-title-format} uses
1158 @code{multiple-frames} so as to put the buffer name in the frame title
1159 only when there is more than one frame.
1161 The value of this variable is not guaranteed to be accurate except
1162 while processing @code{frame-title-format} or
1163 @code{icon-title-format}.
1166 @node Deleting Frames
1167 @section Deleting Frames
1168 @cindex deleting frames
1170 Frames remain potentially visible until you explicitly @dfn{delete}
1171 them. A deleted frame cannot appear on the screen, but continues to
1172 exist as a Lisp object until there are no references to it.
1174 @deffn Command delete-frame &optional frame force
1175 @vindex delete-frame-functions
1176 This function deletes the frame @var{frame}. Unless @var{frame} is a
1177 tooltip, it first runs the hook @code{delete-frame-functions} (each
1178 function gets one argument, @var{frame}). By default, @var{frame} is
1181 A frame cannot be deleted if its minibuffer is used by other frames.
1182 Normally, you cannot delete a frame if all other frames are invisible,
1183 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1186 @defun frame-live-p frame
1187 The function @code{frame-live-p} returns non-@code{nil} if the frame
1188 @var{frame} has not been deleted. The possible non-@code{nil} return
1189 values are like those of @code{framep}. @xref{Frames}.
1192 Some window managers provide a command to delete a window. These work
1193 by sending a special message to the program that operates the window.
1194 When Emacs gets one of these commands, it generates a
1195 @code{delete-frame} event, whose normal definition is a command that
1196 calls the function @code{delete-frame}. @xref{Misc Events}.
1198 @node Finding All Frames
1199 @section Finding All Frames
1200 @cindex frames, scanning all
1203 The function @code{frame-list} returns a list of all the live frames,
1204 i.e.@: those that have not been deleted. It is analogous to
1205 @code{buffer-list} for buffers, and includes frames on all terminals.
1206 The list that you get is newly created, so modifying the list doesn't
1207 have any effect on the internals of Emacs.
1210 @defun visible-frame-list
1211 This function returns a list of just the currently visible frames.
1212 @xref{Visibility of Frames}. (Terminal frames always count as
1213 ``visible,'' even though only the selected one is actually displayed.)
1216 @defun next-frame &optional frame minibuf
1217 The function @code{next-frame} lets you cycle conveniently through all
1218 the frames on the current display from an arbitrary starting point. It
1219 returns the ``next'' frame after @var{frame} in the cycle. If
1220 @var{frame} is omitted or @code{nil}, it defaults to the selected frame
1221 (@pxref{Input Focus}).
1223 The second argument, @var{minibuf}, says which frames to consider:
1227 Exclude minibuffer-only frames.
1228 @item @code{visible}
1229 Consider all visible frames.
1231 Consider all visible or iconified frames.
1233 Consider only the frames using that particular window as their
1236 Consider all frames.
1240 @defun previous-frame &optional frame minibuf
1241 Like @code{next-frame}, but cycles through all frames in the opposite
1245 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1248 @node Frames and Windows
1249 @section Frames and Windows
1251 Each window is part of one and only one frame; you can get that frame
1252 with @code{window-frame}.
1254 @defun window-frame window
1255 This function returns the frame that @var{window} is on.
1258 All the non-minibuffer windows in a frame are arranged in a cyclic
1259 order. The order runs from the frame's top window, which is at the
1260 upper left corner, down and to the right, until it reaches the window at
1261 the lower right corner (always the minibuffer window, if the frame has
1262 one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
1264 @defun frame-first-window &optional frame
1265 This returns the topmost, leftmost window of frame @var{frame}.
1266 If omitted or @code{nil}, @var{frame} defaults to the selected frame.
1269 At any time, exactly one window on any frame is @dfn{selected within the
1270 frame}. The significance of this designation is that selecting the
1271 frame also selects this window. Conversely, selecting a window for
1272 Emacs with @code{select-window} also makes that window selected within
1273 its frame. @xref{Selecting Windows}.
1275 @defun frame-selected-window &optional frame
1276 This function returns the window on @var{frame} that is selected
1277 within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to
1281 @defun set-frame-selected-window frame window &optional norecord
1282 This sets the selected window of frame @var{frame} to @var{window}.
1283 If @var{frame} is @code{nil}, it operates on the selected frame. If
1284 @var{frame} is the selected frame, this makes @var{window} the
1285 selected window. This function returns @var{window}.
1287 Optional argument @var{norecord} non-@code{nil} means to neither change
1288 the order of recently selected windows nor the buffer list (@pxref{The
1292 Another function that (usually) returns one of the windows in a given
1293 frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
1295 @node Minibuffers and Frames
1296 @section Minibuffers and Frames
1298 Normally, each frame has its own minibuffer window at the bottom, which
1299 is used whenever that frame is selected. If the frame has a minibuffer,
1300 you can get it with @code{minibuffer-window} (@pxref{Definition of
1301 minibuffer-window}).
1303 However, you can also create a frame with no minibuffer. Such a frame
1304 must use the minibuffer window of some other frame. When you create the
1305 frame, you can specify explicitly the minibuffer window to use (in some
1306 other frame). If you don't, then the minibuffer is found in the frame
1307 which is the value of the variable @code{default-minibuffer-frame}. Its
1308 value should be a frame that does have a minibuffer.
1310 If you use a minibuffer-only frame, you might want that frame to raise
1311 when you enter the minibuffer. If so, set the variable
1312 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
1314 @defvar default-minibuffer-frame
1315 This variable specifies the frame to use for the minibuffer window, by
1316 default. It does not affect existing frames. It is always local to
1317 the current terminal and cannot be buffer-local. @xref{Multiple
1322 @section Input Focus
1324 @c @cindex selected frame Duplicates selected-frame
1326 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
1327 window always resides on the selected frame.
1329 When Emacs displays its frames on several terminals (@pxref{Multiple
1330 Terminals}), each terminal has its own selected frame. But only one
1331 of these is ``@emph{the} selected frame'': it's the frame that belongs
1332 to the terminal from which the most recent input came. That is, when
1333 Emacs runs a command that came from a certain terminal, the selected
1334 frame is the one of that terminal. Since Emacs runs only a single
1335 command at any given time, it needs to consider only one selected
1336 frame at a time; this frame is what we call @dfn{the selected frame}
1337 in this manual. The display on which the selected frame is shown is
1338 the @dfn{selected frame's display}.
1340 @defun selected-frame
1341 This function returns the selected frame.
1344 Some window systems and window managers direct keyboard input to the
1345 window object that the mouse is in; others require explicit clicks or
1346 commands to @dfn{shift the focus} to various window objects. Either
1347 way, Emacs automatically keeps track of which frame has the focus. To
1348 explicitly switch to a different frame from a Lisp function, call
1349 @code{select-frame-set-input-focus}.
1351 Lisp programs can also switch frames ``temporarily'' by calling the
1352 function @code{select-frame}. This does not alter the window system's
1353 concept of focus; rather, it escapes from the window manager's control
1354 until that control is somehow reasserted.
1356 When using a text-only terminal, only one frame can be displayed at a
1357 time on the terminal, so after a call to @code{select-frame}, the next
1358 redisplay actually displays the newly selected frame. This frame
1359 remains selected until a subsequent call to @code{select-frame}. Each
1360 terminal frame has a number which appears in the mode line before the
1361 buffer name (@pxref{Mode Line Variables}).
1363 @defun select-frame-set-input-focus frame
1364 This function selects @var{frame}, raises it (should it happen to be
1365 obscured by other frames) and tries to give it the X server's focus. On
1366 a text-only terminal, the next redisplay displays the new frame on the
1367 entire terminal screen. The return value of this function is not
1371 @c ??? This is not yet implemented properly.
1372 @defun select-frame frame &optional norecord
1373 This function selects frame @var{frame}, temporarily disregarding the
1374 focus of the X server if any. The selection of @var{frame} lasts until
1375 the next time the user does something to select a different frame, or
1376 until the next time this function is called. (If you are using a
1377 window system, the previously selected frame may be restored as the
1378 selected frame after return to the command loop, because it still may
1379 have the window system's input focus.)
1381 The specified @var{frame} becomes the selected frame, as explained
1382 above, and the terminal that @var{frame} is on becomes the selected
1383 terminal. The window selected within @var{frame} becomes the selected
1384 window. This function returns @var{frame}, or @code{nil} if @var{frame}
1387 Optional argument @var{norecord} non-@code{nil} means to neither change
1388 the order of recently selected windows nor the buffer list. @xref{The
1391 In general, you should never use @code{select-frame} in a way that could
1392 switch to a different terminal without switching back when you're done.
1395 Emacs cooperates with the window system by arranging to select frames as
1396 the server and window manager request. It does so by generating a
1397 special kind of input event, called a @dfn{focus} event, when
1398 appropriate. The command loop handles a focus event by calling
1399 @code{handle-switch-frame}. @xref{Focus Events}.
1401 @deffn Command handle-switch-frame frame
1402 This function handles a focus event by selecting frame @var{frame}.
1404 Focus events normally do their job by invoking this command.
1405 Don't call it for any other reason.
1408 @defun redirect-frame-focus frame &optional focus-frame
1409 This function redirects focus from @var{frame} to @var{focus-frame}.
1410 This means that @var{focus-frame} will receive subsequent keystrokes and
1411 events intended for @var{frame}. After such an event, the value of
1412 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1413 events specifying @var{frame} will instead select @var{focus-frame}.
1415 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1416 redirection for @var{frame}, which therefore once again receives its own
1419 One use of focus redirection is for frames that don't have minibuffers.
1420 These frames use minibuffers on other frames. Activating a minibuffer
1421 on another frame redirects focus to that frame. This puts the focus on
1422 the minibuffer's frame, where it belongs, even though the mouse remains
1423 in the frame that activated the minibuffer.
1425 Selecting a frame can also change focus redirections. Selecting frame
1426 @code{bar}, when @code{foo} had been selected, changes any redirections
1427 pointing to @code{foo} so that they point to @code{bar} instead. This
1428 allows focus redirection to work properly when the user switches from
1429 one frame to another using @code{select-window}.
1431 This means that a frame whose focus is redirected to itself is treated
1432 differently from a frame whose focus is not redirected.
1433 @code{select-frame} affects the former but not the latter.
1435 The redirection lasts until @code{redirect-frame-focus} is called to
1439 @defopt focus-follows-mouse
1440 This option is how you inform Emacs whether the window manager transfers
1441 focus when the user moves the mouse. Non-@code{nil} says that it does.
1442 When this is so, the command @code{other-frame} moves the mouse to a
1443 position consistent with the new selected frame.
1446 @node Visibility of Frames
1447 @section Visibility of Frames
1448 @cindex visible frame
1449 @cindex invisible frame
1450 @cindex iconified frame
1451 @cindex frame visibility
1453 A window frame may be @dfn{visible}, @dfn{invisible}, or
1454 @dfn{iconified}. If it is visible, you can see its contents, unless
1455 other windows cover it. If it is iconified, the frame's contents do
1456 not appear on the screen, but an icon does. (Note: because of the
1457 way in which some window managers implement the concept of multiple
1458 workspaces, or desktops, all frames on other workspaces may appear to
1459 Emacs to be iconified.) If the frame is invisible, it doesn't show on
1460 the screen, not even as an icon.
1462 Visibility is meaningless for terminal frames, since only the selected
1463 one is actually displayed in any case.
1465 @deffn Command make-frame-visible &optional frame
1466 This function makes frame @var{frame} visible. If you omit
1467 @var{frame}, it makes the selected frame visible. This does not raise
1468 the frame, but you can do that with @code{raise-frame} if you wish
1469 (@pxref{Raising and Lowering}).
1472 @deffn Command make-frame-invisible &optional frame force
1473 This function makes frame @var{frame} invisible. If you omit
1474 @var{frame}, it makes the selected frame invisible.
1476 Unless @var{force} is non-@code{nil}, this function refuses to make
1477 @var{frame} invisible if all other frames are invisible..
1480 @deffn Command iconify-frame &optional frame
1481 This function iconifies frame @var{frame}. If you omit @var{frame}, it
1482 iconifies the selected frame.
1485 @defun frame-visible-p frame
1486 This returns the visibility status of frame @var{frame}. The value is
1487 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
1488 @code{icon} if it is iconified.
1490 On a text-only terminal, all frames are considered visible, whether
1491 they are currently being displayed or not, and this function returns
1492 @code{t} for all frames.
1495 The visibility status of a frame is also available as a frame
1496 parameter. You can read or change it as such. @xref{Management
1499 The user can iconify and deiconify frames with the window manager.
1500 This happens below the level at which Emacs can exert any control, but
1501 Emacs does provide events that you can use to keep track of such
1502 changes. @xref{Misc Events}.
1504 @node Raising and Lowering
1505 @section Raising and Lowering Frames
1507 Most window systems use a desktop metaphor. Part of this metaphor is
1508 the idea that windows are stacked in a notional third dimension
1509 perpendicular to the screen surface, and thus ordered from ``highest''
1510 to ``lowest.'' Where two windows overlap, the one higher up covers
1511 the one underneath. Even a window at the bottom of the stack can be
1512 seen if no other window overlaps it.
1514 @c @cindex raising a frame redundant with raise-frame
1515 @cindex lowering a frame
1516 A window's place in this ordering is not fixed; in fact, users tend
1517 to change the order frequently. @dfn{Raising} a window means moving
1518 it ``up,'' to the top of the stack. @dfn{Lowering} a window means
1519 moving it to the bottom of the stack. This motion is in the notional
1520 third dimension only, and does not change the position of the window
1523 With Emacs, frames constitute the windows in the metaphor sketched
1524 above. You can raise and lower frames using these functions:
1526 @deffn Command raise-frame &optional frame
1527 This function raises frame @var{frame} (default, the selected frame).
1528 If @var{frame} is invisible or iconified, this makes it visible.
1531 @deffn Command lower-frame &optional frame
1532 This function lowers frame @var{frame} (default, the selected frame).
1535 @defopt minibuffer-auto-raise
1536 If this is non-@code{nil}, activation of the minibuffer raises the frame
1537 that the minibuffer window is in.
1540 You can also enable auto-raise (raising automatically when a frame is
1541 selected) or auto-lower (lowering automatically when it is deselected)
1542 for any frame using frame parameters. @xref{Management Parameters}.
1544 @node Frame Configurations
1545 @section Frame Configurations
1546 @cindex frame configuration
1548 A @dfn{frame configuration} records the current arrangement of frames,
1549 all their properties, and the window configuration of each one.
1550 (@xref{Window Configurations}.)
1552 @defun current-frame-configuration
1553 This function returns a frame configuration list that describes
1554 the current arrangement of frames and their contents.
1557 @defun set-frame-configuration configuration &optional nodelete
1558 This function restores the state of frames described in
1559 @var{configuration}. However, this function does not restore deleted
1562 Ordinarily, this function deletes all existing frames not listed in
1563 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1564 unwanted frames are iconified instead.
1567 @node Mouse Tracking
1568 @section Mouse Tracking
1569 @cindex mouse tracking
1570 @c @cindex tracking the mouse Duplicates track-mouse
1572 Sometimes it is useful to @dfn{track} the mouse, which means to display
1573 something to indicate where the mouse is and move the indicator as the
1574 mouse moves. For efficient mouse tracking, you need a way to wait until
1575 the mouse actually moves.
1577 The convenient way to track the mouse is to ask for events to represent
1578 mouse motion. Then you can wait for motion by waiting for an event. In
1579 addition, you can easily handle any other sorts of events that may
1580 occur. That is useful, because normally you don't want to track the
1581 mouse forever---only until some other event, such as the release of a
1584 @defspec track-mouse body@dots{}
1585 This special form executes @var{body}, with generation of mouse motion
1586 events enabled. Typically, @var{body} would use @code{read-event} to
1587 read the motion events and modify the display accordingly. @xref{Motion
1588 Events}, for the format of mouse motion events.
1590 The value of @code{track-mouse} is that of the last form in @var{body}.
1591 You should design @var{body} to return when it sees the up-event that
1592 indicates the release of the button, or whatever kind of event means
1593 it is time to stop tracking.
1596 The usual purpose of tracking mouse motion is to indicate on the screen
1597 the consequences of pushing or releasing a button at the current
1600 In many cases, you can avoid the need to track the mouse by using
1601 the @code{mouse-face} text property (@pxref{Special Properties}).
1602 That works at a much lower level and runs more smoothly than
1603 Lisp-level mouse tracking.
1606 @c These are not implemented yet.
1608 These functions change the screen appearance instantaneously. The
1609 effect is transient, only until the next ordinary Emacs redisplay. That
1610 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1611 to change the text, and the body of @code{track-mouse} normally reads
1612 the events itself and does not do redisplay.
1614 @defun x-contour-region window beg end
1615 This function draws lines to make a box around the text from @var{beg}
1616 to @var{end}, in window @var{window}.
1619 @defun x-uncontour-region window beg end
1620 This function erases the lines that would make a box around the text
1621 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1622 a contour that you previously made by calling @code{x-contour-region}.
1625 @defun x-draw-rectangle frame left top right bottom
1626 This function draws a hollow rectangle on frame @var{frame} with the
1627 specified edge coordinates, all measured in pixels from the inside top
1628 left corner. It uses the cursor color, the one used for indicating the
1632 @defun x-erase-rectangle frame left top right bottom
1633 This function erases a hollow rectangle on frame @var{frame} with the
1634 specified edge coordinates, all measured in pixels from the inside top
1635 left corner. Erasure means redrawing the text and background that
1636 normally belong in the specified rectangle.
1640 @node Mouse Position
1641 @section Mouse Position
1642 @cindex mouse position
1643 @cindex position of mouse
1645 The functions @code{mouse-position} and @code{set-mouse-position}
1646 give access to the current position of the mouse.
1648 @defun mouse-position
1649 This function returns a description of the position of the mouse. The
1650 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1651 and @var{y} are integers giving the position in characters relative to
1652 the top left corner of the inside of @var{frame}.
1655 @defvar mouse-position-function
1656 If non-@code{nil}, the value of this variable is a function for
1657 @code{mouse-position} to call. @code{mouse-position} calls this
1658 function just before returning, with its normal return value as the
1659 sole argument, and it returns whatever this function returns to it.
1661 This abnormal hook exists for the benefit of packages like
1662 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1665 @defun set-mouse-position frame x y
1666 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1667 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1668 giving the position in characters relative to the top left corner of the
1669 inside of @var{frame}. If @var{frame} is not visible, this function
1670 does nothing. The return value is not significant.
1673 @defun mouse-pixel-position
1674 This function is like @code{mouse-position} except that it returns
1675 coordinates in units of pixels rather than units of characters.
1678 @defun set-mouse-pixel-position frame x y
1679 This function warps the mouse like @code{set-mouse-position} except that
1680 @var{x} and @var{y} are in units of pixels rather than units of
1681 characters. These coordinates are not required to be within the frame.
1683 If @var{frame} is not visible, this function does nothing. The return
1684 value is not significant.
1690 @section Pop-Up Menus
1692 When using a window system, a Lisp program can pop up a menu so that
1693 the user can choose an alternative with the mouse.
1695 @defun x-popup-menu position menu
1696 This function displays a pop-up menu and returns an indication of
1697 what selection the user makes.
1699 The argument @var{position} specifies where on the screen to put the
1700 top left corner of the menu. It can be either a mouse button event
1701 (which says to put the menu where the user actuated the button) or a
1705 ((@var{xoffset} @var{yoffset}) @var{window})
1709 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1710 pixels, counting from the top left corner of @var{window}. @var{window}
1711 may be a window or a frame.
1713 If @var{position} is @code{t}, it means to use the current mouse
1714 position. If @var{position} is @code{nil}, it means to precompute the
1715 key binding equivalents for the keymaps specified in @var{menu},
1716 without actually displaying or popping up the menu.
1718 The argument @var{menu} says what to display in the menu. It can be a
1719 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
1720 return value is the list of events corresponding to the user's choice.
1721 This list has more than one element if the choice occurred in a
1722 submenu. (Note that @code{x-popup-menu} does not actually execute the
1723 command bound to that sequence of events.) On toolkits that support
1724 menu titles, the title is taken from the prompt string of @var{menu}
1725 if @var{menu} is a keymap, or from the prompt string of the first
1726 keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
1729 Alternatively, @var{menu} can have the following form:
1732 (@var{title} @var{pane1} @var{pane2}...)
1736 where each pane is a list of form
1739 (@var{title} @var{item1} @var{item2}...)
1742 Each item should normally be a cons cell @code{(@var{line} . @var{value})},
1743 where @var{line} is a string, and @var{value} is the value to return if
1744 that @var{line} is chosen. An item can also be a string; this makes a
1745 non-selectable line in the menu.
1747 If the user gets rid of the menu without making a valid choice, for
1748 instance by clicking the mouse away from a valid choice or by typing
1749 keyboard input, then this normally results in a quit and
1750 @code{x-popup-menu} does not return. But if @var{position} is a mouse
1751 button event (indicating that the user invoked the menu with the
1752 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1755 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1756 if you could do the job with a prefix key defined with a menu keymap.
1757 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1758 a} can see the individual items in that menu and provide help for them.
1759 If instead you implement the menu by defining a command that calls
1760 @code{x-popup-menu}, the help facilities cannot know what happens inside
1761 that command, so they cannot give any help for the menu's items.
1763 The menu bar mechanism, which lets you switch between submenus by
1764 moving the mouse, cannot look within the definition of a command to see
1765 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1766 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1767 an integrated fashion. This is why all menu bar submenus are
1768 implemented with menu keymaps within the parent menu, and never with
1769 @code{x-popup-menu}. @xref{Menu Bar}.
1771 If you want a menu bar submenu to have contents that vary, you should
1772 still use a menu keymap to implement it. To make the contents vary, add
1773 a hook function to @code{menu-bar-update-hook} to update the contents of
1774 the menu keymap as necessary.
1777 @section Dialog Boxes
1778 @cindex dialog boxes
1780 A dialog box is a variant of a pop-up menu---it looks a little
1781 different, it always appears in the center of a frame, and it has just
1782 one level and one or more buttons. The main use of dialog boxes is
1783 for asking questions that the user can answer with ``yes,'' ``no,''
1784 and a few other alternatives. With a single button, they can also
1785 force the user to acknowledge important information. The functions
1786 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1787 keyboard, when called from commands invoked by mouse clicks.
1789 @defun x-popup-dialog position contents &optional header
1790 This function displays a pop-up dialog box and returns an indication of
1791 what selection the user makes. The argument @var{contents} specifies
1792 the alternatives to offer; it has this format:
1795 (@var{title} (@var{string} . @var{value})@dots{})
1799 which looks like the list that specifies a single pane for
1800 @code{x-popup-menu}.
1802 The return value is @var{value} from the chosen alternative.
1804 As for @code{x-popup-menu}, an element of the list may be just a
1805 string instead of a cons cell @code{(@var{string} . @var{value})}.
1806 That makes a box that cannot be selected.
1808 If @code{nil} appears in the list, it separates the left-hand items from
1809 the right-hand items; items that precede the @code{nil} appear on the
1810 left, and items that follow the @code{nil} appear on the right. If you
1811 don't include a @code{nil} in the list, then approximately half the
1812 items appear on each side.
1814 Dialog boxes always appear in the center of a frame; the argument
1815 @var{position} specifies which frame. The possible values are as in
1816 @code{x-popup-menu}, but the precise coordinates or the individual
1817 window don't matter; only the frame matters.
1819 If @var{header} is non-@code{nil}, the frame title for the box is
1820 @samp{Information}, otherwise it is @samp{Question}. The former is used
1821 for @code{message-box} (@pxref{message-box}).
1823 In some configurations, Emacs cannot display a real dialog box; so
1824 instead it displays the same items in a pop-up menu in the center of the
1827 If the user gets rid of the dialog box without making a valid choice,
1828 for instance using the window manager, then this produces a quit and
1829 @code{x-popup-dialog} does not return.
1833 @section Pointer Shape
1834 @cindex pointer shape
1835 @cindex mouse pointer shape
1837 You can specify the mouse pointer style for particular text or
1838 images using the @code{pointer} text property, and for images with the
1839 @code{:pointer} and @code{:map} image properties. The values you can
1840 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1841 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1842 @code{hourglass}. @code{text} stands for the usual mouse pointer
1843 style used over text.
1845 Over void parts of the window (parts that do not correspond to any
1846 of the buffer contents), the mouse pointer usually uses the
1847 @code{arrow} style, but you can specify a different style (one of
1848 those above) by setting @code{void-text-area-pointer}.
1850 @defvar void-text-area-pointer
1851 This variable specifies the mouse pointer style for void text areas.
1852 These include the areas after the end of a line or below the last line
1853 in the buffer. The default is to use the @code{arrow} (non-text)
1857 When using X, you can specify what the @code{text} pointer style
1858 really looks like by setting the variable @code{x-pointer-shape}.
1860 @defvar x-pointer-shape
1861 This variable specifies the pointer shape to use ordinarily in the
1862 Emacs frame, for the @code{text} pointer style.
1865 @defvar x-sensitive-text-pointer-shape
1866 This variable specifies the pointer shape to use when the mouse
1867 is over mouse-sensitive text.
1870 These variables affect newly created frames. They do not normally
1871 affect existing frames; however, if you set the mouse color of a
1872 frame, that also installs the current value of those two variables.
1873 @xref{Font and Color Parameters}.
1875 The values you can use, to specify either of these pointer shapes, are
1876 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1877 @key{RET} x-pointer @key{RET}} to see a list of them.
1879 @node Window System Selections
1880 @section Window System Selections
1881 @cindex selection (for window systems)
1883 The X server records a set of @dfn{selections} which permit transfer of
1884 data between application programs. The various selections are
1885 distinguished by @dfn{selection types}, represented in Emacs by
1886 symbols. X clients including Emacs can read or set the selection for
1889 @deffn Command x-set-selection type data
1890 This function sets a ``selection'' in the X server. It takes two
1891 arguments: a selection type @var{type}, and the value to assign to it,
1892 @var{data}. If @var{data} is @code{nil}, it means to clear out the
1893 selection. Otherwise, @var{data} may be a string, a symbol, an integer
1894 (or a cons of two integers or list of two integers), an overlay, or a
1895 cons of two markers pointing to the same buffer. An overlay or a pair
1896 of markers stands for text in the overlay or between the markers.
1898 The argument @var{data} may also be a vector of valid non-vector
1901 Each possible @var{type} has its own selection value, which changes
1902 independently. The usual values of @var{type} are @code{PRIMARY},
1903 @code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
1904 names, in accord with X Window System conventions. If @var{type} is
1905 @code{nil}, that stands for @code{PRIMARY}.
1907 This function returns @var{data}.
1910 @defun x-get-selection &optional type data-type
1911 This function accesses selections set up by Emacs or by other X
1912 clients. It takes two optional arguments, @var{type} and
1913 @var{data-type}. The default for @var{type}, the selection type, is
1916 The @var{data-type} argument specifies the form of data conversion to
1917 use, to convert the raw data obtained from another X client into Lisp
1918 data. Meaningful values include @code{TEXT}, @code{STRING},
1919 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1920 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1921 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1922 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
1923 @code{INTEGER}. (These are symbols with upper-case names in accord
1924 with X conventions.) The default for @var{data-type} is
1929 The X server also has a set of eight numbered @dfn{cut buffers} which can
1930 store text or other data being moved between applications. Cut buffers
1931 are considered obsolete, but Emacs supports them for the sake of X
1932 clients that still use them. Cut buffers are numbered from 0 to 7.
1934 @defun x-get-cut-buffer &optional n
1935 This function returns the contents of cut buffer number @var{n}.
1936 If omitted @var{n} defaults to 0.
1939 @defun x-set-cut-buffer string &optional push
1940 @anchor{Definition of x-set-cut-buffer}
1941 This function stores @var{string} into the first cut buffer (cut buffer
1942 0). If @var{push} is @code{nil}, only the first cut buffer is changed.
1943 If @var{push} is non-@code{nil}, that says to move the values down
1944 through the series of cut buffers, much like the way successive kills in
1945 Emacs move down the kill ring. In other words, the previous value of
1946 the first cut buffer moves into the second cut buffer, and the second to
1947 the third, and so on through all eight cut buffers.
1950 @defopt selection-coding-system
1951 This variable specifies the coding system to use when reading and
1952 writing selections or the clipboard. @xref{Coding
1953 Systems}. The default is @code{compound-text-with-extensions}, which
1954 converts to the text representation that X11 normally uses.
1957 @cindex clipboard support (for MS-Windows)
1958 When Emacs runs on MS-Windows, it does not implement X selections in
1959 general, but it does support the clipboard. @code{x-get-selection}
1960 and @code{x-set-selection} on MS-Windows support the text data type
1961 only; if the clipboard holds other types of data, Emacs treats the
1964 @defopt x-select-enable-clipboard
1965 If this is non-@code{nil}, the Emacs yank functions consult the
1966 clipboard before the primary selection, and the kill functions store in
1967 the clipboard as well as the primary selection. Otherwise they do not
1968 access the clipboard at all. The default is @code{nil} on most systems,
1969 but @code{t} on MS-Windows.
1973 @section Drag and Drop
1975 @vindex x-dnd-test-function
1976 @vindex x-dnd-known-types
1977 When a user drags something from another application over Emacs, that other
1978 application expects Emacs to tell it if Emacs can handle the data that is
1979 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
1980 what to reply. The default value is @code{x-dnd-default-test-function}
1981 which accepts drops if the type of the data to be dropped is present in
1982 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
1983 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
1984 on some other criteria.
1986 @vindex x-dnd-types-alist
1987 If you want to change the way Emacs handles drop of different types
1988 or add a new type, customize @code{x-dnd-types-alist}. This requires
1989 detailed knowledge of what types other applications use for drag and
1992 @vindex dnd-protocol-alist
1993 When an URL is dropped on Emacs it may be a file, but it may also be
1994 another URL type (ftp, http, etc.). Emacs first checks
1995 @code{dnd-protocol-alist} to determine what to do with the URL. If
1996 there is no match there and if @code{browse-url-browser-function} is
1997 an alist, Emacs looks for a match there. If no match is found the
1998 text for the URL is inserted. If you want to alter Emacs behavior,
1999 you can customize these variables.
2002 @section Color Names
2005 @cindex specify color
2006 @cindex numerical RGB color specification
2007 A color name is text (usually in a string) that specifies a color.
2008 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2009 are allowed; use @kbd{M-x list-colors-display} to see a list of
2010 defined names. You can also specify colors numerically in forms such
2011 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2012 @var{r} specifies the red level, @var{g} specifies the green level,
2013 and @var{b} specifies the blue level. You can use either one, two,
2014 three, or four hex digits for @var{r}; then you must use the same
2015 number of hex digits for all @var{g} and @var{b} as well, making
2016 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
2017 X Window System for more details about numerical RGB specification of
2020 These functions provide a way to determine which color names are
2021 valid, and what they look like. In some cases, the value depends on the
2022 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2023 meaning of the term ``selected frame.''
2025 To read user input of color names with completion, use
2026 @code{read-color} (@pxref{High-Level Completion, read-color}).
2028 @defun color-defined-p color &optional frame
2029 This function reports whether a color name is meaningful. It returns
2030 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
2031 which frame's display to ask about; if @var{frame} is omitted or
2032 @code{nil}, the selected frame is used.
2034 Note that this does not tell you whether the display you are using
2035 really supports that color. When using X, you can ask for any defined
2036 color on any kind of display, and you will get some result---typically,
2037 the closest it can do. To determine whether a frame can really display
2038 a certain color, use @code{color-supported-p} (see below).
2040 @findex x-color-defined-p
2041 This function used to be called @code{x-color-defined-p},
2042 and that name is still supported as an alias.
2045 @defun defined-colors &optional frame
2046 This function returns a list of the color names that are defined
2047 and supported on frame @var{frame} (default, the selected frame).
2048 If @var{frame} does not support colors, the value is @code{nil}.
2050 @findex x-defined-colors
2051 This function used to be called @code{x-defined-colors},
2052 and that name is still supported as an alias.
2055 @defun color-supported-p color &optional frame background-p
2056 This returns @code{t} if @var{frame} can really display the color
2057 @var{color} (or at least something close to it). If @var{frame} is
2058 omitted or @code{nil}, the question applies to the selected frame.
2060 Some terminals support a different set of colors for foreground and
2061 background. If @var{background-p} is non-@code{nil}, that means you are
2062 asking whether @var{color} can be used as a background; otherwise you
2063 are asking whether it can be used as a foreground.
2065 The argument @var{color} must be a valid color name.
2068 @defun color-gray-p color &optional frame
2069 This returns @code{t} if @var{color} is a shade of gray, as defined on
2070 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
2071 question applies to the selected frame. If @var{color} is not a valid
2072 color name, this function returns @code{nil}.
2075 @defun color-values color &optional frame
2077 This function returns a value that describes what @var{color} should
2078 ideally look like on @var{frame}. If @var{color} is defined, the
2079 value is a list of three integers, which give the amount of red, the
2080 amount of green, and the amount of blue. Each integer ranges in
2081 principle from 0 to 65535, but some displays may not use the full
2082 range. This three-element list is called the @dfn{rgb values} of the
2085 If @var{color} is not defined, the value is @code{nil}.
2088 (color-values "black")
2090 (color-values "white")
2091 @result{} (65280 65280 65280)
2092 (color-values "red")
2093 @result{} (65280 0 0)
2094 (color-values "pink")
2095 @result{} (65280 49152 51968)
2096 (color-values "hungry")
2100 The color values are returned for @var{frame}'s display. If
2101 @var{frame} is omitted or @code{nil}, the information is returned for
2102 the selected frame's display. If the frame cannot display colors, the
2103 value is @code{nil}.
2105 @findex x-color-values
2106 This function used to be called @code{x-color-values},
2107 and that name is still supported as an alias.
2110 @node Text Terminal Colors
2111 @section Text Terminal Colors
2112 @cindex colors on text-only terminals
2114 Text-only terminals usually support only a small number of colors,
2115 and the computer uses small integers to select colors on the terminal.
2116 This means that the computer cannot reliably tell what the selected
2117 color looks like; instead, you have to inform your application which
2118 small integers correspond to which colors. However, Emacs does know
2119 the standard set of colors and will try to use them automatically.
2121 The functions described in this section control how terminal colors
2124 Several of these functions use or return @dfn{rgb values}, described
2125 in @ref{Color Names}.
2127 These functions accept a display (either a frame or the name of a
2128 terminal) as an optional argument. We hope in the future to make
2129 Emacs support different colors on different text-only terminals; then
2130 this argument will specify which terminal to operate on (the default
2131 being the selected frame's terminal; @pxref{Input Focus}). At
2132 present, though, the @var{frame} argument has no effect.
2134 @defun tty-color-define name number &optional rgb frame
2135 This function associates the color name @var{name} with
2136 color number @var{number} on the terminal.
2138 The optional argument @var{rgb}, if specified, is an rgb value, a list
2139 of three numbers that specify what the color actually looks like.
2140 If you do not specify @var{rgb}, then this color cannot be used by
2141 @code{tty-color-approximate} to approximate other colors, because
2142 Emacs will not know what it looks like.
2145 @defun tty-color-clear &optional frame
2146 This function clears the table of defined colors for a text-only terminal.
2149 @defun tty-color-alist &optional frame
2150 This function returns an alist recording the known colors supported by a
2153 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2154 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
2155 name, @var{number} is the number used to specify it to the terminal.
2156 If present, @var{rgb} is a list of three color values (for red, green,
2157 and blue) that says what the color actually looks like.
2160 @defun tty-color-approximate rgb &optional frame
2161 This function finds the closest color, among the known colors
2162 supported for @var{display}, to that described by the rgb value
2163 @var{rgb} (a list of color values). The return value is an element of
2164 @code{tty-color-alist}.
2167 @defun tty-color-translate color &optional frame
2168 This function finds the closest color to @var{color} among the known
2169 colors supported for @var{display} and returns its index (an integer).
2170 If the name @var{color} is not defined, the value is @code{nil}.
2174 @section X Resources
2176 This section describes some of the functions and variables for
2177 querying and using X resources, or their equivalent on your operating
2178 system. @xref{X Resources,, X Resources, emacs, The GNU Emacs
2179 Manual}, for more information about X resources.
2181 @defun x-get-resource attribute class &optional component subclass
2182 The function @code{x-get-resource} retrieves a resource value from the X
2183 Window defaults database.
2185 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2186 This function searches using a key of the form
2187 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2188 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2191 The optional arguments @var{component} and @var{subclass} add to the key
2192 and the class, respectively. You must specify both of them or neither.
2193 If you specify them, the key is
2194 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2195 @samp{Emacs.@var{class}.@var{subclass}}.
2198 @defvar x-resource-class
2199 This variable specifies the application name that @code{x-get-resource}
2200 should look up. The default value is @code{"Emacs"}. You can examine X
2201 resources for application names other than ``Emacs'' by binding this
2202 variable to some other string, around a call to @code{x-get-resource}.
2205 @defvar x-resource-name
2206 This variable specifies the instance name that @code{x-get-resource}
2207 should look up. The default value is the name Emacs was invoked with,
2208 or the value specified with the @samp{-name} or @samp{-rn} switches.
2211 To illustrate some of the above, suppose that you have the line:
2214 xterm.vt100.background: yellow
2218 in your X resources file (whose name is usually @file{~/.Xdefaults}
2219 or @file{~/.Xresources}). Then:
2223 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2224 (x-get-resource "vt100.background" "VT100.Background"))
2228 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2229 (x-get-resource "background" "VT100" "vt100" "Background"))
2234 @defvar inhibit-x-resources
2235 If this variable is non-@code{nil}, Emacs does not look up X
2236 resources, and X resources do not have any effect when creating new
2240 @node Display Feature Testing
2241 @section Display Feature Testing
2242 @cindex display feature testing
2244 The functions in this section describe the basic capabilities of a
2245 particular display. Lisp programs can use them to adapt their behavior
2246 to what the display can do. For example, a program that ordinarily uses
2247 a popup menu could use the minibuffer if popup menus are not supported.
2249 The optional argument @var{display} in these functions specifies which
2250 display to ask the question about. It can be a display name, a frame
2251 (which designates the display that frame is on), or @code{nil} (which
2252 refers to the selected frame's display, @pxref{Input Focus}).
2254 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2255 obtain information about displays.
2257 @defun display-popup-menus-p &optional display
2258 This function returns @code{t} if popup menus are supported on
2259 @var{display}, @code{nil} if not. Support for popup menus requires that
2260 the mouse be available, since the user cannot choose menu items without
2264 @defun display-graphic-p &optional display
2265 This function returns @code{t} if @var{display} is a graphic display
2266 capable of displaying several frames and several different fonts at
2267 once. This is true for displays that use a window system such as X, and
2268 false for text-only terminals.
2271 @defun display-mouse-p &optional display
2272 @cindex mouse, availability
2273 This function returns @code{t} if @var{display} has a mouse available,
2277 @defun display-color-p &optional display
2278 @findex x-display-color-p
2279 This function returns @code{t} if the screen is a color screen.
2280 It used to be called @code{x-display-color-p}, and that name
2281 is still supported as an alias.
2284 @defun display-grayscale-p &optional display
2285 This function returns @code{t} if the screen can display shades of gray.
2286 (All color displays can do this.)
2289 @defun display-supports-face-attributes-p attributes &optional display
2290 @anchor{Display Face Attribute Testing}
2291 This function returns non-@code{nil} if all the face attributes in
2292 @var{attributes} are supported (@pxref{Face Attributes}).
2294 The definition of `supported' is somewhat heuristic, but basically
2295 means that a face containing all the attributes in @var{attributes},
2296 when merged with the default face for display, can be represented in a
2301 different in appearance than the default face, and
2304 `close in spirit' to what the attributes specify, if not exact.
2307 Point (2) implies that a @code{:weight black} attribute will be
2308 satisfied by any display that can display bold, as will
2309 @code{:foreground "yellow"} as long as some yellowish color can be
2310 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2311 the tty display code's automatic substitution of a `dim' face for
2315 @defun display-selections-p &optional display
2316 This function returns @code{t} if @var{display} supports selections.
2317 Windowed displays normally support selections, but they may also be
2318 supported in some other cases.
2321 @defun display-images-p &optional display
2322 This function returns @code{t} if @var{display} can display images.
2323 Windowed displays ought in principle to handle images, but some
2324 systems lack the support for that. On a display that does not support
2325 images, Emacs cannot display a tool bar.
2328 @defun display-screens &optional display
2329 This function returns the number of screens associated with the display.
2332 @defun display-pixel-height &optional display
2333 This function returns the height of the screen in pixels.
2334 On a character terminal, it gives the height in characters.
2336 For graphical terminals, note that on ``multi-monitor'' setups this
2337 refers to the pixel width for all physical monitors associated with
2338 @var{display}. @xref{Multiple Terminals}.
2341 @defun display-pixel-width &optional display
2342 This function returns the width of the screen in pixels.
2343 On a character terminal, it gives the width in characters.
2345 For graphical terminals, note that on ``multi-monitor'' setups this
2346 refers to the pixel width for all physical monitors associated with
2347 @var{display}. @xref{Multiple Terminals}.
2350 @defun display-mm-height &optional display
2351 This function returns the height of the screen in millimeters,
2352 or @code{nil} if Emacs cannot get that information.
2355 @defun display-mm-width &optional display
2356 This function returns the width of the screen in millimeters,
2357 or @code{nil} if Emacs cannot get that information.
2360 @defopt display-mm-dimensions-alist
2361 This variable allows the user to specify the dimensions of graphical
2362 displays returned by @code{display-mm-height} and
2363 @code{display-mm-width} in case the system provides incorrect values.
2366 @defun display-backing-store &optional display
2367 This function returns the backing store capability of the display.
2368 Backing store means recording the pixels of windows (and parts of
2369 windows) that are not exposed, so that when exposed they can be
2370 displayed very quickly.
2372 Values can be the symbols @code{always}, @code{when-mapped}, or
2373 @code{not-useful}. The function can also return @code{nil}
2374 when the question is inapplicable to a certain kind of display.
2377 @defun display-save-under &optional display
2378 This function returns non-@code{nil} if the display supports the
2379 SaveUnder feature. That feature is used by pop-up windows
2380 to save the pixels they obscure, so that they can pop down
2384 @defun display-planes &optional display
2385 This function returns the number of planes the display supports.
2386 This is typically the number of bits per pixel.
2387 For a tty display, it is log to base two of the number of colors supported.
2390 @defun display-visual-class &optional display
2391 This function returns the visual class for the screen. The value is one
2392 of the symbols @code{static-gray}, @code{gray-scale},
2393 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
2394 @code{direct-color}.
2397 @defun display-color-cells &optional display
2398 This function returns the number of color cells the screen supports.
2401 These functions obtain additional information specifically
2404 @defun x-server-version &optional display
2405 This function returns the list of version numbers of the X server
2406 running the display. The value is a list of three integers: the major
2407 and minor version numbers of the X protocol, and the
2408 distributor-specific release number of the X server software itself.
2411 @defun x-server-vendor &optional display
2412 This function returns the ``vendor'' that provided the X server
2413 software (as a string). Really this means whoever distributes the X
2416 When the developers of X labelled software distributors as
2417 ``vendors,'' they showed their false assumption that no system could
2418 ever be developed and distributed noncommercially.
2422 @defvar x-no-window-manager
2423 This variable's value is @code{t} if no X window manager is in use.
2429 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2430 width and height of an X Window frame, measured in pixels.
2435 arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba