2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
5 @c See the file elisp.texi for copying conditions.
10 A @dfn{frame} is a screen object that contains one or more Emacs
11 windows (@pxref{Windows}). It is the kind of object called a
12 ``window'' in the terminology of graphical environments; but we can't
13 call it a ``window'' here, because Emacs uses that word in a different
14 way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that
15 represents a frame on the screen. @xref{Frame Type}.
17 A frame initially contains a single main window and/or a minibuffer
18 window; you can subdivide the main window vertically or horizontally
19 into smaller windows. @xref{Splitting Windows}.
22 A @dfn{terminal} is a display device capable of displaying one or
23 more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp
24 object that represents a terminal. @xref{Terminal Type}.
27 @cindex graphical terminal
28 @cindex graphical display
29 There are two classes of terminals: @dfn{text terminals} and
30 @dfn{graphical terminals}. Text terminals are non-graphics-capable
31 displays, including @command{xterm} and other terminal emulators. On
32 a text terminal, each Emacs frame occupies the terminal's entire
33 screen; although you can create additional frames and switch between
34 them, the terminal only shows one frame at a time. Graphical
35 terminals, on the other hand, are managed by graphical display systems
36 such as the X Window System, which allow Emacs to show multiple frames
37 simultaneously on the same display.
39 On GNU and Unix systems, you can create additional frames on any
40 available terminal, within a single Emacs session, regardless of
41 whether Emacs was started on a text or graphical terminal. Emacs can
42 display on both graphical and text terminals simultaneously. This
43 comes in handy, for instance, when you connect to the same session
44 from several remote locations. @xref{Multiple Terminals}.
47 This predicate returns a non-@code{nil} value if @var{object} is a
48 frame, and @code{nil} otherwise. For a frame, the value indicates which
49 kind of display the frame uses:
53 The frame is displayed on a text terminal.
55 The frame is displayed on an X graphical terminal.
57 The frame is displayed on a MS-Windows graphical terminal.
59 The frame is displayed on a GNUstep or Macintosh Cocoa graphical
62 The frame is displayed on an MS-DOS terminal.
66 @defun frame-terminal &optional frame
67 This function returns the terminal object that displays @var{frame}.
68 If @var{frame} is @code{nil} or unspecified, it defaults to the
72 @defun terminal-live-p object
73 This predicate returns a non-@code{nil} value if @var{object} is a
74 terminal that is live (i.e., not deleted), and @code{nil} otherwise.
75 For live terminals, the return value indicates what kind of frames are
76 displayed on that terminal; the list of possible values is the same as
77 for @code{framep} above.
81 * Creating Frames:: Creating additional frames.
82 * Multiple Terminals:: Displaying on several different devices.
83 * Frame Parameters:: Controlling frame size, position, font, etc.
84 * Terminal Parameters:: Parameters common for all frames on terminal.
85 * Frame Titles:: Automatic updating of frame titles.
86 * Deleting Frames:: Frames last until explicitly deleted.
87 * Finding All Frames:: How to examine all existing frames.
88 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
89 * Input Focus:: Specifying the selected frame.
90 * Visibility of Frames:: Frames may be visible or invisible, or icons.
91 * Raising and Lowering:: Raising a frame makes it hide other windows;
92 lowering it makes the others hide it.
93 * Frame Configurations:: Saving the state of all frames.
94 * Mouse Tracking:: Getting events that say when the mouse moves.
95 * Mouse Position:: Asking where the mouse is, or moving it.
96 * Pop-Up Menus:: Displaying a menu for the user to select from.
97 * Dialog Boxes:: Displaying a box to ask yes or no.
98 * Pointer Shape:: Specifying the shape of the mouse pointer.
99 * Window System Selections:: Transferring text to and from other X clients.
100 * Drag and Drop:: Internals of Drag-and-Drop implementation.
101 * Color Names:: Getting the definitions of color names.
102 * Text Terminal Colors:: Defining colors for text terminals.
103 * Resources:: Getting resource values from the server.
104 * Display Feature Testing:: Determining the features of a terminal.
107 @node Creating Frames
108 @section Creating Frames
110 To create a new frame, call the function @code{make-frame}.
112 @deffn Command make-frame &optional alist
113 This function creates and returns a new frame, displaying the current
116 The @var{alist} argument is an alist that specifies frame parameters
117 for the new frame. @xref{Frame Parameters}. If you specify the
118 @code{terminal} parameter in @var{alist}, the new frame is created on
119 that terminal. Otherwise, if you specify the @code{window-system}
120 frame parameter in @var{alist}, that determines whether the frame
121 should be displayed on a text terminal or a graphical terminal.
122 @xref{Window Systems}. If neither is specified, the new frame is
123 created in the same terminal as the selected frame.
125 Any parameters not mentioned in @var{alist} default to the values in
126 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
127 parameters not specified there default from the X resources or its
128 equivalent on your operating system (@pxref{X Resources,, X Resources,
129 emacs, The GNU Emacs Manual}). After the frame is created, Emacs
130 applies any parameters listed in @code{frame-inherited-parameters}
131 (see below) and not present in the argument, taking the values from
132 the frame that was selected when @code{make-frame} was called.
134 This function itself does not make the new frame the selected frame.
135 @xref{Input Focus}. The previously selected frame remains selected.
136 On graphical terminals, however, the windowing system may select the
137 new frame for its own reasons.
140 @defvar before-make-frame-hook
141 A normal hook run by @code{make-frame} before it creates the frame.
144 @defvar after-make-frame-functions
145 An abnormal hook run by @code{make-frame} after it creates the frame.
146 Each function in @code{after-make-frame-functions} receives one argument, the
150 @defvar frame-inherited-parameters
151 This variable specifies the list of frame parameters that a newly
152 created frame inherits from the currently selected frame. For each
153 parameter (a symbol) that is an element in the list and is not present
154 in the argument to @code{make-frame}, the function sets the value of
155 that parameter in the created frame to its value in the selected
159 @node Multiple Terminals
160 @section Multiple Terminals
161 @cindex multiple terminals
163 @cindex multiple X displays
164 @cindex displays, multiple
166 Emacs represents each terminal as a @dfn{terminal object} data type
167 (@pxref{Terminal Type}). On GNU and Unix systems, Emacs can use
168 multiple terminals simultaneously in each session. On other systems,
169 it can only use a single terminal. Each terminal object has the
170 following attributes:
174 The name of the device used by the terminal (e.g., @samp{:0.0} or
178 The terminal and keyboard coding systems used on the terminal.
179 @xref{Terminal I/O Encoding}.
182 The kind of display associated with the terminal. This is the symbol
183 returned by the function @code{terminal-live-p} (i.e., @code{x},
184 @code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.
187 A list of terminal parameters. @xref{Terminal Parameters}.
190 There is no primitive for creating terminal objects. Emacs creates
191 them as needed, such as when you call @code{make-frame-on-display}
194 @defun terminal-name &optional terminal
195 This function returns the file name of the device used by
196 @var{terminal}. If @var{terminal} is omitted or @code{nil}, it
197 defaults to the selected frame's terminal. @var{terminal} can also be
198 a frame, meaning that frame's terminal.
202 This function returns a list of all live terminal objects.
205 @defun get-device-terminal device
206 This function returns a terminal whose device name is given by
207 @var{device}. If @var{device} is a string, it can be either the file
208 name of a terminal device, or the name of an X display of the form
209 @samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a
210 frame, this function returns that frame's terminal; @code{nil} means
211 the selected frame. Finally, if @var{device} is a terminal object
212 that represents a live terminal, that terminal is returned. The
213 function signals an error if its argument is none of the above.
216 @defun delete-terminal &optional terminal force
217 This function deletes all frames on @var{terminal} and frees the
218 resources used by it. It runs the abnormal hook
219 @code{delete-terminal-functions}, passing @var{terminal} as the
220 argument to each function.
222 If @var{terminal} is omitted or @code{nil}, it defaults to the
223 selected frame's terminal. @var{terminal} can also be a frame,
224 meaning that frame's terminal.
226 Normally, this function signals an error if you attempt to delete the
227 sole active terminal, but if @var{force} is non-@code{nil}, you are
228 allowed to do so. Emacs automatically calls this function when the
229 last frame on a terminal is deleted (@pxref{Deleting Frames}).
232 @defvar delete-terminal-functions
233 An abnormal hook run by @code{delete-terminal}. Each function
234 receives one argument, the @var{terminal} argument passed to
235 @code{delete-terminal}. Due to technical details, the functions may
236 be called either just before the terminal is deleted, or just
240 @cindex terminal-local variables
241 A few Lisp variables are @dfn{terminal-local}; that is, they have a
242 separate binding for each terminal. The binding in effect at any time
243 is the one for the terminal that the currently selected frame belongs
244 to. These variables include @code{default-minibuffer-frame},
245 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
246 @code{system-key-alist}. They are always terminal-local, and can
247 never be buffer-local (@pxref{Buffer-Local Variables}).
249 On GNU and Unix systems, each X display is a separate graphical
250 terminal. When Emacs is started from within the X window system, it
251 uses the X display specified by the @env{DISPLAY} environment
252 variable, or by the @samp{--display} option (@pxref{Initial Options,,,
253 emacs, The GNU Emacs Manual}). Emacs can connect to other X displays
254 via the command @code{make-frame-on-display}. Each X display has its
255 own selected frame and its own minibuffer windows; however, only one
256 of those frames is ``@emph{the} selected frame'' at any given moment
257 (@pxref{Input Focus}). Emacs can even connect to other text
258 terminals, by interacting with the @command{emacsclient} program.
259 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
261 A single X server can handle more than one display. Each X display
262 has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
263 The first two parts, @var{host} and @var{server}, identify the X
264 server; the third part, @var{screen}, identifies a screen number on
265 that X server. When you use two or more screens belonging to one
266 server, Emacs knows by the similarity in their names that they share a
269 @deffn Command make-frame-on-display display &optional parameters
270 This function creates and returns a new frame on @var{display}, taking
271 the other frame parameters from the alist @var{parameters}.
272 @var{display} should be the name of an X display (a string).
274 Before creating the frame, this function ensures that Emacs is ``set
275 up'' to display graphics. For instance, if Emacs has not processed X
276 resources (e.g., if it was started on a text terminal), it does so at
277 this time. In all other respects, this function behaves like
278 @code{make-frame} (@pxref{Creating Frames}).
281 @defun x-display-list
282 This function returns a list that indicates which X displays Emacs has
283 a connection to. The elements of the list are strings, and each one
287 @defun x-open-connection display &optional xrm-string must-succeed
288 This function opens a connection to the X display @var{display},
289 without creating a frame on that display. Normally, Emacs Lisp
290 programs need not call this function, as @code{make-frame-on-display}
291 calls it automatically. The only reason for calling it is to check
292 whether communication can be established with a given X display.
294 The optional argument @var{xrm-string}, if not @code{nil}, is a string
295 of resource names and values, in the same format used in the
296 @file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The
297 GNU Emacs Manual}. These values apply to all Emacs frames created on
298 this display, overriding the resource values recorded in the X server.
299 Here's an example of what this string might look like:
302 "*BorderWidth: 3\n*InternalBorder: 2\n"
305 If @var{must-succeed} is non-@code{nil}, failure to open the connection
306 terminates Emacs. Otherwise, it is an ordinary Lisp error.
309 @defun x-close-connection display
310 This function closes the connection to display @var{display}. Before
311 you can do this, you must first delete all the frames that were open
312 on that display (@pxref{Deleting Frames}).
315 @cindex multi-monitor
316 On some ``multi-monitor'' setups, a single X display outputs to more
317 than one physical monitor. @code{display-monitor-attributes-list} and
318 @code{frame-monitor-attributes} can be used to obtain information
319 about each physical monitor on multi-monitor setups.
321 @defun display-monitor-attributes-list &optional display
322 This function returns a list of physical monitor attributes on
323 @var{display}. Each element of the list is an association list,
324 representing the attributes of each physical monitor. The first
325 element corresponds to the primary monitor.
327 Attributes for a physical monitor are:
331 Position and size in pixels in the form of @samp{(X Y WIDTH HEIGHT)}
334 Position and size of the workarea in pixels in the form of @samp{(X Y
338 Width and height in millimeters in the form of @samp{(WIDTH HEIGHT)}
341 List of frames dominated by the physical monitor
344 Name of the physical monitor as a string
347 where X, Y, WIDTH, and HEIGHT are integers. @samp{name} is optional.
349 A frame is dominated by a physical monitor when either the
350 largest area of the frame resides in the monitor, or the monitor
351 is the closest to the frame if the frame does not intersect any
352 physical monitors. Every non-tip frame (including invisible one)
353 in a graphical display is dominated by exactly one physical
354 monitor at a time, though it can span multiple (or no) physical
357 @var{display} defaults to the selected frame's display.
360 @defun frame-monitor-attributes &optional frame
361 This function returns the attributes of the physical monitor
362 dominating @var{frame}, which defaults to the selected frame.
364 A frame is dominated by a physical monitor when either the
365 largest area of the frame resides in the monitor, or the monitor
366 is the closest to the frame if the frame does not intersect any
370 @node Frame Parameters
371 @section Frame Parameters
372 @cindex frame parameters
374 A frame has many parameters that control its appearance and behavior.
375 Just what parameters a frame has depends on what display mechanism it
378 Frame parameters exist mostly for the sake of graphical displays.
379 Most frame parameters have no effect when applied to a frame on a text
380 terminal; only the @code{height}, @code{width}, @code{name},
381 @code{title}, @code{menu-bar-lines}, @code{buffer-list} and
382 @code{buffer-predicate} parameters do something special. If the
383 terminal supports colors, the parameters @code{foreground-color},
384 @code{background-color}, @code{background-mode} and
385 @code{display-type} are also meaningful. If the terminal supports
386 frame transparency, the parameter @code{alpha} is also meaningful.
389 * Parameter Access:: How to change a frame's parameters.
390 * Initial Parameters:: Specifying frame parameters when you make a frame.
391 * Window Frame Parameters:: List of frame parameters for window systems.
392 * Size and Position:: Changing the size and position of a frame.
393 * Geometry:: Parsing geometry specifications.
396 @node Parameter Access
397 @subsection Access to Frame Parameters
399 These functions let you read and change the parameter values of a
402 @defun frame-parameter frame parameter
403 This function returns the value of the parameter @var{parameter} (a
404 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
405 selected frame's parameter. If @var{frame} has no setting for
406 @var{parameter}, this function returns @code{nil}.
409 @defun frame-parameters &optional frame
410 The function @code{frame-parameters} returns an alist listing all the
411 parameters of @var{frame} and their values. If @var{frame} is
412 @code{nil} or omitted, this returns the selected frame's parameters
415 @defun modify-frame-parameters frame alist
416 This function alters the parameters of frame @var{frame} based on the
417 elements of @var{alist}. Each element of @var{alist} has the form
418 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
419 parameter. If you don't mention a parameter in @var{alist}, its value
420 doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
424 @defun set-frame-parameter frame parm value
425 This function sets the frame parameter @var{parm} to the specified
426 @var{value}. If @var{frame} is @code{nil}, it defaults to the
430 @defun modify-all-frames-parameters alist
431 This function alters the frame parameters of all existing frames
432 according to @var{alist}, then modifies @code{default-frame-alist}
433 (and, if necessary, @code{initial-frame-alist}) to apply the same
434 parameter values to frames that will be created henceforth.
437 @node Initial Parameters
438 @subsection Initial Frame Parameters
440 You can specify the parameters for the initial startup frame by
441 setting @code{initial-frame-alist} in your init file (@pxref{Init
444 @defopt initial-frame-alist
445 This variable's value is an alist of parameter values used when
446 creating the initial frame. You can set this variable to specify the
447 appearance of the initial frame without altering subsequent frames.
448 Each element has the form:
451 (@var{parameter} . @var{value})
454 Emacs creates the initial frame before it reads your init
455 file. After reading that file, Emacs checks @code{initial-frame-alist},
456 and applies the parameter settings in the altered value to the already
457 created initial frame.
459 If these settings affect the frame geometry and appearance, you'll see
460 the frame appear with the wrong ones and then change to the specified
461 ones. If that bothers you, you can specify the same geometry and
462 appearance with X resources; those do take effect before the frame is
463 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
465 X resource settings typically apply to all frames. If you want to
466 specify some X resources solely for the sake of the initial frame, and
467 you don't want them to apply to subsequent frames, here's how to achieve
468 this. Specify parameters in @code{default-frame-alist} to override the
469 X resources for subsequent frames; then, to prevent these from affecting
470 the initial frame, specify the same parameters in
471 @code{initial-frame-alist} with values that match the X resources.
474 @cindex minibuffer-only frame
475 If these parameters include @code{(minibuffer . nil)}, that indicates
476 that the initial frame should have no minibuffer. In this case, Emacs
477 creates a separate @dfn{minibuffer-only frame} as well.
479 @defopt minibuffer-frame-alist
480 This variable's value is an alist of parameter values used when
481 creating an initial minibuffer-only frame (i.e., the minibuffer-only
482 frame that Emacs creates if @code{initial-frame-alist} specifies a
483 frame with no minibuffer).
486 @defopt default-frame-alist
487 This is an alist specifying default values of frame parameters for all
488 Emacs frames---the first frame, and subsequent frames. When using the X
489 Window System, you can get the same results by means of X resources
492 Setting this variable does not affect existing frames. Furthermore,
493 functions that display a buffer in a separate frame may override the
494 default parameters by supplying their own parameters.
497 If you invoke Emacs with command-line options that specify frame
498 appearance, those options take effect by adding elements to either
499 @code{initial-frame-alist} or @code{default-frame-alist}. Options
500 which affect just the initial frame, such as @samp{--geometry} and
501 @samp{--maximized}, add to @code{initial-frame-alist}; the others add
502 to @code{default-frame-alist}. @pxref{Emacs Invocation,, Command Line
503 Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
505 @node Window Frame Parameters
506 @subsection Window Frame Parameters
507 @cindex frame parameters for windowed displays
509 Just what parameters a frame has depends on what display mechanism
510 it uses. This section describes the parameters that have special
511 meanings on some or all kinds of terminals. Of these, @code{name},
512 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
513 @code{buffer-predicate} provide meaningful information in terminal
514 frames, and @code{tty-color-mode} is meaningful only for frames on
518 * Basic Parameters:: Parameters that are fundamental.
519 * Position Parameters:: The position of the frame on the screen.
520 * Size Parameters:: Frame's size.
521 * Layout Parameters:: Size of parts of the frame, and
522 enabling or disabling some parts.
523 * Buffer Parameters:: Which buffers have been or should be shown.
524 * Management Parameters:: Communicating with the window manager.
525 * Cursor Parameters:: Controlling the cursor appearance.
526 * Font and Color Parameters:: Fonts and colors for the frame text.
529 @node Basic Parameters
530 @subsubsection Basic Parameters
532 These frame parameters give the most basic information about the
533 frame. @code{title} and @code{name} are meaningful on all terminals.
536 @vindex display, a frame parameter
538 The display on which to open this frame. It should be a string of the
539 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
540 @env{DISPLAY} environment variable.
542 @vindex display-type, a frame parameter
544 This parameter describes the range of possible colors that can be used
545 in this frame. Its value is @code{color}, @code{grayscale} or
548 @vindex title, a frame parameter
550 If a frame has a non-@code{nil} title, it appears in the window
551 system's title bar at the top of the frame, and also in the mode line
552 of windows in that frame if @code{mode-line-frame-identification} uses
553 @samp{%F} (@pxref{%-Constructs}). This is normally the case when
554 Emacs is not using a window system, and can only display one frame at
555 a time. @xref{Frame Titles}.
557 @vindex name, a frame parameter
559 The name of the frame. The frame name serves as a default for the frame
560 title, if the @code{title} parameter is unspecified or @code{nil}. If
561 you don't specify a name, Emacs sets the frame name automatically
562 (@pxref{Frame Titles}).
564 If you specify the frame name explicitly when you create the frame, the
565 name is also used (instead of the name of the Emacs executable) when
566 looking up X resources for the frame.
569 If the frame name was specified explicitly when the frame was created,
570 this parameter will be that name. If the frame wasn't explicitly
571 named, this parameter will be @code{nil}.
574 @node Position Parameters
575 @subsubsection Position Parameters
576 @cindex window position on display
578 Position parameters' values are normally measured in pixels, but on
579 text terminals they count characters or lines instead.
582 @vindex left, a frame parameter
584 The position, in pixels, of the left (or right) edge of the frame with
585 respect to the left (or right) edge of the screen. The value may be:
589 A positive integer relates the left edge of the frame to the left edge
590 of the screen. A negative integer relates the right frame edge to the
593 @item @code{(+ @var{pos})}
594 This specifies the position of the left frame edge relative to the left
595 screen edge. The integer @var{pos} may be positive or negative; a
596 negative value specifies a position outside the screen.
598 @item @code{(- @var{pos})}
599 This specifies the position of the right frame edge relative to the right
600 screen edge. The integer @var{pos} may be positive or negative; a
601 negative value specifies a position outside the screen.
604 Some window managers ignore program-specified positions. If you want to
605 be sure the position you specify is not ignored, specify a
606 non-@code{nil} value for the @code{user-position} parameter as well.
608 @vindex top, a frame parameter
610 The screen position of the top (or bottom) edge, in pixels, with respect
611 to the top (or bottom) edge of the screen. It works just like
612 @code{left}, except vertically instead of horizontally.
614 @vindex icon-left, a frame parameter
616 The screen position of the left edge of the frame's icon, in pixels,
617 counting from the left edge of the screen. This takes effect when the
618 frame is iconified, if the window manager supports this feature. If
619 you specify a value for this parameter, then you must also specify a
620 value for @code{icon-top} and vice versa.
622 @vindex icon-top, a frame parameter
624 The screen position of the top edge of the frame's icon, in pixels,
625 counting from the top edge of the screen. This takes effect when the
626 frame is iconified, if the window manager supports this feature.
628 @vindex user-position, a frame parameter
630 When you create a frame and specify its screen position with the
631 @code{left} and @code{top} parameters, use this parameter to say whether
632 the specified position was user-specified (explicitly requested in some
633 way by a human user) or merely program-specified (chosen by a program).
634 A non-@code{nil} value says the position was user-specified.
636 @cindex window positions and window managers
637 Window managers generally heed user-specified positions, and some heed
638 program-specified positions too. But many ignore program-specified
639 positions, placing the window in a default fashion or letting the user
640 place it with the mouse. Some window managers, including @code{twm},
641 let the user specify whether to obey program-specified positions or
644 When you call @code{make-frame}, you should specify a non-@code{nil}
645 value for this parameter if the values of the @code{left} and @code{top}
646 parameters represent the user's stated preference; otherwise, use
650 @node Size Parameters
651 @subsubsection Size Parameters
652 @cindex window size on display
654 Frame parameters specify frame sizes in character units. On
655 graphical displays, the @code{default} face determines the actual
656 pixel sizes of these character units (@pxref{Face Attributes}).
659 @vindex height, a frame parameter
661 The height of the frame contents, in characters. (To get the height in
662 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
664 @vindex width, a frame parameter
666 The width of the frame contents, in characters. (To get the width in
667 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
669 @vindex user-size, a frame parameter
671 This does for the size parameters @code{height} and @code{width} what
672 the @code{user-position} parameter (@pxref{Position Parameters,
673 user-position}) does for the position parameters @code{top} and
676 @cindex full-screen frames
677 @vindex fullscreen, a frame parameter
679 Specify that width, height or both shall be maximized. The value
680 @code{fullwidth} specifies that width shall be as wide as possible.
681 The value @code{fullheight} specifies that height shall be as tall as
682 possible. The value @code{fullboth} specifies that both the width and
683 the height shall be set to the size of the screen. The value
684 @code{maximized} specifies that the frame shall be maximized. The
685 difference between @code{maximized} and @code{fullboth} is that the
686 former can still be resized by dragging window manager decorations
687 with the mouse, while the latter really covers the whole screen and
688 does not allow resizing by mouse dragging.
691 @node Layout Parameters
692 @subsubsection Layout Parameters
693 @cindex layout parameters of frames
694 @cindex frame layout parameters
696 These frame parameters enable or disable various parts of the
697 frame, or control their sizes.
700 @vindex border-width, a frame parameter
702 The width in pixels of the frame's border.
704 @vindex internal-border-width, a frame parameter
705 @item internal-border-width
706 The distance in pixels between text (or fringe) and the frame's border.
708 @vindex vertical-scroll-bars, a frame parameter
709 @item vertical-scroll-bars
710 Whether the frame has scroll bars for vertical scrolling, and which side
711 of the frame they should be on. The possible values are @code{left},
712 @code{right}, and @code{nil} for no scroll bars.
715 @vindex horizontal-scroll-bars, a frame parameter
716 @item horizontal-scroll-bars
717 Whether the frame has scroll bars for horizontal scrolling
718 (non-@code{nil} means yes). Horizontal scroll bars are not currently
722 @vindex scroll-bar-width, a frame parameter
723 @item scroll-bar-width
724 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
725 use the default width.
727 @vindex left-fringe, a frame parameter
728 @vindex right-fringe, a frame parameter
731 The default width of the left and right fringes of windows in this
732 frame (@pxref{Fringes}). If either of these is zero, that effectively
733 removes the corresponding fringe.
735 When you use @code{frame-parameter} to query the value of either of
736 these two frame parameters, the return value is always an integer.
737 When using @code{set-frame-parameter}, passing a @code{nil} value
738 imposes an actual default value of 8 pixels.
740 The combined fringe widths must add up to an integral number of
741 columns, so the actual default fringe widths for the frame, as
742 reported by @code{frame-parameter}, may be larger than what you
743 specify. Any extra width is distributed evenly between the left and
744 right fringe. However, you can force one fringe or the other to a
745 precise width by specifying that width as a negative integer. If both
746 widths are negative, only the left fringe gets the specified width.
748 @vindex right-divider-width, a frame parameter
749 @item right-divider-width
750 The width of the right divider (@pxref{Window Dividers}) of any window
751 on the frame, in pixels. A value of zero means to not draw right
754 @vindex bottom-divider-width, a frame parameter
755 @item bottom-divider-width
756 The width of the bottom divider (@pxref{Window Dividers}) of any window
757 on the frame, in pixels. A value of zero means to not draw bottom
760 @vindex menu-bar-lines frame parameter
762 The number of lines to allocate at the top of the frame for a menu
763 bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
764 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
766 @vindex tool-bar-lines frame parameter
768 The number of lines to use for the tool bar. The default is 1 if Tool
769 Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The
772 @vindex tool-bar-position frame parameter
773 @item tool-bar-position
774 The position of the tool bar. Currently only for the GTK tool bar.
775 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
776 The default is @code{top}.
778 @vindex line-spacing, a frame parameter
780 Additional space to leave below each text line, in pixels (a positive
781 integer). @xref{Line Height}, for more information.
784 @node Buffer Parameters
785 @subsubsection Buffer Parameters
787 These frame parameters, meaningful on all kinds of terminals, deal
788 with which buffers have been, or should, be displayed in the frame.
791 @vindex minibuffer, a frame parameter
793 Whether this frame has its own minibuffer. The value @code{t} means
794 yes, @code{nil} means no, @code{only} means this frame is just a
795 minibuffer. If the value is a minibuffer window (in some other
796 frame), the frame uses that minibuffer.
798 This frame parameter takes effect when the frame is created, and can
799 not be changed afterwards.
801 @vindex buffer-predicate, a frame parameter
802 @item buffer-predicate
803 The buffer-predicate function for this frame. The function
804 @code{other-buffer} uses this predicate (from the selected frame) to
805 decide which buffers it should consider, if the predicate is not
806 @code{nil}. It calls the predicate with one argument, a buffer, once for
807 each buffer; if the predicate returns a non-@code{nil} value, it
808 considers that buffer.
810 @vindex buffer-list, a frame parameter
812 A list of buffers that have been selected in this frame, ordered
813 most-recently-selected first.
815 @vindex unsplittable, a frame parameter
817 If non-@code{nil}, this frame's window is never split automatically.
820 @node Management Parameters
821 @subsubsection Window Management Parameters
822 @cindex window manager interaction, and frame parameters
824 The following frame parameters control various aspects of the
825 frame's interaction with the window manager. They have no effect on
829 @vindex visibility, a frame parameter
831 The state of visibility of the frame. There are three possibilities:
832 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
833 iconified. @xref{Visibility of Frames}.
835 @vindex auto-raise, a frame parameter
837 If non-@code{nil}, Emacs automatically raises the frame when it is
838 selected. Some window managers do not allow this.
840 @vindex auto-lower, a frame parameter
842 If non-@code{nil}, Emacs automatically lowers the frame when it is
843 deselected. Some window managers do not allow this.
845 @vindex icon-type, a frame parameter
847 The type of icon to use for this frame. If the value is a string,
848 that specifies a file containing a bitmap to use; @code{nil} specifies
849 no icon (in which case the window manager decides what to show); any
850 other non-@code{nil} value specifies the default Emacs icon.
852 @vindex icon-name, a frame parameter
854 The name to use in the icon for this frame, when and if the icon
855 appears. If this is @code{nil}, the frame's title is used.
857 @vindex window-id, a frame parameter
859 The ID number which the graphical display uses for this frame. Emacs
860 assigns this parameter when the frame is created; changing the
861 parameter has no effect on the actual ID number.
863 @vindex outer-window-id, a frame parameter
864 @item outer-window-id
865 The ID number of the outermost window-system window in which the frame
866 exists. As with @code{window-id}, changing this parameter has no
869 @vindex wait-for-wm, a frame parameter
871 If non-@code{nil}, tell Xt to wait for the window manager to confirm
872 geometry changes. Some window managers, including versions of Fvwm2
873 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
874 prevent hanging with those window managers.
876 @vindex sticky, a frame parameter
878 If non-@code{nil}, the frame is visible on all virtual desktops on systems
879 with virtual desktops.
882 @vindex parent-id, a frame parameter
884 @c ??? Not yet working.
885 The X window number of the window that should be the parent of this one.
886 Specifying this lets you create an Emacs window inside some other
887 application's window. (It is not certain this will be implemented; try
888 it and see if it works.)
892 @node Cursor Parameters
893 @subsubsection Cursor Parameters
894 @cindex cursor, and frame parameters
896 This frame parameter controls the way the cursor looks.
899 @vindex cursor-type, a frame parameter
901 How to display the cursor. Legitimate values are:
905 Display a filled box. (This is the default.)
907 Display a hollow box.
909 Don't display a cursor.
911 Display a vertical bar between characters.
912 @item (bar . @var{width})
913 Display a vertical bar @var{width} pixels wide between characters.
915 Display a horizontal bar.
916 @item (hbar . @var{height})
917 Display a horizontal bar @var{height} pixels high.
922 The @code{cursor-type} frame parameter may be overridden by the
923 variables @code{cursor-type} and
924 @code{cursor-in-non-selected-windows}:
927 This buffer-local variable controls how the cursor looks in a selected
928 window showing the buffer. If its value is @code{t}, that means to
929 use the cursor specified by the @code{cursor-type} frame parameter.
930 Otherwise, the value should be one of the cursor types listed above,
931 and it overrides the @code{cursor-type} frame parameter.
934 @defopt cursor-in-non-selected-windows
935 This buffer-local variable controls how the cursor looks in a window
936 that is not selected. It supports the same values as the
937 @code{cursor-type} frame parameter; also, @code{nil} means don't
938 display a cursor in nonselected windows, and @code{t} (the default)
939 means use a standard modification of the usual cursor type (solid box
940 becomes hollow box, and bar becomes a narrower bar).
943 @defopt blink-cursor-alist
944 This variable specifies how to blink the cursor. Each element has the
945 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
946 type equals @var{on-state} (comparing using @code{equal}), the
947 corresponding @var{off-state} specifies what the cursor looks like
948 when it blinks ``off''. Both @var{on-state} and @var{off-state}
949 should be suitable values for the @code{cursor-type} frame parameter.
951 There are various defaults for how to blink each type of cursor, if
952 the type is not mentioned as an @var{on-state} here. Changes in this
953 variable do not take effect immediately, only when you specify the
954 @code{cursor-type} frame parameter.
957 @node Font and Color Parameters
958 @subsubsection Font and Color Parameters
959 @cindex font and color, frame parameters
961 These frame parameters control the use of fonts and colors.
964 @vindex font-backend, a frame parameter
966 A list of symbols, specifying the @dfn{font backends} to use for
967 drawing fonts in the frame, in order of priority. On X, there are
968 currently two available font backends: @code{x} (the X core font
969 driver) and @code{xft} (the Xft font driver). On Windows, there are
970 currently two available font backends: @code{gdi} and
971 @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
972 Manual}). On other systems, there is only one available font backend,
973 so it does not make sense to modify this frame parameter.
975 @vindex background-mode, a frame parameter
976 @item background-mode
977 This parameter is either @code{dark} or @code{light}, according
978 to whether the background color is a light one or a dark one.
980 @vindex tty-color-mode, a frame parameter
982 @cindex standard colors for character terminals
983 This parameter overrides the terminal's color support as given by the
984 system's terminal capabilities database in that this parameter's value
985 specifies the color mode to use on a text terminal. The value can be
986 either a symbol or a number. A number specifies the number of colors
987 to use (and, indirectly, what commands to issue to produce each
988 color). For example, @code{(tty-color-mode . 8)} specifies use of the
989 ANSI escape sequences for 8 standard text colors. A value of -1 turns
992 If the parameter's value is a symbol, it specifies a number through
993 the value of @code{tty-color-mode-alist}, and the associated number is
996 @vindex screen-gamma, a frame parameter
998 @cindex gamma correction
999 If this is a number, Emacs performs ``gamma correction'' which adjusts
1000 the brightness of all colors. The value should be the screen gamma of
1001 your display, a floating point number.
1003 Usual PC monitors have a screen gamma of 2.2, so color values in
1004 Emacs, and in X windows generally, are calibrated to display properly
1005 on a monitor with that gamma value. If you specify 2.2 for
1006 @code{screen-gamma}, that means no correction is needed. Other values
1007 request correction, designed to make the corrected colors appear on
1008 your screen the way they would have appeared without correction on an
1009 ordinary monitor with a gamma value of 2.2.
1011 If your monitor displays colors too light, you should specify a
1012 @code{screen-gamma} value smaller than 2.2. This requests correction
1013 that makes colors darker. A screen gamma value of 1.5 may give good
1014 results for LCD color displays.
1016 @vindex alpha, a frame parameter
1018 @cindex opacity, frame
1019 @cindex transparency, frame
1020 @vindex frame-alpha-lower-limit
1021 This parameter specifies the opacity of the frame, on graphical
1022 displays that support variable opacity. It should be an integer
1023 between 0 and 100, where 0 means completely transparent and 100 means
1024 completely opaque. It can also have a @code{nil} value, which tells
1025 Emacs not to set the frame opacity (leaving it to the window manager).
1027 To prevent the frame from disappearing completely from view, the
1028 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
1029 If the value of the frame parameter is less than the value of this
1030 variable, Emacs uses the latter. By default,
1031 @code{frame-alpha-lower-limit} is 20.
1033 The @code{alpha} frame parameter can also be a cons cell
1034 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
1035 opacity of the frame when it is selected, and @samp{inactive} is the
1036 opacity when it is not selected.
1039 The following frame parameters are semi-obsolete in that they are
1040 automatically equivalent to particular face attributes of particular
1041 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
1044 @vindex font, a frame parameter
1046 The name of the font for displaying text in the frame. This is a
1047 string, either a valid font name for your system or the name of an Emacs
1048 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
1049 attribute of the @code{default} face.
1051 @vindex foreground-color, a frame parameter
1052 @item foreground-color
1053 The color to use for the image of a character. It is equivalent to
1054 the @code{:foreground} attribute of the @code{default} face.
1056 @vindex background-color, a frame parameter
1057 @item background-color
1058 The color to use for the background of characters. It is equivalent to
1059 the @code{:background} attribute of the @code{default} face.
1061 @vindex mouse-color, a frame parameter
1063 The color for the mouse pointer. It is equivalent to the @code{:background}
1064 attribute of the @code{mouse} face.
1066 @vindex cursor-color, a frame parameter
1068 The color for the cursor that shows point. It is equivalent to the
1069 @code{:background} attribute of the @code{cursor} face.
1071 @vindex border-color, a frame parameter
1073 The color for the border of the frame. It is equivalent to the
1074 @code{:background} attribute of the @code{border} face.
1076 @vindex scroll-bar-foreground, a frame parameter
1077 @item scroll-bar-foreground
1078 If non-@code{nil}, the color for the foreground of scroll bars. It is
1079 equivalent to the @code{:foreground} attribute of the
1080 @code{scroll-bar} face.
1082 @vindex scroll-bar-background, a frame parameter
1083 @item scroll-bar-background
1084 If non-@code{nil}, the color for the background of scroll bars. It is
1085 equivalent to the @code{:background} attribute of the
1086 @code{scroll-bar} face.
1089 @node Size and Position
1090 @subsection Frame Size And Position
1091 @cindex size of frame
1094 @cindex resize frame
1096 You can read or change the size and position of a frame using the
1097 frame parameters @code{left}, @code{top}, @code{height}, and
1098 @code{width}. Whatever geometry parameters you don't specify are chosen
1099 by the window manager in its usual fashion.
1101 Here are some special features for working with sizes and positions.
1102 (For the precise meaning of ``selected frame'' used by these functions,
1103 see @ref{Input Focus}.)
1105 @defun set-frame-position frame left top
1106 This function sets the position of the top left corner of @var{frame} to
1107 @var{left} and @var{top}. These arguments are measured in pixels, and
1108 normally count from the top left corner of the screen.
1110 Negative parameter values position the bottom edge of the window up from
1111 the bottom edge of the screen, or the right window edge to the left of
1112 the right edge of the screen. It would probably be better if the values
1113 were always counted from the left and top, so that negative arguments
1114 would position the frame partly off the top or left edge of the screen,
1115 but it seems inadvisable to change that now.
1118 @defun frame-height &optional frame
1119 @defunx frame-width &optional frame
1120 These functions return the height and width of @var{frame}, measured in
1121 lines and columns. If you don't supply @var{frame}, they use the
1125 @defun frame-pixel-height &optional frame
1126 @defunx frame-pixel-width &optional frame
1127 These functions return the height and width of the main display area
1128 of @var{frame}, measured in pixels. If you don't supply @var{frame},
1129 they use the selected frame. For a text terminal, the results are in
1130 characters rather than pixels.
1132 These values include the internal borders, and windows' scroll bars
1133 and fringes (which belong to individual windows, not to the frame
1134 itself). The exact value of the heights depends on the window-system
1135 and toolkit in use. With GTK+, the height does not include any tool
1136 bar or menu bar. With the Motif or Lucid toolkits, it includes the
1137 tool bar but not the menu bar. In a graphical version with no
1138 toolkit, it includes both the tool bar and menu bar. For a text
1139 terminal, the result includes the menu bar.
1142 @defun frame-char-height &optional frame
1143 @defunx frame-char-width &optional frame
1144 These functions return the height and width of a character in
1145 @var{frame}, measured in pixels. The values depend on the choice of
1146 font. If you don't supply @var{frame}, these functions use the selected
1150 @defun set-frame-size frame cols rows
1151 This function sets the size of @var{frame}, measured in characters;
1152 @var{cols} and @var{rows} specify the new width and height.
1154 To set the size based on values measured in pixels, use
1155 @code{frame-char-height} and @code{frame-char-width} to convert
1156 them to units of characters.
1159 @defun set-frame-height frame lines &optional pretend
1160 This function resizes @var{frame} to a height of @var{lines} lines. The
1161 sizes of existing windows in @var{frame} are altered proportionally to
1164 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
1165 lines of output in @var{frame}, but does not change its value for the
1166 actual height of the frame. This is only useful on text terminals.
1167 Using a smaller height than the terminal actually implements may be
1168 useful to reproduce behavior observed on a smaller screen, or if the
1169 terminal malfunctions when using its whole screen. Setting the frame
1170 height ``for real'' does not always work, because knowing the correct
1171 actual size may be necessary for correct cursor positioning on
1175 @defun set-frame-width frame width &optional pretend
1176 This function sets the width of @var{frame}, measured in characters.
1177 The argument @var{pretend} has the same meaning as in
1178 @code{set-frame-height}.
1181 @c FIXME? Belongs more in Emacs manual than here?
1182 @c But, e.g., fit-window-to-buffer is in this manual.
1183 @deffn Command fit-frame-to-buffer &optional frame max-height min-height
1184 This command adjusts the height of @var{frame} (the default is the
1185 selected frame) to fit its contents. The optional arguments
1186 @var{max-height} and @var{min-height} specify the maximum and minimum
1187 new frame heights, respectively.
1189 @vindex fit-frame-to-buffer-bottom-margin
1190 The default minimum height corresponds to @code{window-min-height}.
1191 The default maximum height is the screen height below the current top
1192 position of the frame, minus any margin specified by the option
1193 @code{fit-frame-to-buffer-bottom-margin}.
1197 @subsection Geometry
1199 Here's how to examine the data in an X-style window geometry
1202 @defun x-parse-geometry geom
1203 @cindex geometry specification
1204 The function @code{x-parse-geometry} converts a standard X window
1205 geometry string to an alist that you can use as part of the argument to
1208 The alist describes which parameters were specified in @var{geom}, and
1209 gives the values specified for them. Each element looks like
1210 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
1211 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1213 For the size parameters, the value must be an integer. The position
1214 parameter names @code{left} and @code{top} are not totally accurate,
1215 because some values indicate the position of the right or bottom edges
1216 instead. The @var{value} possibilities for the position parameters are:
1217 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1218 as previously described (@pxref{Position Parameters}).
1223 (x-parse-geometry "35x70+0-0")
1224 @result{} ((height . 70) (width . 35)
1225 (top - 0) (left . 0))
1229 @node Terminal Parameters
1230 @section Terminal Parameters
1231 @cindex terminal parameters
1233 Each terminal has a list of associated parameters. These
1234 @dfn{terminal parameters} are mostly a convenient way of storage for
1235 terminal-local variables, but some terminal parameters have a special
1238 This section describes functions to read and change the parameter values
1239 of a terminal. They all accept as their argument either a terminal or
1240 a frame; the latter means use that frame's terminal. An argument of
1241 @code{nil} means the selected frame's terminal.
1243 @defun terminal-parameters &optional terminal
1244 This function returns an alist listing all the parameters of
1245 @var{terminal} and their values.
1248 @defun terminal-parameter terminal parameter
1249 This function returns the value of the parameter @var{parameter} (a
1250 symbol) of @var{terminal}. If @var{terminal} has no setting for
1251 @var{parameter}, this function returns @code{nil}.
1254 @defun set-terminal-parameter terminal parameter value
1255 This function sets the parameter @var{parm} of @var{terminal} to the
1256 specified @var{value}, and returns the previous value of that
1260 Here's a list of a few terminal parameters that have a special
1264 @item background-mode
1265 The classification of the terminal's background color, either
1266 @code{light} or @code{dark}.
1267 @item normal-erase-is-backspace
1268 Value is either 1 or 0, depending on whether
1269 @code{normal-erase-is-backspace-mode} is turned on or off on this
1270 terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1271 @item terminal-initted
1272 After the terminal is initialized, this is set to the
1273 terminal-specific initialization function.
1277 @section Frame Titles
1280 Every frame has a @code{name} parameter; this serves as the default
1281 for the frame title which window systems typically display at the top of
1282 the frame. You can specify a name explicitly by setting the @code{name}
1285 Normally you don't specify the name explicitly, and Emacs computes the
1286 frame name automatically based on a template stored in the variable
1287 @code{frame-title-format}. Emacs recomputes the name each time the
1288 frame is redisplayed.
1290 @defvar frame-title-format
1291 This variable specifies how to compute a name for a frame when you have
1292 not explicitly specified one. The variable's value is actually a mode
1293 line construct, just like @code{mode-line-format}, except that the
1294 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
1298 @defvar icon-title-format
1299 This variable specifies how to compute the name for an iconified frame,
1300 when you have not explicitly specified the frame title. This title
1301 appears in the icon itself.
1304 @defvar multiple-frames
1305 This variable is set automatically by Emacs. Its value is @code{t} when
1306 there are two or more frames (not counting minibuffer-only frames or
1307 invisible frames). The default value of @code{frame-title-format} uses
1308 @code{multiple-frames} so as to put the buffer name in the frame title
1309 only when there is more than one frame.
1311 The value of this variable is not guaranteed to be accurate except
1312 while processing @code{frame-title-format} or
1313 @code{icon-title-format}.
1316 @node Deleting Frames
1317 @section Deleting Frames
1318 @cindex deleting frames
1320 A @dfn{live frame} is one that has not been deleted. When a frame
1321 is deleted, it is removed from its terminal display, although it may
1322 continue to exist as a Lisp object until there are no more references
1325 @deffn Command delete-frame &optional frame force
1326 @vindex delete-frame-functions
1327 This function deletes the frame @var{frame}. Unless @var{frame} is a
1328 tooltip, it first runs the hook @code{delete-frame-functions} (each
1329 function gets one argument, @var{frame}). By default, @var{frame} is
1332 A frame cannot be deleted if its minibuffer is used by other frames.
1333 Normally, you cannot delete a frame if all other frames are invisible,
1334 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1337 @defun frame-live-p frame
1338 The function @code{frame-live-p} returns non-@code{nil} if the frame
1339 @var{frame} has not been deleted. The possible non-@code{nil} return
1340 values are like those of @code{framep}. @xref{Frames}.
1343 Some window managers provide a command to delete a window. These work
1344 by sending a special message to the program that operates the window.
1345 When Emacs gets one of these commands, it generates a
1346 @code{delete-frame} event, whose normal definition is a command that
1347 calls the function @code{delete-frame}. @xref{Misc Events}.
1349 @node Finding All Frames
1350 @section Finding All Frames
1351 @cindex frames, scanning all
1354 This function returns a list of all the live frames, i.e., those that
1355 have not been deleted. It is analogous to @code{buffer-list} for
1356 buffers, and includes frames on all terminals. The list that you get
1357 is newly created, so modifying the list doesn't have any effect on the
1361 @defun visible-frame-list
1362 This function returns a list of just the currently visible frames.
1363 @xref{Visibility of Frames}. Frames on text terminals always count as
1364 ``visible'', even though only the selected one is actually displayed.
1367 @defun next-frame &optional frame minibuf
1368 This function lets you cycle conveniently through all the frames on
1369 the current display from an arbitrary starting point. It returns the
1370 ``next'' frame after @var{frame} in the cycle. If @var{frame} is
1371 omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
1374 The second argument, @var{minibuf}, says which frames to consider:
1378 Exclude minibuffer-only frames.
1379 @item @code{visible}
1380 Consider all visible frames.
1382 Consider all visible or iconified frames.
1384 Consider only the frames using that particular window as their
1387 Consider all frames.
1391 @defun previous-frame &optional frame minibuf
1392 Like @code{next-frame}, but cycles through all frames in the opposite
1396 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1399 @node Minibuffers and Frames
1400 @section Minibuffers and Frames
1402 Normally, each frame has its own minibuffer window at the bottom, which
1403 is used whenever that frame is selected. If the frame has a minibuffer,
1404 you can get it with @code{minibuffer-window} (@pxref{Definition of
1405 minibuffer-window}).
1407 However, you can also create a frame with no minibuffer. Such a frame
1408 must use the minibuffer window of some other frame. When you create the
1409 frame, you can explicitly specify the minibuffer window to use (in some
1410 other frame). If you don't, then the minibuffer is found in the frame
1411 which is the value of the variable @code{default-minibuffer-frame}. Its
1412 value should be a frame that does have a minibuffer.
1414 If you use a minibuffer-only frame, you might want that frame to raise
1415 when you enter the minibuffer. If so, set the variable
1416 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
1418 @defvar default-minibuffer-frame
1419 This variable specifies the frame to use for the minibuffer window, by
1420 default. It does not affect existing frames. It is always local to
1421 the current terminal and cannot be buffer-local. @xref{Multiple
1426 @section Input Focus
1428 @c @cindex selected frame Duplicates selected-frame, same for selected-window.
1430 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
1431 window always resides on the selected frame.
1433 When Emacs displays its frames on several terminals (@pxref{Multiple
1434 Terminals}), each terminal has its own selected frame. But only one
1435 of these is ``@emph{the} selected frame'': it's the frame that belongs
1436 to the terminal from which the most recent input came. That is, when
1437 Emacs runs a command that came from a certain terminal, the selected
1438 frame is the one of that terminal. Since Emacs runs only a single
1439 command at any given time, it needs to consider only one selected
1440 frame at a time; this frame is what we call @dfn{the selected frame}
1441 in this manual. The display on which the selected frame is shown is
1442 the @dfn{selected frame's display}.
1444 @defun selected-frame
1445 This function returns the selected frame.
1448 Some window systems and window managers direct keyboard input to the
1449 window object that the mouse is in; others require explicit clicks or
1450 commands to @dfn{shift the focus} to various window objects. Either
1451 way, Emacs automatically keeps track of which frame has the focus. To
1452 explicitly switch to a different frame from a Lisp function, call
1453 @code{select-frame-set-input-focus}.
1455 Lisp programs can also switch frames ``temporarily'' by calling the
1456 function @code{select-frame}. This does not alter the window system's
1457 concept of focus; rather, it escapes from the window manager's control
1458 until that control is somehow reasserted.
1460 When using a text terminal, only one frame can be displayed at a time
1461 on the terminal, so after a call to @code{select-frame}, the next
1462 redisplay actually displays the newly selected frame. This frame
1463 remains selected until a subsequent call to @code{select-frame}. Each
1464 frame on a text terminal has a number which appears in the mode line
1465 before the buffer name (@pxref{Mode Line Variables}).
1467 @defun select-frame-set-input-focus frame &optional norecord
1468 This function selects @var{frame}, raises it (should it happen to be
1469 obscured by other frames) and tries to give it the X server's focus.
1470 On a text terminal, the next redisplay displays the new frame on the
1471 entire terminal screen. The optional argument @var{norecord} has the
1472 same meaning as for @code{select-frame} (see below). The return value
1473 of this function is not significant.
1476 @deffn Command select-frame frame &optional norecord
1477 This function selects frame @var{frame}, temporarily disregarding the
1478 focus of the X server if any. The selection of @var{frame} lasts until
1479 the next time the user does something to select a different frame, or
1480 until the next time this function is called. (If you are using a
1481 window system, the previously selected frame may be restored as the
1482 selected frame after return to the command loop, because it still may
1483 have the window system's input focus.)
1485 The specified @var{frame} becomes the selected frame, and its terminal
1486 becomes the selected terminal. This function then calls
1487 @code{select-window} as a subroutine, passing the window selected
1488 within @var{frame} as its first argument and @var{norecord} as its
1489 second argument (hence, if @var{norecord} is non-@code{nil}, this
1490 avoids changing the order of recently selected windows nor the buffer
1491 list). @xref{Selecting Windows}.
1493 This function returns @var{frame}, or @code{nil} if @var{frame} has
1496 In general, you should never use @code{select-frame} in a way that
1497 could switch to a different terminal without switching back when
1501 Emacs cooperates with the window system by arranging to select frames as
1502 the server and window manager request. It does so by generating a
1503 special kind of input event, called a @dfn{focus} event, when
1504 appropriate. The command loop handles a focus event by calling
1505 @code{handle-switch-frame}. @xref{Focus Events}.
1507 @deffn Command handle-switch-frame frame
1508 This function handles a focus event by selecting frame @var{frame}.
1510 Focus events normally do their job by invoking this command.
1511 Don't call it for any other reason.
1514 @defun redirect-frame-focus frame &optional focus-frame
1515 This function redirects focus from @var{frame} to @var{focus-frame}.
1516 This means that @var{focus-frame} will receive subsequent keystrokes and
1517 events intended for @var{frame}. After such an event, the value of
1518 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1519 events specifying @var{frame} will instead select @var{focus-frame}.
1521 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1522 redirection for @var{frame}, which therefore once again receives its own
1525 One use of focus redirection is for frames that don't have minibuffers.
1526 These frames use minibuffers on other frames. Activating a minibuffer
1527 on another frame redirects focus to that frame. This puts the focus on
1528 the minibuffer's frame, where it belongs, even though the mouse remains
1529 in the frame that activated the minibuffer.
1531 Selecting a frame can also change focus redirections. Selecting frame
1532 @code{bar}, when @code{foo} had been selected, changes any redirections
1533 pointing to @code{foo} so that they point to @code{bar} instead. This
1534 allows focus redirection to work properly when the user switches from
1535 one frame to another using @code{select-window}.
1537 This means that a frame whose focus is redirected to itself is treated
1538 differently from a frame whose focus is not redirected.
1539 @code{select-frame} affects the former but not the latter.
1541 The redirection lasts until @code{redirect-frame-focus} is called to
1545 @defvar focus-in-hook
1546 This is a normal hook run when an Emacs frame gains input focus.
1549 @defvar focus-out-hook
1550 This is a normal hook run when an Emacs frame loses input focus.
1553 @defopt focus-follows-mouse
1554 This option is how you inform Emacs whether the window manager transfers
1555 focus when the user moves the mouse. Non-@code{nil} says that it does.
1556 When this is so, the command @code{other-frame} moves the mouse to a
1557 position consistent with the new selected frame.
1560 @node Visibility of Frames
1561 @section Visibility of Frames
1562 @cindex visible frame
1563 @cindex invisible frame
1564 @cindex iconified frame
1565 @cindex minimized frame
1566 @cindex frame visibility
1568 A frame on a graphical display may be @dfn{visible}, @dfn{invisible},
1569 or @dfn{iconified}. If it is visible, its contents are displayed in
1570 the usual manner. If it is iconified, its contents are not displayed,
1571 but there is a little icon somewhere to bring the frame back into view
1572 (some window managers refer to this state as @dfn{minimized} rather
1573 than @dfn{iconified}, but from Emacs' point of view they are the same
1574 thing). If a frame is invisible, it is not displayed at all.
1576 Visibility is meaningless on text terminals, since only the selected
1577 one is actually displayed in any case.
1579 @defun frame-visible-p frame
1580 This function returns the visibility status of frame @var{frame}. The
1581 value is @code{t} if @var{frame} is visible, @code{nil} if it is
1582 invisible, and @code{icon} if it is iconified.
1584 On a text terminal, all frames are considered ``visible'' for the
1585 purposes of this function, even though only one frame is displayed.
1586 @xref{Raising and Lowering}.
1589 @deffn Command iconify-frame &optional frame
1590 This function iconifies frame @var{frame}. If you omit @var{frame}, it
1591 iconifies the selected frame.
1594 @deffn Command make-frame-visible &optional frame
1595 This function makes frame @var{frame} visible. If you omit
1596 @var{frame}, it makes the selected frame visible. This does not raise
1597 the frame, but you can do that with @code{raise-frame} if you wish
1598 (@pxref{Raising and Lowering}).
1601 @deffn Command make-frame-invisible &optional frame force
1602 This function makes frame @var{frame} invisible. If you omit
1603 @var{frame}, it makes the selected frame invisible.
1605 Unless @var{force} is non-@code{nil}, this function refuses to make
1606 @var{frame} invisible if all other frames are invisible..
1609 The visibility status of a frame is also available as a frame
1610 parameter. You can read or change it as such. @xref{Management
1611 Parameters}. The user can also iconify and deiconify frames with the
1612 window manager. This happens below the level at which Emacs can exert
1613 any control, but Emacs does provide events that you can use to keep
1614 track of such changes. @xref{Misc Events}.
1616 @node Raising and Lowering
1617 @section Raising and Lowering Frames
1619 @cindex raising a frame
1620 @cindex lowering a frame
1621 Most window systems use a desktop metaphor. Part of this metaphor
1622 is the idea that system-level windows (e.g., Emacs frames) are
1623 stacked in a notional third dimension perpendicular to the screen
1624 surface. Where two overlap, the one higher up covers the one
1625 underneath. You can @dfn{raise} or @dfn{lower} a frame using the
1626 functions @code{raise-frame} and @code{lower-frame}.
1628 @deffn Command raise-frame &optional frame
1629 This function raises frame @var{frame} (default, the selected frame).
1630 If @var{frame} is invisible or iconified, this makes it visible.
1633 @deffn Command lower-frame &optional frame
1634 This function lowers frame @var{frame} (default, the selected frame).
1637 @defopt minibuffer-auto-raise
1638 If this is non-@code{nil}, activation of the minibuffer raises the frame
1639 that the minibuffer window is in.
1642 On window systems, you can also enable auto-raising (on frame
1643 selection) or auto-lowering (on frame deselection) using frame
1644 parameters. @xref{Management Parameters}.
1647 The concept of raising and lowering frames also applies to text
1648 terminal frames. On each text terminal, only the top frame is
1649 displayed at any one time.
1651 @defun tty-top-frame terminal
1652 This function returns the top frame on @var{terminal}. @var{terminal}
1653 should be a terminal object, a frame (meaning that frame's terminal),
1654 or @code{nil} (meaning the selected frame's terminal). If it does not
1655 refer to a text terminal, the return value is @code{nil}.
1658 @node Frame Configurations
1659 @section Frame Configurations
1660 @cindex frame configuration
1662 A @dfn{frame configuration} records the current arrangement of frames,
1663 all their properties, and the window configuration of each one.
1664 (@xref{Window Configurations}.)
1666 @defun current-frame-configuration
1667 This function returns a frame configuration list that describes
1668 the current arrangement of frames and their contents.
1671 @defun set-frame-configuration configuration &optional nodelete
1672 This function restores the state of frames described in
1673 @var{configuration}. However, this function does not restore deleted
1676 Ordinarily, this function deletes all existing frames not listed in
1677 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1678 unwanted frames are iconified instead.
1681 @node Mouse Tracking
1682 @section Mouse Tracking
1683 @cindex mouse tracking
1684 @c @cindex tracking the mouse Duplicates track-mouse
1686 Sometimes it is useful to @dfn{track} the mouse, which means to display
1687 something to indicate where the mouse is and move the indicator as the
1688 mouse moves. For efficient mouse tracking, you need a way to wait until
1689 the mouse actually moves.
1691 The convenient way to track the mouse is to ask for events to represent
1692 mouse motion. Then you can wait for motion by waiting for an event. In
1693 addition, you can easily handle any other sorts of events that may
1694 occur. That is useful, because normally you don't want to track the
1695 mouse forever---only until some other event, such as the release of a
1698 @defspec track-mouse body@dots{}
1699 This special form executes @var{body}, with generation of mouse motion
1700 events enabled. Typically, @var{body} would use @code{read-event} to
1701 read the motion events and modify the display accordingly. @xref{Motion
1702 Events}, for the format of mouse motion events.
1704 The value of @code{track-mouse} is that of the last form in @var{body}.
1705 You should design @var{body} to return when it sees the up-event that
1706 indicates the release of the button, or whatever kind of event means
1707 it is time to stop tracking.
1710 The usual purpose of tracking mouse motion is to indicate on the screen
1711 the consequences of pushing or releasing a button at the current
1714 In many cases, you can avoid the need to track the mouse by using
1715 the @code{mouse-face} text property (@pxref{Special Properties}).
1716 That works at a much lower level and runs more smoothly than
1717 Lisp-level mouse tracking.
1720 @c These are not implemented yet.
1722 These functions change the screen appearance instantaneously. The
1723 effect is transient, only until the next ordinary Emacs redisplay. That
1724 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1725 to change the text, and the body of @code{track-mouse} normally reads
1726 the events itself and does not do redisplay.
1728 @defun x-contour-region window beg end
1729 This function draws lines to make a box around the text from @var{beg}
1730 to @var{end}, in window @var{window}.
1733 @defun x-uncontour-region window beg end
1734 This function erases the lines that would make a box around the text
1735 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1736 a contour that you previously made by calling @code{x-contour-region}.
1739 @defun x-draw-rectangle frame left top right bottom
1740 This function draws a hollow rectangle on frame @var{frame} with the
1741 specified edge coordinates, all measured in pixels from the inside top
1742 left corner. It uses the cursor color, the one used for indicating the
1746 @defun x-erase-rectangle frame left top right bottom
1747 This function erases a hollow rectangle on frame @var{frame} with the
1748 specified edge coordinates, all measured in pixels from the inside top
1749 left corner. Erasure means redrawing the text and background that
1750 normally belong in the specified rectangle.
1754 @node Mouse Position
1755 @section Mouse Position
1756 @cindex mouse position
1757 @cindex position of mouse
1759 The functions @code{mouse-position} and @code{set-mouse-position}
1760 give access to the current position of the mouse.
1762 @defun mouse-position
1763 This function returns a description of the position of the mouse. The
1764 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1765 and @var{y} are integers giving the position in characters relative to
1766 the top left corner of the inside of @var{frame}.
1769 @defvar mouse-position-function
1770 If non-@code{nil}, the value of this variable is a function for
1771 @code{mouse-position} to call. @code{mouse-position} calls this
1772 function just before returning, with its normal return value as the
1773 sole argument, and it returns whatever this function returns to it.
1775 This abnormal hook exists for the benefit of packages like
1776 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1779 @defun set-mouse-position frame x y
1780 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1781 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1782 giving the position in characters relative to the top left corner of the
1783 inside of @var{frame}. If @var{frame} is not visible, this function
1784 does nothing. The return value is not significant.
1787 @defun mouse-pixel-position
1788 This function is like @code{mouse-position} except that it returns
1789 coordinates in units of pixels rather than units of characters.
1792 @defun set-mouse-pixel-position frame x y
1793 This function warps the mouse like @code{set-mouse-position} except that
1794 @var{x} and @var{y} are in units of pixels rather than units of
1795 characters. These coordinates are not required to be within the frame.
1797 If @var{frame} is not visible, this function does nothing. The return
1798 value is not significant.
1801 @defun frame-pointer-visible-p &optional frame
1802 This predicate function returns non-@code{nil} if the mouse pointer
1803 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
1804 @var{frame} omitted or @code{nil} means the selected frame. This is
1805 useful when @code{make-pointer-invisible} is set to @code{t}: it
1806 allows to know if the pointer has been hidden.
1807 @xref{Mouse Avoidance,,,emacs, The Emacs Manual}.
1813 @section Pop-Up Menus
1815 A Lisp program can pop up a menu so that the user can choose an
1816 alternative with the mouse. On a text terminal, if the mouse is not
1817 available, the user can choose an alternative using the keyboard
1818 motion keys---@kbd{C-n}, @kbd{C-p}, or up- and down-arrow keys.
1820 @defun x-popup-menu position menu
1821 This function displays a pop-up menu and returns an indication of
1822 what selection the user makes.
1824 The argument @var{position} specifies where on the screen to put the
1825 top left corner of the menu. It can be either a mouse button event
1826 (which says to put the menu where the user actuated the button) or a
1830 ((@var{xoffset} @var{yoffset}) @var{window})
1834 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1835 pixels, counting from the top left corner of @var{window}. @var{window}
1836 may be a window or a frame.
1838 If @var{position} is @code{t}, it means to use the current mouse
1839 position (or the top-left corner of the frame if the mouse is not
1840 available on a text terminal). If @var{position} is @code{nil}, it
1841 means to precompute the key binding equivalents for the keymaps
1842 specified in @var{menu}, without actually displaying or popping up the
1845 The argument @var{menu} says what to display in the menu. It can be a
1846 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
1847 return value is the list of events corresponding to the user's choice.
1848 This list has more than one element if the choice occurred in a
1849 submenu. (Note that @code{x-popup-menu} does not actually execute the
1850 command bound to that sequence of events.) On text terminals and
1851 toolkits that support menu titles, the title is taken from the prompt
1852 string of @var{menu} if @var{menu} is a keymap, or from the prompt
1853 string of the first keymap in @var{menu} if it is a list of keymaps
1854 (@pxref{Defining Menus}).
1856 Alternatively, @var{menu} can have the following form:
1859 (@var{title} @var{pane1} @var{pane2}...)
1863 where each pane is a list of form
1866 (@var{title} @var{item1} @var{item2}...)
1869 Each @var{item} should be a cons cell, @code{(@var{line} . @var{value})},
1870 where @var{line} is a string and @var{value} is the value to return if
1871 that @var{line} is chosen. Unlike in a menu keymap, a @code{nil}
1872 @var{value} does not make the menu item non-selectable.
1873 Alternatively, each @var{item} can be a string rather than a cons
1874 cell; this makes a non-selectable menu item.
1876 If the user gets rid of the menu without making a valid choice, for
1877 instance by clicking the mouse away from a valid choice or by typing
1878 @kbd{C-g}, then this normally results in a quit and
1879 @code{x-popup-menu} does not return. But if @var{position} is a mouse
1880 button event (indicating that the user invoked the menu with the
1881 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1884 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1885 if you could do the job with a prefix key defined with a menu keymap.
1886 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1887 a} can see the individual items in that menu and provide help for them.
1888 If instead you implement the menu by defining a command that calls
1889 @code{x-popup-menu}, the help facilities cannot know what happens inside
1890 that command, so they cannot give any help for the menu's items.
1892 The menu bar mechanism, which lets you switch between submenus by
1893 moving the mouse, cannot look within the definition of a command to see
1894 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1895 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1896 an integrated fashion. This is why all menu bar submenus are
1897 implemented with menu keymaps within the parent menu, and never with
1898 @code{x-popup-menu}. @xref{Menu Bar}.
1900 If you want a menu bar submenu to have contents that vary, you should
1901 still use a menu keymap to implement it. To make the contents vary, add
1902 a hook function to @code{menu-bar-update-hook} to update the contents of
1903 the menu keymap as necessary.
1906 @section Dialog Boxes
1907 @cindex dialog boxes
1909 A dialog box is a variant of a pop-up menu---it looks a little
1910 different, it always appears in the center of a frame, and it has just
1911 one level and one or more buttons. The main use of dialog boxes is
1912 for asking questions that the user can answer with ``yes'', ``no'',
1913 and a few other alternatives. With a single button, they can also
1914 force the user to acknowledge important information. The functions
1915 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1916 keyboard, when called from commands invoked by mouse clicks.
1918 @defun x-popup-dialog position contents &optional header
1919 This function displays a pop-up dialog box and returns an indication of
1920 what selection the user makes. The argument @var{contents} specifies
1921 the alternatives to offer; it has this format:
1924 (@var{title} (@var{string} . @var{value})@dots{})
1928 which looks like the list that specifies a single pane for
1929 @code{x-popup-menu}.
1931 The return value is @var{value} from the chosen alternative.
1933 As for @code{x-popup-menu}, an element of the list may be just a
1934 string instead of a cons cell @code{(@var{string} . @var{value})}.
1935 That makes a box that cannot be selected.
1937 If @code{nil} appears in the list, it separates the left-hand items from
1938 the right-hand items; items that precede the @code{nil} appear on the
1939 left, and items that follow the @code{nil} appear on the right. If you
1940 don't include a @code{nil} in the list, then approximately half the
1941 items appear on each side.
1943 Dialog boxes always appear in the center of a frame; the argument
1944 @var{position} specifies which frame. The possible values are as in
1945 @code{x-popup-menu}, but the precise coordinates or the individual
1946 window don't matter; only the frame matters.
1948 If @var{header} is non-@code{nil}, the frame title for the box is
1949 @samp{Information}, otherwise it is @samp{Question}. The former is used
1950 for @code{message-box} (@pxref{message-box}). (On text terminals, the
1951 box title is not displayed.)
1953 In some configurations, Emacs cannot display a real dialog box; so
1954 instead it displays the same items in a pop-up menu in the center of the
1957 If the user gets rid of the dialog box without making a valid choice,
1958 for instance using the window manager, then this produces a quit and
1959 @code{x-popup-dialog} does not return.
1963 @section Pointer Shape
1964 @cindex pointer shape
1965 @cindex mouse pointer shape
1967 You can specify the mouse pointer style for particular text or
1968 images using the @code{pointer} text property, and for images with the
1969 @code{:pointer} and @code{:map} image properties. The values you can
1970 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1971 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1972 @code{hourglass}. @code{text} stands for the usual mouse pointer
1973 style used over text.
1975 Over void parts of the window (parts that do not correspond to any
1976 of the buffer contents), the mouse pointer usually uses the
1977 @code{arrow} style, but you can specify a different style (one of
1978 those above) by setting @code{void-text-area-pointer}.
1980 @defopt void-text-area-pointer
1981 This variable specifies the mouse pointer style for void text areas.
1982 These include the areas after the end of a line or below the last line
1983 in the buffer. The default is to use the @code{arrow} (non-text)
1987 When using X, you can specify what the @code{text} pointer style
1988 really looks like by setting the variable @code{x-pointer-shape}.
1990 @defvar x-pointer-shape
1991 This variable specifies the pointer shape to use ordinarily in the
1992 Emacs frame, for the @code{text} pointer style.
1995 @defvar x-sensitive-text-pointer-shape
1996 This variable specifies the pointer shape to use when the mouse
1997 is over mouse-sensitive text.
2000 These variables affect newly created frames. They do not normally
2001 affect existing frames; however, if you set the mouse color of a
2002 frame, that also installs the current value of those two variables.
2003 @xref{Font and Color Parameters}.
2005 The values you can use, to specify either of these pointer shapes, are
2006 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
2007 @key{RET} x-pointer @key{RET}} to see a list of them.
2009 @node Window System Selections
2010 @section Window System Selections
2011 @cindex selection (for window systems)
2013 @cindex primary selection
2014 @cindex secondary selection
2016 In the X window system, data can be transferred between different
2017 applications by means of @dfn{selections}. X defines an arbitrary
2018 number of @dfn{selection types}, each of which can store its own data;
2019 however, only three are commonly used: the @dfn{clipboard},
2020 @dfn{primary selection}, and @dfn{secondary selection}. @xref{Cut and
2021 Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
2022 commands that make use of these selections. This section documents
2023 the low-level functions for reading and setting X selections.
2025 @deffn Command x-set-selection type data
2026 This function sets an X selection. It takes two arguments: a
2027 selection type @var{type}, and the value to assign to it, @var{data}.
2029 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
2030 @code{SECONDARY} or @code{CLIPBOARD}. These are symbols with
2031 upper-case names, in accord with X Window System conventions. If
2032 @var{type} is @code{nil}, that stands for @code{PRIMARY}.
2034 If @var{data} is @code{nil}, it means to clear out the selection.
2035 Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
2036 of two integers or list of two integers), an overlay, or a cons of two
2037 markers pointing to the same buffer. An overlay or a pair of markers
2038 stands for text in the overlay or between the markers. The argument
2039 @var{data} may also be a vector of valid non-vector selection values.
2041 This function returns @var{data}.
2044 @defun x-get-selection &optional type data-type
2045 This function accesses selections set up by Emacs or by other X
2046 clients. It takes two optional arguments, @var{type} and
2047 @var{data-type}. The default for @var{type}, the selection type, is
2050 The @var{data-type} argument specifies the form of data conversion to
2051 use, to convert the raw data obtained from another X client into Lisp
2052 data. Meaningful values include @code{TEXT}, @code{STRING},
2053 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
2054 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
2055 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
2056 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
2057 @code{INTEGER}. (These are symbols with upper-case names in accord
2058 with X conventions.) The default for @var{data-type} is
2062 @defopt selection-coding-system
2063 This variable specifies the coding system to use when reading and
2064 writing selections or the clipboard. @xref{Coding
2065 Systems}. The default is @code{compound-text-with-extensions}, which
2066 converts to the text representation that X11 normally uses.
2069 @cindex clipboard support (for MS-Windows)
2070 When Emacs runs on MS-Windows, it does not implement X selections in
2071 general, but it does support the clipboard. @code{x-get-selection}
2072 and @code{x-set-selection} on MS-Windows support the text data type
2073 only; if the clipboard holds other types of data, Emacs treats the
2077 @section Drag and Drop
2079 @vindex x-dnd-test-function
2080 @vindex x-dnd-known-types
2081 When a user drags something from another application over Emacs, that other
2082 application expects Emacs to tell it if Emacs can handle the data that is
2083 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
2084 what to reply. The default value is @code{x-dnd-default-test-function}
2085 which accepts drops if the type of the data to be dropped is present in
2086 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
2087 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
2088 on some other criteria.
2090 @vindex x-dnd-types-alist
2091 If you want to change the way Emacs handles drop of different types
2092 or add a new type, customize @code{x-dnd-types-alist}. This requires
2093 detailed knowledge of what types other applications use for drag and
2096 @vindex dnd-protocol-alist
2097 When an URL is dropped on Emacs it may be a file, but it may also be
2098 another URL type (ftp, http, etc.). Emacs first checks
2099 @code{dnd-protocol-alist} to determine what to do with the URL@. If
2100 there is no match there and if @code{browse-url-browser-function} is
2101 an alist, Emacs looks for a match there. If no match is found the
2102 text for the URL is inserted. If you want to alter Emacs behavior,
2103 you can customize these variables.
2106 @section Color Names
2109 @cindex specify color
2110 @cindex numerical RGB color specification
2111 A color name is text (usually in a string) that specifies a color.
2112 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2113 are allowed; use @kbd{M-x list-colors-display} to see a list of
2114 defined names. You can also specify colors numerically in forms such
2115 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2116 @var{r} specifies the red level, @var{g} specifies the green level,
2117 and @var{b} specifies the blue level. You can use either one, two,
2118 three, or four hex digits for @var{r}; then you must use the same
2119 number of hex digits for all @var{g} and @var{b} as well, making
2120 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
2121 X Window System for more details about numerical RGB specification of
2124 These functions provide a way to determine which color names are
2125 valid, and what they look like. In some cases, the value depends on the
2126 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2127 meaning of the term ``selected frame''.
2129 To read user input of color names with completion, use
2130 @code{read-color} (@pxref{High-Level Completion, read-color}).
2132 @defun color-defined-p color &optional frame
2133 This function reports whether a color name is meaningful. It returns
2134 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
2135 which frame's display to ask about; if @var{frame} is omitted or
2136 @code{nil}, the selected frame is used.
2138 Note that this does not tell you whether the display you are using
2139 really supports that color. When using X, you can ask for any defined
2140 color on any kind of display, and you will get some result---typically,
2141 the closest it can do. To determine whether a frame can really display
2142 a certain color, use @code{color-supported-p} (see below).
2144 @findex x-color-defined-p
2145 This function used to be called @code{x-color-defined-p},
2146 and that name is still supported as an alias.
2149 @defun defined-colors &optional frame
2150 This function returns a list of the color names that are defined
2151 and supported on frame @var{frame} (default, the selected frame).
2152 If @var{frame} does not support colors, the value is @code{nil}.
2154 @findex x-defined-colors
2155 This function used to be called @code{x-defined-colors},
2156 and that name is still supported as an alias.
2159 @defun color-supported-p color &optional frame background-p
2160 This returns @code{t} if @var{frame} can really display the color
2161 @var{color} (or at least something close to it). If @var{frame} is
2162 omitted or @code{nil}, the question applies to the selected frame.
2164 Some terminals support a different set of colors for foreground and
2165 background. If @var{background-p} is non-@code{nil}, that means you are
2166 asking whether @var{color} can be used as a background; otherwise you
2167 are asking whether it can be used as a foreground.
2169 The argument @var{color} must be a valid color name.
2172 @defun color-gray-p color &optional frame
2173 This returns @code{t} if @var{color} is a shade of gray, as defined on
2174 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
2175 question applies to the selected frame. If @var{color} is not a valid
2176 color name, this function returns @code{nil}.
2179 @defun color-values color &optional frame
2181 This function returns a value that describes what @var{color} should
2182 ideally look like on @var{frame}. If @var{color} is defined, the
2183 value is a list of three integers, which give the amount of red, the
2184 amount of green, and the amount of blue. Each integer ranges in
2185 principle from 0 to 65535, but some displays may not use the full
2186 range. This three-element list is called the @dfn{rgb values} of the
2189 If @var{color} is not defined, the value is @code{nil}.
2192 (color-values "black")
2194 (color-values "white")
2195 @result{} (65280 65280 65280)
2196 (color-values "red")
2197 @result{} (65280 0 0)
2198 (color-values "pink")
2199 @result{} (65280 49152 51968)
2200 (color-values "hungry")
2204 The color values are returned for @var{frame}'s display. If
2205 @var{frame} is omitted or @code{nil}, the information is returned for
2206 the selected frame's display. If the frame cannot display colors, the
2207 value is @code{nil}.
2209 @findex x-color-values
2210 This function used to be called @code{x-color-values},
2211 and that name is still supported as an alias.
2214 @node Text Terminal Colors
2215 @section Text Terminal Colors
2216 @cindex colors on text terminals
2218 Text terminals usually support only a small number of colors, and
2219 the computer uses small integers to select colors on the terminal.
2220 This means that the computer cannot reliably tell what the selected
2221 color looks like; instead, you have to inform your application which
2222 small integers correspond to which colors. However, Emacs does know
2223 the standard set of colors and will try to use them automatically.
2225 The functions described in this section control how terminal colors
2228 Several of these functions use or return @dfn{rgb values}, described
2229 in @ref{Color Names}.
2231 These functions accept a display (either a frame or the name of a
2232 terminal) as an optional argument. We hope in the future to make
2233 Emacs support different colors on different text terminals; then this
2234 argument will specify which terminal to operate on (the default being
2235 the selected frame's terminal; @pxref{Input Focus}). At present,
2236 though, the @var{frame} argument has no effect.
2238 @defun tty-color-define name number &optional rgb frame
2239 This function associates the color name @var{name} with
2240 color number @var{number} on the terminal.
2242 The optional argument @var{rgb}, if specified, is an rgb value, a list
2243 of three numbers that specify what the color actually looks like.
2244 If you do not specify @var{rgb}, then this color cannot be used by
2245 @code{tty-color-approximate} to approximate other colors, because
2246 Emacs will not know what it looks like.
2249 @defun tty-color-clear &optional frame
2250 This function clears the table of defined colors for a text terminal.
2253 @defun tty-color-alist &optional frame
2254 This function returns an alist recording the known colors supported by
2257 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2258 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
2259 name, @var{number} is the number used to specify it to the terminal.
2260 If present, @var{rgb} is a list of three color values (for red, green,
2261 and blue) that says what the color actually looks like.
2264 @defun tty-color-approximate rgb &optional frame
2265 This function finds the closest color, among the known colors
2266 supported for @var{display}, to that described by the rgb value
2267 @var{rgb} (a list of color values). The return value is an element of
2268 @code{tty-color-alist}.
2271 @defun tty-color-translate color &optional frame
2272 This function finds the closest color to @var{color} among the known
2273 colors supported for @var{display} and returns its index (an integer).
2274 If the name @var{color} is not defined, the value is @code{nil}.
2278 @section X Resources
2280 This section describes some of the functions and variables for
2281 querying and using X resources, or their equivalent on your operating
2282 system. @xref{X Resources,, X Resources, emacs, The GNU Emacs
2283 Manual}, for more information about X resources.
2285 @defun x-get-resource attribute class &optional component subclass
2286 The function @code{x-get-resource} retrieves a resource value from the X
2287 Window defaults database.
2289 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2290 This function searches using a key of the form
2291 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2292 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2295 The optional arguments @var{component} and @var{subclass} add to the key
2296 and the class, respectively. You must specify both of them or neither.
2297 If you specify them, the key is
2298 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2299 @samp{Emacs.@var{class}.@var{subclass}}.
2302 @defvar x-resource-class
2303 This variable specifies the application name that @code{x-get-resource}
2304 should look up. The default value is @code{"Emacs"}. You can examine X
2305 resources for application names other than ``Emacs'' by binding this
2306 variable to some other string, around a call to @code{x-get-resource}.
2309 @defvar x-resource-name
2310 This variable specifies the instance name that @code{x-get-resource}
2311 should look up. The default value is the name Emacs was invoked with,
2312 or the value specified with the @samp{-name} or @samp{-rn} switches.
2315 To illustrate some of the above, suppose that you have the line:
2318 xterm.vt100.background: yellow
2322 in your X resources file (whose name is usually @file{~/.Xdefaults}
2323 or @file{~/.Xresources}). Then:
2327 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2328 (x-get-resource "vt100.background" "VT100.Background"))
2332 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2333 (x-get-resource "background" "VT100" "vt100" "Background"))
2338 @defvar inhibit-x-resources
2339 If this variable is non-@code{nil}, Emacs does not look up X
2340 resources, and X resources do not have any effect when creating new
2344 @node Display Feature Testing
2345 @section Display Feature Testing
2346 @cindex display feature testing
2348 The functions in this section describe the basic capabilities of a
2349 particular display. Lisp programs can use them to adapt their behavior
2350 to what the display can do. For example, a program that ordinarily uses
2351 a popup menu could use the minibuffer if popup menus are not supported.
2353 The optional argument @var{display} in these functions specifies which
2354 display to ask the question about. It can be a display name, a frame
2355 (which designates the display that frame is on), or @code{nil} (which
2356 refers to the selected frame's display, @pxref{Input Focus}).
2358 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2359 obtain information about displays.
2361 @defun display-popup-menus-p &optional display
2362 This function returns @code{t} if popup menus are supported on
2363 @var{display}, @code{nil} if not. Support for popup menus requires
2364 that the mouse be available, since the menu is popped up by clicking
2365 the mouse on some portion of the Emacs display.
2368 @defun display-graphic-p &optional display
2369 This function returns @code{t} if @var{display} is a graphic display
2370 capable of displaying several frames and several different fonts at
2371 once. This is true for displays that use a window system such as X,
2372 and false for text terminals.
2375 @defun display-mouse-p &optional display
2376 @cindex mouse, availability
2377 This function returns @code{t} if @var{display} has a mouse available,
2381 @defun display-color-p &optional display
2382 @findex x-display-color-p
2383 This function returns @code{t} if the screen is a color screen.
2384 It used to be called @code{x-display-color-p}, and that name
2385 is still supported as an alias.
2388 @defun display-grayscale-p &optional display
2389 This function returns @code{t} if the screen can display shades of gray.
2390 (All color displays can do this.)
2393 @defun display-supports-face-attributes-p attributes &optional display
2394 @anchor{Display Face Attribute Testing}
2395 This function returns non-@code{nil} if all the face attributes in
2396 @var{attributes} are supported (@pxref{Face Attributes}).
2398 The definition of `supported' is somewhat heuristic, but basically
2399 means that a face containing all the attributes in @var{attributes},
2400 when merged with the default face for display, can be represented in a
2405 different in appearance than the default face, and
2408 `close in spirit' to what the attributes specify, if not exact.
2411 Point (2) implies that a @code{:weight black} attribute will be
2412 satisfied by any display that can display bold, as will
2413 @code{:foreground "yellow"} as long as some yellowish color can be
2414 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2415 the tty display code's automatic substitution of a `dim' face for
2419 @defun display-selections-p &optional display
2420 This function returns @code{t} if @var{display} supports selections.
2421 Windowed displays normally support selections, but they may also be
2422 supported in some other cases.
2425 @defun display-images-p &optional display
2426 This function returns @code{t} if @var{display} can display images.
2427 Windowed displays ought in principle to handle images, but some
2428 systems lack the support for that. On a display that does not support
2429 images, Emacs cannot display a tool bar.
2432 @defun display-screens &optional display
2433 This function returns the number of screens associated with the display.
2436 @defun display-pixel-height &optional display
2437 This function returns the height of the screen in pixels.
2438 On a character terminal, it gives the height in characters.
2440 For graphical terminals, note that on ``multi-monitor'' setups this
2441 refers to the pixel height for all physical monitors associated with
2442 @var{display}. @xref{Multiple Terminals}.
2445 @defun display-pixel-width &optional display
2446 This function returns the width of the screen in pixels.
2447 On a character terminal, it gives the width in characters.
2449 For graphical terminals, note that on ``multi-monitor'' setups this
2450 refers to the pixel width for all physical monitors associated with
2451 @var{display}. @xref{Multiple Terminals}.
2454 @defun display-mm-height &optional display
2455 This function returns the height of the screen in millimeters,
2456 or @code{nil} if Emacs cannot get that information.
2458 For graphical terminals, note that on ``multi-monitor'' setups this
2459 refers to the height for all physical monitors associated with
2460 @var{display}. @xref{Multiple Terminals}.
2463 @defun display-mm-width &optional display
2464 This function returns the width of the screen in millimeters,
2465 or @code{nil} if Emacs cannot get that information.
2467 For graphical terminals, note that on ``multi-monitor'' setups this
2468 refers to the width for all physical monitors associated with
2469 @var{display}. @xref{Multiple Terminals}.
2472 @defopt display-mm-dimensions-alist
2473 This variable allows the user to specify the dimensions of graphical
2474 displays returned by @code{display-mm-height} and
2475 @code{display-mm-width} in case the system provides incorrect values.
2478 @cindex backing store
2479 @defun display-backing-store &optional display
2480 This function returns the backing store capability of the display.
2481 Backing store means recording the pixels of windows (and parts of
2482 windows) that are not exposed, so that when exposed they can be
2483 displayed very quickly.
2485 Values can be the symbols @code{always}, @code{when-mapped}, or
2486 @code{not-useful}. The function can also return @code{nil}
2487 when the question is inapplicable to a certain kind of display.
2490 @cindex SaveUnder feature
2491 @defun display-save-under &optional display
2492 This function returns non-@code{nil} if the display supports the
2493 SaveUnder feature. That feature is used by pop-up windows
2494 to save the pixels they obscure, so that they can pop down
2498 @defun display-planes &optional display
2499 This function returns the number of planes the display supports.
2500 This is typically the number of bits per pixel.
2501 For a tty display, it is log to base two of the number of colors supported.
2504 @defun display-visual-class &optional display
2505 This function returns the visual class for the screen. The value is
2506 one of the symbols @code{static-gray} (a limited, unchangeable number
2507 of grays), @code{gray-scale} (a full range of grays),
2508 @code{static-color} (a limited, unchangeable number of colors),
2509 @code{pseudo-color} (a limited number of colors), @code{true-color} (a
2510 full range of colors), and @code{direct-color} (a full range of
2514 @defun display-color-cells &optional display
2515 This function returns the number of color cells the screen supports.
2518 These functions obtain additional information specifically
2521 @defun x-server-version &optional display
2522 This function returns the list of version numbers of the X server
2523 running the display. The value is a list of three integers: the major
2524 and minor version numbers of the X protocol, and the
2525 distributor-specific release number of the X server software itself.
2528 @defun x-server-vendor &optional display
2529 This function returns the ``vendor'' that provided the X server
2530 software (as a string). Really this means whoever distributes the X
2533 When the developers of X labeled software distributors as
2534 ``vendors'', they showed their false assumption that no system could
2535 ever be developed and distributed noncommercially.
2539 @defvar x-no-window-manager
2540 This variable's value is @code{t} if no X window manager is in use.
2546 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2547 width and height of an X Window frame, measured in pixels.