2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/frames
7 @node Frames, Positions, Windows, Top
11 In Emacs editing, a @dfn{frame} is a screen object that contains one
12 or more Emacs windows, see @ref{Windows}. It's the kind of object that
13 is called a ``window'' in the terminology of graphical environments; but
14 we can't call it a ``window'' here, because Emacs uses that word in a
15 different way. In Emacs Lisp, a @dfn{frame object} is a Lisp object
16 that represents a frame on the screen. @xref{Frame Type}.
18 A frame initially contains a single main window and/or a minibuffer
19 window; you can subdivide the main window vertically or horizontally
20 into smaller windows. @xref{Splitting Windows}.
22 A @dfn{terminal} is a display device capable of displaying one or
23 more Emacs frames. On GNU and Unix systems, Emacs supports any number
24 of different terminals in one session, and can mix GUI and text-only
25 frames in the same session.
27 Emacs represents each terminal on which it displays frames as a
28 special @dfn{terminal object} data type, see @ref{Terminal Type}.
30 @cindex terminal frame
31 When Emacs runs on a text-only terminal, it starts with one
32 @dfn{terminal frame}. If you create additional frames on the same
33 terminal, Emacs displays one and only one at any given time---on that
34 terminal screen, of course. You can create additional frames, either
35 text-only or GUI, on other terminals from the same Emacs session.
36 (This comes in handy when you connect to the same session from several
37 remote locations.) @xref{Multiple Terminals}.
40 When Emacs communicates directly with a supported window system, such
41 as X, it does not have a terminal frame; instead, it starts with
42 a single @dfn{window frame}, but you can create more, and Emacs can
43 display several such frames at once as is usual for window systems.
46 This predicate returns a non-@code{nil} value if @var{object} is a
47 frame, and @code{nil} otherwise. For a frame, the value indicates which
48 kind of display the frame uses:
52 The frame is displayed in an X window.
54 A terminal frame on a character display.
56 The frame is displayed on MS-Windows 9X/NT.
58 The frame is displayed on an MS-DOS terminal.
62 @defun frame-terminal &optional frame
63 This function returns the terminal object (@pxref{Terminal Type}) that
64 displays @var{frame}. If @var{frame} is @code{nil} or unspecified, it
65 defaults to the selected frame.
68 @defun terminal-live-p object
69 This predicate returns a non-@code{nil} value if @var{object} is a
70 terminal that is alive (i.e.@: was not deleted), and @code{nil}
71 otherwise. For live terminals, the return value indicates what kind
72 of frames are displayed on that terminal; the list of possible values
73 is the same as for @code{framep} above.
77 * Creating Frames:: Creating additional frames.
78 * Multiple Displays:: Creating frames on other displays.
79 * Multiple Terminals:: Displaying on several different devices.
80 * Frame Parameters:: Controlling frame size, position, font, etc.
81 * Terminal Parameters:: Parameters common for all frames on terminal.
82 * Frame Titles:: Automatic updating of frame titles.
83 * Deleting Frames:: Frames last until explicitly deleted.
84 * Finding All Frames:: How to examine all existing frames.
85 * Frames and Windows:: A frame contains windows;
86 display of text always works through windows.
87 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
88 * Input Focus:: Specifying the selected frame.
89 * Visibility of Frames:: Frames may be visible or invisible, or icons.
90 * Raising and Lowering:: Raising a frame makes it hide other windows;
91 lowering it makes the others hide it.
92 * Frame Configurations:: Saving the state of all frames.
93 * Mouse Tracking:: Getting events that say when the mouse moves.
94 * Mouse Position:: Asking where the mouse is, or moving it.
95 * Pop-Up Menus:: Displaying a menu for the user to select from.
96 * Dialog Boxes:: Displaying a box to ask yes or no.
97 * Pointer Shape:: Specifying the shape of the mouse pointer.
98 * Window System Selections:: Transferring text to and from other X clients.
99 * Drag and Drop:: Internals of Drag-and-Drop implementation.
100 * Color Names:: Getting the definitions of color names.
101 * Text Terminal Colors:: Defining colors for text-only terminals.
102 * Resources:: Getting resource values from the server.
103 * Display Feature Testing:: Determining the features of a terminal.
106 @xref{Display}, for information about the related topic of
107 controlling Emacs redisplay.
109 @node Creating Frames
110 @section Creating Frames
112 To create a new frame, call the function @code{make-frame}.
114 @defun make-frame &optional alist
115 This function creates and returns a new frame, displaying the current
116 buffer. If you are using a supported window system, it makes a window
117 frame; otherwise, it makes a terminal frame.
119 The argument is an alist specifying frame parameters. Any parameters
120 not mentioned in @var{alist} default according to the value of the
121 variable @code{default-frame-alist}; parameters not specified even there
122 default from the standard X resources or whatever is used instead on
125 After the frame is created, this function applies to it the
126 parameters, if any, listed in the value of
127 @code{frame-inherited-parameters} (see below) and not present in the
128 argument, taking the values from the frame that was selected when
129 @code{make-frame} was called.
131 The set of possible parameters depends in principle on what kind of
132 window system Emacs uses to display its frames. @xref{Window Frame
133 Parameters}, for documentation of individual parameters you can specify.
135 This function itself does not make the new frame the selected frame.
136 @xref{Input Focus}. The previously selected frame remains selected.
137 However, the window system may select the new frame for its own reasons,
138 for instance if the frame appears under the mouse pointer and your
139 setup is for focus to follow the pointer.
142 @defvar before-make-frame-hook
143 A normal hook run by @code{make-frame} before it actually creates the
147 @defvar after-make-frame-functions
148 An abnormal hook run by @code{make-frame} after it creates the frame.
149 Each function in @code{after-make-frame-functions} receives one argument, the
153 @defvar frame-inherited-parameters
154 This variable specifies the list of frame parameters that a newly
155 created frame inherits from the currently selected frame. For each
156 parameter (a symbol) that is an element in the list and is not present
157 in the argument to @code{make-frame}, the function sets the value of
158 that parameter in the created frame to its value in the selected
162 @node Multiple Displays
163 @section Multiple Displays
164 @cindex multiple X displays
165 @cindex displays, multiple
167 A single Emacs can talk to more than one X display.
168 Initially, Emacs uses just one display---the one chosen with the
169 @code{DISPLAY} environment variable or with the @samp{--display} option
170 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
171 another display, use the command @code{make-frame-on-display} or specify
172 the @code{display} frame parameter when you create the frame.
174 Emacs treats each X server as a separate terminal, giving each one its
175 own selected frame and its own minibuffer windows. However, only one of
176 those frames is ``@emph{the} selected frame'' at any given moment, see
179 A few Lisp variables are @dfn{terminal-local}; that is, they have a
180 separate binding for each terminal. The binding in effect at any time
181 is the one for the terminal that the currently selected frame belongs
182 to. These variables include @code{default-minibuffer-frame},
183 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
184 @code{system-key-alist}. They are always terminal-local, and can never
185 be buffer-local (@pxref{Buffer-Local Variables}).
187 A single X server can handle more than one screen. A display name
188 @samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
189 part specifies the screen number for a given server. When you use two
190 screens belonging to one server, Emacs knows by the similarity in their
191 names that they share a single keyboard, and it treats them as a single
194 Note that some graphical terminals can output to more than a one
195 monitor (or other output device) at the same time. On these
196 ``multi-monitor'' setups, a single @var{display} value controls the
197 output to all the physical monitors. In this situation, there is
198 currently no platform-independent way for Emacs to distinguish between
199 the different physical monitors.
201 @deffn Command make-frame-on-display display &optional parameters
202 This creates and returns a new frame on display @var{display}, taking
203 the other frame parameters from @var{parameters}. Aside from the
204 @var{display} argument, it is like @code{make-frame} (@pxref{Creating
208 @defun x-display-list
209 This returns a list that indicates which X displays Emacs has a
210 connection to. The elements of the list are strings, and each one is
214 @defun x-open-connection display &optional xrm-string must-succeed
215 This function opens a connection to the X display @var{display}. It
216 does not create a frame on that display, but it permits you to check
217 that communication can be established with that display.
219 The optional argument @var{xrm-string}, if not @code{nil}, is a
220 string of resource names and values, in the same format used in the
221 @file{.Xresources} file. The values you specify override the resource
222 values recorded in the X server itself; they apply to all Emacs frames
223 created on this display. Here's an example of what this string might
227 "*BorderWidth: 3\n*InternalBorder: 2\n"
230 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
232 If @var{must-succeed} is non-@code{nil}, failure to open the connection
233 terminates Emacs. Otherwise, it is an ordinary Lisp error.
236 @defun x-close-connection display
237 This function closes the connection to display @var{display}. Before
238 you can do this, you must first delete all the frames that were open on
239 that display (@pxref{Deleting Frames}).
242 @node Multiple Terminals
243 @section Multiple Terminals
244 @cindex multiple terminals
247 Emacs represents each terminal on which it displays frames as a
248 special @dfn{terminal object} data type, see @ref{Terminal Type}. The
249 terminal object has the following attributes:
253 The name of the device used by the terminal (e.g., @file{/dev/tty}).
256 The terminal and keyboard coding systems (@pxref{Terminal I/O
257 Encoding}) used on the terminal.
260 The kind of frames (@pxref{Frames}) the terminal is displaying.
263 A list of the terminal parameters (@pxref{Terminal Parameters}).
266 There's no primitive for creating terminal objects; Emacs creates
267 them as needed when you call one of the primitives, such as
268 @code{make-frame-on-tty} (@pxref{Multiple Displays}), that start
269 displaying on a new terminal.
272 This function return the list of all the terminal objects used by
273 Emacs to display frames in this session.
276 @defun delete-terminal &optional terminal force
277 This function deletes all frames on @var{terminal} and frees the
278 resources used by it. @var{terminal} can be a terminal object, a
279 frame (meaning that frame's terminal), or @code{nil} (meaning the
280 selected frame's terminal). Normally, the function signals an error
281 if you attempt to delete the sole active terminal, but if @var{force}
282 is non-@code{nil}, you are allowed to do so. This function runs the
283 hook @code{delete-terminal-functions}, passing each function a single
284 argument, @var{terminal}.
287 @defun terminal-name &optional terminal
288 This function returns the file name of the device used by
289 @var{terminal}. If @var{terminal} is omitted or @code{nil}, it
290 defaults to the selected frame's terminal. @var{terminal} can also be
291 a frame, meaning that frame's terminal.
294 @defun get-device-terminal device
295 This function is in a sense the opposite of @code{terminal-name}: it
296 returns a terminal whose device name is given by @var{device}. If
297 @var{device} is a string, it can be either the file name of a terminal
298 device or the name of an X display of the form
299 @samp{@var{host}:@var{server}.@var{screen}} (@pxref{Multiple
300 Displays}). If @var{device} is a frame, this function returns that
301 frame's terminal; @code{nil} means the selected frame. Finally, if
302 @var{device} is a terminal object that represents a live terminal,
303 that terminal is returned. The function signals an error if its
304 argument is none of the above.
307 @node Frame Parameters
308 @section Frame Parameters
309 @cindex frame parameters
311 A frame has many parameters that control its appearance and behavior.
312 Just what parameters a frame has depends on what display mechanism it
315 Frame parameters exist mostly for the sake of window systems. A
316 terminal frame has a few parameters, mostly for compatibility's sake;
317 only the @code{height}, @code{width}, @code{name}, @code{title},
318 @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
319 parameters do something special. If the terminal supports colors, the
320 parameters @code{foreground-color}, @code{background-color},
321 @code{background-mode} and @code{display-type} are also meaningful.
322 If the terminal supports frame transparency, the parameter
323 @code{alpha} is also meaningful.
325 You can use frame parameters to define frame-local bindings for
326 variables. @xref{Frame-Local Variables}.
329 * Parameter Access:: How to change a frame's parameters.
330 * Initial Parameters:: Specifying frame parameters when you make a frame.
331 * Window Frame Parameters:: List of frame parameters for window systems.
332 * Size and Position:: Changing the size and position of a frame.
333 * Geometry:: Parsing geometry specifications.
336 @node Parameter Access
337 @subsection Access to Frame Parameters
339 These functions let you read and change the parameter values of a
342 @defun frame-parameter frame parameter
343 This function returns the value of the parameter @var{parameter} (a
344 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
345 selected frame's parameter. If @var{frame} has no setting for
346 @var{parameter}, this function returns @code{nil}.
349 @defun frame-parameters &optional frame
350 The function @code{frame-parameters} returns an alist listing all the
351 parameters of @var{frame} and their values. If @var{frame} is
352 @code{nil} or omitted, this returns the selected frame's parameters
355 @defun modify-frame-parameters frame alist
356 This function alters the parameters of frame @var{frame} based on the
357 elements of @var{alist}. Each element of @var{alist} has the form
358 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
359 parameter. If you don't mention a parameter in @var{alist}, its value
360 doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
363 You can use this function to define frame-local bindings for
364 variables, see @ref{Frame-Local Variables}.
367 @defun set-frame-parameter frame parm value
368 This function sets the frame parameter @var{parm} to the specified
369 @var{value}. If @var{frame} is @code{nil}, it defaults to the
373 @defun modify-all-frames-parameters alist
374 This function alters the frame parameters of all existing frames
375 according to @var{alist}, then modifies @code{default-frame-alist}
376 (and, if necessary, @code{initial-frame-alist}) to apply the same
377 parameter values to frames that will be created henceforth.
380 @node Initial Parameters
381 @subsection Initial Frame Parameters
383 You can specify the parameters for the initial startup frame
384 by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
386 @defvar initial-frame-alist
387 This variable's value is an alist of parameter values used when creating
388 the initial window frame. You can set this variable to specify the
389 appearance of the initial frame without altering subsequent frames.
390 Each element has the form:
393 (@var{parameter} . @var{value})
396 Emacs creates the initial frame before it reads your init
397 file. After reading that file, Emacs checks @code{initial-frame-alist},
398 and applies the parameter settings in the altered value to the already
399 created initial frame.
401 If these settings affect the frame geometry and appearance, you'll see
402 the frame appear with the wrong ones and then change to the specified
403 ones. If that bothers you, you can specify the same geometry and
404 appearance with X resources; those do take effect before the frame is
405 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
407 X resource settings typically apply to all frames. If you want to
408 specify some X resources solely for the sake of the initial frame, and
409 you don't want them to apply to subsequent frames, here's how to achieve
410 this. Specify parameters in @code{default-frame-alist} to override the
411 X resources for subsequent frames; then, to prevent these from affecting
412 the initial frame, specify the same parameters in
413 @code{initial-frame-alist} with values that match the X resources.
416 If these parameters specify a separate minibuffer-only frame with
417 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
420 @defvar minibuffer-frame-alist
421 This variable's value is an alist of parameter values used when creating
422 an initial minibuffer-only frame---if such a frame is needed, according
423 to the parameters for the main initial frame.
426 @defvar default-frame-alist
427 This is an alist specifying default values of frame parameters for all
428 Emacs frames---the first frame, and subsequent frames. When using the X
429 Window System, you can get the same results by means of X resources
432 Setting this variable does not affect existing frames.
435 Functions that display a buffer in a separate frame can override the
436 default parameters by supplying their own parameters. @xref{Definition
437 of special-display-frame-alist}.
439 If you use options that specify window appearance when you invoke Emacs,
440 they take effect by adding elements to @code{default-frame-alist}. One
441 exception is @samp{-geometry}, which adds the specified position to
442 @code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command
443 Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
445 @node Window Frame Parameters
446 @subsection Window Frame Parameters
448 Just what parameters a frame has depends on what display mechanism
449 it uses. This section describes the parameters that have special
450 meanings on some or all kinds of terminals. Of these, @code{name},
451 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
452 @code{buffer-predicate} provide meaningful information in terminal
453 frames, and @code{tty-color-mode} is meaningful @emph{only} in
457 * Basic Parameters:: Parameters that are fundamental.
458 * Position Parameters:: The position of the frame on the screen.
459 * Size Parameters:: Frame's size.
460 * Layout Parameters:: Size of parts of the frame, and
461 enabling or disabling some parts.
462 * Buffer Parameters:: Which buffers have been or should be shown.
463 * Management Parameters:: Communicating with the window manager.
464 * Cursor Parameters:: Controlling the cursor appearance.
465 * Color Parameters:: Colors of various parts of the frame.
468 @node Basic Parameters
469 @subsubsection Basic Parameters
471 These frame parameters give the most basic information about the
472 frame. @code{title} and @code{name} are meaningful on all terminals.
476 The display on which to open this frame. It should be a string of the
477 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
478 @code{DISPLAY} environment variable.
481 This parameter describes the range of possible colors that can be used
482 in this frame. Its value is @code{color}, @code{grayscale} or
486 If a frame has a non-@code{nil} title, it appears in the window
487 system's title bar at the top of the frame, and also in the mode line
488 of windows in that frame if @code{mode-line-frame-identification} uses
489 @samp{%F} (@pxref{%-Constructs}). This is normally the case when
490 Emacs is not using a window system, and can only display one frame at
491 a time. @xref{Frame Titles}.
494 The name of the frame. The frame name serves as a default for the frame
495 title, if the @code{title} parameter is unspecified or @code{nil}. If
496 you don't specify a name, Emacs sets the frame name automatically
497 (@pxref{Frame Titles}).
499 If you specify the frame name explicitly when you create the frame, the
500 name is also used (instead of the name of the Emacs executable) when
501 looking up X resources for the frame.
504 @node Position Parameters
505 @subsubsection Position Parameters
507 Position parameters' values are normally measured in pixels, but on
508 text-only terminals they count characters or lines instead.
512 The position, in pixels, of the left (or right) edge of the frame with
513 respect to the left (or right) edge of the screen. The value may be:
517 A positive integer relates the left edge of the frame to the left edge
518 of the screen. A negative integer relates the right frame edge to the
521 @item @code{(+ @var{pos})}
522 This specifies the position of the left frame edge relative to the left
523 screen edge. The integer @var{pos} may be positive or negative; a
524 negative value specifies a position outside the screen.
526 @item @code{(- @var{pos})}
527 This specifies the position of the right frame edge relative to the right
528 screen edge. The integer @var{pos} may be positive or negative; a
529 negative value specifies a position outside the screen.
532 Some window managers ignore program-specified positions. If you want to
533 be sure the position you specify is not ignored, specify a
534 non-@code{nil} value for the @code{user-position} parameter as well.
537 The screen position of the top (or bottom) edge, in pixels, with respect
538 to the top (or bottom) edge of the screen. It works just like
539 @code{left}, except vertically instead of horizontally.
542 The screen position of the left edge @emph{of the frame's icon}, in
543 pixels, counting from the left edge of the screen. This takes effect if
544 and when the frame is iconified.
546 If you specify a value for this parameter, then you must also specify
547 a value for @code{icon-top} and vice versa. The window manager may
548 ignore these two parameters.
551 The screen position of the top edge @emph{of the frame's icon}, in
552 pixels, counting from the top edge of the screen. This takes effect if
553 and when the frame is iconified.
556 When you create a frame and specify its screen position with the
557 @code{left} and @code{top} parameters, use this parameter to say whether
558 the specified position was user-specified (explicitly requested in some
559 way by a human user) or merely program-specified (chosen by a program).
560 A non-@code{nil} value says the position was user-specified.
562 Window managers generally heed user-specified positions, and some heed
563 program-specified positions too. But many ignore program-specified
564 positions, placing the window in a default fashion or letting the user
565 place it with the mouse. Some window managers, including @code{twm},
566 let the user specify whether to obey program-specified positions or
569 When you call @code{make-frame}, you should specify a non-@code{nil}
570 value for this parameter if the values of the @code{left} and @code{top}
571 parameters represent the user's stated preference; otherwise, use
575 @node Size Parameters
576 @subsubsection Size Parameters
578 Size parameters' values are normally measured in pixels, but on
579 text-only terminals they count characters or lines instead.
583 The height of the frame contents, in characters. (To get the height in
584 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
587 The width of the frame contents, in characters. (To get the width in
588 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
591 This does for the size parameters @code{height} and @code{width} what
592 the @code{user-position} parameter (see above) does for the position
593 parameters @code{top} and @code{left}.
596 Specify that width, height or both shall be set to the size of the screen.
597 The value @code{fullwidth} specifies that width shall be the size of the
598 screen. The value @code{fullheight} specifies that height shall be the
599 size of the screen. The value @code{fullboth} specifies that both the
600 width and the height shall be set to the size of the screen.
603 @node Layout Parameters
604 @subsubsection Layout Parameters
606 These frame parameters enable or disable various parts of the
607 frame, or control their sizes.
611 The width in pixels of the frame's border.
613 @item internal-border-width
614 The distance in pixels between text (or fringe) and the frame's border.
616 @item vertical-scroll-bars
617 Whether the frame has scroll bars for vertical scrolling, and which side
618 of the frame they should be on. The possible values are @code{left},
619 @code{right}, and @code{nil} for no scroll bars.
622 @item horizontal-scroll-bars
623 Whether the frame has scroll bars for horizontal scrolling
624 (non-@code{nil} means yes). Horizontal scroll bars are not currently
628 @item scroll-bar-width
629 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
630 use the default width.
634 The default width of the left and right fringes of windows in this
635 frame (@pxref{Fringes}). If either of these is zero, that effectively
636 removes the corresponding fringe. A value of @code{nil} stands for
637 the standard fringe width, which is the width needed to display the
640 The combined fringe widths must add up to an integral number of
641 columns, so the actual default fringe widths for the frame may be
642 larger than the specified values. The extra width needed to reach an
643 acceptable total is distributed evenly between the left and right
644 fringe. However, you can force one fringe or the other to a precise
645 width by specifying that width as a negative integer. If both widths are
646 negative, only the left fringe gets the specified width.
649 The number of lines to allocate at the top of the frame for a menu
650 bar. The default is 1. A value of @code{nil} means don't display a
651 menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one
652 menu bar line; they treat larger values as 1.)
655 The number of lines to use for the tool bar. A value of @code{nil}
656 means don't display a tool bar. (GTK allows at most one tool bar line;
657 it treats larger values as 1.)
660 Additional space to leave below each text line, in pixels (a positive
661 integer). @xref{Line Height}, for more information.
664 @node Buffer Parameters
665 @subsubsection Buffer Parameters
667 These frame parameters, meaningful on all kinds of terminals, deal
668 with which buffers have been, or should, be displayed in the frame.
672 Whether this frame has its own minibuffer. The value @code{t} means
673 yes, @code{nil} means no, @code{only} means this frame is just a
674 minibuffer. If the value is a minibuffer window (in some other frame),
675 the new frame uses that minibuffer.
677 @item buffer-predicate
678 The buffer-predicate function for this frame. The function
679 @code{other-buffer} uses this predicate (from the selected frame) to
680 decide which buffers it should consider, if the predicate is not
681 @code{nil}. It calls the predicate with one argument, a buffer, once for
682 each buffer; if the predicate returns a non-@code{nil} value, it
683 considers that buffer.
686 A list of buffers that have been selected in this frame,
687 ordered most-recently-selected first.
690 If non-@code{nil}, this frame's window is never split automatically.
693 @node Management Parameters
694 @subsubsection Window Management Parameters
695 @cindex window manager, and frame parameters
697 These frame parameters, meaningful only on window system displays,
698 interact with the window manager.
702 The state of visibility of the frame. There are three possibilities:
703 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
704 iconified. @xref{Visibility of Frames}.
707 Whether selecting the frame raises it (non-@code{nil} means yes).
710 Whether deselecting the frame lowers it (non-@code{nil} means yes).
713 The type of icon to use for this frame when it is iconified. If the
714 value is a string, that specifies a file containing a bitmap to use.
715 Any other non-@code{nil} value specifies the default bitmap icon (a
716 picture of a gnu); @code{nil} specifies a text icon.
719 The name to use in the icon for this frame, when and if the icon
720 appears. If this is @code{nil}, the frame's title is used.
723 The number of the window-system window used by the frame
724 to contain the actual Emacs windows.
726 @item outer-window-id
727 The number of the outermost window-system window used for the whole frame.
730 If non-@code{nil}, tell Xt to wait for the window manager to confirm
731 geometry changes. Some window managers, including versions of Fvwm2
732 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
733 prevent hanging with those window managers.
737 @c ??? Not yet working.
738 The X window number of the window that should be the parent of this one.
739 Specifying this lets you create an Emacs window inside some other
740 application's window. (It is not certain this will be implemented; try
741 it and see if it works.)
745 @node Cursor Parameters
746 @subsubsection Cursor Parameters
748 This frame parameter controls the way the cursor looks.
752 How to display the cursor. Legitimate values are:
756 Display a filled box. (This is the default.)
758 Display a hollow box.
760 Don't display a cursor.
762 Display a vertical bar between characters.
763 @item (bar . @var{width})
764 Display a vertical bar @var{width} pixels wide between characters.
766 Display a horizontal bar.
767 @item (hbar . @var{height})
768 Display a horizontal bar @var{height} pixels high.
773 The buffer-local variable @code{cursor-type} overrides the value of
774 the @code{cursor-type} frame parameter, but if it is @code{t}, that
775 means to use the cursor specified for the frame.
777 @defvar blink-cursor-alist
778 This variable specifies how to blink the cursor. Each element has the
779 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
780 type equals @var{on-state} (comparing using @code{equal}), the
781 corresponding @var{off-state} specifies what the cursor looks like
782 when it blinks ``off.'' Both @var{on-state} and @var{off-state}
783 should be suitable values for the @code{cursor-type} frame parameter.
785 There are various defaults for how to blink each type of cursor, if
786 the type is not mentioned as an @var{on-state} here. Changes in this
787 variable do not take effect immediately, only when you specify the
788 @code{cursor-type} frame parameter.
791 @defvar cursor-in-non-selected-windows
792 This variable controls how the cursor looks in a window that is not
793 selected. It supports the same values as the @code{cursor-type} frame
794 parameter; also, @code{nil} means don't display a cursor in
795 nonselected windows, and @code{t} (the default) means use a standard
796 modificatoin of the usual cursor type (solid box becomes hollow box,
797 and bar becomes a narrower bar).
800 @node Color Parameters
801 @subsubsection Color Parameters
803 These frame parameters control the use of colors.
806 @item background-mode
807 This parameter is either @code{dark} or @code{light}, according
808 to whether the background color is a light one or a dark one.
811 @cindex standard colors for character terminals
812 This parameter overrides the terminal's color support as given by the
813 system's terminal capabilities database in that this parameter's value
814 specifies the color mode to use in terminal frames. The value can be
815 either a symbol or a number. A number specifies the number of colors
816 to use (and, indirectly, what commands to issue to produce each
817 color). For example, @code{(tty-color-mode . 8)} specifies use of the
818 ANSI escape sequences for 8 standard text colors. A value of -1 turns
821 If the parameter's value is a symbol, it specifies a number through
822 the value of @code{tty-color-mode-alist}, and the associated number is
826 @cindex gamma correction
827 If this is a number, Emacs performs ``gamma correction'' which adjusts
828 the brightness of all colors. The value should be the screen gamma of
829 your display, a floating point number.
831 Usual PC monitors have a screen gamma of 2.2, so color values in
832 Emacs, and in X windows generally, are calibrated to display properly
833 on a monitor with that gamma value. If you specify 2.2 for
834 @code{screen-gamma}, that means no correction is needed. Other values
835 request correction, designed to make the corrected colors appear on
836 your screen the way they would have appeared without correction on an
837 ordinary monitor with a gamma value of 2.2.
839 If your monitor displays colors too light, you should specify a
840 @code{screen-gamma} value smaller than 2.2. This requests correction
841 that makes colors darker. A screen gamma value of 1.5 may give good
842 results for LCD color displays.
845 @cindex opacity, frame
846 @cindex transparency, frame
847 @vindex frame-alpha-lower-limit
848 This parameter specifies the opacity of the frame, on graphical
849 displays that support variable opacity. It should be an integer
850 between 0 and 100, where 0 means completely transparent and 100 means
851 completely opaque. It can also have a @code{nil} value, which tells
852 Emacs not to set the frame opacity (leaving it to the window manager).
854 To prevent the frame from disappearing completely from view, the
855 variable @var{frame-alpha-lower-limit} defines a lower opacity limit.
856 If the value of the frame parameter is less than the value of this
857 variable, Emacs uses the latter. By default,
858 @var{frame-alpha-lower-limit} is 20.
860 The @code{alpha} frame parameter can also be a cons cell
861 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
862 opacity of the frame when it is selected, and @samp{inactive} is the
863 opactity when it is not selected.
866 The following frame parameters are semi-obsolete in that they are
867 automatically equivalent to particular face attributes of particular
868 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
872 The name of the font for displaying text in the frame. This is a
873 string, either a valid font name for your system or the name of an Emacs
874 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
875 attribute of the @code{default} face.
877 @item foreground-color
878 The color to use for the image of a character. It is equivalent to
879 the @code{:foreground} attribute of the @code{default} face.
881 @item background-color
882 The color to use for the background of characters. It is equivalent to
883 the @code{:background} attribute of the @code{default} face.
886 The color for the mouse pointer. It is equivalent to the @code{:background}
887 attribute of the @code{mouse} face.
890 The color for the cursor that shows point. It is equivalent to the
891 @code{:background} attribute of the @code{cursor} face.
894 The color for the border of the frame. It is equivalent to the
895 @code{:background} attribute of the @code{border} face.
897 @item scroll-bar-foreground
898 If non-@code{nil}, the color for the foreground of scroll bars. It is
899 equivalent to the @code{:foreground} attribute of the
900 @code{scroll-bar} face.
902 @item scroll-bar-background
903 If non-@code{nil}, the color for the background of scroll bars. It is
904 equivalent to the @code{:background} attribute of the
905 @code{scroll-bar} face.
908 @node Size and Position
909 @subsection Frame Size And Position
910 @cindex size of frame
915 You can read or change the size and position of a frame using the
916 frame parameters @code{left}, @code{top}, @code{height}, and
917 @code{width}. Whatever geometry parameters you don't specify are chosen
918 by the window manager in its usual fashion.
920 Here are some special features for working with sizes and positions.
921 (For the precise meaning of ``selected frame'' used by these functions,
922 see @ref{Input Focus}.)
924 @defun set-frame-position frame left top
925 This function sets the position of the top left corner of @var{frame} to
926 @var{left} and @var{top}. These arguments are measured in pixels, and
927 normally count from the top left corner of the screen.
929 Negative parameter values position the bottom edge of the window up from
930 the bottom edge of the screen, or the right window edge to the left of
931 the right edge of the screen. It would probably be better if the values
932 were always counted from the left and top, so that negative arguments
933 would position the frame partly off the top or left edge of the screen,
934 but it seems inadvisable to change that now.
937 @defun frame-height &optional frame
938 @defunx frame-width &optional frame
939 These functions return the height and width of @var{frame}, measured in
940 lines and columns. If you don't supply @var{frame}, they use the
946 These functions are old aliases for @code{frame-height} and
947 @code{frame-width}. When you are using a non-window terminal, the size
948 of the frame is normally the same as the size of the terminal screen.
951 @defun frame-pixel-height &optional frame
952 @defunx frame-pixel-width &optional frame
953 These functions return the height and width of the main display area
954 of @var{frame}, measured in pixels. If you don't supply @var{frame},
955 they use the selected frame.
957 These values include the internal borders, and windows' scroll bars
958 and fringes (which belong to individual windows, not to the frame
959 itself), but do not include menu bars or tool bars (except when using
960 X without an X toolkit).
963 @defun frame-char-height &optional frame
964 @defunx frame-char-width &optional frame
965 These functions return the height and width of a character in
966 @var{frame}, measured in pixels. The values depend on the choice of
967 font. If you don't supply @var{frame}, these functions use the selected
971 @defun set-frame-size frame cols rows
972 This function sets the size of @var{frame}, measured in characters;
973 @var{cols} and @var{rows} specify the new width and height.
975 To set the size based on values measured in pixels, use
976 @code{frame-char-height} and @code{frame-char-width} to convert
977 them to units of characters.
980 @defun set-frame-height frame lines &optional pretend
981 This function resizes @var{frame} to a height of @var{lines} lines. The
982 sizes of existing windows in @var{frame} are altered proportionally to
985 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
986 lines of output in @var{frame}, but does not change its value for the
987 actual height of the frame. This is only useful for a terminal frame.
988 Using a smaller height than the terminal actually implements may be
989 useful to reproduce behavior observed on a smaller screen, or if the
990 terminal malfunctions when using its whole screen. Setting the frame
991 height ``for real'' does not always work, because knowing the correct
992 actual size may be necessary for correct cursor positioning on a
996 @defun set-frame-width frame width &optional pretend
997 This function sets the width of @var{frame}, measured in characters.
998 The argument @var{pretend} has the same meaning as in
999 @code{set-frame-height}.
1002 @findex set-screen-height
1003 @findex set-screen-width
1004 The older functions @code{set-screen-height} and
1005 @code{set-screen-width} were used to specify the height and width of the
1006 screen, in Emacs versions that did not support multiple frames. They
1007 are semi-obsolete, but still work; they apply to the selected frame.
1010 @subsection Geometry
1012 Here's how to examine the data in an X-style window geometry
1015 @defun x-parse-geometry geom
1016 @cindex geometry specification
1017 The function @code{x-parse-geometry} converts a standard X window
1018 geometry string to an alist that you can use as part of the argument to
1021 The alist describes which parameters were specified in @var{geom}, and
1022 gives the values specified for them. Each element looks like
1023 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
1024 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1026 For the size parameters, the value must be an integer. The position
1027 parameter names @code{left} and @code{top} are not totally accurate,
1028 because some values indicate the position of the right or bottom edges
1029 instead. The @var{value} possibilities for the position parameters are:
1030 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1031 as previously described (@pxref{Position Parameters}).
1036 (x-parse-geometry "35x70+0-0")
1037 @result{} ((height . 70) (width . 35)
1038 (top - 0) (left . 0))
1042 @node Terminal Parameters
1043 @section Terminal Parameters
1044 @cindex terminal parameters
1046 Each terminal has a list of associated parameters. These
1047 @dfn{terminal parameters} are mostly a convenient way of storage for
1048 terminal-local variables, but some terminal parameters have a special
1051 This section describes functions to read and change the parameter values
1052 of a terminal. They all accept as their argument either a terminal or
1053 a frame; the latter means use that frame's terminal. An argument of
1054 @code{nil} means the selected frame's terminal.
1056 @defun terminal-parameters &optional terminal
1057 This function returns an alist listing all the parameters of
1058 @var{terminal} and their values.
1061 @defun terminal-parameter terminal parameter
1062 This function returns the value of the parameter @var{parameter} (a
1063 symbol) of @var{terminal}. If @var{terminal} has no setting for
1064 @var{parameter}, this function returns @code{nil}.
1067 @defun set-terminal-parameter terminal parameter value
1068 This function sets the parameter @var{parm} of @var{terminal} to the
1069 specified @var{value}, and returns the previous value of that
1073 Here's a list of a few terminal parameters that have a special
1077 @item background-mode
1078 The classification of the terminal's background color, either
1079 @code{light} or @code{dark}.
1080 @item normal-erase-is-backspace
1081 Value is either 1 or 0, depending on whether
1082 @code{normal-erase-is-backspace-mode} is turned on or off on this
1083 terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1084 @item terminal-initted
1085 After the terminal is initialized, this is set to the
1086 terminal-specific initialization function.
1090 @section Frame Titles
1093 Every frame has a @code{name} parameter; this serves as the default
1094 for the frame title which window systems typically display at the top of
1095 the frame. You can specify a name explicitly by setting the @code{name}
1098 Normally you don't specify the name explicitly, and Emacs computes the
1099 frame name automatically based on a template stored in the variable
1100 @code{frame-title-format}. Emacs recomputes the name each time the
1101 frame is redisplayed.
1103 @defvar frame-title-format
1104 This variable specifies how to compute a name for a frame when you have
1105 not explicitly specified one. The variable's value is actually a mode
1106 line construct, just like @code{mode-line-format}, except that the
1107 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
1111 @defvar icon-title-format
1112 This variable specifies how to compute the name for an iconified frame,
1113 when you have not explicitly specified the frame title. This title
1114 appears in the icon itself.
1117 @defvar multiple-frames
1118 This variable is set automatically by Emacs. Its value is @code{t} when
1119 there are two or more frames (not counting minibuffer-only frames or
1120 invisible frames). The default value of @code{frame-title-format} uses
1121 @code{multiple-frames} so as to put the buffer name in the frame title
1122 only when there is more than one frame.
1124 The value of this variable is not guaranteed to be accurate except
1125 while processing @code{frame-title-format} or
1126 @code{icon-title-format}.
1129 @node Deleting Frames
1130 @section Deleting Frames
1131 @cindex deleting frames
1133 Frames remain potentially visible until you explicitly @dfn{delete}
1134 them. A deleted frame cannot appear on the screen, but continues to
1135 exist as a Lisp object until there are no references to it.
1137 @deffn Command delete-frame &optional frame force
1138 @vindex delete-frame-functions
1139 This function deletes the frame @var{frame}. Unless @var{frame} is a
1140 tooltip, it first runs the hook @code{delete-frame-functions} (each
1141 function gets one argument, @var{frame}). By default, @var{frame} is
1144 A frame cannot be deleted if its minibuffer is used by other frames.
1145 Normally, you cannot delete a frame if all other frames are invisible,
1146 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1149 @defun frame-live-p frame
1150 The function @code{frame-live-p} returns non-@code{nil} if the frame
1151 @var{frame} has not been deleted. The possible non-@code{nil} return
1152 values are like those of @code{framep}. @xref{Frames}.
1155 Some window managers provide a command to delete a window. These work
1156 by sending a special message to the program that operates the window.
1157 When Emacs gets one of these commands, it generates a
1158 @code{delete-frame} event, whose normal definition is a command that
1159 calls the function @code{delete-frame}. @xref{Misc Events}.
1161 @node Finding All Frames
1162 @section Finding All Frames
1163 @cindex frames, scanning all
1166 The function @code{frame-list} returns a list of all the frames that
1167 have not been deleted. It is analogous to @code{buffer-list} for
1168 buffers, and includes frames on all terminals. The list that you get is
1169 newly created, so modifying the list doesn't have any effect on the
1173 @defun visible-frame-list
1174 This function returns a list of just the currently visible frames.
1175 @xref{Visibility of Frames}. (Terminal frames always count as
1176 ``visible,'' even though only the selected one is actually displayed.)
1179 @defun next-frame &optional frame minibuf
1180 The function @code{next-frame} lets you cycle conveniently through all
1181 the frames on the current display from an arbitrary starting point. It
1182 returns the ``next'' frame after @var{frame} in the cycle. If
1183 @var{frame} is omitted or @code{nil}, it defaults to the selected frame
1184 (@pxref{Input Focus}).
1186 The second argument, @var{minibuf}, says which frames to consider:
1190 Exclude minibuffer-only frames.
1191 @item @code{visible}
1192 Consider all visible frames.
1194 Consider all visible or iconified frames.
1196 Consider only the frames using that particular window as their
1199 Consider all frames.
1203 @defun previous-frame &optional frame minibuf
1204 Like @code{next-frame}, but cycles through all frames in the opposite
1208 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1211 @node Frames and Windows
1212 @section Frames and Windows
1214 Each window is part of one and only one frame; you can get that frame
1215 with @code{window-frame}.
1217 @defun window-frame window
1218 This function returns the frame that @var{window} is on.
1221 All the non-minibuffer windows in a frame are arranged in a cyclic
1222 order. The order runs from the frame's top window, which is at the
1223 upper left corner, down and to the right, until it reaches the window at
1224 the lower right corner (always the minibuffer window, if the frame has
1225 one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
1227 @defun frame-first-window &optional frame
1228 This returns the topmost, leftmost window of frame @var{frame}.
1229 If omitted or @code{nil}, @var{frame} defaults to the selected frame.
1232 At any time, exactly one window on any frame is @dfn{selected within the
1233 frame}. The significance of this designation is that selecting the
1234 frame also selects this window. Conversely, selecting a window for
1235 Emacs with @code{select-window} also makes that window selected within
1236 its frame. @xref{Selecting Windows}.
1238 @defun frame-selected-window &optional frame
1239 This function returns the window on @var{frame} that is selected
1240 within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to
1244 @defun set-frame-selected-window frame window &optional norecord
1245 This sets the selected window of frame @var{frame} to @var{window}.
1246 If @var{frame} is @code{nil}, it operates on the selected frame. If
1247 @var{frame} is the selected frame, this makes @var{window} the
1248 selected window. This function returns @var{window}.
1250 Optional argument @var{norecord} non-@code{nil} means to neither change
1251 the order of recently selected windows nor the buffer list (@pxref{The
1255 Another function that (usually) returns one of the windows in a given
1256 frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
1258 @node Minibuffers and Frames
1259 @section Minibuffers and Frames
1261 Normally, each frame has its own minibuffer window at the bottom, which
1262 is used whenever that frame is selected. If the frame has a minibuffer,
1263 you can get it with @code{minibuffer-window} (@pxref{Definition of
1264 minibuffer-window}).
1266 However, you can also create a frame with no minibuffer. Such a frame
1267 must use the minibuffer window of some other frame. When you create the
1268 frame, you can specify explicitly the minibuffer window to use (in some
1269 other frame). If you don't, then the minibuffer is found in the frame
1270 which is the value of the variable @code{default-minibuffer-frame}. Its
1271 value should be a frame that does have a minibuffer.
1273 If you use a minibuffer-only frame, you might want that frame to raise
1274 when you enter the minibuffer. If so, set the variable
1275 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
1277 @defvar default-minibuffer-frame
1278 This variable specifies the frame to use for the minibuffer window, by
1279 default. It does not affect existing frames. It is always local to
1280 the current terminal and cannot be buffer-local. @xref{Multiple
1285 @section Input Focus
1287 @c @cindex selected frame Duplicates selected-frame
1289 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
1290 window always resides on the selected frame.
1292 When Emacs displays its frames on several terminals (@pxref{Multiple
1293 Displays}), each terminal has its own selected frame. But only one of
1294 these is ``@emph{the} selected frame'': it's the frame that belongs to
1295 the terminal from which the most recent input came. That is, when Emacs
1296 runs a command that came from a certain terminal, the selected frame is
1297 the one of that terminal. Since Emacs runs only a single command at any
1298 given time, it needs to consider only one selected frame at a time; this
1299 frame is what we call @dfn{the selected frame} in this manual. The
1300 display on which the selected frame is shown is the @dfn{selected
1303 @defun selected-frame
1304 This function returns the selected frame.
1307 Some window systems and window managers direct keyboard input to the
1308 window object that the mouse is in; others require explicit clicks or
1309 commands to @dfn{shift the focus} to various window objects. Either
1310 way, Emacs automatically keeps track of which frame has the focus. To
1311 explicitly switch to a different frame from a Lisp function, call
1312 @code{select-frame-set-input-focus}.
1314 Lisp programs can also switch frames ``temporarily'' by calling the
1315 function @code{select-frame}. This does not alter the window system's
1316 concept of focus; rather, it escapes from the window manager's control
1317 until that control is somehow reasserted.
1319 When using a text-only terminal, only one frame can be displayed at a
1320 time on the terminal, so after a call to @code{select-frame}, the next
1321 redisplay actually displays the newly selected frame. This frame
1322 remains selected until a subsequent call to @code{select-frame}. Each
1323 terminal frame has a number which appears in the mode line before the
1324 buffer name (@pxref{Mode Line Variables}).
1326 @defun select-frame-set-input-focus frame
1327 This function selects @var{frame}, raises it (should it happen to be
1328 obscured by other frames) and tries to give it the X server's focus. On
1329 a text-only terminal, the next redisplay displays the new frame on the
1330 entire terminal screen. The return value of this function is not
1334 @c ??? This is not yet implemented properly.
1335 @defun select-frame frame &optional norecord
1336 This function selects frame @var{frame}, temporarily disregarding the
1337 focus of the X server if any. The selection of @var{frame} lasts until
1338 the next time the user does something to select a different frame, or
1339 until the next time this function is called. (If you are using a
1340 window system, the previously selected frame may be restored as the
1341 selected frame after return to the command loop, because it still may
1342 have the window system's input focus.)
1344 The specified @var{frame} becomes the selected frame, as explained
1345 above, and the terminal that @var{frame} is on becomes the selected
1346 terminal. The window selected within @var{frame} becomes the selected
1347 window. This function returns @var{frame}, or @code{nil} if @var{frame}
1350 Optional argument @var{norecord} non-@code{nil} means to neither change
1351 the order of recently selected windows nor the buffer list. @xref{The
1354 In general, you should never use @code{select-frame} in a way that could
1355 switch to a different terminal without switching back when you're done.
1358 Emacs cooperates with the window system by arranging to select frames as
1359 the server and window manager request. It does so by generating a
1360 special kind of input event, called a @dfn{focus} event, when
1361 appropriate. The command loop handles a focus event by calling
1362 @code{handle-switch-frame}. @xref{Focus Events}.
1364 @deffn Command handle-switch-frame frame
1365 This function handles a focus event by selecting frame @var{frame}.
1367 Focus events normally do their job by invoking this command.
1368 Don't call it for any other reason.
1371 @defun redirect-frame-focus frame &optional focus-frame
1372 This function redirects focus from @var{frame} to @var{focus-frame}.
1373 This means that @var{focus-frame} will receive subsequent keystrokes and
1374 events intended for @var{frame}. After such an event, the value of
1375 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1376 events specifying @var{frame} will instead select @var{focus-frame}.
1378 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1379 redirection for @var{frame}, which therefore once again receives its own
1382 One use of focus redirection is for frames that don't have minibuffers.
1383 These frames use minibuffers on other frames. Activating a minibuffer
1384 on another frame redirects focus to that frame. This puts the focus on
1385 the minibuffer's frame, where it belongs, even though the mouse remains
1386 in the frame that activated the minibuffer.
1388 Selecting a frame can also change focus redirections. Selecting frame
1389 @code{bar}, when @code{foo} had been selected, changes any redirections
1390 pointing to @code{foo} so that they point to @code{bar} instead. This
1391 allows focus redirection to work properly when the user switches from
1392 one frame to another using @code{select-window}.
1394 This means that a frame whose focus is redirected to itself is treated
1395 differently from a frame whose focus is not redirected.
1396 @code{select-frame} affects the former but not the latter.
1398 The redirection lasts until @code{redirect-frame-focus} is called to
1402 @defopt focus-follows-mouse
1403 This option is how you inform Emacs whether the window manager transfers
1404 focus when the user moves the mouse. Non-@code{nil} says that it does.
1405 When this is so, the command @code{other-frame} moves the mouse to a
1406 position consistent with the new selected frame.
1409 @node Visibility of Frames
1410 @section Visibility of Frames
1411 @cindex visible frame
1412 @cindex invisible frame
1413 @cindex iconified frame
1414 @cindex frame visibility
1416 A window frame may be @dfn{visible}, @dfn{invisible}, or
1417 @dfn{iconified}. If it is visible, you can see its contents, unless
1418 other windows cover it. If it is iconified, the frame's contents do
1419 not appear on the screen, but an icon does. (Note: because of the
1420 way in which some window managers implement the concept of multiple
1421 workspaces, or desktops, all frames on other workspaces may appear to
1422 Emacs to be iconified.) If the frame is invisible, it doesn't show on
1423 the screen, not even as an icon.
1425 Visibility is meaningless for terminal frames, since only the selected
1426 one is actually displayed in any case.
1428 @deffn Command make-frame-visible &optional frame
1429 This function makes frame @var{frame} visible. If you omit
1430 @var{frame}, it makes the selected frame visible. This does not raise
1431 the frame, but you can do that with @code{raise-frame} if you wish
1432 (@pxref{Raising and Lowering}).
1435 @deffn Command make-frame-invisible &optional frame force
1436 This function makes frame @var{frame} invisible. If you omit
1437 @var{frame}, it makes the selected frame invisible.
1439 Unless @var{force} is non-@code{nil}, this function refuses to make
1440 @var{frame} invisible if all other frames are invisible..
1443 @deffn Command iconify-frame &optional frame
1444 This function iconifies frame @var{frame}. If you omit @var{frame}, it
1445 iconifies the selected frame.
1448 @defun frame-visible-p frame
1449 This returns the visibility status of frame @var{frame}. The value is
1450 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
1451 @code{icon} if it is iconified.
1453 On a text-only terminal, all frames are considered visible, whether
1454 they are currently being displayed or not, and this function returns
1455 @code{t} for all frames.
1458 The visibility status of a frame is also available as a frame
1459 parameter. You can read or change it as such. @xref{Management
1462 The user can iconify and deiconify frames with the window manager.
1463 This happens below the level at which Emacs can exert any control, but
1464 Emacs does provide events that you can use to keep track of such
1465 changes. @xref{Misc Events}.
1467 @node Raising and Lowering
1468 @section Raising and Lowering Frames
1470 Most window systems use a desktop metaphor. Part of this metaphor is
1471 the idea that windows are stacked in a notional third dimension
1472 perpendicular to the screen surface, and thus ordered from ``highest''
1473 to ``lowest.'' Where two windows overlap, the one higher up covers
1474 the one underneath. Even a window at the bottom of the stack can be
1475 seen if no other window overlaps it.
1477 @c @cindex raising a frame redundant with raise-frame
1478 @cindex lowering a frame
1479 A window's place in this ordering is not fixed; in fact, users tend
1480 to change the order frequently. @dfn{Raising} a window means moving
1481 it ``up,'' to the top of the stack. @dfn{Lowering} a window means
1482 moving it to the bottom of the stack. This motion is in the notional
1483 third dimension only, and does not change the position of the window
1486 With Emacs, frames constitute the windows in the metaphor sketched
1487 above. You can raise and lower frames using these functions:
1489 @deffn Command raise-frame &optional frame
1490 This function raises frame @var{frame} (default, the selected frame).
1491 If @var{frame} is invisible or iconified, this makes it visible.
1494 @deffn Command lower-frame &optional frame
1495 This function lowers frame @var{frame} (default, the selected frame).
1498 @defopt minibuffer-auto-raise
1499 If this is non-@code{nil}, activation of the minibuffer raises the frame
1500 that the minibuffer window is in.
1503 You can also enable auto-raise (raising automatically when a frame is
1504 selected) or auto-lower (lowering automatically when it is deselected)
1505 for any frame using frame parameters. @xref{Management Parameters}.
1507 @node Frame Configurations
1508 @section Frame Configurations
1509 @cindex frame configuration
1511 A @dfn{frame configuration} records the current arrangement of frames,
1512 all their properties, and the window configuration of each one.
1513 (@xref{Window Configurations}.)
1515 @defun current-frame-configuration
1516 This function returns a frame configuration list that describes
1517 the current arrangement of frames and their contents.
1520 @defun set-frame-configuration configuration &optional nodelete
1521 This function restores the state of frames described in
1522 @var{configuration}. However, this function does not restore deleted
1525 Ordinarily, this function deletes all existing frames not listed in
1526 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1527 unwanted frames are iconified instead.
1530 @node Mouse Tracking
1531 @section Mouse Tracking
1532 @cindex mouse tracking
1533 @c @cindex tracking the mouse Duplicates track-mouse
1535 Sometimes it is useful to @dfn{track} the mouse, which means to display
1536 something to indicate where the mouse is and move the indicator as the
1537 mouse moves. For efficient mouse tracking, you need a way to wait until
1538 the mouse actually moves.
1540 The convenient way to track the mouse is to ask for events to represent
1541 mouse motion. Then you can wait for motion by waiting for an event. In
1542 addition, you can easily handle any other sorts of events that may
1543 occur. That is useful, because normally you don't want to track the
1544 mouse forever---only until some other event, such as the release of a
1547 @defspec track-mouse body@dots{}
1548 This special form executes @var{body}, with generation of mouse motion
1549 events enabled. Typically, @var{body} would use @code{read-event} to
1550 read the motion events and modify the display accordingly. @xref{Motion
1551 Events}, for the format of mouse motion events.
1553 The value of @code{track-mouse} is that of the last form in @var{body}.
1554 You should design @var{body} to return when it sees the up-event that
1555 indicates the release of the button, or whatever kind of event means
1556 it is time to stop tracking.
1559 The usual purpose of tracking mouse motion is to indicate on the screen
1560 the consequences of pushing or releasing a button at the current
1563 In many cases, you can avoid the need to track the mouse by using
1564 the @code{mouse-face} text property (@pxref{Special Properties}).
1565 That works at a much lower level and runs more smoothly than
1566 Lisp-level mouse tracking.
1569 @c These are not implemented yet.
1571 These functions change the screen appearance instantaneously. The
1572 effect is transient, only until the next ordinary Emacs redisplay. That
1573 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1574 to change the text, and the body of @code{track-mouse} normally reads
1575 the events itself and does not do redisplay.
1577 @defun x-contour-region window beg end
1578 This function draws lines to make a box around the text from @var{beg}
1579 to @var{end}, in window @var{window}.
1582 @defun x-uncontour-region window beg end
1583 This function erases the lines that would make a box around the text
1584 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1585 a contour that you previously made by calling @code{x-contour-region}.
1588 @defun x-draw-rectangle frame left top right bottom
1589 This function draws a hollow rectangle on frame @var{frame} with the
1590 specified edge coordinates, all measured in pixels from the inside top
1591 left corner. It uses the cursor color, the one used for indicating the
1595 @defun x-erase-rectangle frame left top right bottom
1596 This function erases a hollow rectangle on frame @var{frame} with the
1597 specified edge coordinates, all measured in pixels from the inside top
1598 left corner. Erasure means redrawing the text and background that
1599 normally belong in the specified rectangle.
1603 @node Mouse Position
1604 @section Mouse Position
1605 @cindex mouse position
1606 @cindex position of mouse
1608 The functions @code{mouse-position} and @code{set-mouse-position}
1609 give access to the current position of the mouse.
1611 @defun mouse-position
1612 This function returns a description of the position of the mouse. The
1613 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1614 and @var{y} are integers giving the position in characters relative to
1615 the top left corner of the inside of @var{frame}.
1618 @defvar mouse-position-function
1619 If non-@code{nil}, the value of this variable is a function for
1620 @code{mouse-position} to call. @code{mouse-position} calls this
1621 function just before returning, with its normal return value as the
1622 sole argument, and it returns whatever this function returns to it.
1624 This abnormal hook exists for the benefit of packages like
1625 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1628 @defun set-mouse-position frame x y
1629 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1630 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1631 giving the position in characters relative to the top left corner of the
1632 inside of @var{frame}. If @var{frame} is not visible, this function
1633 does nothing. The return value is not significant.
1636 @defun mouse-pixel-position
1637 This function is like @code{mouse-position} except that it returns
1638 coordinates in units of pixels rather than units of characters.
1641 @defun set-mouse-pixel-position frame x y
1642 This function warps the mouse like @code{set-mouse-position} except that
1643 @var{x} and @var{y} are in units of pixels rather than units of
1644 characters. These coordinates are not required to be within the frame.
1646 If @var{frame} is not visible, this function does nothing. The return
1647 value is not significant.
1653 @section Pop-Up Menus
1655 When using a window system, a Lisp program can pop up a menu so that
1656 the user can choose an alternative with the mouse.
1658 @defun x-popup-menu position menu
1659 This function displays a pop-up menu and returns an indication of
1660 what selection the user makes.
1662 The argument @var{position} specifies where on the screen to put the
1663 top left corner of the menu. It can be either a mouse button event
1664 (which says to put the menu where the user actuated the button) or a
1668 ((@var{xoffset} @var{yoffset}) @var{window})
1672 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1673 pixels, counting from the top left corner of @var{window}. @var{window}
1674 may be a window or a frame.
1676 If @var{position} is @code{t}, it means to use the current mouse
1677 position. If @var{position} is @code{nil}, it means to precompute the
1678 key binding equivalents for the keymaps specified in @var{menu},
1679 without actually displaying or popping up the menu.
1681 The argument @var{menu} says what to display in the menu. It can be a
1682 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
1683 return value is the list of events corresponding to the user's choice.
1684 (This list has more than one element if the choice occurred in a
1685 submenu.) Note that @code{x-popup-menu} does not actually execute the
1686 command bound to that sequence of events.
1688 Alternatively, @var{menu} can have the following form:
1691 (@var{title} @var{pane1} @var{pane2}...)
1695 where each pane is a list of form
1698 (@var{title} @var{item1} @var{item2}...)
1701 Each item should normally be a cons cell @code{(@var{line} . @var{value})},
1702 where @var{line} is a string, and @var{value} is the value to return if
1703 that @var{line} is chosen. An item can also be a string; this makes a
1704 non-selectable line in the menu.
1706 If the user gets rid of the menu without making a valid choice, for
1707 instance by clicking the mouse away from a valid choice or by typing
1708 keyboard input, then this normally results in a quit and
1709 @code{x-popup-menu} does not return. But if @var{position} is a mouse
1710 button event (indicating that the user invoked the menu with the
1711 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1714 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1715 if you could do the job with a prefix key defined with a menu keymap.
1716 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1717 a} can see the individual items in that menu and provide help for them.
1718 If instead you implement the menu by defining a command that calls
1719 @code{x-popup-menu}, the help facilities cannot know what happens inside
1720 that command, so they cannot give any help for the menu's items.
1722 The menu bar mechanism, which lets you switch between submenus by
1723 moving the mouse, cannot look within the definition of a command to see
1724 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1725 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1726 an integrated fashion. This is why all menu bar submenus are
1727 implemented with menu keymaps within the parent menu, and never with
1728 @code{x-popup-menu}. @xref{Menu Bar}.
1730 If you want a menu bar submenu to have contents that vary, you should
1731 still use a menu keymap to implement it. To make the contents vary, add
1732 a hook function to @code{menu-bar-update-hook} to update the contents of
1733 the menu keymap as necessary.
1736 @section Dialog Boxes
1737 @cindex dialog boxes
1739 A dialog box is a variant of a pop-up menu---it looks a little
1740 different, it always appears in the center of a frame, and it has just
1741 one level and one or more buttons. The main use of dialog boxes is
1742 for asking questions that the user can answer with ``yes,'' ``no,''
1743 and a few other alternatives. With a single button, they can also
1744 force the user to acknowledge important information. The functions
1745 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1746 keyboard, when called from commands invoked by mouse clicks.
1748 @defun x-popup-dialog position contents &optional header
1749 This function displays a pop-up dialog box and returns an indication of
1750 what selection the user makes. The argument @var{contents} specifies
1751 the alternatives to offer; it has this format:
1754 (@var{title} (@var{string} . @var{value})@dots{})
1758 which looks like the list that specifies a single pane for
1759 @code{x-popup-menu}.
1761 The return value is @var{value} from the chosen alternative.
1763 As for @code{x-popup-menu}, an element of the list may be just a
1764 string instead of a cons cell @code{(@var{string} . @var{value})}.
1765 That makes a box that cannot be selected.
1767 If @code{nil} appears in the list, it separates the left-hand items from
1768 the right-hand items; items that precede the @code{nil} appear on the
1769 left, and items that follow the @code{nil} appear on the right. If you
1770 don't include a @code{nil} in the list, then approximately half the
1771 items appear on each side.
1773 Dialog boxes always appear in the center of a frame; the argument
1774 @var{position} specifies which frame. The possible values are as in
1775 @code{x-popup-menu}, but the precise coordinates or the individual
1776 window don't matter; only the frame matters.
1778 If @var{header} is non-@code{nil}, the frame title for the box is
1779 @samp{Information}, otherwise it is @samp{Question}. The former is used
1780 for @code{message-box} (@pxref{message-box}).
1782 In some configurations, Emacs cannot display a real dialog box; so
1783 instead it displays the same items in a pop-up menu in the center of the
1786 If the user gets rid of the dialog box without making a valid choice,
1787 for instance using the window manager, then this produces a quit and
1788 @code{x-popup-dialog} does not return.
1792 @section Pointer Shape
1793 @cindex pointer shape
1794 @cindex mouse pointer shape
1796 You can specify the mouse pointer style for particular text or
1797 images using the @code{pointer} text property, and for images with the
1798 @code{:pointer} and @code{:map} image properties. The values you can
1799 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1800 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1801 @code{hourglass}. @code{text} stands for the usual mouse pointer
1802 style used over text.
1804 Over void parts of the window (parts that do not correspond to any
1805 of the buffer contents), the mouse pointer usually uses the
1806 @code{arrow} style, but you can specify a different style (one of
1807 those above) by setting @code{void-text-area-pointer}.
1809 @defvar void-text-area-pointer
1810 This variable specifies the mouse pointer style for void text areas.
1811 These include the areas after the end of a line or below the last line
1812 in the buffer. The default is to use the @code{arrow} (non-text)
1816 When using X, you can specify what the @code{text} pointer style
1817 really looks like by setting the variable @code{x-pointer-shape}.
1819 @defvar x-pointer-shape
1820 This variable specifies the pointer shape to use ordinarily in the
1821 Emacs frame, for the @code{text} pointer style.
1824 @defvar x-sensitive-text-pointer-shape
1825 This variable specifies the pointer shape to use when the mouse
1826 is over mouse-sensitive text.
1829 These variables affect newly created frames. They do not normally
1830 affect existing frames; however, if you set the mouse color of a
1831 frame, that also installs the current value of those two variables.
1832 @xref{Color Parameters}.
1834 The values you can use, to specify either of these pointer shapes, are
1835 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1836 @key{RET} x-pointer @key{RET}} to see a list of them.
1838 @node Window System Selections
1839 @section Window System Selections
1840 @cindex selection (for window systems)
1842 The X server records a set of @dfn{selections} which permit transfer of
1843 data between application programs. The various selections are
1844 distinguished by @dfn{selection types}, represented in Emacs by
1845 symbols. X clients including Emacs can read or set the selection for
1848 @deffn Command x-set-selection type data
1849 This function sets a ``selection'' in the X server. It takes two
1850 arguments: a selection type @var{type}, and the value to assign to it,
1851 @var{data}. If @var{data} is @code{nil}, it means to clear out the
1852 selection. Otherwise, @var{data} may be a string, a symbol, an integer
1853 (or a cons of two integers or list of two integers), an overlay, or a
1854 cons of two markers pointing to the same buffer. An overlay or a pair
1855 of markers stands for text in the overlay or between the markers.
1857 The argument @var{data} may also be a vector of valid non-vector
1860 Each possible @var{type} has its own selection value, which changes
1861 independently. The usual values of @var{type} are @code{PRIMARY},
1862 @code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
1863 names, in accord with X Window System conventions. If @var{type} is
1864 @code{nil}, that stands for @code{PRIMARY}.
1866 This function returns @var{data}.
1869 @defun x-get-selection &optional type data-type
1870 This function accesses selections set up by Emacs or by other X
1871 clients. It takes two optional arguments, @var{type} and
1872 @var{data-type}. The default for @var{type}, the selection type, is
1875 The @var{data-type} argument specifies the form of data conversion to
1876 use, to convert the raw data obtained from another X client into Lisp
1877 data. Meaningful values include @code{TEXT}, @code{STRING},
1878 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1879 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1880 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1881 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
1882 @code{INTEGER}. (These are symbols with upper-case names in accord
1883 with X conventions.) The default for @var{data-type} is
1888 The X server also has a set of eight numbered @dfn{cut buffers} which can
1889 store text or other data being moved between applications. Cut buffers
1890 are considered obsolete, but Emacs supports them for the sake of X
1891 clients that still use them. Cut buffers are numbered from 0 to 7.
1893 @defun x-get-cut-buffer &optional n
1894 This function returns the contents of cut buffer number @var{n}.
1895 If omitted @var{n} defaults to 0.
1898 @defun x-set-cut-buffer string &optional push
1899 @anchor{Definition of x-set-cut-buffer}
1900 This function stores @var{string} into the first cut buffer (cut buffer
1901 0). If @var{push} is @code{nil}, only the first cut buffer is changed.
1902 If @var{push} is non-@code{nil}, that says to move the values down
1903 through the series of cut buffers, much like the way successive kills in
1904 Emacs move down the kill ring. In other words, the previous value of
1905 the first cut buffer moves into the second cut buffer, and the second to
1906 the third, and so on through all eight cut buffers.
1909 @defvar selection-coding-system
1910 This variable specifies the coding system to use when reading and
1911 writing selections or the clipboard. @xref{Coding
1912 Systems}. The default is @code{compound-text-with-extensions}, which
1913 converts to the text representation that X11 normally uses.
1916 @cindex clipboard support (for MS-Windows)
1917 When Emacs runs on MS-Windows, it does not implement X selections in
1918 general, but it does support the clipboard. @code{x-get-selection}
1919 and @code{x-set-selection} on MS-Windows support the text data type
1920 only; if the clipboard holds other types of data, Emacs treats the
1923 @defopt x-select-enable-clipboard
1924 If this is non-@code{nil}, the Emacs yank functions consult the
1925 clipboard before the primary selection, and the kill functions store in
1926 the clipboard as well as the primary selection. Otherwise they do not
1927 access the clipboard at all. The default is @code{nil} on most systems,
1928 but @code{t} on MS-Windows.
1932 @section Drag and Drop
1934 @vindex x-dnd-test-function
1935 @vindex x-dnd-known-types
1936 When a user drags something from another application over Emacs, that other
1937 application expects Emacs to tell it if Emacs can handle the data that is
1938 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
1939 what to reply. The default value is @code{x-dnd-default-test-function}
1940 which accepts drops if the type of the data to be dropped is present in
1941 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
1942 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
1943 on some other criteria.
1945 @vindex x-dnd-types-alist
1946 If you want to change the way Emacs handles drop of different types
1947 or add a new type, customize @code{x-dnd-types-alist}. This requires
1948 detailed knowledge of what types other applications use for drag and
1951 @vindex dnd-protocol-alist
1952 When an URL is dropped on Emacs it may be a file, but it may also be
1953 another URL type (ftp, http, etc.). Emacs first checks
1954 @code{dnd-protocol-alist} to determine what to do with the URL. If
1955 there is no match there and if @code{browse-url-browser-function} is
1956 an alist, Emacs looks for a match there. If no match is found the
1957 text for the URL is inserted. If you want to alter Emacs behavior,
1958 you can customize these variables.
1961 @section Color Names
1964 @cindex specify color
1965 @cindex numerical RGB color specification
1966 A color name is text (usually in a string) that specifies a color.
1967 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
1968 are allowed; use @kbd{M-x list-colors-display} to see a list of
1969 defined names. You can also specify colors numerically in forms such
1970 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
1971 @var{r} specifies the red level, @var{g} specifies the green level,
1972 and @var{b} specifies the blue level. You can use either one, two,
1973 three, or four hex digits for @var{r}; then you must use the same
1974 number of hex digits for all @var{g} and @var{b} as well, making
1975 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
1976 X Window System for more details about numerical RGB specification of
1979 These functions provide a way to determine which color names are
1980 valid, and what they look like. In some cases, the value depends on the
1981 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
1982 meaning of the term ``selected frame.''
1984 To read user input of color names with completion, use
1985 @code{read-color} (@pxref{High-Level Completion, read-color}).
1987 @defun color-defined-p color &optional frame
1988 This function reports whether a color name is meaningful. It returns
1989 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
1990 which frame's display to ask about; if @var{frame} is omitted or
1991 @code{nil}, the selected frame is used.
1993 Note that this does not tell you whether the display you are using
1994 really supports that color. When using X, you can ask for any defined
1995 color on any kind of display, and you will get some result---typically,
1996 the closest it can do. To determine whether a frame can really display
1997 a certain color, use @code{color-supported-p} (see below).
1999 @findex x-color-defined-p
2000 This function used to be called @code{x-color-defined-p},
2001 and that name is still supported as an alias.
2004 @defun defined-colors &optional frame
2005 This function returns a list of the color names that are defined
2006 and supported on frame @var{frame} (default, the selected frame).
2007 If @var{frame} does not support colors, the value is @code{nil}.
2009 @findex x-defined-colors
2010 This function used to be called @code{x-defined-colors},
2011 and that name is still supported as an alias.
2014 @defun color-supported-p color &optional frame background-p
2015 This returns @code{t} if @var{frame} can really display the color
2016 @var{color} (or at least something close to it). If @var{frame} is
2017 omitted or @code{nil}, the question applies to the selected frame.
2019 Some terminals support a different set of colors for foreground and
2020 background. If @var{background-p} is non-@code{nil}, that means you are
2021 asking whether @var{color} can be used as a background; otherwise you
2022 are asking whether it can be used as a foreground.
2024 The argument @var{color} must be a valid color name.
2027 @defun color-gray-p color &optional frame
2028 This returns @code{t} if @var{color} is a shade of gray, as defined on
2029 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
2030 question applies to the selected frame. If @var{color} is not a valid
2031 color name, this function returns @code{nil}.
2034 @defun color-values color &optional frame
2036 This function returns a value that describes what @var{color} should
2037 ideally look like on @var{frame}. If @var{color} is defined, the
2038 value is a list of three integers, which give the amount of red, the
2039 amount of green, and the amount of blue. Each integer ranges in
2040 principle from 0 to 65535, but some displays may not use the full
2041 range. This three-element list is called the @dfn{rgb values} of the
2044 If @var{color} is not defined, the value is @code{nil}.
2047 (color-values "black")
2049 (color-values "white")
2050 @result{} (65280 65280 65280)
2051 (color-values "red")
2052 @result{} (65280 0 0)
2053 (color-values "pink")
2054 @result{} (65280 49152 51968)
2055 (color-values "hungry")
2059 The color values are returned for @var{frame}'s display. If
2060 @var{frame} is omitted or @code{nil}, the information is returned for
2061 the selected frame's display. If the frame cannot display colors, the
2062 value is @code{nil}.
2064 @findex x-color-values
2065 This function used to be called @code{x-color-values},
2066 and that name is still supported as an alias.
2069 @node Text Terminal Colors
2070 @section Text Terminal Colors
2071 @cindex colors on text-only terminals
2073 Text-only terminals usually support only a small number of colors,
2074 and the computer uses small integers to select colors on the terminal.
2075 This means that the computer cannot reliably tell what the selected
2076 color looks like; instead, you have to inform your application which
2077 small integers correspond to which colors. However, Emacs does know
2078 the standard set of colors and will try to use them automatically.
2080 The functions described in this section control how terminal colors
2083 Several of these functions use or return @dfn{rgb values}, described
2084 in @ref{Color Names}.
2086 These functions accept a display (either a frame or the name of a
2087 terminal) as an optional argument. We hope in the future to make Emacs
2088 support more than one text-only terminal at one time; then this argument
2089 will specify which terminal to operate on (the default being the
2090 selected frame's terminal; @pxref{Input Focus}). At present, though,
2091 the @var{frame} argument has no effect.
2093 @defun tty-color-define name number &optional rgb frame
2094 This function associates the color name @var{name} with
2095 color number @var{number} on the terminal.
2097 The optional argument @var{rgb}, if specified, is an rgb value, a list
2098 of three numbers that specify what the color actually looks like.
2099 If you do not specify @var{rgb}, then this color cannot be used by
2100 @code{tty-color-approximate} to approximate other colors, because
2101 Emacs will not know what it looks like.
2104 @defun tty-color-clear &optional frame
2105 This function clears the table of defined colors for a text-only terminal.
2108 @defun tty-color-alist &optional frame
2109 This function returns an alist recording the known colors supported by a
2112 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2113 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
2114 name, @var{number} is the number used to specify it to the terminal.
2115 If present, @var{rgb} is a list of three color values (for red, green,
2116 and blue) that says what the color actually looks like.
2119 @defun tty-color-approximate rgb &optional frame
2120 This function finds the closest color, among the known colors
2121 supported for @var{display}, to that described by the rgb value
2122 @var{rgb} (a list of color values). The return value is an element of
2123 @code{tty-color-alist}.
2126 @defun tty-color-translate color &optional frame
2127 This function finds the closest color to @var{color} among the known
2128 colors supported for @var{display} and returns its index (an integer).
2129 If the name @var{color} is not defined, the value is @code{nil}.
2133 @section X Resources
2135 @defun x-get-resource attribute class &optional component subclass
2136 The function @code{x-get-resource} retrieves a resource value from the X
2137 Window defaults database.
2139 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2140 This function searches using a key of the form
2141 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2142 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2145 The optional arguments @var{component} and @var{subclass} add to the key
2146 and the class, respectively. You must specify both of them or neither.
2147 If you specify them, the key is
2148 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2149 @samp{Emacs.@var{class}.@var{subclass}}.
2152 @defvar x-resource-class
2153 This variable specifies the application name that @code{x-get-resource}
2154 should look up. The default value is @code{"Emacs"}. You can examine X
2155 resources for application names other than ``Emacs'' by binding this
2156 variable to some other string, around a call to @code{x-get-resource}.
2159 @defvar x-resource-name
2160 This variable specifies the instance name that @code{x-get-resource}
2161 should look up. The default value is the name Emacs was invoked with,
2162 or the value specified with the @samp{-name} or @samp{-rn} switches.
2165 To illustrate some of the above, suppose that you have the line:
2168 xterm.vt100.background: yellow
2172 in your X resources file (whose name is usually @file{~/.Xdefaults}
2173 or @file{~/.Xresources}). Then:
2177 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2178 (x-get-resource "vt100.background" "VT100.Background"))
2182 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2183 (x-get-resource "background" "VT100" "vt100" "Background"))
2188 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
2190 @node Display Feature Testing
2191 @section Display Feature Testing
2192 @cindex display feature testing
2194 The functions in this section describe the basic capabilities of a
2195 particular display. Lisp programs can use them to adapt their behavior
2196 to what the display can do. For example, a program that ordinarily uses
2197 a popup menu could use the minibuffer if popup menus are not supported.
2199 The optional argument @var{display} in these functions specifies which
2200 display to ask the question about. It can be a display name, a frame
2201 (which designates the display that frame is on), or @code{nil} (which
2202 refers to the selected frame's display, @pxref{Input Focus}).
2204 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2205 obtain information about displays.
2207 @defun display-popup-menus-p &optional display
2208 This function returns @code{t} if popup menus are supported on
2209 @var{display}, @code{nil} if not. Support for popup menus requires that
2210 the mouse be available, since the user cannot choose menu items without
2214 @defun display-graphic-p &optional display
2215 This function returns @code{t} if @var{display} is a graphic display
2216 capable of displaying several frames and several different fonts at
2217 once. This is true for displays that use a window system such as X, and
2218 false for text-only terminals.
2221 @defun display-mouse-p &optional display
2222 @cindex mouse, availability
2223 This function returns @code{t} if @var{display} has a mouse available,
2227 @defun display-color-p &optional display
2228 @findex x-display-color-p
2229 This function returns @code{t} if the screen is a color screen.
2230 It used to be called @code{x-display-color-p}, and that name
2231 is still supported as an alias.
2234 @defun display-grayscale-p &optional display
2235 This function returns @code{t} if the screen can display shades of gray.
2236 (All color displays can do this.)
2239 @defun display-supports-face-attributes-p attributes &optional display
2240 @anchor{Display Face Attribute Testing}
2241 This function returns non-@code{nil} if all the face attributes in
2242 @var{attributes} are supported (@pxref{Face Attributes}).
2244 The definition of `supported' is somewhat heuristic, but basically
2245 means that a face containing all the attributes in @var{attributes},
2246 when merged with the default face for display, can be represented in a
2251 different in appearance than the default face, and
2254 `close in spirit' to what the attributes specify, if not exact.
2257 Point (2) implies that a @code{:weight black} attribute will be
2258 satisfied by any display that can display bold, as will
2259 @code{:foreground "yellow"} as long as some yellowish color can be
2260 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2261 the tty display code's automatic substitution of a `dim' face for
2265 @defun display-selections-p &optional display
2266 This function returns @code{t} if @var{display} supports selections.
2267 Windowed displays normally support selections, but they may also be
2268 supported in some other cases.
2271 @defun display-images-p &optional display
2272 This function returns @code{t} if @var{display} can display images.
2273 Windowed displays ought in principle to handle images, but some
2274 systems lack the support for that. On a display that does not support
2275 images, Emacs cannot display a tool bar.
2278 @defun display-screens &optional display
2279 This function returns the number of screens associated with the display.
2282 @defun display-pixel-height &optional display
2283 This function returns the height of the screen in pixels.
2284 On a character terminal, it gives the height in characters.
2286 For graphical terminals, note that on ``multi-monitor'' setups this
2287 refers to the pixel width for all physical monitors associated with
2288 @var{display}. @xref{Multiple Displays}.
2291 @defun display-pixel-width &optional display
2292 This function returns the width of the screen in pixels.
2293 On a character terminal, it gives the width in characters.
2295 For graphical terminals, note that on ``multi-monitor'' setups this
2296 refers to the pixel width for all physical monitors associated with
2297 @var{display}. @xref{Multiple Displays}.
2300 @defun display-mm-height &optional display
2301 This function returns the height of the screen in millimeters,
2302 or @code{nil} if Emacs cannot get that information.
2305 @defun display-mm-width &optional display
2306 This function returns the width of the screen in millimeters,
2307 or @code{nil} if Emacs cannot get that information.
2310 @defvar display-mm-dimensions-alist
2311 This variable allows the user to specify the dimensions of graphical
2312 displays returned by @code{display-mm-height} and
2313 @code{display-mm-width} in case the system provides incorrect values.
2316 @defun display-backing-store &optional display
2317 This function returns the backing store capability of the display.
2318 Backing store means recording the pixels of windows (and parts of
2319 windows) that are not exposed, so that when exposed they can be
2320 displayed very quickly.
2322 Values can be the symbols @code{always}, @code{when-mapped}, or
2323 @code{not-useful}. The function can also return @code{nil}
2324 when the question is inapplicable to a certain kind of display.
2327 @defun display-save-under &optional display
2328 This function returns non-@code{nil} if the display supports the
2329 SaveUnder feature. That feature is used by pop-up windows
2330 to save the pixels they obscure, so that they can pop down
2334 @defun display-planes &optional display
2335 This function returns the number of planes the display supports.
2336 This is typically the number of bits per pixel.
2337 For a tty display, it is log to base two of the number of colors supported.
2340 @defun display-visual-class &optional display
2341 This function returns the visual class for the screen. The value is one
2342 of the symbols @code{static-gray}, @code{gray-scale},
2343 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
2344 @code{direct-color}.
2347 @defun display-color-cells &optional display
2348 This function returns the number of color cells the screen supports.
2351 These functions obtain additional information specifically
2354 @defun x-server-version &optional display
2355 This function returns the list of version numbers of the X server
2356 running the display. The value is a list of three integers: the major
2357 and minor version numbers of the X protocol, and the
2358 distributor-specific release number of the X server software itself.
2361 @defun x-server-vendor &optional display
2362 This function returns the ``vendor'' that provided the X server
2363 software (as a string). Really this means whoever distributes the X
2366 When the developers of X labelled software distributors as
2367 ``vendors,'' they showed their false assumption that no system could
2368 ever be developed and distributed noncommercially.
2372 @defvar x-no-window-manager
2373 This variable's value is @code{t} if no X window manager is in use.
2379 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2380 width and height of an X Window frame, measured in pixels.
2385 arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba