2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2011
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/frames
7 @node Frames, Positions, Windows, Top
11 A @dfn{frame} is a screen object that contains one or more Emacs
12 windows (@pxref{Windows}). It is the kind of object called a
13 ``window'' in the terminology of graphical environments; but we can't
14 call it a ``window'' here, because Emacs uses that word in a different
15 way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that
16 represents a frame on the screen. @xref{Frame Type}.
18 A frame initially contains a single main window and/or a minibuffer
19 window; you can subdivide the main window vertically or horizontally
20 into smaller windows. @xref{Splitting Windows}.
23 A @dfn{terminal} is a display device capable of displaying one or
24 more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp
25 object that represents a terminal. @xref{Terminal Type}.
27 @cindex terminal frame
29 There are two classes of terminals: text-only terminals and
30 graphical terminals. Text-only terminals are non-graphics-capable
31 display devices, including ``terminal emulators'' such as xterm. On
32 text-only terminals, each frame occupies the entire terminal screen;
33 although you can create additional frames and switch between them,
34 only one frame can be shown at any given time. We refer to frames on
35 text-only terminals as @dfn{terminal frames}. Graphical terminals, on
36 the other hand, are graphics-capable windowing systems, such as the X
37 Window System. On a graphical terminal, Emacs can display multiple
38 frames simultaneously. We refer to such frames as @dfn{window
41 On GNU and Unix systems, you can create additional frames on any
42 available terminal, within a single Emacs session, regardless of
43 whether Emacs was started on a text-only or graphical terminal. Emacs
44 can display on both graphical and text-only terminals simultaneously.
45 This comes in handy, for instance, when you connect to the same
46 session from several remote locations. @xref{Multiple Terminals}.
49 This predicate returns a non-@code{nil} value if @var{object} is a
50 frame, and @code{nil} otherwise. For a frame, the value indicates which
51 kind of display the frame uses:
55 The frame is displayed in an X window.
57 A terminal frame on a character display.
59 The frame is displayed on MS-Windows 9X/NT.
61 The frame is displayed on a GNUstep or Macintosh Cocoa display.
63 The frame is displayed on an MS-DOS terminal.
67 @defun frame-terminal &optional frame
68 This function returns the terminal object that displays @var{frame}.
69 If @var{frame} is @code{nil} or unspecified, it defaults to the
73 @defun terminal-live-p object
74 This predicate returns a non-@code{nil} value if @var{object} is a
75 terminal that is alive (i.e.@: was not deleted), and @code{nil}
76 otherwise. For live terminals, the return value indicates what kind
77 of frames are displayed on that terminal; the list of possible values
78 is the same as for @code{framep} above.
82 * Creating Frames:: Creating additional frames.
83 * Multiple Terminals:: Displaying on several different devices.
84 * Frame Parameters:: Controlling frame size, position, font, etc.
85 * Terminal Parameters:: Parameters common for all frames on terminal.
86 * Frame Titles:: Automatic updating of frame titles.
87 * Deleting Frames:: Frames last until explicitly deleted.
88 * Finding All Frames:: How to examine all existing frames.
89 * Frames and Windows:: A frame contains windows;
90 display of text always works through windows.
91 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
92 * Input Focus:: Specifying the selected frame.
93 * Visibility of Frames:: Frames may be visible or invisible, or icons.
94 * Raising and Lowering:: Raising a frame makes it hide other windows;
95 lowering it makes the others hide it.
96 * Frame Configurations:: Saving the state of all frames.
97 * Mouse Tracking:: Getting events that say when the mouse moves.
98 * Mouse Position:: Asking where the mouse is, or moving it.
99 * Pop-Up Menus:: Displaying a menu for the user to select from.
100 * Dialog Boxes:: Displaying a box to ask yes or no.
101 * Pointer Shape:: Specifying the shape of the mouse pointer.
102 * Window System Selections:: Transferring text to and from other X clients.
103 * Drag and Drop:: Internals of Drag-and-Drop implementation.
104 * Color Names:: Getting the definitions of color names.
105 * Text Terminal Colors:: Defining colors for text-only terminals.
106 * Resources:: Getting resource values from the server.
107 * Display Feature Testing:: Determining the features of a terminal.
110 @node Creating Frames
111 @section Creating Frames
113 To create a new frame, call the function @code{make-frame}.
115 @defun make-frame &optional alist
116 This function creates and returns a new frame, displaying the current
119 The @var{alist} argument is an alist that specifies frame parameters
120 for the new frame. @xref{Frame Parameters}. If you specify the
121 @code{terminal} parameter in @var{alist}, the new frame is created on
122 that terminal. Otherwise, if you specify the @code{window-system}
123 frame parameter in @var{alist}, that determines whether the frame
124 should be displayed on a text-only or graphical terminal.
125 @xref{Window Systems}. If neither is specified, the new frame is
126 created in the same terminal as the selected frame.
128 Any parameters not mentioned in @var{alist} default to the values in
129 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
130 parameters not specified there default from the X resources or its
131 equivalent on your operating system (@pxref{X Resources,, X Resources,
132 emacs, The GNU Emacs Manual}). After the frame is created, Emacs
133 applies any parameters listed in @code{frame-inherited-parameters}
134 (see below) and not present in the argument, taking the values from
135 the frame that was selected when @code{make-frame} was called.
137 This function itself does not make the new frame the selected frame.
138 @xref{Input Focus}. The previously selected frame remains selected.
139 On graphical terminals, however, the windowing system may select the
140 new frame for its own reasons.
143 @defvar before-make-frame-hook
144 A normal hook run by @code{make-frame} before it creates the frame.
147 @defvar after-make-frame-functions
148 An abnormal hook run by @code{make-frame} after it creates the frame.
149 Each function in @code{after-make-frame-functions} receives one argument, the
153 @defvar frame-inherited-parameters
154 This variable specifies the list of frame parameters that a newly
155 created frame inherits from the currently selected frame. For each
156 parameter (a symbol) that is an element in the list and is not present
157 in the argument to @code{make-frame}, the function sets the value of
158 that parameter in the created frame to its value in the selected
162 @node Multiple Terminals
163 @section Multiple Terminals
164 @cindex multiple terminals
166 @cindex multiple X displays
167 @cindex displays, multiple
169 Emacs represents each terminal, whether graphical or text-only, as a
170 @dfn{terminal object} data type (@pxref{Terminal Type}). On GNU and
171 Unix systems, Emacs can use multiple terminals simultaneously in each
172 session. On other systems, it can only use a single terminal. Each
173 terminal object has the following attributes:
177 The name of the device used by the terminal (e.g., @samp{:0.0} or
181 The terminal and keyboard coding systems used on the terminal.
182 @xref{Terminal I/O Encoding}.
185 The kind of display associated with the terminal. This is the symbol
186 returned by the function @code{terminal-live-p} (i.e., @code{x},
187 @code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.
190 A list of terminal parameters. @xref{Terminal Parameters}.
193 There is no primitive for creating terminal objects. Emacs creates
194 them as needed, such as when you call @code{make-frame-on-display}
195 (which is described below).
197 @defun terminal-name &optional terminal
198 This function returns the file name of the device used by
199 @var{terminal}. If @var{terminal} is omitted or @code{nil}, it
200 defaults to the selected frame's terminal. @var{terminal} can also be
201 a frame, meaning that frame's terminal.
205 This function returns a list of all terminal objects currently in use.
208 @defun get-device-terminal device
209 This function returns a terminal whose device name is given by
210 @var{device}. If @var{device} is a string, it can be either the file
211 name of a terminal device, or the name of an X display of the form
212 @samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a
213 frame, this function returns that frame's terminal; @code{nil} means
214 the selected frame. Finally, if @var{device} is a terminal object
215 that represents a live terminal, that terminal is returned. The
216 function signals an error if its argument is none of the above.
219 @defun delete-terminal &optional terminal force
220 This function deletes all frames on @var{terminal} and frees the
221 resources used by it. It runs the abnormal hook
222 @code{delete-terminal-functions}, passing @var{terminal} as the
223 argument to each function.
225 If @var{terminal} is omitted or @code{nil}, it defaults to the
226 selected frame's terminal. @var{terminal} can also be a frame,
227 meaning that frame's terminal.
229 Normally, this function signals an error if you attempt to delete the
230 sole active terminal, but if @var{force} is non-@code{nil}, you are
231 allowed to do so. Emacs automatically calls this function when the
232 last frame on a terminal is deleted (@pxref{Deleting Frames}).
235 @defvar delete-terminal-functions
236 An abnormal hook run by @code{delete-terminal}. Each function
237 receives one argument, the @var{terminal} argument passed to
238 @code{delete-terminal}. Due to technical details, the functions may
239 be called either just before the terminal is deleted, or just
243 @cindex terminal-local variables
244 A few Lisp variables are @dfn{terminal-local}; that is, they have a
245 separate binding for each terminal. The binding in effect at any time
246 is the one for the terminal that the currently selected frame belongs
247 to. These variables include @code{default-minibuffer-frame},
248 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
249 @code{system-key-alist}. They are always terminal-local, and can
250 never be buffer-local (@pxref{Buffer-Local Variables}).
252 On GNU and Unix systems, each X display is a separate graphical
253 terminal. When Emacs is started from within the X window system, it
254 uses the X display chosen with the @code{DISPLAY} environment
255 variable, or with the @samp{--display} option. @xref{Initial
256 Options,,, emacs, The GNU Emacs Manual}. Emacs can connect to other X
257 displays via the command @code{make-frame-on-display}. Each X display
258 has its own selected frame and its own minibuffer windows; however,
259 only one of those frames is ``@emph{the} selected frame'' at any given
260 moment (@pxref{Input Focus}). Emacs can even connect to other
261 text-only terminals, by interacting with the @command{emacsclient}
262 program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
264 A single X server can handle more than one display. Each X display
265 has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
266 The first two parts, @var{host} and @var{server}, identify the X
267 server; the third part, @var{screen}, identifies a screen number on
268 that X server. When you use two or more screens belonging to one
269 server, Emacs knows by the similarity in their names that they share a
272 On some ``multi-monitor'' setups, a single X display outputs to more
273 than one monitor. Currently, there is no way for Emacs to distinguish
274 between the different physical monitors.
276 @deffn Command make-frame-on-display display &optional parameters
277 This function creates and returns a new frame on @var{display}, taking
278 the other frame parameters from the alist @var{parameters}.
279 @var{display} should be the name of an X display (a string).
281 Before creating the frame, this function ensures that Emacs is ``set
282 up'' to display graphics. For instance, if Emacs has not processed X
283 resources (e.g., if it was started on a text-only terminal), it does
284 so at this time. In all other respects, this function behaves like
285 @code{make-frame} (@pxref{Creating Frames}).
288 @defun x-display-list
289 This function returns a list that indicates which X displays Emacs has
290 a connection to. The elements of the list are strings, and each one
294 @defun x-open-connection display &optional xrm-string must-succeed
295 This function opens a connection to the X display @var{display},
296 without creating a frame on that display. Normally, Emacs Lisp
297 programs need not call this function, as @code{make-frame-on-display}
298 calls it automatically. The only reason for calling it is to check
299 whether communication can be established with a given X display.
301 The optional argument @var{xrm-string}, if not @code{nil}, is a string
302 of resource names and values, in the same format used in the
303 @file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The
304 GNU Emacs Manual}. These values apply to all Emacs frames created on
305 this display, overriding the resource values recorded in the X server.
306 Here's an example of what this string might look like:
309 "*BorderWidth: 3\n*InternalBorder: 2\n"
312 If @var{must-succeed} is non-@code{nil}, failure to open the connection
313 terminates Emacs. Otherwise, it is an ordinary Lisp error.
316 @defun x-close-connection display
317 This function closes the connection to display @var{display}. Before
318 you can do this, you must first delete all the frames that were open
319 on that display (@pxref{Deleting Frames}).
322 @node Frame Parameters
323 @section Frame Parameters
324 @cindex frame parameters
326 A frame has many parameters that control its appearance and behavior.
327 Just what parameters a frame has depends on what display mechanism it
330 Frame parameters exist mostly for the sake of window systems. A
331 terminal frame has a few parameters, mostly for compatibility's sake;
332 only the @code{height}, @code{width}, @code{name}, @code{title},
333 @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
334 parameters do something special. If the terminal supports colors, the
335 parameters @code{foreground-color}, @code{background-color},
336 @code{background-mode} and @code{display-type} are also meaningful.
337 If the terminal supports frame transparency, the parameter
338 @code{alpha} is also meaningful.
341 * Parameter Access:: How to change a frame's parameters.
342 * Initial Parameters:: Specifying frame parameters when you make a frame.
343 * Window Frame Parameters:: List of frame parameters for window systems.
344 * Size and Position:: Changing the size and position of a frame.
345 * Geometry:: Parsing geometry specifications.
348 @node Parameter Access
349 @subsection Access to Frame Parameters
351 These functions let you read and change the parameter values of a
354 @defun frame-parameter frame parameter
355 This function returns the value of the parameter @var{parameter} (a
356 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
357 selected frame's parameter. If @var{frame} has no setting for
358 @var{parameter}, this function returns @code{nil}.
361 @defun frame-parameters &optional frame
362 The function @code{frame-parameters} returns an alist listing all the
363 parameters of @var{frame} and their values. If @var{frame} is
364 @code{nil} or omitted, this returns the selected frame's parameters
367 @defun modify-frame-parameters frame alist
368 This function alters the parameters of frame @var{frame} based on the
369 elements of @var{alist}. Each element of @var{alist} has the form
370 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
371 parameter. If you don't mention a parameter in @var{alist}, its value
372 doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
376 @defun set-frame-parameter frame parm value
377 This function sets the frame parameter @var{parm} to the specified
378 @var{value}. If @var{frame} is @code{nil}, it defaults to the
382 @defun modify-all-frames-parameters alist
383 This function alters the frame parameters of all existing frames
384 according to @var{alist}, then modifies @code{default-frame-alist}
385 (and, if necessary, @code{initial-frame-alist}) to apply the same
386 parameter values to frames that will be created henceforth.
389 @node Initial Parameters
390 @subsection Initial Frame Parameters
392 You can specify the parameters for the initial startup frame
393 by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
395 @defopt initial-frame-alist
396 This variable's value is an alist of parameter values used when creating
397 the initial window frame. You can set this variable to specify the
398 appearance of the initial frame without altering subsequent frames.
399 Each element has the form:
402 (@var{parameter} . @var{value})
405 Emacs creates the initial frame before it reads your init
406 file. After reading that file, Emacs checks @code{initial-frame-alist},
407 and applies the parameter settings in the altered value to the already
408 created initial frame.
410 If these settings affect the frame geometry and appearance, you'll see
411 the frame appear with the wrong ones and then change to the specified
412 ones. If that bothers you, you can specify the same geometry and
413 appearance with X resources; those do take effect before the frame is
414 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
416 X resource settings typically apply to all frames. If you want to
417 specify some X resources solely for the sake of the initial frame, and
418 you don't want them to apply to subsequent frames, here's how to achieve
419 this. Specify parameters in @code{default-frame-alist} to override the
420 X resources for subsequent frames; then, to prevent these from affecting
421 the initial frame, specify the same parameters in
422 @code{initial-frame-alist} with values that match the X resources.
425 If these parameters specify a separate minibuffer-only frame with
426 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
429 @defopt minibuffer-frame-alist
430 This variable's value is an alist of parameter values used when
431 creating an initial minibuffer-only frame. This is the
432 minibuffer-only frame that Emacs creates if @code{initial-frame-alist}
433 specifies a frame with no minibuffer.
436 @defopt default-frame-alist
437 This is an alist specifying default values of frame parameters for all
438 Emacs frames---the first frame, and subsequent frames. When using the X
439 Window System, you can get the same results by means of X resources
442 Setting this variable does not affect existing frames.
445 Functions that display a buffer in a separate frame can override the
446 default parameters by supplying their own parameters. @xref{Definition
447 of special-display-frame-alist}.
449 If you use options that specify window appearance when you invoke Emacs,
450 they take effect by adding elements to @code{default-frame-alist}. One
451 exception is @samp{-geometry}, which adds the specified position to
452 @code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command
453 Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
455 @node Window Frame Parameters
456 @subsection Window Frame Parameters
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 @emph{only} in
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 @code{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-only 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 @emph{of the frame's icon}, in
567 pixels, counting from the left edge of the screen. This takes effect if
568 and when the frame is iconified.
570 If you specify a value for this parameter, then you must also specify
571 a value for @code{icon-top} and vice versa. The window manager may
572 ignore these two parameters.
574 @vindex icon-top, a frame parameter
576 The screen position of the top edge @emph{of the frame's icon}, in
577 pixels, counting from the top edge of the screen. This takes effect if
578 and when the frame is iconified.
580 @vindex user-position, a frame parameter
582 When you create a frame and specify its screen position with the
583 @code{left} and @code{top} parameters, use this parameter to say whether
584 the specified position was user-specified (explicitly requested in some
585 way by a human user) or merely program-specified (chosen by a program).
586 A non-@code{nil} value says the position was user-specified.
588 @cindex window positions and window managers
589 Window managers generally heed user-specified positions, and some heed
590 program-specified positions too. But many ignore program-specified
591 positions, placing the window in a default fashion or letting the user
592 place it with the mouse. Some window managers, including @code{twm},
593 let the user specify whether to obey program-specified positions or
596 When you call @code{make-frame}, you should specify a non-@code{nil}
597 value for this parameter if the values of the @code{left} and @code{top}
598 parameters represent the user's stated preference; otherwise, use
602 @node Size Parameters
603 @subsubsection Size Parameters
604 @cindex window size on display
606 Size parameters' values are normally measured in pixels, but on
607 text-only terminals they count characters or lines instead.
610 @vindex height, a frame parameter
612 The height of the frame contents, in characters. (To get the height in
613 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
615 @vindex width, a frame parameter
617 The width of the frame contents, in characters. (To get the width in
618 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
620 @vindex user-size, a frame parameter
622 This does for the size parameters @code{height} and @code{width} what
623 the @code{user-position} parameter (@pxref{Position Parameters,
624 user-position}) does for the position parameters @code{top} and
627 @cindex full-screen frames
628 @vindex fullscreen, a frame parameter
630 Specify that width, height or both shall be maximized. The value
631 @code{fullwidth} specifies that width shall be as wide as possible.
632 The value @code{fullheight} specifies that height shall be as tall as
633 possible. The value @code{fullboth} specifies that both the width and
634 the height shall be set to the size of the screen. The value
635 @code{maximized} specifies that the frame shall be maximized. The
636 difference between @code{maximized} and @code{fullboth} is that the
637 former still has window manager decorations while the latter really
638 covers the whole screen.
641 @node Layout Parameters
642 @subsubsection Layout Parameters
643 @cindex layout parameters of frames
644 @cindex frame layout parameters
646 These frame parameters enable or disable various parts of the
647 frame, or control their sizes.
650 @vindex border-width, a frame parameter
652 The width in pixels of the frame's border.
654 @vindex internal-border-width, a frame parameter
655 @item internal-border-width
656 The distance in pixels between text (or fringe) and the frame's border.
658 @vindex vertical-scroll-bars, a frame parameter
659 @item vertical-scroll-bars
660 Whether the frame has scroll bars for vertical scrolling, and which side
661 of the frame they should be on. The possible values are @code{left},
662 @code{right}, and @code{nil} for no scroll bars.
665 @vindex horizontal-scroll-bars, a frame parameter
666 @item horizontal-scroll-bars
667 Whether the frame has scroll bars for horizontal scrolling
668 (non-@code{nil} means yes). Horizontal scroll bars are not currently
672 @vindex scroll-bar-width, a frame parameter
673 @item scroll-bar-width
674 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
675 use the default width.
677 @vindex left-fringe, a frame parameter
678 @vindex right-fringe, a frame parameter
681 The default width of the left and right fringes of windows in this
682 frame (@pxref{Fringes}). If either of these is zero, that effectively
683 removes the corresponding fringe.
685 When you use @code{frame-parameter} to query the value of either of
686 these two frame parameters, the return value is always an integer.
687 When using @code{set-frame-parameter}, passing a @code{nil} value
688 imposes an actual default value of 8 pixels.
690 The combined fringe widths must add up to an integral number of
691 columns, so the actual default fringe widths for the frame, as
692 reported by @code{frame-parameter}, may be larger than what you
693 specify. Any extra width is distributed evenly between the left and
694 right fringe. However, you can force one fringe or the other to a
695 precise width by specifying that width as a negative integer. If both
696 widths are negative, only the left fringe gets the specified width.
698 @vindex menu-bar-lines frame parameter
700 The number of lines to allocate at the top of the frame for a menu
701 bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
702 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
704 @vindex tool-bar-lines frame parameter
706 The number of lines to use for the tool bar. The default is 1 if Tool
707 Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The
710 @vindex tool-bar-position frame parameter
711 @item tool-bar-position
712 The position of the tool bar. Currently only for the GTK tool bar.
713 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
714 The default is @code{top}.
716 @vindex line-spacing, a frame parameter
718 Additional space to leave below each text line, in pixels (a positive
719 integer). @xref{Line Height}, for more information.
722 @node Buffer Parameters
723 @subsubsection Buffer Parameters
725 These frame parameters, meaningful on all kinds of terminals, deal
726 with which buffers have been, or should, be displayed in the frame.
729 @vindex minibuffer, a frame parameter
731 Whether this frame has its own minibuffer. The value @code{t} means
732 yes, @code{nil} means no, @code{only} means this frame is just a
733 minibuffer. If the value is a minibuffer window (in some other
734 frame), the frame uses that minibuffer.
736 This frame parameter takes effect when the frame is created, and can
737 not be changed afterwards.
739 @vindex buffer-predicate, a frame parameter
740 @item buffer-predicate
741 The buffer-predicate function for this frame. The function
742 @code{other-buffer} uses this predicate (from the selected frame) to
743 decide which buffers it should consider, if the predicate is not
744 @code{nil}. It calls the predicate with one argument, a buffer, once for
745 each buffer; if the predicate returns a non-@code{nil} value, it
746 considers that buffer.
748 @vindex buffer-list, a frame parameter
750 A list of buffers that have been selected in this frame, ordered
751 most-recently-selected first.
753 @vindex unsplittable, a frame parameter
755 If non-@code{nil}, this frame's window is never split automatically.
758 @node Management Parameters
759 @subsubsection Window Management Parameters
760 @cindex window manager interaction, and frame parameters
762 These frame parameters, meaningful only on window system displays,
763 interact with the window manager.
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 Whether selecting the frame raises it (non-@code{nil} means yes).
776 @vindex auto-lower, a frame parameter
778 Whether deselecting the frame lowers it (non-@code{nil} means yes).
780 @vindex icon-type, a frame parameter
782 The type of icon to use for this frame when it is iconified. If the
783 value is a string, that specifies a file containing a bitmap to use.
784 Any other non-@code{nil} value specifies the default bitmap icon (a
785 picture of a gnu); @code{nil} specifies a text icon.
787 @vindex icon-name, a frame parameter
789 The name to use in the icon for this frame, when and if the icon
790 appears. If this is @code{nil}, the frame's title is used.
792 @vindex window-id, a frame parameter
794 The number of the window-system window used by the frame
795 to contain the actual Emacs windows.
797 @vindex outer-window-id, a frame parameter
798 @item outer-window-id
799 The number of the outermost window-system window used for the whole frame.
801 @vindex wait-for-wm, a frame parameter
803 If non-@code{nil}, tell Xt to wait for the window manager to confirm
804 geometry changes. Some window managers, including versions of Fvwm2
805 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
806 prevent hanging with those window managers.
808 @vindex sticky, a frame parameter
810 If non-@code{nil}, the frame is visible on all virtual desktops on systems
811 with virtual desktops.
814 @vindex parent-id, a frame parameter
816 @c ??? Not yet working.
817 The X window number of the window that should be the parent of this one.
818 Specifying this lets you create an Emacs window inside some other
819 application's window. (It is not certain this will be implemented; try
820 it and see if it works.)
824 @node Cursor Parameters
825 @subsubsection Cursor Parameters
826 @cindex cursor, and frame parameters
828 This frame parameter controls the way the cursor looks.
831 @vindex cursor-type, a frame parameter
833 How to display the cursor. Legitimate values are:
837 Display a filled box. (This is the default.)
839 Display a hollow box.
841 Don't display a cursor.
843 Display a vertical bar between characters.
844 @item (bar . @var{width})
845 Display a vertical bar @var{width} pixels wide between characters.
847 Display a horizontal bar.
848 @item (hbar . @var{height})
849 Display a horizontal bar @var{height} pixels high.
854 The buffer-local variable @code{cursor-type} overrides the value of
855 the @code{cursor-type} frame parameter, but if it is @code{t}, that
856 means to use the cursor specified for the frame.
858 @defopt blink-cursor-alist
859 This variable specifies how to blink the cursor. Each element has the
860 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
861 type equals @var{on-state} (comparing using @code{equal}), the
862 corresponding @var{off-state} specifies what the cursor looks like
863 when it blinks ``off.'' Both @var{on-state} and @var{off-state}
864 should be suitable values for the @code{cursor-type} frame parameter.
866 There are various defaults for how to blink each type of cursor, if
867 the type is not mentioned as an @var{on-state} here. Changes in this
868 variable do not take effect immediately, only when you specify the
869 @code{cursor-type} frame parameter.
872 @defopt cursor-in-non-selected-windows
873 This variable controls how the cursor looks in a window that is not
874 selected. It supports the same values as the @code{cursor-type} frame
875 parameter; also, @code{nil} means don't display a cursor in
876 nonselected windows, and @code{t} (the default) means use a standard
877 modification of the usual cursor type (solid box becomes hollow box,
878 and bar becomes a narrower bar).
881 @node Font and Color Parameters
882 @subsubsection Font and Color Parameters
883 @cindex font and color, frame parameters
885 These frame parameters control the use of fonts and colors.
888 @vindex font-backend, a frame parameter
890 A list of symbols, specifying the @dfn{font backends} to use for
891 drawing fonts in the frame, in order of priority. On X, there are
892 currently two available font backends: @code{x} (the X core font
893 driver) and @code{xft} (the Xft font driver). On other systems, there
894 is only one available font backend, so it does not make sense to
895 modify this frame parameter.
897 @vindex background-mode, a frame parameter
898 @item background-mode
899 This parameter is either @code{dark} or @code{light}, according
900 to whether the background color is a light one or a dark one.
902 @vindex tty-color-mode, a frame parameter
904 @cindex standard colors for character terminals
905 This parameter overrides the terminal's color support as given by the
906 system's terminal capabilities database in that this parameter's value
907 specifies the color mode to use in terminal frames. The value can be
908 either a symbol or a number. A number specifies the number of colors
909 to use (and, indirectly, what commands to issue to produce each
910 color). For example, @code{(tty-color-mode . 8)} specifies use of the
911 ANSI escape sequences for 8 standard text colors. A value of -1 turns
914 If the parameter's value is a symbol, it specifies a number through
915 the value of @code{tty-color-mode-alist}, and the associated number is
918 @vindex screen-gamma, a frame parameter
920 @cindex gamma correction
921 If this is a number, Emacs performs ``gamma correction'' which adjusts
922 the brightness of all colors. The value should be the screen gamma of
923 your display, a floating point number.
925 Usual PC monitors have a screen gamma of 2.2, so color values in
926 Emacs, and in X windows generally, are calibrated to display properly
927 on a monitor with that gamma value. If you specify 2.2 for
928 @code{screen-gamma}, that means no correction is needed. Other values
929 request correction, designed to make the corrected colors appear on
930 your screen the way they would have appeared without correction on an
931 ordinary monitor with a gamma value of 2.2.
933 If your monitor displays colors too light, you should specify a
934 @code{screen-gamma} value smaller than 2.2. This requests correction
935 that makes colors darker. A screen gamma value of 1.5 may give good
936 results for LCD color displays.
938 @vindex alpha, a frame parameter
940 @cindex opacity, frame
941 @cindex transparency, frame
942 @vindex frame-alpha-lower-limit
943 This parameter specifies the opacity of the frame, on graphical
944 displays that support variable opacity. It should be an integer
945 between 0 and 100, where 0 means completely transparent and 100 means
946 completely opaque. It can also have a @code{nil} value, which tells
947 Emacs not to set the frame opacity (leaving it to the window manager).
949 To prevent the frame from disappearing completely from view, the
950 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
951 If the value of the frame parameter is less than the value of this
952 variable, Emacs uses the latter. By default,
953 @code{frame-alpha-lower-limit} is 20.
955 The @code{alpha} frame parameter can also be a cons cell
956 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
957 opacity of the frame when it is selected, and @samp{inactive} is the
958 opactity when it is not selected.
961 The following frame parameters are semi-obsolete in that they are
962 automatically equivalent to particular face attributes of particular
963 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
966 @vindex font, a frame parameter
968 The name of the font for displaying text in the frame. This is a
969 string, either a valid font name for your system or the name of an Emacs
970 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
971 attribute of the @code{default} face.
973 @vindex foreground-color, a frame parameter
974 @item foreground-color
975 The color to use for the image of a character. It is equivalent to
976 the @code{:foreground} attribute of the @code{default} face.
978 @vindex background-color, a frame parameter
979 @item background-color
980 The color to use for the background of characters. It is equivalent to
981 the @code{:background} attribute of the @code{default} face.
983 @vindex mouse-color, a frame parameter
985 The color for the mouse pointer. It is equivalent to the @code{:background}
986 attribute of the @code{mouse} face.
988 @vindex cursor-color, a frame parameter
990 The color for the cursor that shows point. It is equivalent to the
991 @code{:background} attribute of the @code{cursor} face.
993 @vindex border-color, a frame parameter
995 The color for the border of the frame. It is equivalent to the
996 @code{:background} attribute of the @code{border} face.
998 @vindex scroll-bar-foreground, a frame parameter
999 @item scroll-bar-foreground
1000 If non-@code{nil}, the color for the foreground of scroll bars. It is
1001 equivalent to the @code{:foreground} attribute of the
1002 @code{scroll-bar} face.
1004 @vindex scroll-bar-background, a frame parameter
1005 @item scroll-bar-background
1006 If non-@code{nil}, the color for the background of scroll bars. It is
1007 equivalent to the @code{:background} attribute of the
1008 @code{scroll-bar} face.
1011 @node Size and Position
1012 @subsection Frame Size And Position
1013 @cindex size of frame
1016 @cindex resize frame
1018 You can read or change the size and position of a frame using the
1019 frame parameters @code{left}, @code{top}, @code{height}, and
1020 @code{width}. Whatever geometry parameters you don't specify are chosen
1021 by the window manager in its usual fashion.
1023 Here are some special features for working with sizes and positions.
1024 (For the precise meaning of ``selected frame'' used by these functions,
1025 see @ref{Input Focus}.)
1027 @defun set-frame-position frame left top
1028 This function sets the position of the top left corner of @var{frame} to
1029 @var{left} and @var{top}. These arguments are measured in pixels, and
1030 normally count from the top left corner of the screen.
1032 Negative parameter values position the bottom edge of the window up from
1033 the bottom edge of the screen, or the right window edge to the left of
1034 the right edge of the screen. It would probably be better if the values
1035 were always counted from the left and top, so that negative arguments
1036 would position the frame partly off the top or left edge of the screen,
1037 but it seems inadvisable to change that now.
1040 @defun frame-height &optional frame
1041 @defunx frame-width &optional frame
1042 These functions return the height and width of @var{frame}, measured in
1043 lines and columns. If you don't supply @var{frame}, they use the
1047 @defun frame-pixel-height &optional frame
1048 @defunx frame-pixel-width &optional frame
1049 These functions return the height and width of the main display area
1050 of @var{frame}, measured in pixels. If you don't supply @var{frame},
1051 they use the selected frame. For a text-only terminal, the results are
1052 in characters rather than pixels.
1054 These values include the internal borders, and windows' scroll bars and
1055 fringes (which belong to individual windows, not to the frame itself).
1056 The exact value of the heights depends on the window-system and toolkit
1057 in use. With Gtk+, the height does not include any tool bar or menu
1058 bar. With the Motif or Lucid toolkits, it includes the tool bar but
1059 not the menu bar. In a graphical version with no toolkit, it includes
1060 both the tool bar and menu bar. For a text-only terminal, the result
1061 includes the menu bar.
1064 @defun frame-char-height &optional frame
1065 @defunx frame-char-width &optional frame
1066 These functions return the height and width of a character in
1067 @var{frame}, measured in pixels. The values depend on the choice of
1068 font. If you don't supply @var{frame}, these functions use the selected
1072 @defun set-frame-size frame cols rows
1073 This function sets the size of @var{frame}, measured in characters;
1074 @var{cols} and @var{rows} specify the new width and height.
1076 To set the size based on values measured in pixels, use
1077 @code{frame-char-height} and @code{frame-char-width} to convert
1078 them to units of characters.
1081 @defun set-frame-height frame lines &optional pretend
1082 This function resizes @var{frame} to a height of @var{lines} lines. The
1083 sizes of existing windows in @var{frame} are altered proportionally to
1086 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
1087 lines of output in @var{frame}, but does not change its value for the
1088 actual height of the frame. This is only useful for a terminal frame.
1089 Using a smaller height than the terminal actually implements may be
1090 useful to reproduce behavior observed on a smaller screen, or if the
1091 terminal malfunctions when using its whole screen. Setting the frame
1092 height ``for real'' does not always work, because knowing the correct
1093 actual size may be necessary for correct cursor positioning on a
1097 @defun set-frame-width frame width &optional pretend
1098 This function sets the width of @var{frame}, measured in characters.
1099 The argument @var{pretend} has the same meaning as in
1100 @code{set-frame-height}.
1103 @findex set-screen-height
1104 @findex set-screen-width
1105 The older functions @code{set-screen-height} and
1106 @code{set-screen-width} were used to specify the height and width of the
1107 screen, in Emacs versions that did not support multiple frames. They
1108 are semi-obsolete, but still work; they apply to the selected frame.
1111 @subsection Geometry
1113 Here's how to examine the data in an X-style window geometry
1116 @defun x-parse-geometry geom
1117 @cindex geometry specification
1118 The function @code{x-parse-geometry} converts a standard X window
1119 geometry string to an alist that you can use as part of the argument to
1122 The alist describes which parameters were specified in @var{geom}, and
1123 gives the values specified for them. Each element looks like
1124 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
1125 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1127 For the size parameters, the value must be an integer. The position
1128 parameter names @code{left} and @code{top} are not totally accurate,
1129 because some values indicate the position of the right or bottom edges
1130 instead. The @var{value} possibilities for the position parameters are:
1131 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1132 as previously described (@pxref{Position Parameters}).
1137 (x-parse-geometry "35x70+0-0")
1138 @result{} ((height . 70) (width . 35)
1139 (top - 0) (left . 0))
1143 @node Terminal Parameters
1144 @section Terminal Parameters
1145 @cindex terminal parameters
1147 Each terminal has a list of associated parameters. These
1148 @dfn{terminal parameters} are mostly a convenient way of storage for
1149 terminal-local variables, but some terminal parameters have a special
1152 This section describes functions to read and change the parameter values
1153 of a terminal. They all accept as their argument either a terminal or
1154 a frame; the latter means use that frame's terminal. An argument of
1155 @code{nil} means the selected frame's terminal.
1157 @defun terminal-parameters &optional terminal
1158 This function returns an alist listing all the parameters of
1159 @var{terminal} and their values.
1162 @defun terminal-parameter terminal parameter
1163 This function returns the value of the parameter @var{parameter} (a
1164 symbol) of @var{terminal}. If @var{terminal} has no setting for
1165 @var{parameter}, this function returns @code{nil}.
1168 @defun set-terminal-parameter terminal parameter value
1169 This function sets the parameter @var{parm} of @var{terminal} to the
1170 specified @var{value}, and returns the previous value of that
1174 Here's a list of a few terminal parameters that have a special
1178 @item background-mode
1179 The classification of the terminal's background color, either
1180 @code{light} or @code{dark}.
1181 @item normal-erase-is-backspace
1182 Value is either 1 or 0, depending on whether
1183 @code{normal-erase-is-backspace-mode} is turned on or off on this
1184 terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1185 @item terminal-initted
1186 After the terminal is initialized, this is set to the
1187 terminal-specific initialization function.
1191 @section Frame Titles
1194 Every frame has a @code{name} parameter; this serves as the default
1195 for the frame title which window systems typically display at the top of
1196 the frame. You can specify a name explicitly by setting the @code{name}
1199 Normally you don't specify the name explicitly, and Emacs computes the
1200 frame name automatically based on a template stored in the variable
1201 @code{frame-title-format}. Emacs recomputes the name each time the
1202 frame is redisplayed.
1204 @defvar frame-title-format
1205 This variable specifies how to compute a name for a frame when you have
1206 not explicitly specified one. The variable's value is actually a mode
1207 line construct, just like @code{mode-line-format}, except that the
1208 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
1212 @defvar icon-title-format
1213 This variable specifies how to compute the name for an iconified frame,
1214 when you have not explicitly specified the frame title. This title
1215 appears in the icon itself.
1218 @defvar multiple-frames
1219 This variable is set automatically by Emacs. Its value is @code{t} when
1220 there are two or more frames (not counting minibuffer-only frames or
1221 invisible frames). The default value of @code{frame-title-format} uses
1222 @code{multiple-frames} so as to put the buffer name in the frame title
1223 only when there is more than one frame.
1225 The value of this variable is not guaranteed to be accurate except
1226 while processing @code{frame-title-format} or
1227 @code{icon-title-format}.
1230 @node Deleting Frames
1231 @section Deleting Frames
1232 @cindex deleting frames
1234 Frames remain potentially visible until you explicitly @dfn{delete}
1235 them. A deleted frame cannot appear on the screen, but continues to
1236 exist as a Lisp object until there are no references to it.
1238 @deffn Command delete-frame &optional frame force
1239 @vindex delete-frame-functions
1240 This function deletes the frame @var{frame}. Unless @var{frame} is a
1241 tooltip, it first runs the hook @code{delete-frame-functions} (each
1242 function gets one argument, @var{frame}). By default, @var{frame} is
1245 A frame cannot be deleted if its minibuffer is used by other frames.
1246 Normally, you cannot delete a frame if all other frames are invisible,
1247 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1250 @defun frame-live-p frame
1251 The function @code{frame-live-p} returns non-@code{nil} if the frame
1252 @var{frame} has not been deleted. The possible non-@code{nil} return
1253 values are like those of @code{framep}. @xref{Frames}.
1256 Some window managers provide a command to delete a window. These work
1257 by sending a special message to the program that operates the window.
1258 When Emacs gets one of these commands, it generates a
1259 @code{delete-frame} event, whose normal definition is a command that
1260 calls the function @code{delete-frame}. @xref{Misc Events}.
1262 @node Finding All Frames
1263 @section Finding All Frames
1264 @cindex frames, scanning all
1267 The function @code{frame-list} returns a list of all the live frames,
1268 i.e.@: those that have not been deleted. It is analogous to
1269 @code{buffer-list} for buffers, and includes frames on all terminals.
1270 The list that you get is newly created, so modifying the list doesn't
1271 have any effect on the internals of Emacs.
1274 @defun visible-frame-list
1275 This function returns a list of just the currently visible frames.
1276 @xref{Visibility of Frames}. (Terminal frames always count as
1277 ``visible,'' even though only the selected one is actually displayed.)
1280 @defun next-frame &optional frame minibuf
1281 The function @code{next-frame} lets you cycle conveniently through all
1282 the frames on the current display from an arbitrary starting point. It
1283 returns the ``next'' frame after @var{frame} in the cycle. If
1284 @var{frame} is omitted or @code{nil}, it defaults to the selected frame
1285 (@pxref{Input Focus}).
1287 The second argument, @var{minibuf}, says which frames to consider:
1291 Exclude minibuffer-only frames.
1292 @item @code{visible}
1293 Consider all visible frames.
1295 Consider all visible or iconified frames.
1297 Consider only the frames using that particular window as their
1300 Consider all frames.
1304 @defun previous-frame &optional frame minibuf
1305 Like @code{next-frame}, but cycles through all frames in the opposite
1309 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1312 @node Frames and Windows
1313 @section Frames and Windows
1315 Each window is part of one and only one frame; you can get that frame
1316 with @code{window-frame}.
1318 @defun window-frame window
1319 This function returns the frame that @var{window} is on.
1322 All the non-minibuffer windows in a frame are arranged in a cyclic
1323 order. The order runs from the frame's top window, which is at the
1324 upper left corner, down and to the right, until it reaches the window at
1325 the lower right corner (always the minibuffer window, if the frame has
1326 one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
1328 @defun frame-first-window &optional frame
1329 This returns the topmost, leftmost window of frame @var{frame}.
1330 If omitted or @code{nil}, @var{frame} defaults to the selected frame.
1333 At any time, exactly one window on any frame is @dfn{selected within the
1334 frame}. The significance of this designation is that selecting the
1335 frame also selects this window. Conversely, selecting a window for
1336 Emacs with @code{select-window} also makes that window selected within
1337 its frame. @xref{Selecting Windows}.
1339 @defun frame-selected-window &optional frame
1340 This function returns the window on @var{frame} that is selected
1341 within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to
1345 @defun set-frame-selected-window frame window &optional norecord
1346 This sets the selected window of frame @var{frame} to @var{window}.
1347 If @var{frame} is @code{nil}, it operates on the selected frame. If
1348 @var{frame} is the selected frame, this makes @var{window} the
1349 selected window. This function returns @var{window}.
1351 Optional argument @var{norecord} non-@code{nil} means to neither change
1352 the order of recently selected windows nor the buffer list (@pxref{The
1356 Another function that (usually) returns one of the windows in a given
1357 frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
1359 @node Minibuffers and Frames
1360 @section Minibuffers and Frames
1362 Normally, each frame has its own minibuffer window at the bottom, which
1363 is used whenever that frame is selected. If the frame has a minibuffer,
1364 you can get it with @code{minibuffer-window} (@pxref{Definition of
1365 minibuffer-window}).
1367 However, you can also create a frame with no minibuffer. Such a frame
1368 must use the minibuffer window of some other frame. When you create the
1369 frame, you can explicitly specify the minibuffer window to use (in some
1370 other frame). If you don't, then the minibuffer is found in the frame
1371 which is the value of the variable @code{default-minibuffer-frame}. Its
1372 value should be a frame that does have a minibuffer.
1374 If you use a minibuffer-only frame, you might want that frame to raise
1375 when you enter the minibuffer. If so, set the variable
1376 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
1378 @defvar default-minibuffer-frame
1379 This variable specifies the frame to use for the minibuffer window, by
1380 default. It does not affect existing frames. It is always local to
1381 the current terminal and cannot be buffer-local. @xref{Multiple
1386 @section Input Focus
1388 @c @cindex selected frame Duplicates selected-frame
1390 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
1391 window always resides on the selected frame.
1393 When Emacs displays its frames on several terminals (@pxref{Multiple
1394 Terminals}), each terminal has its own selected frame. But only one
1395 of these is ``@emph{the} selected frame'': it's the frame that belongs
1396 to the terminal from which the most recent input came. That is, when
1397 Emacs runs a command that came from a certain terminal, the selected
1398 frame is the one of that terminal. Since Emacs runs only a single
1399 command at any given time, it needs to consider only one selected
1400 frame at a time; this frame is what we call @dfn{the selected frame}
1401 in this manual. The display on which the selected frame is shown is
1402 the @dfn{selected frame's display}.
1404 @defun selected-frame
1405 This function returns the selected frame.
1408 Some window systems and window managers direct keyboard input to the
1409 window object that the mouse is in; others require explicit clicks or
1410 commands to @dfn{shift the focus} to various window objects. Either
1411 way, Emacs automatically keeps track of which frame has the focus. To
1412 explicitly switch to a different frame from a Lisp function, call
1413 @code{select-frame-set-input-focus}.
1415 Lisp programs can also switch frames ``temporarily'' by calling the
1416 function @code{select-frame}. This does not alter the window system's
1417 concept of focus; rather, it escapes from the window manager's control
1418 until that control is somehow reasserted.
1420 When using a text-only terminal, only one frame can be displayed at a
1421 time on the terminal, so after a call to @code{select-frame}, the next
1422 redisplay actually displays the newly selected frame. This frame
1423 remains selected until a subsequent call to @code{select-frame}. Each
1424 terminal frame has a number which appears in the mode line before the
1425 buffer name (@pxref{Mode Line Variables}).
1427 @defun select-frame-set-input-focus frame
1428 This function selects @var{frame}, raises it (should it happen to be
1429 obscured by other frames) and tries to give it the X server's focus. On
1430 a text-only terminal, the next redisplay displays the new frame on the
1431 entire terminal screen. The return value of this function is not
1435 @c ??? This is not yet implemented properly.
1436 @defun select-frame frame &optional norecord
1437 This function selects frame @var{frame}, temporarily disregarding the
1438 focus of the X server if any. The selection of @var{frame} lasts until
1439 the next time the user does something to select a different frame, or
1440 until the next time this function is called. (If you are using a
1441 window system, the previously selected frame may be restored as the
1442 selected frame after return to the command loop, because it still may
1443 have the window system's input focus.)
1445 The specified @var{frame} becomes the selected frame, as explained
1446 above, and the terminal that @var{frame} is on becomes the selected
1447 terminal. The window selected within @var{frame} becomes the selected
1448 window. This function returns @var{frame}, or @code{nil} if @var{frame}
1451 Optional argument @var{norecord} non-@code{nil} means to neither change
1452 the order of recently selected windows nor the buffer list. @xref{The
1455 In general, you should never use @code{select-frame} in a way that could
1456 switch to a different terminal without switching back when you're done.
1459 Emacs cooperates with the window system by arranging to select frames as
1460 the server and window manager request. It does so by generating a
1461 special kind of input event, called a @dfn{focus} event, when
1462 appropriate. The command loop handles a focus event by calling
1463 @code{handle-switch-frame}. @xref{Focus Events}.
1465 @deffn Command handle-switch-frame frame
1466 This function handles a focus event by selecting frame @var{frame}.
1468 Focus events normally do their job by invoking this command.
1469 Don't call it for any other reason.
1472 @defun redirect-frame-focus frame &optional focus-frame
1473 This function redirects focus from @var{frame} to @var{focus-frame}.
1474 This means that @var{focus-frame} will receive subsequent keystrokes and
1475 events intended for @var{frame}. After such an event, the value of
1476 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1477 events specifying @var{frame} will instead select @var{focus-frame}.
1479 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1480 redirection for @var{frame}, which therefore once again receives its own
1483 One use of focus redirection is for frames that don't have minibuffers.
1484 These frames use minibuffers on other frames. Activating a minibuffer
1485 on another frame redirects focus to that frame. This puts the focus on
1486 the minibuffer's frame, where it belongs, even though the mouse remains
1487 in the frame that activated the minibuffer.
1489 Selecting a frame can also change focus redirections. Selecting frame
1490 @code{bar}, when @code{foo} had been selected, changes any redirections
1491 pointing to @code{foo} so that they point to @code{bar} instead. This
1492 allows focus redirection to work properly when the user switches from
1493 one frame to another using @code{select-window}.
1495 This means that a frame whose focus is redirected to itself is treated
1496 differently from a frame whose focus is not redirected.
1497 @code{select-frame} affects the former but not the latter.
1499 The redirection lasts until @code{redirect-frame-focus} is called to
1503 @defopt focus-follows-mouse
1504 This option is how you inform Emacs whether the window manager transfers
1505 focus when the user moves the mouse. Non-@code{nil} says that it does.
1506 When this is so, the command @code{other-frame} moves the mouse to a
1507 position consistent with the new selected frame.
1510 @node Visibility of Frames
1511 @section Visibility of Frames
1512 @cindex visible frame
1513 @cindex invisible frame
1514 @cindex iconified frame
1515 @cindex frame visibility
1517 A window frame may be @dfn{visible}, @dfn{invisible}, or
1518 @dfn{iconified}. If it is visible, you can see its contents, unless
1519 other windows cover it. If it is iconified, the frame's contents do
1520 not appear on the screen, but an icon does. (Note: because of the
1521 way in which some window managers implement the concept of multiple
1522 workspaces, or desktops, all frames on other workspaces may appear to
1523 Emacs to be iconified.) If the frame is invisible, it doesn't show on
1524 the screen, not even as an icon.
1526 Visibility is meaningless for terminal frames, since only the selected
1527 one is actually displayed in any case.
1529 @deffn Command make-frame-visible &optional frame
1530 This function makes frame @var{frame} visible. If you omit
1531 @var{frame}, it makes the selected frame visible. This does not raise
1532 the frame, but you can do that with @code{raise-frame} if you wish
1533 (@pxref{Raising and Lowering}).
1536 @deffn Command make-frame-invisible &optional frame force
1537 This function makes frame @var{frame} invisible. If you omit
1538 @var{frame}, it makes the selected frame invisible.
1540 Unless @var{force} is non-@code{nil}, this function refuses to make
1541 @var{frame} invisible if all other frames are invisible..
1544 @deffn Command iconify-frame &optional frame
1545 This function iconifies frame @var{frame}. If you omit @var{frame}, it
1546 iconifies the selected frame.
1549 @defun frame-visible-p frame
1550 This returns the visibility status of frame @var{frame}. The value is
1551 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
1552 @code{icon} if it is iconified.
1554 On a text-only terminal, all frames are considered visible, whether
1555 they are currently being displayed or not, and this function returns
1556 @code{t} for all frames.
1559 The visibility status of a frame is also available as a frame
1560 parameter. You can read or change it as such. @xref{Management
1563 The user can iconify and deiconify frames with the window manager.
1564 This happens below the level at which Emacs can exert any control, but
1565 Emacs does provide events that you can use to keep track of such
1566 changes. @xref{Misc Events}.
1568 @node Raising and Lowering
1569 @section Raising and Lowering Frames
1571 Most window systems use a desktop metaphor. Part of this metaphor is
1572 the idea that windows are stacked in a notional third dimension
1573 perpendicular to the screen surface, and thus ordered from ``highest''
1574 to ``lowest.'' Where two windows overlap, the one higher up covers
1575 the one underneath. Even a window at the bottom of the stack can be
1576 seen if no other window overlaps it.
1578 @c @cindex raising a frame redundant with raise-frame
1579 @cindex lowering a frame
1580 A window's place in this ordering is not fixed; in fact, users tend
1581 to change the order frequently. @dfn{Raising} a window means moving
1582 it ``up,'' to the top of the stack. @dfn{Lowering} a window means
1583 moving it to the bottom of the stack. This motion is in the notional
1584 third dimension only, and does not change the position of the window
1587 With Emacs, frames constitute the windows in the metaphor sketched
1588 above. You can raise and lower frames using these functions:
1590 @deffn Command raise-frame &optional frame
1591 This function raises frame @var{frame} (default, the selected frame).
1592 If @var{frame} is invisible or iconified, this makes it visible.
1595 @deffn Command lower-frame &optional frame
1596 This function lowers frame @var{frame} (default, the selected frame).
1599 @defopt minibuffer-auto-raise
1600 If this is non-@code{nil}, activation of the minibuffer raises the frame
1601 that the minibuffer window is in.
1604 You can also enable auto-raise (raising automatically when a frame is
1605 selected) or auto-lower (lowering automatically when it is deselected)
1606 for any frame using frame parameters. @xref{Management Parameters}.
1608 @node Frame Configurations
1609 @section Frame Configurations
1610 @cindex frame configuration
1612 A @dfn{frame configuration} records the current arrangement of frames,
1613 all their properties, and the window configuration of each one.
1614 (@xref{Window Configurations}.)
1616 @defun current-frame-configuration
1617 This function returns a frame configuration list that describes
1618 the current arrangement of frames and their contents.
1621 @defun set-frame-configuration configuration &optional nodelete
1622 This function restores the state of frames described in
1623 @var{configuration}. However, this function does not restore deleted
1626 Ordinarily, this function deletes all existing frames not listed in
1627 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1628 unwanted frames are iconified instead.
1631 @node Mouse Tracking
1632 @section Mouse Tracking
1633 @cindex mouse tracking
1634 @c @cindex tracking the mouse Duplicates track-mouse
1636 Sometimes it is useful to @dfn{track} the mouse, which means to display
1637 something to indicate where the mouse is and move the indicator as the
1638 mouse moves. For efficient mouse tracking, you need a way to wait until
1639 the mouse actually moves.
1641 The convenient way to track the mouse is to ask for events to represent
1642 mouse motion. Then you can wait for motion by waiting for an event. In
1643 addition, you can easily handle any other sorts of events that may
1644 occur. That is useful, because normally you don't want to track the
1645 mouse forever---only until some other event, such as the release of a
1648 @defspec track-mouse body@dots{}
1649 This special form executes @var{body}, with generation of mouse motion
1650 events enabled. Typically, @var{body} would use @code{read-event} to
1651 read the motion events and modify the display accordingly. @xref{Motion
1652 Events}, for the format of mouse motion events.
1654 The value of @code{track-mouse} is that of the last form in @var{body}.
1655 You should design @var{body} to return when it sees the up-event that
1656 indicates the release of the button, or whatever kind of event means
1657 it is time to stop tracking.
1660 The usual purpose of tracking mouse motion is to indicate on the screen
1661 the consequences of pushing or releasing a button at the current
1664 In many cases, you can avoid the need to track the mouse by using
1665 the @code{mouse-face} text property (@pxref{Special Properties}).
1666 That works at a much lower level and runs more smoothly than
1667 Lisp-level mouse tracking.
1670 @c These are not implemented yet.
1672 These functions change the screen appearance instantaneously. The
1673 effect is transient, only until the next ordinary Emacs redisplay. That
1674 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1675 to change the text, and the body of @code{track-mouse} normally reads
1676 the events itself and does not do redisplay.
1678 @defun x-contour-region window beg end
1679 This function draws lines to make a box around the text from @var{beg}
1680 to @var{end}, in window @var{window}.
1683 @defun x-uncontour-region window beg end
1684 This function erases the lines that would make a box around the text
1685 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1686 a contour that you previously made by calling @code{x-contour-region}.
1689 @defun x-draw-rectangle frame left top right bottom
1690 This function draws a hollow rectangle on frame @var{frame} with the
1691 specified edge coordinates, all measured in pixels from the inside top
1692 left corner. It uses the cursor color, the one used for indicating the
1696 @defun x-erase-rectangle frame left top right bottom
1697 This function erases a hollow rectangle on frame @var{frame} with the
1698 specified edge coordinates, all measured in pixels from the inside top
1699 left corner. Erasure means redrawing the text and background that
1700 normally belong in the specified rectangle.
1704 @node Mouse Position
1705 @section Mouse Position
1706 @cindex mouse position
1707 @cindex position of mouse
1709 The functions @code{mouse-position} and @code{set-mouse-position}
1710 give access to the current position of the mouse.
1712 @defun mouse-position
1713 This function returns a description of the position of the mouse. The
1714 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1715 and @var{y} are integers giving the position in characters relative to
1716 the top left corner of the inside of @var{frame}.
1719 @defvar mouse-position-function
1720 If non-@code{nil}, the value of this variable is a function for
1721 @code{mouse-position} to call. @code{mouse-position} calls this
1722 function just before returning, with its normal return value as the
1723 sole argument, and it returns whatever this function returns to it.
1725 This abnormal hook exists for the benefit of packages like
1726 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1729 @defun set-mouse-position frame x y
1730 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1731 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1732 giving the position in characters relative to the top left corner of the
1733 inside of @var{frame}. If @var{frame} is not visible, this function
1734 does nothing. The return value is not significant.
1737 @defun mouse-pixel-position
1738 This function is like @code{mouse-position} except that it returns
1739 coordinates in units of pixels rather than units of characters.
1742 @defun set-mouse-pixel-position frame x y
1743 This function warps the mouse like @code{set-mouse-position} except that
1744 @var{x} and @var{y} are in units of pixels rather than units of
1745 characters. These coordinates are not required to be within the frame.
1747 If @var{frame} is not visible, this function does nothing. The return
1748 value is not significant.
1751 @defun frame-pointer-visible-p &optional frame
1752 This predicate function returns non-@code{nil} if the mouse pointer
1753 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
1754 @var{frame} omitted or @code{nil} means the selected frame. This is
1755 useful when @code{make-pointer-invisible} is set to @code{t}: it
1756 allows to know if the pointer has been hidden.
1757 @xref{Mouse Avoidance,,,emacs}.
1763 @section Pop-Up Menus
1765 When using a window system, a Lisp program can pop up a menu so that
1766 the user can choose an alternative with the mouse.
1768 @defun x-popup-menu position menu
1769 This function displays a pop-up menu and returns an indication of
1770 what selection the user makes.
1772 The argument @var{position} specifies where on the screen to put the
1773 top left corner of the menu. It can be either a mouse button event
1774 (which says to put the menu where the user actuated the button) or a
1778 ((@var{xoffset} @var{yoffset}) @var{window})
1782 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1783 pixels, counting from the top left corner of @var{window}. @var{window}
1784 may be a window or a frame.
1786 If @var{position} is @code{t}, it means to use the current mouse
1787 position. If @var{position} is @code{nil}, it means to precompute the
1788 key binding equivalents for the keymaps specified in @var{menu},
1789 without actually displaying or popping up the menu.
1791 The argument @var{menu} says what to display in the menu. It can be a
1792 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
1793 return value is the list of events corresponding to the user's choice.
1794 This list has more than one element if the choice occurred in a
1795 submenu. (Note that @code{x-popup-menu} does not actually execute the
1796 command bound to that sequence of events.) On toolkits that support
1797 menu titles, the title is taken from the prompt string of @var{menu}
1798 if @var{menu} is a keymap, or from the prompt string of the first
1799 keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
1802 Alternatively, @var{menu} can have the following form:
1805 (@var{title} @var{pane1} @var{pane2}...)
1809 where each pane is a list of form
1812 (@var{title} @var{item1} @var{item2}...)
1815 Each item should normally be a cons cell @code{(@var{line} . @var{value})},
1816 where @var{line} is a string, and @var{value} is the value to return if
1817 that @var{line} is chosen. An item can also be a string; this makes a
1818 non-selectable line in the menu.
1820 If the user gets rid of the menu without making a valid choice, for
1821 instance by clicking the mouse away from a valid choice or by typing
1822 keyboard input, then this normally results in a quit and
1823 @code{x-popup-menu} does not return. But if @var{position} is a mouse
1824 button event (indicating that the user invoked the menu with the
1825 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1828 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1829 if you could do the job with a prefix key defined with a menu keymap.
1830 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1831 a} can see the individual items in that menu and provide help for them.
1832 If instead you implement the menu by defining a command that calls
1833 @code{x-popup-menu}, the help facilities cannot know what happens inside
1834 that command, so they cannot give any help for the menu's items.
1836 The menu bar mechanism, which lets you switch between submenus by
1837 moving the mouse, cannot look within the definition of a command to see
1838 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1839 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1840 an integrated fashion. This is why all menu bar submenus are
1841 implemented with menu keymaps within the parent menu, and never with
1842 @code{x-popup-menu}. @xref{Menu Bar}.
1844 If you want a menu bar submenu to have contents that vary, you should
1845 still use a menu keymap to implement it. To make the contents vary, add
1846 a hook function to @code{menu-bar-update-hook} to update the contents of
1847 the menu keymap as necessary.
1850 @section Dialog Boxes
1851 @cindex dialog boxes
1853 A dialog box is a variant of a pop-up menu---it looks a little
1854 different, it always appears in the center of a frame, and it has just
1855 one level and one or more buttons. The main use of dialog boxes is
1856 for asking questions that the user can answer with ``yes,'' ``no,''
1857 and a few other alternatives. With a single button, they can also
1858 force the user to acknowledge important information. The functions
1859 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1860 keyboard, when called from commands invoked by mouse clicks.
1862 @defun x-popup-dialog position contents &optional header
1863 This function displays a pop-up dialog box and returns an indication of
1864 what selection the user makes. The argument @var{contents} specifies
1865 the alternatives to offer; it has this format:
1868 (@var{title} (@var{string} . @var{value})@dots{})
1872 which looks like the list that specifies a single pane for
1873 @code{x-popup-menu}.
1875 The return value is @var{value} from the chosen alternative.
1877 As for @code{x-popup-menu}, an element of the list may be just a
1878 string instead of a cons cell @code{(@var{string} . @var{value})}.
1879 That makes a box that cannot be selected.
1881 If @code{nil} appears in the list, it separates the left-hand items from
1882 the right-hand items; items that precede the @code{nil} appear on the
1883 left, and items that follow the @code{nil} appear on the right. If you
1884 don't include a @code{nil} in the list, then approximately half the
1885 items appear on each side.
1887 Dialog boxes always appear in the center of a frame; the argument
1888 @var{position} specifies which frame. The possible values are as in
1889 @code{x-popup-menu}, but the precise coordinates or the individual
1890 window don't matter; only the frame matters.
1892 If @var{header} is non-@code{nil}, the frame title for the box is
1893 @samp{Information}, otherwise it is @samp{Question}. The former is used
1894 for @code{message-box} (@pxref{message-box}).
1896 In some configurations, Emacs cannot display a real dialog box; so
1897 instead it displays the same items in a pop-up menu in the center of the
1900 If the user gets rid of the dialog box without making a valid choice,
1901 for instance using the window manager, then this produces a quit and
1902 @code{x-popup-dialog} does not return.
1906 @section Pointer Shape
1907 @cindex pointer shape
1908 @cindex mouse pointer shape
1910 You can specify the mouse pointer style for particular text or
1911 images using the @code{pointer} text property, and for images with the
1912 @code{:pointer} and @code{:map} image properties. The values you can
1913 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1914 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1915 @code{hourglass}. @code{text} stands for the usual mouse pointer
1916 style used over text.
1918 Over void parts of the window (parts that do not correspond to any
1919 of the buffer contents), the mouse pointer usually uses the
1920 @code{arrow} style, but you can specify a different style (one of
1921 those above) by setting @code{void-text-area-pointer}.
1923 @defvar void-text-area-pointer
1924 This variable specifies the mouse pointer style for void text areas.
1925 These include the areas after the end of a line or below the last line
1926 in the buffer. The default is to use the @code{arrow} (non-text)
1930 When using X, you can specify what the @code{text} pointer style
1931 really looks like by setting the variable @code{x-pointer-shape}.
1933 @defvar x-pointer-shape
1934 This variable specifies the pointer shape to use ordinarily in the
1935 Emacs frame, for the @code{text} pointer style.
1938 @defvar x-sensitive-text-pointer-shape
1939 This variable specifies the pointer shape to use when the mouse
1940 is over mouse-sensitive text.
1943 These variables affect newly created frames. They do not normally
1944 affect existing frames; however, if you set the mouse color of a
1945 frame, that also installs the current value of those two variables.
1946 @xref{Font and Color Parameters}.
1948 The values you can use, to specify either of these pointer shapes, are
1949 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1950 @key{RET} x-pointer @key{RET}} to see a list of them.
1952 @node Window System Selections
1953 @section Window System Selections
1954 @cindex selection (for window systems)
1956 @cindex primary selection
1957 @cindex secondary selection
1959 In the X window system, data can be transferred between different
1960 applications by means of @dfn{selections}. X defines an arbitrary
1961 number of @dfn{selection types}, each of which can store its own data;
1962 however, only three are commonly used: the @dfn{clipboard},
1963 @dfn{primary selection}, and @dfn{secondary selection}. @xref{Cut and
1964 Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
1965 commands that make use of these selections. This section documents
1966 the low-level functions for reading and setting X selections.
1968 @deffn Command x-set-selection type data
1969 This function sets an X selection. It takes two arguments: a
1970 selection type @var{type}, and the value to assign to it, @var{data}.
1972 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
1973 @code{SECONDARY} or @code{CLIPBOARD}. These are symbols with
1974 upper-case names, in accord with X Window System conventions. If
1975 @var{type} is @code{nil}, that stands for @code{PRIMARY}.
1977 If @var{data} is @code{nil}, it means to clear out the selection.
1978 Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
1979 of two integers or list of two integers), an overlay, or a cons of two
1980 markers pointing to the same buffer. An overlay or a pair of markers
1981 stands for text in the overlay or between the markers. The argument
1982 @var{data} may also be a vector of valid non-vector selection values.
1984 This function returns @var{data}.
1987 @defun x-get-selection &optional type data-type
1988 This function accesses selections set up by Emacs or by other X
1989 clients. It takes two optional arguments, @var{type} and
1990 @var{data-type}. The default for @var{type}, the selection type, is
1993 The @var{data-type} argument specifies the form of data conversion to
1994 use, to convert the raw data obtained from another X client into Lisp
1995 data. Meaningful values include @code{TEXT}, @code{STRING},
1996 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1997 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1998 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1999 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
2000 @code{INTEGER}. (These are symbols with upper-case names in accord
2001 with X conventions.) The default for @var{data-type} is
2005 @defopt selection-coding-system
2006 This variable specifies the coding system to use when reading and
2007 writing selections or the clipboard. @xref{Coding
2008 Systems}. The default is @code{compound-text-with-extensions}, which
2009 converts to the text representation that X11 normally uses.
2012 @cindex clipboard support (for MS-Windows)
2013 When Emacs runs on MS-Windows, it does not implement X selections in
2014 general, but it does support the clipboard. @code{x-get-selection}
2015 and @code{x-set-selection} on MS-Windows support the text data type
2016 only; if the clipboard holds other types of data, Emacs treats the
2020 @section Drag and Drop
2022 @vindex x-dnd-test-function
2023 @vindex x-dnd-known-types
2024 When a user drags something from another application over Emacs, that other
2025 application expects Emacs to tell it if Emacs can handle the data that is
2026 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
2027 what to reply. The default value is @code{x-dnd-default-test-function}
2028 which accepts drops if the type of the data to be dropped is present in
2029 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
2030 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
2031 on some other criteria.
2033 @vindex x-dnd-types-alist
2034 If you want to change the way Emacs handles drop of different types
2035 or add a new type, customize @code{x-dnd-types-alist}. This requires
2036 detailed knowledge of what types other applications use for drag and
2039 @vindex dnd-protocol-alist
2040 When an URL is dropped on Emacs it may be a file, but it may also be
2041 another URL type (ftp, http, etc.). Emacs first checks
2042 @code{dnd-protocol-alist} to determine what to do with the URL. If
2043 there is no match there and if @code{browse-url-browser-function} is
2044 an alist, Emacs looks for a match there. If no match is found the
2045 text for the URL is inserted. If you want to alter Emacs behavior,
2046 you can customize these variables.
2049 @section Color Names
2052 @cindex specify color
2053 @cindex numerical RGB color specification
2054 A color name is text (usually in a string) that specifies a color.
2055 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2056 are allowed; use @kbd{M-x list-colors-display} to see a list of
2057 defined names. You can also specify colors numerically in forms such
2058 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2059 @var{r} specifies the red level, @var{g} specifies the green level,
2060 and @var{b} specifies the blue level. You can use either one, two,
2061 three, or four hex digits for @var{r}; then you must use the same
2062 number of hex digits for all @var{g} and @var{b} as well, making
2063 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
2064 X Window System for more details about numerical RGB specification of
2067 These functions provide a way to determine which color names are
2068 valid, and what they look like. In some cases, the value depends on the
2069 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2070 meaning of the term ``selected frame.''
2072 To read user input of color names with completion, use
2073 @code{read-color} (@pxref{High-Level Completion, read-color}).
2075 @defun color-defined-p color &optional frame
2076 This function reports whether a color name is meaningful. It returns
2077 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
2078 which frame's display to ask about; if @var{frame} is omitted or
2079 @code{nil}, the selected frame is used.
2081 Note that this does not tell you whether the display you are using
2082 really supports that color. When using X, you can ask for any defined
2083 color on any kind of display, and you will get some result---typically,
2084 the closest it can do. To determine whether a frame can really display
2085 a certain color, use @code{color-supported-p} (see below).
2087 @findex x-color-defined-p
2088 This function used to be called @code{x-color-defined-p},
2089 and that name is still supported as an alias.
2092 @defun defined-colors &optional frame
2093 This function returns a list of the color names that are defined
2094 and supported on frame @var{frame} (default, the selected frame).
2095 If @var{frame} does not support colors, the value is @code{nil}.
2097 @findex x-defined-colors
2098 This function used to be called @code{x-defined-colors},
2099 and that name is still supported as an alias.
2102 @defun color-supported-p color &optional frame background-p
2103 This returns @code{t} if @var{frame} can really display the color
2104 @var{color} (or at least something close to it). If @var{frame} is
2105 omitted or @code{nil}, the question applies to the selected frame.
2107 Some terminals support a different set of colors for foreground and
2108 background. If @var{background-p} is non-@code{nil}, that means you are
2109 asking whether @var{color} can be used as a background; otherwise you
2110 are asking whether it can be used as a foreground.
2112 The argument @var{color} must be a valid color name.
2115 @defun color-gray-p color &optional frame
2116 This returns @code{t} if @var{color} is a shade of gray, as defined on
2117 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
2118 question applies to the selected frame. If @var{color} is not a valid
2119 color name, this function returns @code{nil}.
2122 @defun color-values color &optional frame
2124 This function returns a value that describes what @var{color} should
2125 ideally look like on @var{frame}. If @var{color} is defined, the
2126 value is a list of three integers, which give the amount of red, the
2127 amount of green, and the amount of blue. Each integer ranges in
2128 principle from 0 to 65535, but some displays may not use the full
2129 range. This three-element list is called the @dfn{rgb values} of the
2132 If @var{color} is not defined, the value is @code{nil}.
2135 (color-values "black")
2137 (color-values "white")
2138 @result{} (65280 65280 65280)
2139 (color-values "red")
2140 @result{} (65280 0 0)
2141 (color-values "pink")
2142 @result{} (65280 49152 51968)
2143 (color-values "hungry")
2147 The color values are returned for @var{frame}'s display. If
2148 @var{frame} is omitted or @code{nil}, the information is returned for
2149 the selected frame's display. If the frame cannot display colors, the
2150 value is @code{nil}.
2152 @findex x-color-values
2153 This function used to be called @code{x-color-values},
2154 and that name is still supported as an alias.
2157 @node Text Terminal Colors
2158 @section Text Terminal Colors
2159 @cindex colors on text-only terminals
2161 Text-only terminals usually support only a small number of colors,
2162 and the computer uses small integers to select colors on the terminal.
2163 This means that the computer cannot reliably tell what the selected
2164 color looks like; instead, you have to inform your application which
2165 small integers correspond to which colors. However, Emacs does know
2166 the standard set of colors and will try to use them automatically.
2168 The functions described in this section control how terminal colors
2171 Several of these functions use or return @dfn{rgb values}, described
2172 in @ref{Color Names}.
2174 These functions accept a display (either a frame or the name of a
2175 terminal) as an optional argument. We hope in the future to make
2176 Emacs support different colors on different text-only terminals; then
2177 this argument will specify which terminal to operate on (the default
2178 being the selected frame's terminal; @pxref{Input Focus}). At
2179 present, though, the @var{frame} argument has no effect.
2181 @defun tty-color-define name number &optional rgb frame
2182 This function associates the color name @var{name} with
2183 color number @var{number} on the terminal.
2185 The optional argument @var{rgb}, if specified, is an rgb value, a list
2186 of three numbers that specify what the color actually looks like.
2187 If you do not specify @var{rgb}, then this color cannot be used by
2188 @code{tty-color-approximate} to approximate other colors, because
2189 Emacs will not know what it looks like.
2192 @defun tty-color-clear &optional frame
2193 This function clears the table of defined colors for a text-only terminal.
2196 @defun tty-color-alist &optional frame
2197 This function returns an alist recording the known colors supported by a
2200 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2201 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
2202 name, @var{number} is the number used to specify it to the terminal.
2203 If present, @var{rgb} is a list of three color values (for red, green,
2204 and blue) that says what the color actually looks like.
2207 @defun tty-color-approximate rgb &optional frame
2208 This function finds the closest color, among the known colors
2209 supported for @var{display}, to that described by the rgb value
2210 @var{rgb} (a list of color values). The return value is an element of
2211 @code{tty-color-alist}.
2214 @defun tty-color-translate color &optional frame
2215 This function finds the closest color to @var{color} among the known
2216 colors supported for @var{display} and returns its index (an integer).
2217 If the name @var{color} is not defined, the value is @code{nil}.
2221 @section X Resources
2223 This section describes some of the functions and variables for
2224 querying and using X resources, or their equivalent on your operating
2225 system. @xref{X Resources,, X Resources, emacs, The GNU Emacs
2226 Manual}, for more information about X resources.
2228 @defun x-get-resource attribute class &optional component subclass
2229 The function @code{x-get-resource} retrieves a resource value from the X
2230 Window defaults database.
2232 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2233 This function searches using a key of the form
2234 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2235 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2238 The optional arguments @var{component} and @var{subclass} add to the key
2239 and the class, respectively. You must specify both of them or neither.
2240 If you specify them, the key is
2241 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2242 @samp{Emacs.@var{class}.@var{subclass}}.
2245 @defvar x-resource-class
2246 This variable specifies the application name that @code{x-get-resource}
2247 should look up. The default value is @code{"Emacs"}. You can examine X
2248 resources for application names other than ``Emacs'' by binding this
2249 variable to some other string, around a call to @code{x-get-resource}.
2252 @defvar x-resource-name
2253 This variable specifies the instance name that @code{x-get-resource}
2254 should look up. The default value is the name Emacs was invoked with,
2255 or the value specified with the @samp{-name} or @samp{-rn} switches.
2258 To illustrate some of the above, suppose that you have the line:
2261 xterm.vt100.background: yellow
2265 in your X resources file (whose name is usually @file{~/.Xdefaults}
2266 or @file{~/.Xresources}). Then:
2270 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2271 (x-get-resource "vt100.background" "VT100.Background"))
2275 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2276 (x-get-resource "background" "VT100" "vt100" "Background"))
2281 @defvar inhibit-x-resources
2282 If this variable is non-@code{nil}, Emacs does not look up X
2283 resources, and X resources do not have any effect when creating new
2287 @node Display Feature Testing
2288 @section Display Feature Testing
2289 @cindex display feature testing
2291 The functions in this section describe the basic capabilities of a
2292 particular display. Lisp programs can use them to adapt their behavior
2293 to what the display can do. For example, a program that ordinarily uses
2294 a popup menu could use the minibuffer if popup menus are not supported.
2296 The optional argument @var{display} in these functions specifies which
2297 display to ask the question about. It can be a display name, a frame
2298 (which designates the display that frame is on), or @code{nil} (which
2299 refers to the selected frame's display, @pxref{Input Focus}).
2301 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2302 obtain information about displays.
2304 @defun display-popup-menus-p &optional display
2305 This function returns @code{t} if popup menus are supported on
2306 @var{display}, @code{nil} if not. Support for popup menus requires that
2307 the mouse be available, since the user cannot choose menu items without
2311 @defun display-graphic-p &optional display
2312 This function returns @code{t} if @var{display} is a graphic display
2313 capable of displaying several frames and several different fonts at
2314 once. This is true for displays that use a window system such as X, and
2315 false for text-only terminals.
2318 @defun display-mouse-p &optional display
2319 @cindex mouse, availability
2320 This function returns @code{t} if @var{display} has a mouse available,
2324 @defun display-color-p &optional display
2325 @findex x-display-color-p
2326 This function returns @code{t} if the screen is a color screen.
2327 It used to be called @code{x-display-color-p}, and that name
2328 is still supported as an alias.
2331 @defun display-grayscale-p &optional display
2332 This function returns @code{t} if the screen can display shades of gray.
2333 (All color displays can do this.)
2336 @defun display-supports-face-attributes-p attributes &optional display
2337 @anchor{Display Face Attribute Testing}
2338 This function returns non-@code{nil} if all the face attributes in
2339 @var{attributes} are supported (@pxref{Face Attributes}).
2341 The definition of `supported' is somewhat heuristic, but basically
2342 means that a face containing all the attributes in @var{attributes},
2343 when merged with the default face for display, can be represented in a
2348 different in appearance than the default face, and
2351 `close in spirit' to what the attributes specify, if not exact.
2354 Point (2) implies that a @code{:weight black} attribute will be
2355 satisfied by any display that can display bold, as will
2356 @code{:foreground "yellow"} as long as some yellowish color can be
2357 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2358 the tty display code's automatic substitution of a `dim' face for
2362 @defun display-selections-p &optional display
2363 This function returns @code{t} if @var{display} supports selections.
2364 Windowed displays normally support selections, but they may also be
2365 supported in some other cases.
2368 @defun display-images-p &optional display
2369 This function returns @code{t} if @var{display} can display images.
2370 Windowed displays ought in principle to handle images, but some
2371 systems lack the support for that. On a display that does not support
2372 images, Emacs cannot display a tool bar.
2375 @defun display-screens &optional display
2376 This function returns the number of screens associated with the display.
2379 @defun display-pixel-height &optional display
2380 This function returns the height of the screen in pixels.
2381 On a character terminal, it gives the height in characters.
2383 For graphical terminals, note that on ``multi-monitor'' setups this
2384 refers to the pixel width for all physical monitors associated with
2385 @var{display}. @xref{Multiple Terminals}.
2388 @defun display-pixel-width &optional display
2389 This function returns the width of the screen in pixels.
2390 On a character terminal, it gives the width in characters.
2392 For graphical terminals, note that on ``multi-monitor'' setups this
2393 refers to the pixel width for all physical monitors associated with
2394 @var{display}. @xref{Multiple Terminals}.
2397 @defun display-mm-height &optional display
2398 This function returns the height of the screen in millimeters,
2399 or @code{nil} if Emacs cannot get that information.
2402 @defun display-mm-width &optional display
2403 This function returns the width of the screen in millimeters,
2404 or @code{nil} if Emacs cannot get that information.
2407 @defopt display-mm-dimensions-alist
2408 This variable allows the user to specify the dimensions of graphical
2409 displays returned by @code{display-mm-height} and
2410 @code{display-mm-width} in case the system provides incorrect values.
2413 @defun display-backing-store &optional display
2414 This function returns the backing store capability of the display.
2415 Backing store means recording the pixels of windows (and parts of
2416 windows) that are not exposed, so that when exposed they can be
2417 displayed very quickly.
2419 Values can be the symbols @code{always}, @code{when-mapped}, or
2420 @code{not-useful}. The function can also return @code{nil}
2421 when the question is inapplicable to a certain kind of display.
2424 @defun display-save-under &optional display
2425 This function returns non-@code{nil} if the display supports the
2426 SaveUnder feature. That feature is used by pop-up windows
2427 to save the pixels they obscure, so that they can pop down
2431 @defun display-planes &optional display
2432 This function returns the number of planes the display supports.
2433 This is typically the number of bits per pixel.
2434 For a tty display, it is log to base two of the number of colors supported.
2437 @defun display-visual-class &optional display
2438 This function returns the visual class for the screen. The value is
2439 one of the symbols @code{static-gray} (a limited, unchangeable number
2440 of grays), @code{gray-scale} (a full range of grays),
2441 @code{static-color} (a limited, unchangeable number of colors),
2442 @code{pseudo-color} (a limited number of colors), @code{true-color} (a
2443 full range of colors), and @code{direct-color} (a full range of
2447 @defun display-color-cells &optional display
2448 This function returns the number of color cells the screen supports.
2451 These functions obtain additional information specifically
2454 @defun x-server-version &optional display
2455 This function returns the list of version numbers of the X server
2456 running the display. The value is a list of three integers: the major
2457 and minor version numbers of the X protocol, and the
2458 distributor-specific release number of the X server software itself.
2461 @defun x-server-vendor &optional display
2462 This function returns the ``vendor'' that provided the X server
2463 software (as a string). Really this means whoever distributes the X
2466 When the developers of X labelled software distributors as
2467 ``vendors,'' they showed their false assumption that no system could
2468 ever be developed and distributed noncommercially.
2472 @defvar x-no-window-manager
2473 This variable's value is @code{t} if no X window manager is in use.
2479 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2480 width and height of an X Window frame, measured in pixels.