2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
9 A @dfn{frame} is a screen object that contains one or more Emacs
10 windows (@pxref{Windows}). It is the kind of object called a
11 ``window'' in the terminology of graphical environments; but we can't
12 call it a ``window'' here, because Emacs uses that word in a different
13 way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that
14 represents a frame on the screen. @xref{Frame Type}.
16 A frame initially contains a single main window and/or a minibuffer
17 window; you can subdivide the main window vertically or horizontally
18 into smaller windows. @xref{Splitting Windows}.
21 A @dfn{terminal} is a display device capable of displaying one or
22 more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp
23 object that represents a terminal. @xref{Terminal Type}.
26 @cindex graphical terminal
27 @cindex graphical display
28 There are two classes of terminals: @dfn{text terminals} and
29 @dfn{graphical terminals}. Text terminals are non-graphics-capable
30 displays, including @command{xterm} and other terminal emulators. On
31 a text terminal, each Emacs frame occupies the terminal's entire
32 screen; although you can create additional frames and switch between
33 them, the terminal only shows one frame at a time. Graphical
34 terminals, on the other hand, are managed by graphical display systems
35 such as the X Window System, which allow Emacs to show multiple frames
36 simultaneously on the same display.
38 On GNU and Unix systems, you can create additional frames on any
39 available terminal, within a single Emacs session, regardless of
40 whether Emacs was started on a text or graphical terminal. Emacs can
41 display on both graphical and text terminals simultaneously. This
42 comes in handy, for instance, when you connect to the same session
43 from several remote locations. @xref{Multiple Terminals}.
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 on a text terminal.
54 The frame is displayed on an X graphical terminal.
56 The frame is displayed on a MS-Windows graphical terminal.
58 The frame is displayed on a GNUstep or Macintosh Cocoa graphical
61 The frame is displayed on an MS-DOS terminal.
65 @defun frame-terminal &optional frame
66 This function returns the terminal object that displays @var{frame}.
67 If @var{frame} is @code{nil} or unspecified, it defaults to the
71 @defun terminal-live-p object
72 This predicate returns a non-@code{nil} value if @var{object} is a
73 terminal that is live (i.e.@: not deleted), and @code{nil} otherwise.
74 For live terminals, the return value indicates what kind of frames are
75 displayed on that terminal; the list of possible values is the same as
76 for @code{framep} above.
80 * Creating Frames:: Creating additional frames.
81 * Multiple Terminals:: Displaying on several different devices.
82 * Frame Parameters:: Controlling frame size, position, font, etc.
83 * Terminal Parameters:: Parameters common for all frames on terminal.
84 * Frame Titles:: Automatic updating of frame titles.
85 * Deleting Frames:: Frames last until explicitly deleted.
86 * Finding All Frames:: How to examine all existing frames.
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 terminals.
102 * Resources:: Getting resource values from the server.
103 * Display Feature Testing:: Determining the features of a terminal.
106 @node Creating Frames
107 @section Creating Frames
109 To create a new frame, call the function @code{make-frame}.
111 @deffn Command make-frame &optional alist
112 This function creates and returns a new frame, displaying the current
115 The @var{alist} argument is an alist that specifies frame parameters
116 for the new frame. @xref{Frame Parameters}. If you specify the
117 @code{terminal} parameter in @var{alist}, the new frame is created on
118 that terminal. Otherwise, if you specify the @code{window-system}
119 frame parameter in @var{alist}, that determines whether the frame
120 should be displayed on a text terminal or a graphical terminal.
121 @xref{Window Systems}. If neither is specified, the new frame is
122 created in the same terminal as the selected frame.
124 Any parameters not mentioned in @var{alist} default to the values in
125 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
126 parameters not specified there default from the X resources or its
127 equivalent on your operating system (@pxref{X Resources,, X Resources,
128 emacs, The GNU Emacs Manual}). After the frame is created, Emacs
129 applies any parameters listed in @code{frame-inherited-parameters}
130 (see below) and not present in the argument, taking the values from
131 the frame that was selected when @code{make-frame} was called.
133 This function itself does not make the new frame the selected frame.
134 @xref{Input Focus}. The previously selected frame remains selected.
135 On graphical terminals, however, the windowing system may select the
136 new frame for its own reasons.
139 @defvar before-make-frame-hook
140 A normal hook run by @code{make-frame} before it creates the frame.
143 @defvar after-make-frame-functions
144 An abnormal hook run by @code{make-frame} after it creates the frame.
145 Each function in @code{after-make-frame-functions} receives one argument, the
149 @defvar frame-inherited-parameters
150 This variable specifies the list of frame parameters that a newly
151 created frame inherits from the currently selected frame. For each
152 parameter (a symbol) that is an element in the list and is not present
153 in the argument to @code{make-frame}, the function sets the value of
154 that parameter in the created frame to its value in the selected
158 @node Multiple Terminals
159 @section Multiple Terminals
160 @cindex multiple terminals
162 @cindex multiple X displays
163 @cindex displays, multiple
165 Emacs represents each terminal as a @dfn{terminal object} data type
166 (@pxref{Terminal Type}). On GNU and Unix systems, Emacs can use
167 multiple terminals simultaneously in each session. On other systems,
168 it can only use a single terminal. Each terminal object has the
169 following attributes:
173 The name of the device used by the terminal (e.g.@: @samp{:0.0} or
177 The terminal and keyboard coding systems used on the terminal.
178 @xref{Terminal I/O Encoding}.
181 The kind of display associated with the terminal. This is the symbol
182 returned by the function @code{terminal-live-p} (i.e.@: @code{x},
183 @code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.
186 A list of terminal parameters. @xref{Terminal Parameters}.
189 There is no primitive for creating terminal objects. Emacs creates
190 them as needed, such as when you call @code{make-frame-on-display}
193 @defun terminal-name &optional terminal
194 This function returns the file name of the device used by
195 @var{terminal}. If @var{terminal} is omitted or @code{nil}, it
196 defaults to the selected frame's terminal. @var{terminal} can also be
197 a frame, meaning that frame's terminal.
201 This function returns a list of all live terminal objects.
204 @defun get-device-terminal device
205 This function returns a terminal whose device name is given by
206 @var{device}. If @var{device} is a string, it can be either the file
207 name of a terminal device, or the name of an X display of the form
208 @samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a
209 frame, this function returns that frame's terminal; @code{nil} means
210 the selected frame. Finally, if @var{device} is a terminal object
211 that represents a live terminal, that terminal is returned. The
212 function signals an error if its argument is none of the above.
215 @defun delete-terminal &optional terminal force
216 This function deletes all frames on @var{terminal} and frees the
217 resources used by it. It runs the abnormal hook
218 @code{delete-terminal-functions}, passing @var{terminal} as the
219 argument to each function.
221 If @var{terminal} is omitted or @code{nil}, it defaults to the
222 selected frame's terminal. @var{terminal} can also be a frame,
223 meaning that frame's terminal.
225 Normally, this function signals an error if you attempt to delete the
226 sole active terminal, but if @var{force} is non-@code{nil}, you are
227 allowed to do so. Emacs automatically calls this function when the
228 last frame on a terminal is deleted (@pxref{Deleting Frames}).
231 @defvar delete-terminal-functions
232 An abnormal hook run by @code{delete-terminal}. Each function
233 receives one argument, the @var{terminal} argument passed to
234 @code{delete-terminal}. Due to technical details, the functions may
235 be called either just before the terminal is deleted, or just
239 @cindex terminal-local variables
240 A few Lisp variables are @dfn{terminal-local}; that is, they have a
241 separate binding for each terminal. The binding in effect at any time
242 is the one for the terminal that the currently selected frame belongs
243 to. These variables include @code{default-minibuffer-frame},
244 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
245 @code{system-key-alist}. They are always terminal-local, and can
246 never be buffer-local (@pxref{Buffer-Local Variables}).
248 On GNU and Unix systems, each X display is a separate graphical
249 terminal. When Emacs is started from within the X window system, it
250 uses the X display specified by the @env{DISPLAY} environment
251 variable, or by the @samp{--display} option (@pxref{Initial Options,,,
252 emacs, The GNU Emacs Manual}). Emacs can connect to other X displays
253 via the command @code{make-frame-on-display}. Each X display has its
254 own selected frame and its own minibuffer windows; however, only one
255 of those frames is ``@emph{the} selected frame'' at any given moment
256 (@pxref{Input Focus}). Emacs can even connect to other text
257 terminals, by interacting with the @command{emacsclient} program.
258 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
260 A single X server can handle more than one display. Each X display
261 has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
262 The first two parts, @var{host} and @var{server}, identify the X
263 server; the third part, @var{screen}, identifies a screen number on
264 that X server. When you use two or more screens belonging to one
265 server, Emacs knows by the similarity in their names that they share a
268 On some ``multi-monitor'' setups, a single X display outputs to more
269 than one physical monitor. Currently, there is no way for Emacs to
270 distinguish between the different physical monitors.
272 @deffn Command make-frame-on-display display &optional parameters
273 This function creates and returns a new frame on @var{display}, taking
274 the other frame parameters from the alist @var{parameters}.
275 @var{display} should be the name of an X display (a string).
277 Before creating the frame, this function ensures that Emacs is ``set
278 up'' to display graphics. For instance, if Emacs has not processed X
279 resources (e.g.@: if it was started on a text terminal), it does so at
280 this time. In all other respects, this function behaves like
281 @code{make-frame} (@pxref{Creating Frames}).
284 @defun x-display-list
285 This function returns a list that indicates which X displays Emacs has
286 a connection to. The elements of the list are strings, and each one
290 @defun x-open-connection display &optional xrm-string must-succeed
291 This function opens a connection to the X display @var{display},
292 without creating a frame on that display. Normally, Emacs Lisp
293 programs need not call this function, as @code{make-frame-on-display}
294 calls it automatically. The only reason for calling it is to check
295 whether communication can be established with a given X display.
297 The optional argument @var{xrm-string}, if not @code{nil}, is a string
298 of resource names and values, in the same format used in the
299 @file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The
300 GNU Emacs Manual}. These values apply to all Emacs frames created on
301 this display, overriding the resource values recorded in the X server.
302 Here's an example of what this string might look like:
305 "*BorderWidth: 3\n*InternalBorder: 2\n"
308 If @var{must-succeed} is non-@code{nil}, failure to open the connection
309 terminates Emacs. Otherwise, it is an ordinary Lisp error.
312 @defun x-close-connection display
313 This function closes the connection to display @var{display}. Before
314 you can do this, you must first delete all the frames that were open
315 on that display (@pxref{Deleting Frames}).
318 @node Frame Parameters
319 @section Frame Parameters
320 @cindex frame parameters
322 A frame has many parameters that control its appearance and behavior.
323 Just what parameters a frame has depends on what display mechanism it
326 Frame parameters exist mostly for the sake of graphical displays.
327 Most frame parameters have no effect when applied to a frame on a text
328 terminal; only the @code{height}, @code{width}, @code{name},
329 @code{title}, @code{menu-bar-lines}, @code{buffer-list} and
330 @code{buffer-predicate} parameters do something special. If the
331 terminal supports colors, the parameters @code{foreground-color},
332 @code{background-color}, @code{background-mode} and
333 @code{display-type} are also meaningful. If the terminal supports
334 frame transparency, the parameter @code{alpha} is also meaningful.
337 * Parameter Access:: How to change a frame's parameters.
338 * Initial Parameters:: Specifying frame parameters when you make a frame.
339 * Window Frame Parameters:: List of frame parameters for window systems.
340 * Size and Position:: Changing the size and position of a frame.
341 * Geometry:: Parsing geometry specifications.
344 @node Parameter Access
345 @subsection Access to Frame Parameters
347 These functions let you read and change the parameter values of a
350 @defun frame-parameter frame parameter
351 This function returns the value of the parameter @var{parameter} (a
352 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
353 selected frame's parameter. If @var{frame} has no setting for
354 @var{parameter}, this function returns @code{nil}.
357 @defun frame-parameters &optional frame
358 The function @code{frame-parameters} returns an alist listing all the
359 parameters of @var{frame} and their values. If @var{frame} is
360 @code{nil} or omitted, this returns the selected frame's parameters
363 @defun modify-frame-parameters frame alist
364 This function alters the parameters of frame @var{frame} based on the
365 elements of @var{alist}. Each element of @var{alist} has the form
366 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
367 parameter. If you don't mention a parameter in @var{alist}, its value
368 doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
372 @defun set-frame-parameter frame parm value
373 This function sets the frame parameter @var{parm} to the specified
374 @var{value}. If @var{frame} is @code{nil}, it defaults to the
378 @defun modify-all-frames-parameters alist
379 This function alters the frame parameters of all existing frames
380 according to @var{alist}, then modifies @code{default-frame-alist}
381 (and, if necessary, @code{initial-frame-alist}) to apply the same
382 parameter values to frames that will be created henceforth.
385 @node Initial Parameters
386 @subsection Initial Frame Parameters
388 You can specify the parameters for the initial startup frame by
389 setting @code{initial-frame-alist} in your init file (@pxref{Init
392 @defopt initial-frame-alist
393 This variable's value is an alist of parameter values used when
394 creating the initial frame. You can set this variable to specify the
395 appearance of the initial frame without altering subsequent frames.
396 Each element has the form:
399 (@var{parameter} . @var{value})
402 Emacs creates the initial frame before it reads your init
403 file. After reading that file, Emacs checks @code{initial-frame-alist},
404 and applies the parameter settings in the altered value to the already
405 created initial frame.
407 If these settings affect the frame geometry and appearance, you'll see
408 the frame appear with the wrong ones and then change to the specified
409 ones. If that bothers you, you can specify the same geometry and
410 appearance with X resources; those do take effect before the frame is
411 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
413 X resource settings typically apply to all frames. If you want to
414 specify some X resources solely for the sake of the initial frame, and
415 you don't want them to apply to subsequent frames, here's how to achieve
416 this. Specify parameters in @code{default-frame-alist} to override the
417 X resources for subsequent frames; then, to prevent these from affecting
418 the initial frame, specify the same parameters in
419 @code{initial-frame-alist} with values that match the X resources.
422 If these parameters specify a separate @dfn{minibuffer-only frame} with
423 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
426 @cindex minibuffer-only frame
427 @defopt minibuffer-frame-alist
428 This variable's value is an alist of parameter values used when
429 creating an initial minibuffer-only frame. This is the
430 minibuffer-only frame that Emacs creates if @code{initial-frame-alist}
431 specifies a frame with no minibuffer.
434 @defopt default-frame-alist
435 This is an alist specifying default values of frame parameters for all
436 Emacs frames---the first frame, and subsequent frames. When using the X
437 Window System, you can get the same results by means of X resources
440 Setting this variable does not affect existing frames.
443 Functions that display a buffer in a separate frame can override the
444 default parameters by supplying their own parameters. @xref{Definition
445 of special-display-frame-alist}.
447 If you invoke Emacs with command-line options that specify frame
448 appearance, those options take effect by adding elements to either
449 @code{initial-frame-alist} or @code{default-frame-alist}. Options
450 which affect just the initial frame, such as @samp{-geometry} and
451 @samp{--maximized}, add to @code{initial-frame-alist}; the others add
452 to @code{default-frame-alist}. @pxref{Emacs Invocation,, Command Line
453 Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
455 @node Window Frame Parameters
456 @subsection Window Frame Parameters
457 @cindex frame parameters for windowed displays
459 Just what parameters a frame has depends on what display mechanism
460 it uses. This section describes the parameters that have special
461 meanings on some or all kinds of terminals. Of these, @code{name},
462 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
463 @code{buffer-predicate} provide meaningful information in terminal
464 frames, and @code{tty-color-mode} is meaningful only for frames on
468 * Basic Parameters:: Parameters that are fundamental.
469 * Position Parameters:: The position of the frame on the screen.
470 * Size Parameters:: Frame's size.
471 * Layout Parameters:: Size of parts of the frame, and
472 enabling or disabling some parts.
473 * Buffer Parameters:: Which buffers have been or should be shown.
474 * Management Parameters:: Communicating with the window manager.
475 * Cursor Parameters:: Controlling the cursor appearance.
476 * Font and Color Parameters:: Fonts and colors for the frame text.
479 @node Basic Parameters
480 @subsubsection Basic Parameters
482 These frame parameters give the most basic information about the
483 frame. @code{title} and @code{name} are meaningful on all terminals.
486 @vindex display, a frame parameter
488 The display on which to open this frame. It should be a string of the
489 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
490 @env{DISPLAY} environment variable.
492 @vindex display-type, a frame parameter
494 This parameter describes the range of possible colors that can be used
495 in this frame. Its value is @code{color}, @code{grayscale} or
498 @vindex title, a frame parameter
500 If a frame has a non-@code{nil} title, it appears in the window
501 system's title bar at the top of the frame, and also in the mode line
502 of windows in that frame if @code{mode-line-frame-identification} uses
503 @samp{%F} (@pxref{%-Constructs}). This is normally the case when
504 Emacs is not using a window system, and can only display one frame at
505 a time. @xref{Frame Titles}.
507 @vindex name, a frame parameter
509 The name of the frame. The frame name serves as a default for the frame
510 title, if the @code{title} parameter is unspecified or @code{nil}. If
511 you don't specify a name, Emacs sets the frame name automatically
512 (@pxref{Frame Titles}).
514 If you specify the frame name explicitly when you create the frame, the
515 name is also used (instead of the name of the Emacs executable) when
516 looking up X resources for the frame.
519 If the frame name was specified explicitly when the frame was created,
520 this parameter will be that name. If the frame wasn't explicitly
521 named, this parameter will be @code{nil}.
524 @node Position Parameters
525 @subsubsection Position Parameters
526 @cindex window position on display
528 Position parameters' values are normally measured in pixels, but on
529 text terminals they count characters or lines instead.
532 @vindex left, a frame parameter
534 The position, in pixels, of the left (or right) edge of the frame with
535 respect to the left (or right) edge of the screen. The value may be:
539 A positive integer relates the left edge of the frame to the left edge
540 of the screen. A negative integer relates the right frame edge to the
543 @item @code{(+ @var{pos})}
544 This specifies the position of the left frame edge relative to the left
545 screen edge. The integer @var{pos} may be positive or negative; a
546 negative value specifies a position outside the screen.
548 @item @code{(- @var{pos})}
549 This specifies the position of the right frame edge relative to the right
550 screen edge. The integer @var{pos} may be positive or negative; a
551 negative value specifies a position outside the screen.
554 Some window managers ignore program-specified positions. If you want to
555 be sure the position you specify is not ignored, specify a
556 non-@code{nil} value for the @code{user-position} parameter as well.
558 @vindex top, a frame parameter
560 The screen position of the top (or bottom) edge, in pixels, with respect
561 to the top (or bottom) edge of the screen. It works just like
562 @code{left}, except vertically instead of horizontally.
564 @vindex icon-left, a frame parameter
566 The screen position of the left edge of the frame's icon, in pixels,
567 counting from the left edge of the screen. This takes effect when the
568 frame is iconified, if the window manager supports this feature. If
569 you specify a value for this parameter, then you must also specify a
570 value for @code{icon-top} and vice versa.
572 @vindex icon-top, a frame parameter
574 The screen position of the top edge of the frame's icon, in pixels,
575 counting from the top edge of the screen. This takes effect when the
576 frame is iconified, if the window manager supports this feature.
578 @vindex user-position, a frame parameter
580 When you create a frame and specify its screen position with the
581 @code{left} and @code{top} parameters, use this parameter to say whether
582 the specified position was user-specified (explicitly requested in some
583 way by a human user) or merely program-specified (chosen by a program).
584 A non-@code{nil} value says the position was user-specified.
586 @cindex window positions and window managers
587 Window managers generally heed user-specified positions, and some heed
588 program-specified positions too. But many ignore program-specified
589 positions, placing the window in a default fashion or letting the user
590 place it with the mouse. Some window managers, including @code{twm},
591 let the user specify whether to obey program-specified positions or
594 When you call @code{make-frame}, you should specify a non-@code{nil}
595 value for this parameter if the values of the @code{left} and @code{top}
596 parameters represent the user's stated preference; otherwise, use
600 @node Size Parameters
601 @subsubsection Size Parameters
602 @cindex window size on display
604 Frame parameters specify frame sizes in character units. On
605 graphical displays, the @code{default} face determines the actual
606 pixel sizes of these character units (@pxref{Face Attributes}).
609 @vindex height, a frame parameter
611 The height of the frame contents, in characters. (To get the height in
612 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
614 @vindex width, a frame parameter
616 The width of the frame contents, in characters. (To get the width in
617 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
619 @vindex user-size, a frame parameter
621 This does for the size parameters @code{height} and @code{width} what
622 the @code{user-position} parameter (@pxref{Position Parameters,
623 user-position}) does for the position parameters @code{top} and
626 @cindex full-screen frames
627 @vindex fullscreen, a frame parameter
629 Specify that width, height or both shall be maximized. The value
630 @code{fullwidth} specifies that width shall be as wide as possible.
631 The value @code{fullheight} specifies that height shall be as tall as
632 possible. The value @code{fullboth} specifies that both the width and
633 the height shall be set to the size of the screen. The value
634 @code{maximized} specifies that the frame shall be maximized. The
635 difference between @code{maximized} and @code{fullboth} is that the
636 former still has window manager decorations while the latter really
637 covers the whole screen.
640 @node Layout Parameters
641 @subsubsection Layout Parameters
642 @cindex layout parameters of frames
643 @cindex frame layout parameters
645 These frame parameters enable or disable various parts of the
646 frame, or control their sizes.
649 @vindex border-width, a frame parameter
651 The width in pixels of the frame's border.
653 @vindex internal-border-width, a frame parameter
654 @item internal-border-width
655 The distance in pixels between text (or fringe) and the frame's border.
657 @vindex vertical-scroll-bars, a frame parameter
658 @item vertical-scroll-bars
659 Whether the frame has scroll bars for vertical scrolling, and which side
660 of the frame they should be on. The possible values are @code{left},
661 @code{right}, and @code{nil} for no scroll bars.
664 @vindex horizontal-scroll-bars, a frame parameter
665 @item horizontal-scroll-bars
666 Whether the frame has scroll bars for horizontal scrolling
667 (non-@code{nil} means yes). Horizontal scroll bars are not currently
671 @vindex scroll-bar-width, a frame parameter
672 @item scroll-bar-width
673 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
674 use the default width.
676 @vindex left-fringe, a frame parameter
677 @vindex right-fringe, a frame parameter
680 The default width of the left and right fringes of windows in this
681 frame (@pxref{Fringes}). If either of these is zero, that effectively
682 removes the corresponding fringe.
684 When you use @code{frame-parameter} to query the value of either of
685 these two frame parameters, the return value is always an integer.
686 When using @code{set-frame-parameter}, passing a @code{nil} value
687 imposes an actual default value of 8 pixels.
689 The combined fringe widths must add up to an integral number of
690 columns, so the actual default fringe widths for the frame, as
691 reported by @code{frame-parameter}, may be larger than what you
692 specify. Any extra width is distributed evenly between the left and
693 right fringe. However, you can force one fringe or the other to a
694 precise width by specifying that width as a negative integer. If both
695 widths are negative, only the left fringe gets the specified width.
697 @vindex menu-bar-lines frame parameter
699 The number of lines to allocate at the top of the frame for a menu
700 bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
701 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
703 @vindex tool-bar-lines frame parameter
705 The number of lines to use for the tool bar. The default is 1 if Tool
706 Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The
709 @vindex tool-bar-position frame parameter
710 @item tool-bar-position
711 The position of the tool bar. Currently only for the GTK tool bar.
712 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
713 The default is @code{top}.
715 @vindex line-spacing, a frame parameter
717 Additional space to leave below each text line, in pixels (a positive
718 integer). @xref{Line Height}, for more information.
721 @node Buffer Parameters
722 @subsubsection Buffer Parameters
724 These frame parameters, meaningful on all kinds of terminals, deal
725 with which buffers have been, or should, be displayed in the frame.
728 @vindex minibuffer, a frame parameter
730 Whether this frame has its own minibuffer. The value @code{t} means
731 yes, @code{nil} means no, @code{only} means this frame is just a
732 minibuffer. If the value is a minibuffer window (in some other
733 frame), the frame uses that minibuffer.
735 This frame parameter takes effect when the frame is created, and can
736 not be changed afterwards.
738 @vindex buffer-predicate, a frame parameter
739 @item buffer-predicate
740 The buffer-predicate function for this frame. The function
741 @code{other-buffer} uses this predicate (from the selected frame) to
742 decide which buffers it should consider, if the predicate is not
743 @code{nil}. It calls the predicate with one argument, a buffer, once for
744 each buffer; if the predicate returns a non-@code{nil} value, it
745 considers that buffer.
747 @vindex buffer-list, a frame parameter
749 A list of buffers that have been selected in this frame, ordered
750 most-recently-selected first.
752 @vindex unsplittable, a frame parameter
754 If non-@code{nil}, this frame's window is never split automatically.
757 @node Management Parameters
758 @subsubsection Window Management Parameters
759 @cindex window manager interaction, and frame parameters
761 The following frame parameters control various aspects of the
762 frame's interaction with the window manager. They have no effect on
766 @vindex visibility, a frame parameter
768 The state of visibility of the frame. There are three possibilities:
769 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
770 iconified. @xref{Visibility of Frames}.
772 @vindex auto-raise, a frame parameter
774 If non-@code{nil}, Emacs automatically raises the frame when it is
775 selected. Some window managers do not allow this.
777 @vindex auto-lower, a frame parameter
779 If non-@code{nil}, Emacs automatically lowers the frame when it is
780 deselected. Some window managers do not allow this.
782 @vindex icon-type, a frame parameter
784 The type of icon to use for this frame. If the value is a string,
785 that specifies a file containing a bitmap to use; @code{nil} specifies
786 no icon (in which case the window manager decides what to show); any
787 other non-@code{nil} value specifies the default Emacs icon.
789 @vindex icon-name, a frame parameter
791 The name to use in the icon for this frame, when and if the icon
792 appears. If this is @code{nil}, the frame's title is used.
794 @vindex window-id, a frame parameter
796 The ID number which the graphical display uses for this frame. Emacs
797 assigns this parameter when the frame is created; changing the
798 parameter has no effect on the actual ID number.
800 @vindex outer-window-id, a frame parameter
801 @item outer-window-id
802 The ID number of the outermost window-system window in which the frame
803 exists. As with @code{window-id}, changing this parameter has no
806 @vindex wait-for-wm, a frame parameter
808 If non-@code{nil}, tell Xt to wait for the window manager to confirm
809 geometry changes. Some window managers, including versions of Fvwm2
810 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
811 prevent hanging with those window managers.
813 @vindex sticky, a frame parameter
815 If non-@code{nil}, the frame is visible on all virtual desktops on systems
816 with virtual desktops.
819 @vindex parent-id, a frame parameter
821 @c ??? Not yet working.
822 The X window number of the window that should be the parent of this one.
823 Specifying this lets you create an Emacs window inside some other
824 application's window. (It is not certain this will be implemented; try
825 it and see if it works.)
829 @node Cursor Parameters
830 @subsubsection Cursor Parameters
831 @cindex cursor, and frame parameters
833 This frame parameter controls the way the cursor looks.
836 @vindex cursor-type, a frame parameter
838 How to display the cursor. Legitimate values are:
842 Display a filled box. (This is the default.)
844 Display a hollow box.
846 Don't display a cursor.
848 Display a vertical bar between characters.
849 @item (bar . @var{width})
850 Display a vertical bar @var{width} pixels wide between characters.
852 Display a horizontal bar.
853 @item (hbar . @var{height})
854 Display a horizontal bar @var{height} pixels high.
859 The @code{cursor-type} frame parameter may be overridden by the
860 variables @code{cursor-type} and
861 @code{cursor-in-non-selected-windows}:
864 This buffer-local variable controls how the cursor looks in a selected
865 window showing the buffer. If its value is @code{t}, that means to
866 use the cursor specified by the @code{cursor-type} frame parameter.
867 Otherwise, the value should be one of the cursor types listed above,
868 and it overrides the @code{cursor-type} frame parameter.
871 @defopt cursor-in-non-selected-windows
872 This buffer-local variable controls how the cursor looks in a window
873 that is not selected. It supports the same values as the
874 @code{cursor-type} frame parameter; also, @code{nil} means don't
875 display a cursor in nonselected windows, and @code{t} (the default)
876 means use a standard modification of the usual cursor type (solid box
877 becomes hollow box, and bar becomes a narrower bar).
880 @defopt blink-cursor-alist
881 This variable specifies how to blink the cursor. Each element has the
882 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
883 type equals @var{on-state} (comparing using @code{equal}), the
884 corresponding @var{off-state} specifies what the cursor looks like
885 when it blinks ``off''. Both @var{on-state} and @var{off-state}
886 should be suitable values for the @code{cursor-type} frame parameter.
888 There are various defaults for how to blink each type of cursor, if
889 the type is not mentioned as an @var{on-state} here. Changes in this
890 variable do not take effect immediately, only when you specify the
891 @code{cursor-type} frame parameter.
894 @node Font and Color Parameters
895 @subsubsection Font and Color Parameters
896 @cindex font and color, frame parameters
898 These frame parameters control the use of fonts and colors.
901 @vindex font-backend, a frame parameter
903 A list of symbols, specifying the @dfn{font backends} to use for
904 drawing fonts in the frame, in order of priority. On X, there are
905 currently two available font backends: @code{x} (the X core font
906 driver) and @code{xft} (the Xft font driver). On Windows, there are
907 currently two available font backends: @code{gdi} and
908 @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
909 Manual}). On other systems, there is only one available font backend,
910 so it does not make sense to modify this frame parameter.
912 @vindex background-mode, a frame parameter
913 @item background-mode
914 This parameter is either @code{dark} or @code{light}, according
915 to whether the background color is a light one or a dark one.
917 @vindex tty-color-mode, a frame parameter
919 @cindex standard colors for character terminals
920 This parameter overrides the terminal's color support as given by the
921 system's terminal capabilities database in that this parameter's value
922 specifies the color mode to use on a text terminal. The value can be
923 either a symbol or a number. A number specifies the number of colors
924 to use (and, indirectly, what commands to issue to produce each
925 color). For example, @code{(tty-color-mode . 8)} specifies use of the
926 ANSI escape sequences for 8 standard text colors. A value of -1 turns
929 If the parameter's value is a symbol, it specifies a number through
930 the value of @code{tty-color-mode-alist}, and the associated number is
933 @vindex screen-gamma, a frame parameter
935 @cindex gamma correction
936 If this is a number, Emacs performs ``gamma correction'' which adjusts
937 the brightness of all colors. The value should be the screen gamma of
938 your display, a floating point number.
940 Usual PC monitors have a screen gamma of 2.2, so color values in
941 Emacs, and in X windows generally, are calibrated to display properly
942 on a monitor with that gamma value. If you specify 2.2 for
943 @code{screen-gamma}, that means no correction is needed. Other values
944 request correction, designed to make the corrected colors appear on
945 your screen the way they would have appeared without correction on an
946 ordinary monitor with a gamma value of 2.2.
948 If your monitor displays colors too light, you should specify a
949 @code{screen-gamma} value smaller than 2.2. This requests correction
950 that makes colors darker. A screen gamma value of 1.5 may give good
951 results for LCD color displays.
953 @vindex alpha, a frame parameter
955 @cindex opacity, frame
956 @cindex transparency, frame
957 @vindex frame-alpha-lower-limit
958 This parameter specifies the opacity of the frame, on graphical
959 displays that support variable opacity. It should be an integer
960 between 0 and 100, where 0 means completely transparent and 100 means
961 completely opaque. It can also have a @code{nil} value, which tells
962 Emacs not to set the frame opacity (leaving it to the window manager).
964 To prevent the frame from disappearing completely from view, the
965 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
966 If the value of the frame parameter is less than the value of this
967 variable, Emacs uses the latter. By default,
968 @code{frame-alpha-lower-limit} is 20.
970 The @code{alpha} frame parameter can also be a cons cell
971 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
972 opacity of the frame when it is selected, and @samp{inactive} is the
973 opacity when it is not selected.
976 The following frame parameters are semi-obsolete in that they are
977 automatically equivalent to particular face attributes of particular
978 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
981 @vindex font, a frame parameter
983 The name of the font for displaying text in the frame. This is a
984 string, either a valid font name for your system or the name of an Emacs
985 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
986 attribute of the @code{default} face.
988 @vindex foreground-color, a frame parameter
989 @item foreground-color
990 The color to use for the image of a character. It is equivalent to
991 the @code{:foreground} attribute of the @code{default} face.
993 @vindex background-color, a frame parameter
994 @item background-color
995 The color to use for the background of characters. It is equivalent to
996 the @code{:background} attribute of the @code{default} face.
998 @vindex mouse-color, a frame parameter
1000 The color for the mouse pointer. It is equivalent to the @code{:background}
1001 attribute of the @code{mouse} face.
1003 @vindex cursor-color, a frame parameter
1005 The color for the cursor that shows point. It is equivalent to the
1006 @code{:background} attribute of the @code{cursor} face.
1008 @vindex border-color, a frame parameter
1010 The color for the border of the frame. It is equivalent to the
1011 @code{:background} attribute of the @code{border} face.
1013 @vindex scroll-bar-foreground, a frame parameter
1014 @item scroll-bar-foreground
1015 If non-@code{nil}, the color for the foreground of scroll bars. It is
1016 equivalent to the @code{:foreground} attribute of the
1017 @code{scroll-bar} face.
1019 @vindex scroll-bar-background, a frame parameter
1020 @item scroll-bar-background
1021 If non-@code{nil}, the color for the background of scroll bars. It is
1022 equivalent to the @code{:background} attribute of the
1023 @code{scroll-bar} face.
1026 @node Size and Position
1027 @subsection Frame Size And Position
1028 @cindex size of frame
1031 @cindex resize frame
1033 You can read or change the size and position of a frame using the
1034 frame parameters @code{left}, @code{top}, @code{height}, and
1035 @code{width}. Whatever geometry parameters you don't specify are chosen
1036 by the window manager in its usual fashion.
1038 Here are some special features for working with sizes and positions.
1039 (For the precise meaning of ``selected frame'' used by these functions,
1040 see @ref{Input Focus}.)
1042 @defun set-frame-position frame left top
1043 This function sets the position of the top left corner of @var{frame} to
1044 @var{left} and @var{top}. These arguments are measured in pixels, and
1045 normally count from the top left corner of the screen.
1047 Negative parameter values position the bottom edge of the window up from
1048 the bottom edge of the screen, or the right window edge to the left of
1049 the right edge of the screen. It would probably be better if the values
1050 were always counted from the left and top, so that negative arguments
1051 would position the frame partly off the top or left edge of the screen,
1052 but it seems inadvisable to change that now.
1055 @defun frame-height &optional frame
1056 @defunx frame-width &optional frame
1057 These functions return the height and width of @var{frame}, measured in
1058 lines and columns. If you don't supply @var{frame}, they use the
1062 @defun frame-pixel-height &optional frame
1063 @defunx frame-pixel-width &optional frame
1064 These functions return the height and width of the main display area
1065 of @var{frame}, measured in pixels. If you don't supply @var{frame},
1066 they use the selected frame. For a text terminal, the results are in
1067 characters rather than pixels.
1069 These values include the internal borders, and windows' scroll bars
1070 and fringes (which belong to individual windows, not to the frame
1071 itself). The exact value of the heights depends on the window-system
1072 and toolkit in use. With GTK+, the height does not include any tool
1073 bar or menu bar. With the Motif or Lucid toolkits, it includes the
1074 tool bar but not the menu bar. In a graphical version with no
1075 toolkit, it includes both the tool bar and menu bar. For a text
1076 terminal, the result includes the menu bar.
1079 @defun frame-char-height &optional frame
1080 @defunx frame-char-width &optional frame
1081 These functions return the height and width of a character in
1082 @var{frame}, measured in pixels. The values depend on the choice of
1083 font. If you don't supply @var{frame}, these functions use the selected
1087 @defun set-frame-size frame cols rows
1088 This function sets the size of @var{frame}, measured in characters;
1089 @var{cols} and @var{rows} specify the new width and height.
1091 To set the size based on values measured in pixels, use
1092 @code{frame-char-height} and @code{frame-char-width} to convert
1093 them to units of characters.
1096 @defun set-frame-height frame lines &optional pretend
1097 This function resizes @var{frame} to a height of @var{lines} lines. The
1098 sizes of existing windows in @var{frame} are altered proportionally to
1101 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
1102 lines of output in @var{frame}, but does not change its value for the
1103 actual height of the frame. This is only useful on text terminals.
1104 Using a smaller height than the terminal actually implements may be
1105 useful to reproduce behavior observed on a smaller screen, or if the
1106 terminal malfunctions when using its whole screen. Setting the frame
1107 height ``for real'' does not always work, because knowing the correct
1108 actual size may be necessary for correct cursor positioning on
1112 @defun set-frame-width frame width &optional pretend
1113 This function sets the width of @var{frame}, measured in characters.
1114 The argument @var{pretend} has the same meaning as in
1115 @code{set-frame-height}.
1119 @subsection Geometry
1121 Here's how to examine the data in an X-style window geometry
1124 @defun x-parse-geometry geom
1125 @cindex geometry specification
1126 The function @code{x-parse-geometry} converts a standard X window
1127 geometry string to an alist that you can use as part of the argument to
1130 The alist describes which parameters were specified in @var{geom}, and
1131 gives the values specified for them. Each element looks like
1132 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
1133 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1135 For the size parameters, the value must be an integer. The position
1136 parameter names @code{left} and @code{top} are not totally accurate,
1137 because some values indicate the position of the right or bottom edges
1138 instead. The @var{value} possibilities for the position parameters are:
1139 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1140 as previously described (@pxref{Position Parameters}).
1145 (x-parse-geometry "35x70+0-0")
1146 @result{} ((height . 70) (width . 35)
1147 (top - 0) (left . 0))
1151 @node Terminal Parameters
1152 @section Terminal Parameters
1153 @cindex terminal parameters
1155 Each terminal has a list of associated parameters. These
1156 @dfn{terminal parameters} are mostly a convenient way of storage for
1157 terminal-local variables, but some terminal parameters have a special
1160 This section describes functions to read and change the parameter values
1161 of a terminal. They all accept as their argument either a terminal or
1162 a frame; the latter means use that frame's terminal. An argument of
1163 @code{nil} means the selected frame's terminal.
1165 @defun terminal-parameters &optional terminal
1166 This function returns an alist listing all the parameters of
1167 @var{terminal} and their values.
1170 @defun terminal-parameter terminal parameter
1171 This function returns the value of the parameter @var{parameter} (a
1172 symbol) of @var{terminal}. If @var{terminal} has no setting for
1173 @var{parameter}, this function returns @code{nil}.
1176 @defun set-terminal-parameter terminal parameter value
1177 This function sets the parameter @var{parm} of @var{terminal} to the
1178 specified @var{value}, and returns the previous value of that
1182 Here's a list of a few terminal parameters that have a special
1186 @item background-mode
1187 The classification of the terminal's background color, either
1188 @code{light} or @code{dark}.
1189 @item normal-erase-is-backspace
1190 Value is either 1 or 0, depending on whether
1191 @code{normal-erase-is-backspace-mode} is turned on or off on this
1192 terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1193 @item terminal-initted
1194 After the terminal is initialized, this is set to the
1195 terminal-specific initialization function.
1199 @section Frame Titles
1202 Every frame has a @code{name} parameter; this serves as the default
1203 for the frame title which window systems typically display at the top of
1204 the frame. You can specify a name explicitly by setting the @code{name}
1207 Normally you don't specify the name explicitly, and Emacs computes the
1208 frame name automatically based on a template stored in the variable
1209 @code{frame-title-format}. Emacs recomputes the name each time the
1210 frame is redisplayed.
1212 @defvar frame-title-format
1213 This variable specifies how to compute a name for a frame when you have
1214 not explicitly specified one. The variable's value is actually a mode
1215 line construct, just like @code{mode-line-format}, except that the
1216 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
1220 @defvar icon-title-format
1221 This variable specifies how to compute the name for an iconified frame,
1222 when you have not explicitly specified the frame title. This title
1223 appears in the icon itself.
1226 @defvar multiple-frames
1227 This variable is set automatically by Emacs. Its value is @code{t} when
1228 there are two or more frames (not counting minibuffer-only frames or
1229 invisible frames). The default value of @code{frame-title-format} uses
1230 @code{multiple-frames} so as to put the buffer name in the frame title
1231 only when there is more than one frame.
1233 The value of this variable is not guaranteed to be accurate except
1234 while processing @code{frame-title-format} or
1235 @code{icon-title-format}.
1238 @node Deleting Frames
1239 @section Deleting Frames
1240 @cindex deleting frames
1242 A @dfn{live frame} is one that has not been deleted. When a frame
1243 is deleted, it is removed from its terminal display, although it may
1244 continue to exist as a Lisp object until there are no more references
1247 @deffn Command delete-frame &optional frame force
1248 @vindex delete-frame-functions
1249 This function deletes the frame @var{frame}. Unless @var{frame} is a
1250 tooltip, it first runs the hook @code{delete-frame-functions} (each
1251 function gets one argument, @var{frame}). By default, @var{frame} is
1254 A frame cannot be deleted if its minibuffer is used by other frames.
1255 Normally, you cannot delete a frame if all other frames are invisible,
1256 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1259 @defun frame-live-p frame
1260 The function @code{frame-live-p} returns non-@code{nil} if the frame
1261 @var{frame} has not been deleted. The possible non-@code{nil} return
1262 values are like those of @code{framep}. @xref{Frames}.
1265 Some window managers provide a command to delete a window. These work
1266 by sending a special message to the program that operates the window.
1267 When Emacs gets one of these commands, it generates a
1268 @code{delete-frame} event, whose normal definition is a command that
1269 calls the function @code{delete-frame}. @xref{Misc Events}.
1271 @node Finding All Frames
1272 @section Finding All Frames
1273 @cindex frames, scanning all
1276 This function returns a list of all the live frames, i.e.@: those that
1277 have not been deleted. It is analogous to @code{buffer-list} for
1278 buffers, and includes frames on all terminals. The list that you get
1279 is newly created, so modifying the list doesn't have any effect on the
1283 @defun visible-frame-list
1284 This function returns a list of just the currently visible frames.
1285 @xref{Visibility of Frames}. Frames on text terminals always count as
1286 ``visible'', even though only the selected one is actually displayed.
1289 @defun next-frame &optional frame minibuf
1290 This function lets you cycle conveniently through all the frames on
1291 the current display from an arbitrary starting point. It returns the
1292 ``next'' frame after @var{frame} in the cycle. If @var{frame} is
1293 omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
1296 The second argument, @var{minibuf}, says which frames to consider:
1300 Exclude minibuffer-only frames.
1301 @item @code{visible}
1302 Consider all visible frames.
1304 Consider all visible or iconified frames.
1306 Consider only the frames using that particular window as their
1309 Consider all frames.
1313 @defun previous-frame &optional frame minibuf
1314 Like @code{next-frame}, but cycles through all frames in the opposite
1318 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1321 @node Minibuffers and Frames
1322 @section Minibuffers and Frames
1324 Normally, each frame has its own minibuffer window at the bottom, which
1325 is used whenever that frame is selected. If the frame has a minibuffer,
1326 you can get it with @code{minibuffer-window} (@pxref{Definition of
1327 minibuffer-window}).
1329 However, you can also create a frame with no minibuffer. Such a frame
1330 must use the minibuffer window of some other frame. When you create the
1331 frame, you can explicitly specify the minibuffer window to use (in some
1332 other frame). If you don't, then the minibuffer is found in the frame
1333 which is the value of the variable @code{default-minibuffer-frame}. Its
1334 value should be a frame that does have a minibuffer.
1336 If you use a minibuffer-only frame, you might want that frame to raise
1337 when you enter the minibuffer. If so, set the variable
1338 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
1340 @defvar default-minibuffer-frame
1341 This variable specifies the frame to use for the minibuffer window, by
1342 default. It does not affect existing frames. It is always local to
1343 the current terminal and cannot be buffer-local. @xref{Multiple
1348 @section Input Focus
1350 @c @cindex selected frame Duplicates selected-frame
1352 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
1353 window always resides on the selected frame.
1355 When Emacs displays its frames on several terminals (@pxref{Multiple
1356 Terminals}), each terminal has its own selected frame. But only one
1357 of these is ``@emph{the} selected frame'': it's the frame that belongs
1358 to the terminal from which the most recent input came. That is, when
1359 Emacs runs a command that came from a certain terminal, the selected
1360 frame is the one of that terminal. Since Emacs runs only a single
1361 command at any given time, it needs to consider only one selected
1362 frame at a time; this frame is what we call @dfn{the selected frame}
1363 in this manual. The display on which the selected frame is shown is
1364 the @dfn{selected frame's display}.
1366 @defun selected-frame
1367 This function returns the selected frame.
1370 Some window systems and window managers direct keyboard input to the
1371 window object that the mouse is in; others require explicit clicks or
1372 commands to @dfn{shift the focus} to various window objects. Either
1373 way, Emacs automatically keeps track of which frame has the focus. To
1374 explicitly switch to a different frame from a Lisp function, call
1375 @code{select-frame-set-input-focus}.
1377 Lisp programs can also switch frames ``temporarily'' by calling the
1378 function @code{select-frame}. This does not alter the window system's
1379 concept of focus; rather, it escapes from the window manager's control
1380 until that control is somehow reasserted.
1382 When using a text terminal, only one frame can be displayed at a time
1383 on the terminal, so after a call to @code{select-frame}, the next
1384 redisplay actually displays the newly selected frame. This frame
1385 remains selected until a subsequent call to @code{select-frame}. Each
1386 frame on a text terminal has a number which appears in the mode line
1387 before the buffer name (@pxref{Mode Line Variables}).
1389 @defun select-frame-set-input-focus frame &optional norecord
1390 This function selects @var{frame}, raises it (should it happen to be
1391 obscured by other frames) and tries to give it the X server's focus.
1392 On a text terminal, the next redisplay displays the new frame on the
1393 entire terminal screen. The optional argument @var{norecord} has the
1394 same meaning as for @code{select-frame} (see below). The return value
1395 of this function is not significant.
1398 @deffn Command select-frame frame &optional norecord
1399 This function selects frame @var{frame}, temporarily disregarding the
1400 focus of the X server if any. The selection of @var{frame} lasts until
1401 the next time the user does something to select a different frame, or
1402 until the next time this function is called. (If you are using a
1403 window system, the previously selected frame may be restored as the
1404 selected frame after return to the command loop, because it still may
1405 have the window system's input focus.)
1407 The specified @var{frame} becomes the selected frame, and its terminal
1408 becomes the selected terminal. This function then calls
1409 @code{select-window} as a subroutine, passing the window selected
1410 within @var{frame} as its first argument and @var{norecord} as its
1411 second argument (hence, if @var{norecord} is non-@code{nil}, this
1412 avoids changing the order of recently selected windows nor the buffer
1413 list). @xref{Selecting Windows}.
1415 This function returns @var{frame}, or @code{nil} if @var{frame} has
1418 In general, you should never use @code{select-frame} in a way that
1419 could switch to a different terminal without switching back when
1423 Emacs cooperates with the window system by arranging to select frames as
1424 the server and window manager request. It does so by generating a
1425 special kind of input event, called a @dfn{focus} event, when
1426 appropriate. The command loop handles a focus event by calling
1427 @code{handle-switch-frame}. @xref{Focus Events}.
1429 @deffn Command handle-switch-frame frame
1430 This function handles a focus event by selecting frame @var{frame}.
1432 Focus events normally do their job by invoking this command.
1433 Don't call it for any other reason.
1436 @defun redirect-frame-focus frame &optional focus-frame
1437 This function redirects focus from @var{frame} to @var{focus-frame}.
1438 This means that @var{focus-frame} will receive subsequent keystrokes and
1439 events intended for @var{frame}. After such an event, the value of
1440 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1441 events specifying @var{frame} will instead select @var{focus-frame}.
1443 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1444 redirection for @var{frame}, which therefore once again receives its own
1447 One use of focus redirection is for frames that don't have minibuffers.
1448 These frames use minibuffers on other frames. Activating a minibuffer
1449 on another frame redirects focus to that frame. This puts the focus on
1450 the minibuffer's frame, where it belongs, even though the mouse remains
1451 in the frame that activated the minibuffer.
1453 Selecting a frame can also change focus redirections. Selecting frame
1454 @code{bar}, when @code{foo} had been selected, changes any redirections
1455 pointing to @code{foo} so that they point to @code{bar} instead. This
1456 allows focus redirection to work properly when the user switches from
1457 one frame to another using @code{select-window}.
1459 This means that a frame whose focus is redirected to itself is treated
1460 differently from a frame whose focus is not redirected.
1461 @code{select-frame} affects the former but not the latter.
1463 The redirection lasts until @code{redirect-frame-focus} is called to
1467 @defopt focus-follows-mouse
1468 This option is how you inform Emacs whether the window manager transfers
1469 focus when the user moves the mouse. Non-@code{nil} says that it does.
1470 When this is so, the command @code{other-frame} moves the mouse to a
1471 position consistent with the new selected frame.
1474 @node Visibility of Frames
1475 @section Visibility of Frames
1476 @cindex visible frame
1477 @cindex invisible frame
1478 @cindex iconified frame
1479 @cindex minimized frame
1480 @cindex frame visibility
1482 A frame on a graphical display may be @dfn{visible}, @dfn{invisible},
1483 or @dfn{iconified}. If it is visible, its contents are displayed in
1484 the usual manner. If it is iconified, its contents are not displayed,
1485 but there is a little icon somewhere to bring the frame back into view
1486 (some window managers refer to this state as @dfn{minimized} rather
1487 than @dfn{iconified}, but from Emacs' point of view they are the same
1488 thing). If a frame is invisible, it is not displayed at all.
1490 Visibility is meaningless on text terminals, since only the selected
1491 one is actually displayed in any case.
1493 @defun frame-visible-p frame
1494 This function returns the visibility status of frame @var{frame}. The
1495 value is @code{t} if @var{frame} is visible, @code{nil} if it is
1496 invisible, and @code{icon} if it is iconified.
1498 On a text terminal, all frames are considered visible, whether they
1499 are currently being displayed or not.
1502 @deffn Command iconify-frame &optional frame
1503 This function iconifies frame @var{frame}. If you omit @var{frame}, it
1504 iconifies the selected frame.
1507 @deffn Command make-frame-visible &optional frame
1508 This function makes frame @var{frame} visible. If you omit
1509 @var{frame}, it makes the selected frame visible. This does not raise
1510 the frame, but you can do that with @code{raise-frame} if you wish
1511 (@pxref{Raising and Lowering}).
1514 @deffn Command make-frame-invisible &optional frame force
1515 This function makes frame @var{frame} invisible. If you omit
1516 @var{frame}, it makes the selected frame invisible.
1518 Unless @var{force} is non-@code{nil}, this function refuses to make
1519 @var{frame} invisible if all other frames are invisible..
1522 The visibility status of a frame is also available as a frame
1523 parameter. You can read or change it as such. @xref{Management
1524 Parameters}. The user can also iconify and deiconify frames with the
1525 window manager. This happens below the level at which Emacs can exert
1526 any control, but Emacs does provide events that you can use to keep
1527 track of such changes. @xref{Misc Events}.
1529 @node Raising and Lowering
1530 @section Raising and Lowering Frames
1532 @cindex raising a frame
1533 @cindex lowering a frame
1534 Most window systems use a desktop metaphor. Part of this metaphor
1535 is the idea that system-level windows (e.g.@: Emacs frames) are
1536 stacked in a notional third dimension perpendicular to the screen
1537 surface. Where two overlap, the one higher up covers the one
1538 underneath. You can @dfn{raise} or @dfn{lower} a frame using the
1539 functions @code{raise-frame} and @code{lower-frame}.
1541 @deffn Command raise-frame &optional frame
1542 This function raises frame @var{frame} (default, the selected frame).
1543 If @var{frame} is invisible or iconified, this makes it visible.
1546 @deffn Command lower-frame &optional frame
1547 This function lowers frame @var{frame} (default, the selected frame).
1550 @defopt minibuffer-auto-raise
1551 If this is non-@code{nil}, activation of the minibuffer raises the frame
1552 that the minibuffer window is in.
1555 You can also enable auto-raise (raising automatically when a frame is
1556 selected) or auto-lower (lowering automatically when it is deselected)
1557 for any frame using frame parameters. @xref{Management Parameters}.
1559 @node Frame Configurations
1560 @section Frame Configurations
1561 @cindex frame configuration
1563 A @dfn{frame configuration} records the current arrangement of frames,
1564 all their properties, and the window configuration of each one.
1565 (@xref{Window Configurations}.)
1567 @defun current-frame-configuration
1568 This function returns a frame configuration list that describes
1569 the current arrangement of frames and their contents.
1572 @defun set-frame-configuration configuration &optional nodelete
1573 This function restores the state of frames described in
1574 @var{configuration}. However, this function does not restore deleted
1577 Ordinarily, this function deletes all existing frames not listed in
1578 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1579 unwanted frames are iconified instead.
1582 @node Mouse Tracking
1583 @section Mouse Tracking
1584 @cindex mouse tracking
1585 @c @cindex tracking the mouse Duplicates track-mouse
1587 Sometimes it is useful to @dfn{track} the mouse, which means to display
1588 something to indicate where the mouse is and move the indicator as the
1589 mouse moves. For efficient mouse tracking, you need a way to wait until
1590 the mouse actually moves.
1592 The convenient way to track the mouse is to ask for events to represent
1593 mouse motion. Then you can wait for motion by waiting for an event. In
1594 addition, you can easily handle any other sorts of events that may
1595 occur. That is useful, because normally you don't want to track the
1596 mouse forever---only until some other event, such as the release of a
1599 @defspec track-mouse body@dots{}
1600 This special form executes @var{body}, with generation of mouse motion
1601 events enabled. Typically, @var{body} would use @code{read-event} to
1602 read the motion events and modify the display accordingly. @xref{Motion
1603 Events}, for the format of mouse motion events.
1605 The value of @code{track-mouse} is that of the last form in @var{body}.
1606 You should design @var{body} to return when it sees the up-event that
1607 indicates the release of the button, or whatever kind of event means
1608 it is time to stop tracking.
1611 The usual purpose of tracking mouse motion is to indicate on the screen
1612 the consequences of pushing or releasing a button at the current
1615 In many cases, you can avoid the need to track the mouse by using
1616 the @code{mouse-face} text property (@pxref{Special Properties}).
1617 That works at a much lower level and runs more smoothly than
1618 Lisp-level mouse tracking.
1621 @c These are not implemented yet.
1623 These functions change the screen appearance instantaneously. The
1624 effect is transient, only until the next ordinary Emacs redisplay. That
1625 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1626 to change the text, and the body of @code{track-mouse} normally reads
1627 the events itself and does not do redisplay.
1629 @defun x-contour-region window beg end
1630 This function draws lines to make a box around the text from @var{beg}
1631 to @var{end}, in window @var{window}.
1634 @defun x-uncontour-region window beg end
1635 This function erases the lines that would make a box around the text
1636 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1637 a contour that you previously made by calling @code{x-contour-region}.
1640 @defun x-draw-rectangle frame left top right bottom
1641 This function draws a hollow rectangle on frame @var{frame} with the
1642 specified edge coordinates, all measured in pixels from the inside top
1643 left corner. It uses the cursor color, the one used for indicating the
1647 @defun x-erase-rectangle frame left top right bottom
1648 This function erases a hollow rectangle on frame @var{frame} with the
1649 specified edge coordinates, all measured in pixels from the inside top
1650 left corner. Erasure means redrawing the text and background that
1651 normally belong in the specified rectangle.
1655 @node Mouse Position
1656 @section Mouse Position
1657 @cindex mouse position
1658 @cindex position of mouse
1660 The functions @code{mouse-position} and @code{set-mouse-position}
1661 give access to the current position of the mouse.
1663 @defun mouse-position
1664 This function returns a description of the position of the mouse. The
1665 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1666 and @var{y} are integers giving the position in characters relative to
1667 the top left corner of the inside of @var{frame}.
1670 @defvar mouse-position-function
1671 If non-@code{nil}, the value of this variable is a function for
1672 @code{mouse-position} to call. @code{mouse-position} calls this
1673 function just before returning, with its normal return value as the
1674 sole argument, and it returns whatever this function returns to it.
1676 This abnormal hook exists for the benefit of packages like
1677 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1680 @defun set-mouse-position frame x y
1681 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1682 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1683 giving the position in characters relative to the top left corner of the
1684 inside of @var{frame}. If @var{frame} is not visible, this function
1685 does nothing. The return value is not significant.
1688 @defun mouse-pixel-position
1689 This function is like @code{mouse-position} except that it returns
1690 coordinates in units of pixels rather than units of characters.
1693 @defun set-mouse-pixel-position frame x y
1694 This function warps the mouse like @code{set-mouse-position} except that
1695 @var{x} and @var{y} are in units of pixels rather than units of
1696 characters. These coordinates are not required to be within the frame.
1698 If @var{frame} is not visible, this function does nothing. The return
1699 value is not significant.
1702 @defun frame-pointer-visible-p &optional frame
1703 This predicate function returns non-@code{nil} if the mouse pointer
1704 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
1705 @var{frame} omitted or @code{nil} means the selected frame. This is
1706 useful when @code{make-pointer-invisible} is set to @code{t}: it
1707 allows to know if the pointer has been hidden.
1708 @xref{Mouse Avoidance,,,emacs, The Emacs Manual}.
1714 @section Pop-Up Menus
1716 When using a window system, a Lisp program can pop up a menu so that
1717 the user can choose an alternative with the mouse.
1719 @defun x-popup-menu position menu
1720 This function displays a pop-up menu and returns an indication of
1721 what selection the user makes.
1723 The argument @var{position} specifies where on the screen to put the
1724 top left corner of the menu. It can be either a mouse button event
1725 (which says to put the menu where the user actuated the button) or a
1729 ((@var{xoffset} @var{yoffset}) @var{window})
1733 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1734 pixels, counting from the top left corner of @var{window}. @var{window}
1735 may be a window or a frame.
1737 If @var{position} is @code{t}, it means to use the current mouse
1738 position. If @var{position} is @code{nil}, it means to precompute the
1739 key binding equivalents for the keymaps specified in @var{menu},
1740 without actually displaying or popping up the menu.
1742 The argument @var{menu} says what to display in the menu. It can be a
1743 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
1744 return value is the list of events corresponding to the user's choice.
1745 This list has more than one element if the choice occurred in a
1746 submenu. (Note that @code{x-popup-menu} does not actually execute the
1747 command bound to that sequence of events.) On toolkits that support
1748 menu titles, the title is taken from the prompt string of @var{menu}
1749 if @var{menu} is a keymap, or from the prompt string of the first
1750 keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
1753 Alternatively, @var{menu} can have the following form:
1756 (@var{title} @var{pane1} @var{pane2}...)
1760 where each pane is a list of form
1763 (@var{title} @var{item1} @var{item2}...)
1766 Each @var{item} should be a cons cell, @code{(@var{line} . @var{value})},
1767 where @var{line} is a string and @var{value} is the value to return if
1768 that @var{line} is chosen. Unlike in a menu keymap, a @code{nil}
1769 @var{value} does not make the menu item non-selectable.
1770 Alternatively, each @var{item} can be a string rather than a cons
1771 cell; this makes a non-selectable menu item.
1773 If the user gets rid of the menu without making a valid choice, for
1774 instance by clicking the mouse away from a valid choice or by typing
1775 keyboard input, then this normally results in a quit and
1776 @code{x-popup-menu} does not return. But if @var{position} is a mouse
1777 button event (indicating that the user invoked the menu with the
1778 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1781 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1782 if you could do the job with a prefix key defined with a menu keymap.
1783 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1784 a} can see the individual items in that menu and provide help for them.
1785 If instead you implement the menu by defining a command that calls
1786 @code{x-popup-menu}, the help facilities cannot know what happens inside
1787 that command, so they cannot give any help for the menu's items.
1789 The menu bar mechanism, which lets you switch between submenus by
1790 moving the mouse, cannot look within the definition of a command to see
1791 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1792 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1793 an integrated fashion. This is why all menu bar submenus are
1794 implemented with menu keymaps within the parent menu, and never with
1795 @code{x-popup-menu}. @xref{Menu Bar}.
1797 If you want a menu bar submenu to have contents that vary, you should
1798 still use a menu keymap to implement it. To make the contents vary, add
1799 a hook function to @code{menu-bar-update-hook} to update the contents of
1800 the menu keymap as necessary.
1803 @section Dialog Boxes
1804 @cindex dialog boxes
1806 A dialog box is a variant of a pop-up menu---it looks a little
1807 different, it always appears in the center of a frame, and it has just
1808 one level and one or more buttons. The main use of dialog boxes is
1809 for asking questions that the user can answer with ``yes'', ``no'',
1810 and a few other alternatives. With a single button, they can also
1811 force the user to acknowledge important information. The functions
1812 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1813 keyboard, when called from commands invoked by mouse clicks.
1815 @defun x-popup-dialog position contents &optional header
1816 This function displays a pop-up dialog box and returns an indication of
1817 what selection the user makes. The argument @var{contents} specifies
1818 the alternatives to offer; it has this format:
1821 (@var{title} (@var{string} . @var{value})@dots{})
1825 which looks like the list that specifies a single pane for
1826 @code{x-popup-menu}.
1828 The return value is @var{value} from the chosen alternative.
1830 As for @code{x-popup-menu}, an element of the list may be just a
1831 string instead of a cons cell @code{(@var{string} . @var{value})}.
1832 That makes a box that cannot be selected.
1834 If @code{nil} appears in the list, it separates the left-hand items from
1835 the right-hand items; items that precede the @code{nil} appear on the
1836 left, and items that follow the @code{nil} appear on the right. If you
1837 don't include a @code{nil} in the list, then approximately half the
1838 items appear on each side.
1840 Dialog boxes always appear in the center of a frame; the argument
1841 @var{position} specifies which frame. The possible values are as in
1842 @code{x-popup-menu}, but the precise coordinates or the individual
1843 window don't matter; only the frame matters.
1845 If @var{header} is non-@code{nil}, the frame title for the box is
1846 @samp{Information}, otherwise it is @samp{Question}. The former is used
1847 for @code{message-box} (@pxref{message-box}).
1849 In some configurations, Emacs cannot display a real dialog box; so
1850 instead it displays the same items in a pop-up menu in the center of the
1853 If the user gets rid of the dialog box without making a valid choice,
1854 for instance using the window manager, then this produces a quit and
1855 @code{x-popup-dialog} does not return.
1859 @section Pointer Shape
1860 @cindex pointer shape
1861 @cindex mouse pointer shape
1863 You can specify the mouse pointer style for particular text or
1864 images using the @code{pointer} text property, and for images with the
1865 @code{:pointer} and @code{:map} image properties. The values you can
1866 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1867 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1868 @code{hourglass}. @code{text} stands for the usual mouse pointer
1869 style used over text.
1871 Over void parts of the window (parts that do not correspond to any
1872 of the buffer contents), the mouse pointer usually uses the
1873 @code{arrow} style, but you can specify a different style (one of
1874 those above) by setting @code{void-text-area-pointer}.
1876 @defopt void-text-area-pointer
1877 This variable specifies the mouse pointer style for void text areas.
1878 These include the areas after the end of a line or below the last line
1879 in the buffer. The default is to use the @code{arrow} (non-text)
1883 When using X, you can specify what the @code{text} pointer style
1884 really looks like by setting the variable @code{x-pointer-shape}.
1886 @defvar x-pointer-shape
1887 This variable specifies the pointer shape to use ordinarily in the
1888 Emacs frame, for the @code{text} pointer style.
1891 @defvar x-sensitive-text-pointer-shape
1892 This variable specifies the pointer shape to use when the mouse
1893 is over mouse-sensitive text.
1896 These variables affect newly created frames. They do not normally
1897 affect existing frames; however, if you set the mouse color of a
1898 frame, that also installs the current value of those two variables.
1899 @xref{Font and Color Parameters}.
1901 The values you can use, to specify either of these pointer shapes, are
1902 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1903 @key{RET} x-pointer @key{RET}} to see a list of them.
1905 @node Window System Selections
1906 @section Window System Selections
1907 @cindex selection (for window systems)
1909 @cindex primary selection
1910 @cindex secondary selection
1912 In the X window system, data can be transferred between different
1913 applications by means of @dfn{selections}. X defines an arbitrary
1914 number of @dfn{selection types}, each of which can store its own data;
1915 however, only three are commonly used: the @dfn{clipboard},
1916 @dfn{primary selection}, and @dfn{secondary selection}. @xref{Cut and
1917 Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
1918 commands that make use of these selections. This section documents
1919 the low-level functions for reading and setting X selections.
1921 @deffn Command x-set-selection type data
1922 This function sets an X selection. It takes two arguments: a
1923 selection type @var{type}, and the value to assign to it, @var{data}.
1925 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
1926 @code{SECONDARY} or @code{CLIPBOARD}. These are symbols with
1927 upper-case names, in accord with X Window System conventions. If
1928 @var{type} is @code{nil}, that stands for @code{PRIMARY}.
1930 If @var{data} is @code{nil}, it means to clear out the selection.
1931 Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
1932 of two integers or list of two integers), an overlay, or a cons of two
1933 markers pointing to the same buffer. An overlay or a pair of markers
1934 stands for text in the overlay or between the markers. The argument
1935 @var{data} may also be a vector of valid non-vector selection values.
1937 This function returns @var{data}.
1940 @defun x-get-selection &optional type data-type
1941 This function accesses selections set up by Emacs or by other X
1942 clients. It takes two optional arguments, @var{type} and
1943 @var{data-type}. The default for @var{type}, the selection type, is
1946 The @var{data-type} argument specifies the form of data conversion to
1947 use, to convert the raw data obtained from another X client into Lisp
1948 data. Meaningful values include @code{TEXT}, @code{STRING},
1949 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1950 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1951 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1952 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
1953 @code{INTEGER}. (These are symbols with upper-case names in accord
1954 with X conventions.) The default for @var{data-type} is
1958 @defopt selection-coding-system
1959 This variable specifies the coding system to use when reading and
1960 writing selections or the clipboard. @xref{Coding
1961 Systems}. The default is @code{compound-text-with-extensions}, which
1962 converts to the text representation that X11 normally uses.
1965 @cindex clipboard support (for MS-Windows)
1966 When Emacs runs on MS-Windows, it does not implement X selections in
1967 general, but it does support the clipboard. @code{x-get-selection}
1968 and @code{x-set-selection} on MS-Windows support the text data type
1969 only; if the clipboard holds other types of data, Emacs treats the
1973 @section Drag and Drop
1975 @vindex x-dnd-test-function
1976 @vindex x-dnd-known-types
1977 When a user drags something from another application over Emacs, that other
1978 application expects Emacs to tell it if Emacs can handle the data that is
1979 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
1980 what to reply. The default value is @code{x-dnd-default-test-function}
1981 which accepts drops if the type of the data to be dropped is present in
1982 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
1983 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
1984 on some other criteria.
1986 @vindex x-dnd-types-alist
1987 If you want to change the way Emacs handles drop of different types
1988 or add a new type, customize @code{x-dnd-types-alist}. This requires
1989 detailed knowledge of what types other applications use for drag and
1992 @vindex dnd-protocol-alist
1993 When an URL is dropped on Emacs it may be a file, but it may also be
1994 another URL type (ftp, http, etc.). Emacs first checks
1995 @code{dnd-protocol-alist} to determine what to do with the URL. If
1996 there is no match there and if @code{browse-url-browser-function} is
1997 an alist, Emacs looks for a match there. If no match is found the
1998 text for the URL is inserted. If you want to alter Emacs behavior,
1999 you can customize these variables.
2002 @section Color Names
2005 @cindex specify color
2006 @cindex numerical RGB color specification
2007 A color name is text (usually in a string) that specifies a color.
2008 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2009 are allowed; use @kbd{M-x list-colors-display} to see a list of
2010 defined names. You can also specify colors numerically in forms such
2011 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2012 @var{r} specifies the red level, @var{g} specifies the green level,
2013 and @var{b} specifies the blue level. You can use either one, two,
2014 three, or four hex digits for @var{r}; then you must use the same
2015 number of hex digits for all @var{g} and @var{b} as well, making
2016 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
2017 X Window System for more details about numerical RGB specification of
2020 These functions provide a way to determine which color names are
2021 valid, and what they look like. In some cases, the value depends on the
2022 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2023 meaning of the term ``selected frame''.
2025 To read user input of color names with completion, use
2026 @code{read-color} (@pxref{High-Level Completion, read-color}).
2028 @defun color-defined-p color &optional frame
2029 This function reports whether a color name is meaningful. It returns
2030 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
2031 which frame's display to ask about; if @var{frame} is omitted or
2032 @code{nil}, the selected frame is used.
2034 Note that this does not tell you whether the display you are using
2035 really supports that color. When using X, you can ask for any defined
2036 color on any kind of display, and you will get some result---typically,
2037 the closest it can do. To determine whether a frame can really display
2038 a certain color, use @code{color-supported-p} (see below).
2040 @findex x-color-defined-p
2041 This function used to be called @code{x-color-defined-p},
2042 and that name is still supported as an alias.
2045 @defun defined-colors &optional frame
2046 This function returns a list of the color names that are defined
2047 and supported on frame @var{frame} (default, the selected frame).
2048 If @var{frame} does not support colors, the value is @code{nil}.
2050 @findex x-defined-colors
2051 This function used to be called @code{x-defined-colors},
2052 and that name is still supported as an alias.
2055 @defun color-supported-p color &optional frame background-p
2056 This returns @code{t} if @var{frame} can really display the color
2057 @var{color} (or at least something close to it). If @var{frame} is
2058 omitted or @code{nil}, the question applies to the selected frame.
2060 Some terminals support a different set of colors for foreground and
2061 background. If @var{background-p} is non-@code{nil}, that means you are
2062 asking whether @var{color} can be used as a background; otherwise you
2063 are asking whether it can be used as a foreground.
2065 The argument @var{color} must be a valid color name.
2068 @defun color-gray-p color &optional frame
2069 This returns @code{t} if @var{color} is a shade of gray, as defined on
2070 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
2071 question applies to the selected frame. If @var{color} is not a valid
2072 color name, this function returns @code{nil}.
2075 @defun color-values color &optional frame
2077 This function returns a value that describes what @var{color} should
2078 ideally look like on @var{frame}. If @var{color} is defined, the
2079 value is a list of three integers, which give the amount of red, the
2080 amount of green, and the amount of blue. Each integer ranges in
2081 principle from 0 to 65535, but some displays may not use the full
2082 range. This three-element list is called the @dfn{rgb values} of the
2085 If @var{color} is not defined, the value is @code{nil}.
2088 (color-values "black")
2090 (color-values "white")
2091 @result{} (65280 65280 65280)
2092 (color-values "red")
2093 @result{} (65280 0 0)
2094 (color-values "pink")
2095 @result{} (65280 49152 51968)
2096 (color-values "hungry")
2100 The color values are returned for @var{frame}'s display. If
2101 @var{frame} is omitted or @code{nil}, the information is returned for
2102 the selected frame's display. If the frame cannot display colors, the
2103 value is @code{nil}.
2105 @findex x-color-values
2106 This function used to be called @code{x-color-values},
2107 and that name is still supported as an alias.
2110 @node Text Terminal Colors
2111 @section Text Terminal Colors
2112 @cindex colors on text terminals
2114 Text terminals usually support only a small number of colors, and
2115 the computer uses small integers to select colors on the terminal.
2116 This means that the computer cannot reliably tell what the selected
2117 color looks like; instead, you have to inform your application which
2118 small integers correspond to which colors. However, Emacs does know
2119 the standard set of colors and will try to use them automatically.
2121 The functions described in this section control how terminal colors
2124 Several of these functions use or return @dfn{rgb values}, described
2125 in @ref{Color Names}.
2127 These functions accept a display (either a frame or the name of a
2128 terminal) as an optional argument. We hope in the future to make
2129 Emacs support different colors on different text terminals; then this
2130 argument will specify which terminal to operate on (the default being
2131 the selected frame's terminal; @pxref{Input Focus}). At present,
2132 though, the @var{frame} argument has no effect.
2134 @defun tty-color-define name number &optional rgb frame
2135 This function associates the color name @var{name} with
2136 color number @var{number} on the terminal.
2138 The optional argument @var{rgb}, if specified, is an rgb value, a list
2139 of three numbers that specify what the color actually looks like.
2140 If you do not specify @var{rgb}, then this color cannot be used by
2141 @code{tty-color-approximate} to approximate other colors, because
2142 Emacs will not know what it looks like.
2145 @defun tty-color-clear &optional frame
2146 This function clears the table of defined colors for a text terminal.
2149 @defun tty-color-alist &optional frame
2150 This function returns an alist recording the known colors supported by
2153 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2154 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
2155 name, @var{number} is the number used to specify it to the terminal.
2156 If present, @var{rgb} is a list of three color values (for red, green,
2157 and blue) that says what the color actually looks like.
2160 @defun tty-color-approximate rgb &optional frame
2161 This function finds the closest color, among the known colors
2162 supported for @var{display}, to that described by the rgb value
2163 @var{rgb} (a list of color values). The return value is an element of
2164 @code{tty-color-alist}.
2167 @defun tty-color-translate color &optional frame
2168 This function finds the closest color to @var{color} among the known
2169 colors supported for @var{display} and returns its index (an integer).
2170 If the name @var{color} is not defined, the value is @code{nil}.
2174 @section X Resources
2176 This section describes some of the functions and variables for
2177 querying and using X resources, or their equivalent on your operating
2178 system. @xref{X Resources,, X Resources, emacs, The GNU Emacs
2179 Manual}, for more information about X resources.
2181 @defun x-get-resource attribute class &optional component subclass
2182 The function @code{x-get-resource} retrieves a resource value from the X
2183 Window defaults database.
2185 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2186 This function searches using a key of the form
2187 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2188 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2191 The optional arguments @var{component} and @var{subclass} add to the key
2192 and the class, respectively. You must specify both of them or neither.
2193 If you specify them, the key is
2194 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2195 @samp{Emacs.@var{class}.@var{subclass}}.
2198 @defvar x-resource-class
2199 This variable specifies the application name that @code{x-get-resource}
2200 should look up. The default value is @code{"Emacs"}. You can examine X
2201 resources for application names other than ``Emacs'' by binding this
2202 variable to some other string, around a call to @code{x-get-resource}.
2205 @defvar x-resource-name
2206 This variable specifies the instance name that @code{x-get-resource}
2207 should look up. The default value is the name Emacs was invoked with,
2208 or the value specified with the @samp{-name} or @samp{-rn} switches.
2211 To illustrate some of the above, suppose that you have the line:
2214 xterm.vt100.background: yellow
2218 in your X resources file (whose name is usually @file{~/.Xdefaults}
2219 or @file{~/.Xresources}). Then:
2223 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2224 (x-get-resource "vt100.background" "VT100.Background"))
2228 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2229 (x-get-resource "background" "VT100" "vt100" "Background"))
2234 @defvar inhibit-x-resources
2235 If this variable is non-@code{nil}, Emacs does not look up X
2236 resources, and X resources do not have any effect when creating new
2240 @node Display Feature Testing
2241 @section Display Feature Testing
2242 @cindex display feature testing
2244 The functions in this section describe the basic capabilities of a
2245 particular display. Lisp programs can use them to adapt their behavior
2246 to what the display can do. For example, a program that ordinarily uses
2247 a popup menu could use the minibuffer if popup menus are not supported.
2249 The optional argument @var{display} in these functions specifies which
2250 display to ask the question about. It can be a display name, a frame
2251 (which designates the display that frame is on), or @code{nil} (which
2252 refers to the selected frame's display, @pxref{Input Focus}).
2254 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2255 obtain information about displays.
2257 @defun display-popup-menus-p &optional display
2258 This function returns @code{t} if popup menus are supported on
2259 @var{display}, @code{nil} if not. Support for popup menus requires that
2260 the mouse be available, since the user cannot choose menu items without
2264 @defun display-graphic-p &optional display
2265 This function returns @code{t} if @var{display} is a graphic display
2266 capable of displaying several frames and several different fonts at
2267 once. This is true for displays that use a window system such as X,
2268 and false for text terminals.
2271 @defun display-mouse-p &optional display
2272 @cindex mouse, availability
2273 This function returns @code{t} if @var{display} has a mouse available,
2277 @defun display-color-p &optional display
2278 @findex x-display-color-p
2279 This function returns @code{t} if the screen is a color screen.
2280 It used to be called @code{x-display-color-p}, and that name
2281 is still supported as an alias.
2284 @defun display-grayscale-p &optional display
2285 This function returns @code{t} if the screen can display shades of gray.
2286 (All color displays can do this.)
2289 @defun display-supports-face-attributes-p attributes &optional display
2290 @anchor{Display Face Attribute Testing}
2291 This function returns non-@code{nil} if all the face attributes in
2292 @var{attributes} are supported (@pxref{Face Attributes}).
2294 The definition of `supported' is somewhat heuristic, but basically
2295 means that a face containing all the attributes in @var{attributes},
2296 when merged with the default face for display, can be represented in a
2301 different in appearance than the default face, and
2304 `close in spirit' to what the attributes specify, if not exact.
2307 Point (2) implies that a @code{:weight black} attribute will be
2308 satisfied by any display that can display bold, as will
2309 @code{:foreground "yellow"} as long as some yellowish color can be
2310 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2311 the tty display code's automatic substitution of a `dim' face for
2315 @defun display-selections-p &optional display
2316 This function returns @code{t} if @var{display} supports selections.
2317 Windowed displays normally support selections, but they may also be
2318 supported in some other cases.
2321 @defun display-images-p &optional display
2322 This function returns @code{t} if @var{display} can display images.
2323 Windowed displays ought in principle to handle images, but some
2324 systems lack the support for that. On a display that does not support
2325 images, Emacs cannot display a tool bar.
2328 @defun display-screens &optional display
2329 This function returns the number of screens associated with the display.
2332 @defun display-pixel-height &optional display
2333 This function returns the height of the screen in pixels.
2334 On a character terminal, it gives the height in characters.
2336 For graphical terminals, note that on ``multi-monitor'' setups this
2337 refers to the pixel width for all physical monitors associated with
2338 @var{display}. @xref{Multiple Terminals}.
2341 @defun display-pixel-width &optional display
2342 This function returns the width of the screen in pixels.
2343 On a character terminal, it gives the width in characters.
2345 For graphical terminals, note that on ``multi-monitor'' setups this
2346 refers to the pixel width for all physical monitors associated with
2347 @var{display}. @xref{Multiple Terminals}.
2350 @defun display-mm-height &optional display
2351 This function returns the height of the screen in millimeters,
2352 or @code{nil} if Emacs cannot get that information.
2355 @defun display-mm-width &optional display
2356 This function returns the width of the screen in millimeters,
2357 or @code{nil} if Emacs cannot get that information.
2360 @defopt display-mm-dimensions-alist
2361 This variable allows the user to specify the dimensions of graphical
2362 displays returned by @code{display-mm-height} and
2363 @code{display-mm-width} in case the system provides incorrect values.
2366 @defun display-backing-store &optional display
2367 This function returns the backing store capability of the display.
2368 Backing store means recording the pixels of windows (and parts of
2369 windows) that are not exposed, so that when exposed they can be
2370 displayed very quickly.
2372 Values can be the symbols @code{always}, @code{when-mapped}, or
2373 @code{not-useful}. The function can also return @code{nil}
2374 when the question is inapplicable to a certain kind of display.
2377 @defun display-save-under &optional display
2378 This function returns non-@code{nil} if the display supports the
2379 SaveUnder feature. That feature is used by pop-up windows
2380 to save the pixels they obscure, so that they can pop down
2384 @defun display-planes &optional display
2385 This function returns the number of planes the display supports.
2386 This is typically the number of bits per pixel.
2387 For a tty display, it is log to base two of the number of colors supported.
2390 @defun display-visual-class &optional display
2391 This function returns the visual class for the screen. The value is
2392 one of the symbols @code{static-gray} (a limited, unchangeable number
2393 of grays), @code{gray-scale} (a full range of grays),
2394 @code{static-color} (a limited, unchangeable number of colors),
2395 @code{pseudo-color} (a limited number of colors), @code{true-color} (a
2396 full range of colors), and @code{direct-color} (a full range of
2400 @defun display-color-cells &optional display
2401 This function returns the number of color cells the screen supports.
2404 These functions obtain additional information specifically
2407 @defun x-server-version &optional display
2408 This function returns the list of version numbers of the X server
2409 running the display. The value is a list of three integers: the major
2410 and minor version numbers of the X protocol, and the
2411 distributor-specific release number of the X server software itself.
2414 @defun x-server-vendor &optional display
2415 This function returns the ``vendor'' that provided the X server
2416 software (as a string). Really this means whoever distributes the X
2419 When the developers of X labeled software distributors as
2420 ``vendors'', they showed their false assumption that no system could
2421 ever be developed and distributed noncommercially.
2425 @defvar x-no-window-manager
2426 This variable's value is @code{t} if no X window manager is in use.
2432 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2433 width and height of an X Window frame, measured in pixels.