2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2016 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 Geometry:: Geometric properties of frames.
84 * Frame Parameters:: Controlling frame size, position, font, etc.
85 * Terminal Parameters:: Parameters common for all frames on terminal.
86 * Frame Titles:: Automatic updating of frame titles.
87 * Deleting Frames:: Frames last until explicitly deleted.
88 * Finding All Frames:: How to examine all existing frames.
89 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
90 * Input Focus:: Specifying the selected frame.
91 * Visibility of Frames:: Frames may be visible or invisible, or icons.
92 * Raising and Lowering:: Raising a frame makes it hide other windows;
93 lowering it makes the others hide it.
94 * Frame Configurations:: Saving the state of all frames.
95 * Mouse Tracking:: Getting events that say when the mouse moves.
96 * Mouse Position:: Asking where the mouse is, or moving it.
97 * Pop-Up Menus:: Displaying a menu for the user to select from.
98 * Dialog Boxes:: Displaying a box to ask yes or no.
99 * Pointer Shape:: Specifying the shape of the mouse pointer.
100 * Window System Selections:: Transferring text to and from other X clients.
101 * Drag and Drop:: Internals of Drag-and-Drop implementation.
102 * Color Names:: Getting the definitions of color names.
103 * Text Terminal Colors:: Defining colors for text terminals.
104 * Resources:: Getting resource values from the server.
105 * Display Feature Testing:: Determining the features of a terminal.
108 @node Creating Frames
109 @section Creating Frames
110 @cindex frame creation
112 To create a new frame, call the function @code{make-frame}.
114 @deffn Command make-frame &optional alist
115 This function creates and returns a new frame, displaying the current
118 The @var{alist} argument is an alist that specifies frame parameters
119 for the new frame. @xref{Frame Parameters}. If you specify the
120 @code{terminal} parameter in @var{alist}, the new frame is created on
121 that terminal. Otherwise, if you specify the @code{window-system}
122 frame parameter in @var{alist}, that determines whether the frame
123 should be displayed on a text terminal or a graphical terminal.
124 @xref{Window Systems}. If neither is specified, the new frame is
125 created in the same terminal as the selected frame.
127 Any parameters not mentioned in @var{alist} default to the values in
128 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
129 parameters not specified there default from the X resources or its
130 equivalent on your operating system (@pxref{X Resources,, X Resources,
131 emacs, The GNU Emacs Manual}). After the frame is created, Emacs
132 applies any parameters listed in @code{frame-inherited-parameters}
133 (see below) and not present in the argument, taking the values from
134 the frame that was selected when @code{make-frame} was called.
136 Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
137 window manager might position the frame differently than specified by
138 the positional parameters in @var{alist} (@pxref{Position
139 Parameters}). For example, some window managers have a policy of
140 displaying the frame on the monitor that contains the largest part of
141 the window (a.k.a.@: the @dfn{dominating} monitor).
143 This function itself does not make the new frame the selected frame.
144 @xref{Input Focus}. The previously selected frame remains selected.
145 On graphical terminals, however, the windowing system may select the
146 new frame for its own reasons.
149 @defvar before-make-frame-hook
150 A normal hook run by @code{make-frame} before it creates the frame.
153 @defvar after-make-frame-functions
154 An abnormal hook run by @code{make-frame} after it creates the frame.
155 Each function in @code{after-make-frame-functions} receives one argument, the
159 @defvar frame-inherited-parameters
160 This variable specifies the list of frame parameters that a newly
161 created frame inherits from the currently selected frame. For each
162 parameter (a symbol) that is an element in the list and is not present
163 in the argument to @code{make-frame}, the function sets the value of
164 that parameter in the created frame to its value in the selected
168 @node Multiple Terminals
169 @section Multiple Terminals
170 @cindex multiple terminals
172 @cindex multiple X displays
173 @cindex displays, multiple
175 Emacs represents each terminal as a @dfn{terminal object} data type
176 (@pxref{Terminal Type}). On GNU and Unix systems, Emacs can use
177 multiple terminals simultaneously in each session. On other systems,
178 it can only use a single terminal. Each terminal object has the
179 following attributes:
183 The name of the device used by the terminal (e.g., @samp{:0.0} or
187 The terminal and keyboard coding systems used on the terminal.
188 @xref{Terminal I/O Encoding}.
191 The kind of display associated with the terminal. This is the symbol
192 returned by the function @code{terminal-live-p} (i.e., @code{x},
193 @code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.
196 A list of terminal parameters. @xref{Terminal Parameters}.
199 There is no primitive for creating terminal objects. Emacs creates
200 them as needed, such as when you call @code{make-frame-on-display}
203 @defun terminal-name &optional terminal
204 This function returns the file name of the device used by
205 @var{terminal}. If @var{terminal} is omitted or @code{nil}, it
206 defaults to the selected frame's terminal. @var{terminal} can also be
207 a frame, meaning that frame's terminal.
211 This function returns a list of all live terminal objects.
214 @defun get-device-terminal device
215 This function returns a terminal whose device name is given by
216 @var{device}. If @var{device} is a string, it can be either the file
217 name of a terminal device, or the name of an X display of the form
218 @samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a
219 frame, this function returns that frame's terminal; @code{nil} means
220 the selected frame. Finally, if @var{device} is a terminal object
221 that represents a live terminal, that terminal is returned. The
222 function signals an error if its argument is none of the above.
225 @defun delete-terminal &optional terminal force
226 This function deletes all frames on @var{terminal} and frees the
227 resources used by it. It runs the abnormal hook
228 @code{delete-terminal-functions}, passing @var{terminal} as the
229 argument to each function.
231 If @var{terminal} is omitted or @code{nil}, it defaults to the
232 selected frame's terminal. @var{terminal} can also be a frame,
233 meaning that frame's terminal.
235 Normally, this function signals an error if you attempt to delete the
236 sole active terminal, but if @var{force} is non-@code{nil}, you are
237 allowed to do so. Emacs automatically calls this function when the
238 last frame on a terminal is deleted (@pxref{Deleting Frames}).
241 @defvar delete-terminal-functions
242 An abnormal hook run by @code{delete-terminal}. Each function
243 receives one argument, the @var{terminal} argument passed to
244 @code{delete-terminal}. Due to technical details, the functions may
245 be called either just before the terminal is deleted, or just
249 @cindex terminal-local variables
250 A few Lisp variables are @dfn{terminal-local}; that is, they have a
251 separate binding for each terminal. The binding in effect at any time
252 is the one for the terminal that the currently selected frame belongs
253 to. These variables include @code{default-minibuffer-frame},
254 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
255 @code{system-key-alist}. They are always terminal-local, and can
256 never be buffer-local (@pxref{Buffer-Local Variables}).
258 On GNU and Unix systems, each X display is a separate graphical
259 terminal. When Emacs is started from within the X window system, it
260 uses the X display specified by the @env{DISPLAY} environment
261 variable, or by the @samp{--display} option (@pxref{Initial Options,,,
262 emacs, The GNU Emacs Manual}). Emacs can connect to other X displays
263 via the command @code{make-frame-on-display}. Each X display has its
264 own selected frame and its own minibuffer windows; however, only one
265 of those frames is @emph{the} selected frame at any given moment
266 (@pxref{Input Focus}). Emacs can even connect to other text
267 terminals, by interacting with the @command{emacsclient} program.
268 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
270 @cindex X display names
271 @cindex display name on X
272 A single X server can handle more than one display. Each X display
273 has a three-part name,
274 @samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}. The
275 first part, @var{hostname}, specifies the name of the machine to which
276 the display is physically connected. The second part,
277 @var{displaynumber}, is a zero-based number that identifies one or
278 more monitors connected to that machine that share a common keyboard
279 and pointing device (mouse, tablet, etc.). The third part,
280 @var{screennumber}, identifies a zero-based screen number (a separate
281 monitor) that is part of a single monitor collection on that X server.
282 When you use two or more screens belonging to one server, Emacs knows
283 by the similarity in their names that they share a single keyboard.
285 Systems that don't use the X window system, such as MS-Windows,
286 don't support the notion of X displays, and have only one display on
287 each host. The display name on these systems doesn't follow the above
288 3-part format; for example, the display name on MS-Windows systems is
289 a constant string @samp{w32}, and exists for compatibility, so that
290 you could pass it to functions that expect a display name.
292 @deffn Command make-frame-on-display display &optional parameters
293 This function creates and returns a new frame on @var{display}, taking
294 the other frame parameters from the alist @var{parameters}.
295 @var{display} should be the name of an X display (a string).
297 Before creating the frame, this function ensures that Emacs is set
298 up to display graphics. For instance, if Emacs has not processed X
299 resources (e.g., if it was started on a text terminal), it does so at
300 this time. In all other respects, this function behaves like
301 @code{make-frame} (@pxref{Creating Frames}).
304 @defun x-display-list
305 This function returns a list that indicates which X displays Emacs has
306 a connection to. The elements of the list are strings, and each one
310 @defun x-open-connection display &optional xrm-string must-succeed
311 This function opens a connection to the X display @var{display},
312 without creating a frame on that display. Normally, Emacs Lisp
313 programs need not call this function, as @code{make-frame-on-display}
314 calls it automatically. The only reason for calling it is to check
315 whether communication can be established with a given X display.
317 The optional argument @var{xrm-string}, if not @code{nil}, is a string
318 of resource names and values, in the same format used in the
319 @file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The
320 GNU Emacs Manual}. These values apply to all Emacs frames created on
321 this display, overriding the resource values recorded in the X server.
322 Here's an example of what this string might look like:
325 "*BorderWidth: 3\n*InternalBorder: 2\n"
328 If @var{must-succeed} is non-@code{nil}, failure to open the connection
329 terminates Emacs. Otherwise, it is an ordinary Lisp error.
332 @defun x-close-connection display
333 This function closes the connection to display @var{display}. Before
334 you can do this, you must first delete all the frames that were open
335 on that display (@pxref{Deleting Frames}).
338 @cindex multi-monitor
339 On some multi-monitor setups, a single X display outputs to more
340 than one physical monitor. You can use the functions
341 @code{display-monitor-attributes-list} and @code{frame-monitor-attributes}
342 to obtain information about such setups.
344 @defun display-monitor-attributes-list &optional display
345 This function returns a list of physical monitor attributes on
346 @var{display}, which can be a display name (a string), a terminal, or
347 a frame; if omitted or @code{nil}, it defaults to the selected frame's
348 display. Each element of the list is an association list,
349 representing the attributes of a physical monitor. The first element
350 corresponds to the primary monitor. The attribute keys and values
355 Position of the top-left corner of the monitor's screen and its size,
356 in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}. Note
357 that, if the monitor is not the primary monitor, some of the
358 coordinates might be negative.
361 Position of the top-left corner and size of the work area (usable
362 space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}.
363 This may be different from @samp{geometry} in that space occupied by
364 various window manager features (docks, taskbars, etc.)@: may be
365 excluded from the work area. Whether or not such features actually
366 subtract from the work area depends on the platform and environment.
367 Again, if the monitor is not the primary monitor, some of the
368 coordinates might be negative.
371 Width and height in millimeters as @samp{(@var{width} @var{height})}
374 List of frames that this physical monitor dominates (see below).
377 Name of the physical monitor as @var{string}.
380 Source of the multi-monitor information as @var{string};
381 e.g., @samp{XRandr} or @samp{Xinerama}.
384 @var{x}, @var{y}, @var{width}, and @var{height} are integers.
385 @samp{name} and @samp{source} may be absent.
387 A frame is @dfn{dominated} by a physical monitor when either the
388 largest area of the frame resides in that monitor, or (if the frame
389 does not intersect any physical monitors) that monitor is the closest
390 to the frame. Every (non-tooltip) frame (whether visible or not) in a
391 graphical display is dominated by exactly one physical monitor at a
392 time, though the frame can span multiple (or no) physical monitors.
394 Here's an example of the data produced by this function on a 2-monitor
398 (display-monitor-attributes-list)
400 (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor}
401 (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height}
404 (frames #<frame emacs@@host *Messages* 0x11578c0>
405 #<frame emacs@@host *scratch* 0x114b838>))
406 ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor}
407 (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used}
415 @defun frame-monitor-attributes &optional frame
416 This function returns the attributes of the physical monitor
417 dominating (see above) @var{frame}, which defaults to the selected frame.
422 @section Frame Geometry
423 @cindex frame geometry
424 @cindex frame position
425 @cindex position of frame
427 @cindex size of frame
429 The geometry of a frame depends on the toolkit that was used to build
430 this instance of Emacs and the terminal that displays the frame. This
431 chapter describes these dependencies and some of the functions to deal
432 with them. Note that the @var{frame} argument of all of these functions
433 has to specify a live frame (@pxref{Deleting Frames}). If omitted or
434 @code{nil}, it specifies the selected frame (@pxref{Input Focus}).
437 * Frame Layout:: Basic layout of frames.
438 * Frame Font:: The default font of a frame and how to set it.
439 * Size and Position:: Changing the size and position of a frame.
440 * Implied Frame Resizing:: Implied resizing of frames and how to prevent it.
445 @subsection Frame Layout
447 @cindex layout of frame
449 The drawing below sketches the layout of a frame on a graphical
454 <------------ Outer Frame Width ----------->
455 ___________________________________________
456 ^(0) ___________ External Border __________ |
457 | | |_____________ Title Bar ______________| |
458 | | (1)_____________ Menu Bar ______________| | ^
459 | | (2)_____________ Tool Bar ______________| | ^
460 | | (3) _________ Internal Border ________ | | ^
463 Outer | | | Inner | | | Native
464 Frame | | | Frame | | | Frame
465 Height | | | Height | | | Height
467 | | | |<--+--- Inner Frame Width ------->| | | |
469 | | | |___v______________________________| | | |
470 | | |___________ Internal Border __________| | v
471 v |______________ External Border _____________|
472 <-------- Native Frame Width -------->
477 In practice not all of the areas shown in the drawing will or may be
478 present. The meaning of these areas is:
486 The @dfn{outer frame} is a rectangle comprising all areas shown in the
487 drawing. The edges of that rectangle are called the @dfn{outer edges}
488 of the frame. The @dfn{outer width} and @dfn{outer height} of the frame
489 specify the size of that rectangle.
491 @cindex outer position
492 The upper left corner of the outer frame (indicated by @samp{(0)} in the
493 drawing above) is the @dfn{outer position} or the frame. It is
494 specified by and settable via the @code{left} and @code{top} frame
495 parameters (@pxref{Position Parameters}) as well as the functions
496 @code{frame-position} and @code{set-frame-position} (@pxref{Size and
499 @item External Border
500 @cindex external border
501 The @dfn{external border} is part of the decorations supplied by the
502 window manager. It's typically used for resizing the frame with the
503 mouse. The external border is normally not shown on ``fullboth'' and
504 maximized frames (@pxref{Size Parameters}) and doesn't exist for text
507 The external border should not be confused with the @dfn{outer
508 border} specified by the @code{border-width} frame parameter
509 (@pxref{Layout Parameters}). Since the outer border is usually ignored
510 on most platforms it is not covered here.
514 The @dfn{title bar} is also part of the window manager's decorations and
515 typically displays the title of the frame (@pxref{Frame Titles}) as well
516 as buttons for minimizing, maximizing and deleting the frame. The title
517 bar is usually not displayed on fullboth (@pxref{Size Parameters})
518 or tooltip frames. Title bars don't exist for text terminal frames.
521 @cindex internal menu bar
522 @cindex external menu bar
523 The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs
524 itself) or external (drawn by a toolkit). Most builds (GTK+, Lucid,
525 Motif and Windows) rely on an external menu bar. NS also uses an
526 external menu bar which, however, is not part of the outer frame.
527 Non-toolkit builds can provide an internal menu bar. On text terminal
528 frames, the menu bar is part of the frame's root window (@pxref{Windows
532 @cindex internal tool bar
533 @cindex external tool bar
534 Like the menu bar, the tool bar (@pxref{Tool Bar}) can be either
535 internal (drawn by Emacs itself) or external (drawn by a toolkit). The
536 GTK+ and NS builds have the tool bar drawn by the toolkit. The
537 remaining builds use internal tool bars. With GTK+ the tool bar can be
538 located on either side of the frame, immediately outside the internal
545 @cindex native height
547 The @dfn{native frame} is a rectangle located entirely within the outer
548 frame. It excludes the areas occupied by the external border, the title
549 bar and any external menu or external tool bar. The area enclosed by
550 the native frame is sometimes also referred to as the @dfn{display area}
551 of the frame. The edges of the native frame are called the @dfn{native
552 edges} of the frame. The @dfn{native width} and @dfn{native height} of
553 the frame specify the size of the rectangle.
555 @cindex native position
556 The top left corner of the native frame specifies the @dfn{native
557 position} of the frame. (1)--(3) in the drawing above indicate that
558 position for the various builds:
561 @item (1) non-toolkit and terminal frames
563 @item (2) Lucid, Motif and Windows frames
565 @item (3) GTK+ and NS frames
568 Accordingly, the native height of a frame includes the height of the
569 tool bar but not that of the menu bar (Lucid, Motif, Windows) or those
570 of the menu bar and the tool bar (non-toolkit and text terminal frames).
572 The native position of a frame is the reference position of functions
573 that set or return the current position of the mouse (@pxref{Mouse
574 Position}) and for functions dealing with the position of windows like
575 @code{window-edges}, @code{window-at} or @code{coordinates-in-window-p}
576 (@pxref{Coordinates and Windows}).
578 @item Internal Border
579 The internal border (@pxref{Layout Parameters}) is a border drawn by
580 Emacs around the inner frame (see below).
587 The @dfn{inner frame} is the rectangle reserved for the frame's windows.
588 It's enclosed by the internal border which, however, is not part of the
589 inner frame. Its edges are called the @dfn{inner edges} of the frame.
590 The @dfn{inner width} and @dfn{inner height} specify the size of the
593 @cindex minibuffer-less frame
594 @cindex minibuffer-only frame
595 As a rule, the inner frame is subdivided into the frame's root window
596 (@pxref{Windows and Frames}) and the frame's minibuffer window
597 (@pxref{Minibuffer Windows}). There are two notable exceptions to this
598 rule: A @dfn{minibuffer-less frame} contains a root window only and does
599 not contain a minibuffer window. A @dfn{minibuffer-only frame} contains
600 only a minibuffer window which also serves as that frame's root window.
601 See @ref{Initial Parameters} for how to create such frame
606 The @dfn{text area} of a frame is a somewhat fictitious area located
607 entirely within the native frame. It can be obtained by removing from
608 the native frame any internal borders, one vertical and one horizontal
609 scroll bar, and one left and one right fringe as specified for this
610 frame, see @ref{Layout Parameters}.
613 @cindex absolute position
614 The @dfn{absolute position} of a frame or its edges is usually given in
615 terms of pixels counted from an origin at position (0, 0) of the frame's
616 display. Note that with multiple monitors the origin does not
617 necessarily coincide with the top left corner of the entire usable
618 display area. Hence the absolute outer position of a frame or the
619 absolute positions of the edges of the outer, native or inner frame can
620 be negative in such an environment even when that frame is completely
623 For a frame on a graphical terminal the following function returns the
624 sizes of the areas described above:
626 @defun frame-geometry &optional frame
627 This function returns geometric attributes of @var{frame}. The return
628 value is an association list of the attributes listed below. All
629 coordinate, height and width values are integers counting pixels.
633 A cons of the absolute X- and Y-coordinates of the outer position of
634 @var{frame}, relative to the origin at position (0, 0) of @var{frame}'s
638 A cons of the outer width and height of @var{frame}.
640 @item external-border-size
641 A cons of the horizontal and vertical width of @var{frame}'s external
642 borders as supplied by the window manager. If the window manager
643 doesn't supply these values, Emacs will try to guess them from the
644 coordinates of the outer and inner frame.
647 A cons of the width and height of the title bar of @var{frame} as
648 supplied by the window manager or operating system. If both of them are
649 zero, the frame has no title bar. If only the width is zero, Emacs was
650 not able to retrieve the width information.
652 @item menu-bar-external
653 If non-@code{nil}, this means the menu bar is external (not part of the
654 native frame of @var{frame}).
657 A cons of the width and height of the menu bar of @var{frame}.
659 @item tool-bar-external
660 If non-@code{nil}, this means the tool bar is external (not part of the
661 native frame of @var{frame}).
663 @item tool-bar-position
664 This tells on which side the tool bar on @var{frame} is and can be one
665 of @code{left}, @code{top}, @code{right} or @code{bottom}. The only
666 toolkit that currently supports a value other than @code{top} is GTK+.
669 A cons of the width and height of the tool bar of @var{frame}.
671 @item internal-border-width
672 The width of the internal border of @var{frame}.
676 The following function can be used to retrieve the edges of the outer,
677 native and inner frame.
679 @defun frame-edges &optional frame type
680 This function returns the edges of the outer, native or inner frame of
681 @var{frame}. @var{frame} must be a live frame and defaults to the
682 selected one. The list returned has the form (@var{left} @var{top}
683 @var{right} @var{bottom}) where all values are in pixels relative to the
684 position (0, 0) of @var{frame}'s display. For terminal frames
685 @var{left} and @var{top} are both zero.
687 Optional argument @var{type} specifies the type of the edges to return:
688 @var{type} @code{outer-edges} means to return the outer edges of
689 @var{frame}, @code{native-edges} (or @code{nil}) means to return its
690 native edges and @code{inner-edges} means to return its inner edges.
692 Notice that the pixels at the positions @var{bottom} and @var{right}
693 lie immediately outside the corresponding frame. This means that if you
694 have, for example, two side-by-side frames positioned such that the
695 right outer edge of the frame on the left equals the left outer edge of
696 the frame on the right, the pixels representing that edge are part
697 of the frame on the right.
702 @subsection Frame Font
704 @cindex default character size
705 @cindex default character width
706 @cindex default width of character
707 @cindex default character height
708 @cindex default height of character
709 Each frame has a @dfn{default font} which specifies the default
710 character size for that frame. This size is meant when retrieving or
711 changing the size of a frame in terms of columns or lines
712 (@pxref{Size Parameters}). It is also used when resizing (@pxref{Window
713 Sizes}) or splitting (@pxref{Splitting Windows}) windows.
717 @cindex canonical character height
718 @cindex canonical character width
719 The terms @dfn{line height} and @dfn{canonical character height} are
720 sometimes used instead of ``default character height''. Similarly, the
721 terms @dfn{column width} and @dfn{canonical character width} are used
722 instead of ``default character width''.
724 @defun frame-char-height &optional frame
725 @defunx frame-char-width &optional frame
726 These functions return the default height and width of a character in
727 @var{frame}, measured in pixels. Together, these values establish the
728 size of the default font on @var{frame}. The values depend on the
729 choice of font for @var{frame}, see @ref{Font and Color Parameters}.
732 The default font can be also set directly with the following function:
734 @deffn Command set-frame-font font &optional keep-size frames
735 This sets the default font to @var{font}. When called interactively, it
736 prompts for the name of a font, and uses that font on the selected
737 frame. When called from Lisp, @var{font} should be a font name (a
738 string), a font object, font entity, or a font spec.
740 If the optional argument @var{keep-size} is @code{nil}, this keeps the
741 number of frame lines and columns fixed. (If non-@code{nil}, the option
742 @code{frame-inhibit-implied-resize} described in the next section will
743 override this.) If @var{keep-size} is non-@code{nil} (or with a prefix
744 argument), it tries to keep the size of the display area of the current
745 frame fixed by adjusting the number of lines and columns.
747 If the optional argument @var{frames} is @code{nil}, this applies the
748 font to the selected frame only. If @var{frames} is non-@code{nil}, it
749 should be a list of frames to act upon, or @code{t} meaning all existing
750 and all future graphical frames.
754 @node Size and Position
755 @subsection Size and Position
757 @cindex frame position
758 @cindex position of frame
760 You can read or change the position of a frame using the frame
761 parameters @code{left} and @code{top} (@pxref{Position Parameters}) and
762 its size using the @code{height} and @code{width} parameters
763 (@pxref{Size Parameters}). Here are some special features for working
764 with sizes and positions. For all of these functions the argument
765 @var{frame} must denote a live frame and defaults to the selected frame.
767 @defun frame-position &optional Lisp_Object &optional frame
768 This function returns the outer position (@pxref{Frame Layout}) of
769 @var{frame} in pixels. The value is a cons giving the coordinates of
770 the top left corner of the outer frame of @var{frame} relative to an
771 origin at the position (0, 0) of the frame's display. On a text
772 terminal frame both values are zero.
775 @defun set-frame-position frame X Y
776 This function sets the outer frame position of @var{frame} to @var{X}
777 and @var{Y}. The latter arguments specify pixels and normally count
778 from an origin at the position (0, 0) of @var{frame}'s display.
780 A negative parameter value positions the right edge of the outer frame
781 by @var{-x} pixels left from the right edge of the screen or the bottom
782 edge by @var{-y} pixels up from the bottom edge of the screen.
784 This function has no effect on text terminal frames.
787 @defun frame-pixel-height &optional frame
788 @defunx frame-pixel-width &optional frame
789 These functions return the inner height and width (the height and
790 width of the display area, see @ref{Frame Layout}) of @var{frame} in
791 pixels. For a text terminal, the results are in characters rather than
795 @defun frame-text-height &optional frame
796 @defunx frame-text-width &optional frame
797 These functions return the height and width of the text area of
798 @var{frame} (@pxref{Frame Layout}), measured in pixels. For a text
799 terminal, the results are in characters rather than pixels.
801 The value returned by @code{frame-text-height} differs from that
802 returned by @code{frame-pixel-height} by not including the heights of
803 any internal tool bar or menu bar, the height of one horizontal scroll
804 bar and the widths of the internal border.
806 The value returned by @code{frame-text-width} differs from that returned
807 by @code{frame-pixel-width} by not including the width of one vertical
808 scroll bar, the widths of one left and one right fringe and the widths
809 of the internal border.
812 @defun frame-height &optional frame
813 @defunx frame-width &optional frame
814 These functions return the height and width of the text area of
815 @var{frame}, measured in units of the default font height and width of
816 @var{frame} (@pxref{Frame Font}). These functions are plain shorthands
817 for writing @code{(frame-parameter frame 'height)} and
818 @code{(frame-parameter frame 'width)}.
820 If the text area of @var{frame} measured in pixels is not a multiple of
821 its default font size, the values returned by these functions are
822 rounded down to the number of characters of the default font that fully
823 fit into the text area.
826 @defopt frame-resize-pixelwise
827 If this option is @code{nil}, a frame's size is usually rounded to a
828 multiple of the current values of that frame's @code{frame-char-height}
829 and @code{frame-char-width} whenever the frame is resized. If this is
830 non-@code{nil}, no rounding occurs, hence frame sizes can
831 increase/decrease by one pixel.
833 Setting this variable usually causes the next resize operation to pass
834 the corresponding size hints to the window manager. This means that
835 this variable should be set only in a user's initial file; applications
836 should never bind it temporarily.
838 The precise meaning of a value of @code{nil} for this option depends on
839 the toolkit used. Dragging the external border with the mouse is done
840 character-wise provided the window manager is willing to process the
841 corresponding size hints. Calling @code{set-frame-size} (see below)
842 with arguments that do not specify the frame size as an integer multiple
843 of its character size, however, may: be ignored, cause a rounding
844 (GTK+), or be accepted (Lucid, Motif, MS-Windows).
846 With some window managers you may have to set this to non-@code{nil} in
847 order to make a frame appear truly maximized or full-screen.
850 @defun set-frame-size frame width height &optional pixelwise
851 This function sets the size of the text area of @var{frame}, measured in
852 terms of the canonical height and width of a character on @var{frame}
853 (@pxref{Frame Font}).
855 The optional argument @var{pixelwise} non-@code{nil} means to measure
856 the new width and height in units of pixels instead. Note that if
857 @code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
858 fully honor the request if it does not increase/decrease the frame size
859 to a multiple of its character size.
862 @defun set-frame-height frame height &optional pretend pixelwise
863 This function resizes the text area of @var{frame} to a height of
864 @var{height} lines. The sizes of existing windows in @var{frame} are
865 altered proportionally to fit.
867 If @var{pretend} is non-@code{nil}, then Emacs displays @var{height}
868 lines of output in @var{frame}, but does not change its value for the
869 actual height of the frame. This is only useful on text terminals.
870 Using a smaller height than the terminal actually implements may be
871 useful to reproduce behavior observed on a smaller screen, or if the
872 terminal malfunctions when using its whole screen. Setting the frame
873 height directly does not always work, because knowing the correct
874 actual size may be necessary for correct cursor positioning on
877 The optional fourth argument @var{pixelwise} non-@code{nil} means that
878 @var{frame} should be @var{height} pixels high. Note that if
879 @code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
880 fully honor the request if it does not increase/decrease the frame
881 height to a multiple of its character height.
884 @defun set-frame-width frame width &optional pretend pixelwise
885 This function sets the width of the text area of @var{frame}, measured
886 in characters. The argument @var{pretend} has the same meaning as in
887 @code{set-frame-height}.
889 The optional fourth argument @var{pixelwise} non-@code{nil} means that
890 @var{frame} should be @var{width} pixels wide. Note that if
891 @code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
892 fully honor the request if it does not increase/decrease the frame width
893 to a multiple of its character width.
896 None of these three functions will make a frame smaller than needed to
897 display all of its windows together with their scroll bars, fringes,
898 margins, dividers, mode and header lines. This contrasts with requests
899 by the window manager triggered, for example, by dragging the external
900 border of a frame with the mouse. Such requests are always honored by
901 clipping, if necessary, portions that cannot be displayed at the right,
902 bottom corner of the frame.
905 @node Implied Frame Resizing
906 @subsection Implied Frame Resizing
907 @cindex implied frame resizing
908 @cindex implied resizing of frame
910 By default, Emacs tries to keep the number of lines and columns of a
911 frame's text area unaltered when, for example, adding or removing the
912 menu bar, changing the default font or setting the width of the frame's
913 scroll bars. This means, however, that in such case Emacs must ask the
914 window manager to resize the outer frame in order to accommodate the
915 size change. Note that wrapping a menu or tool bar usually does not
916 resize the frame's outer size, hence this will alter the number of
919 Occasionally, such @dfn{implied frame resizing} may be unwanted, for
920 example, when the frame is maximized or made full-screen (where it's
921 turned off by default). In other cases you can disable implied resizing
922 with the following option:
924 @defopt frame-inhibit-implied-resize
925 If this option is @code{nil}, changing font, menu bar, tool bar,
926 internal borders, fringes or scroll bars of a specific frame may
927 implicitly resize the frame's display area in order to preserve the
928 number of columns or lines the frame displays. If this option is
929 non-@code{nil}, no implied resizing is done.
931 The value of this option can be also be a list of frame parameters. In
932 that case, implied resizing is inhibited when changing a parameter that
933 appears in this list. The frame parameters currently handled by this
934 option are: @code{font}, @code{font-backend},
935 @code{internal-border-width}, @code{menu-bar-lines} and
936 @code{tool-bar-lines}.
938 Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height},
939 @code{vertical-scroll-bars}, @code{horizontal-scroll-bars},
940 @code{left-fringe} and @code{right-fringe} frame parameters is handled
941 as if the frame contained just one live window. This means, for
942 example, that removing vertical scroll bars on a frame containing
943 several side by side windows will shrink the outer frame width by the
944 width of one scroll bar provided this option is @code{nil} and keep it
945 unchanged if this option is either @code{t} or a list containing
946 @code{vertical-scroll-bars}.
948 The default value is @code{'(tool-bar-lines)} for Lucid, Motif and
949 Windows (which means that adding/removing a tool bar there does not
950 change the outer frame height), @code{nil} on all other window systems
951 including GTK+ (which means that changing any of the parameters listed
952 above may change the size of the outer frame), and @code{t} otherwise
953 (which means the outer frame size never changes implicitly when there's
954 no window system support).
956 Note that when a frame is not large enough to accommodate a change of
957 any of the parameters listed above, Emacs may try to enlarge the frame
958 even if this option is non-@code{nil}.
962 @node Frame Parameters
963 @section Frame Parameters
964 @cindex frame parameters
966 A frame has many parameters that control its appearance and behavior.
967 Just what parameters a frame has depends on what display mechanism it
970 Frame parameters exist mostly for the sake of graphical displays.
971 Most frame parameters have no effect when applied to a frame on a text
972 terminal; only the @code{height}, @code{width}, @code{name},
973 @code{title}, @code{menu-bar-lines}, @code{buffer-list} and
974 @code{buffer-predicate} parameters do something special. If the
975 terminal supports colors, the parameters @code{foreground-color},
976 @code{background-color}, @code{background-mode} and
977 @code{display-type} are also meaningful. If the terminal supports
978 frame transparency, the parameter @code{alpha} is also meaningful.
981 * Parameter Access:: How to change a frame's parameters.
982 * Initial Parameters:: Specifying frame parameters when you make a frame.
983 * Window Frame Parameters:: List of frame parameters for window systems.
984 * Geometry:: Parsing geometry specifications.
987 @node Parameter Access
988 @subsection Access to Frame Parameters
990 These functions let you read and change the parameter values of a
993 @defun frame-parameter frame parameter
994 This function returns the value of the parameter @var{parameter} (a
995 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
996 selected frame's parameter. If @var{frame} has no setting for
997 @var{parameter}, this function returns @code{nil}.
1000 @defun frame-parameters &optional frame
1001 The function @code{frame-parameters} returns an alist listing all the
1002 parameters of @var{frame} and their values. If @var{frame} is
1003 @code{nil} or omitted, this returns the selected frame's parameters
1006 @defun modify-frame-parameters frame alist
1007 This function alters the frame @var{frame} based on the elements of
1008 @var{alist}. Each element of @var{alist} has the form
1009 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming
1010 a parameter. If you don't mention a parameter in @var{alist}, its
1011 value doesn't change. If @var{frame} is @code{nil}, it defaults to
1014 Some parameters are only meaningful for frames on certain kinds of
1015 display (@pxref{Frames}). If @var{alist} includes parameters that are
1016 not meaningful for the @var{frame}'s display, this function will
1017 change its value in the frame's parameter list, but will otherwise
1020 When @var{alist} specifies more than one parameter whose value can
1021 affect the new size of @var{frame}, the final size of the frame may
1022 differ according to the toolkit used. For example, specifying that a
1023 frame should from now on have a menu and/or tool bar instead of none and
1024 simultaneously specifying the new height of the frame will inevitably
1025 lead to a recalculation of the frame's height. Conceptually, in such
1026 case, this function will try to have the explicit height specification
1027 prevail. It cannot be excluded, however, that the addition (or removal)
1028 of the menu or tool bar, when eventually performed by the toolkit, will
1029 defeat this intention.
1031 Sometimes, binding @code{frame-inhibit-implied-resize} (@pxref{Implied
1032 Frame Resizing}) to a non-@code{nil} value around calls to this function
1033 may fix the problem sketched here. Sometimes, however, exactly such
1034 binding may be hit by the problem.
1037 @defun set-frame-parameter frame parm value
1038 This function sets the frame parameter @var{parm} to the specified
1039 @var{value}. If @var{frame} is @code{nil}, it defaults to the selected
1043 @defun modify-all-frames-parameters alist
1044 This function alters the frame parameters of all existing frames
1045 according to @var{alist}, then modifies @code{default-frame-alist}
1046 (and, if necessary, @code{initial-frame-alist}) to apply the same
1047 parameter values to frames that will be created henceforth.
1050 @node Initial Parameters
1051 @subsection Initial Frame Parameters
1052 @cindex parameters of initial frame
1054 You can specify the parameters for the initial startup frame by
1055 setting @code{initial-frame-alist} in your init file (@pxref{Init
1058 @defopt initial-frame-alist
1059 This variable's value is an alist of parameter values used when
1060 creating the initial frame. You can set this variable to specify the
1061 appearance of the initial frame without altering subsequent frames.
1062 Each element has the form:
1065 (@var{parameter} . @var{value})
1068 Emacs creates the initial frame before it reads your init
1069 file. After reading that file, Emacs checks @code{initial-frame-alist},
1070 and applies the parameter settings in the altered value to the already
1071 created initial frame.
1073 If these settings affect the frame geometry and appearance, you'll see
1074 the frame appear with the wrong ones and then change to the specified
1075 ones. If that bothers you, you can specify the same geometry and
1076 appearance with X resources; those do take effect before the frame is
1077 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
1079 X resource settings typically apply to all frames. If you want to
1080 specify some X resources solely for the sake of the initial frame, and
1081 you don't want them to apply to subsequent frames, here's how to achieve
1082 this. Specify parameters in @code{default-frame-alist} to override the
1083 X resources for subsequent frames; then, to prevent these from affecting
1084 the initial frame, specify the same parameters in
1085 @code{initial-frame-alist} with values that match the X resources.
1088 @cindex minibuffer-only frame
1089 If these parameters include @code{(minibuffer . nil)}, that indicates
1090 that the initial frame should have no minibuffer. In this case, Emacs
1091 creates a separate @dfn{minibuffer-only frame} as well.
1093 @defopt minibuffer-frame-alist
1094 This variable's value is an alist of parameter values used when
1095 creating an initial minibuffer-only frame (i.e., the minibuffer-only
1096 frame that Emacs creates if @code{initial-frame-alist} specifies a
1097 frame with no minibuffer).
1100 @defopt default-frame-alist
1101 This is an alist specifying default values of frame parameters for all
1102 Emacs frames---the first frame, and subsequent frames. When using the X
1103 Window System, you can get the same results by means of X resources
1106 Setting this variable does not affect existing frames. Furthermore,
1107 functions that display a buffer in a separate frame may override the
1108 default parameters by supplying their own parameters.
1111 If you invoke Emacs with command-line options that specify frame
1112 appearance, those options take effect by adding elements to either
1113 @code{initial-frame-alist} or @code{default-frame-alist}. Options
1114 which affect just the initial frame, such as @samp{--geometry} and
1115 @samp{--maximized}, add to @code{initial-frame-alist}; the others add
1116 to @code{default-frame-alist}. @pxref{Emacs Invocation,, Command Line
1117 Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
1119 @node Window Frame Parameters
1120 @subsection Window Frame Parameters
1121 @cindex frame parameters for windowed displays
1123 Just what parameters a frame has depends on what display mechanism
1124 it uses. This section describes the parameters that have special
1125 meanings on some or all kinds of terminals. Of these, @code{name},
1126 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
1127 @code{buffer-predicate} provide meaningful information in terminal
1128 frames, and @code{tty-color-mode} is meaningful only for frames on
1132 * Basic Parameters:: Parameters that are fundamental.
1133 * Position Parameters:: The position of the frame on the screen.
1134 * Size Parameters:: Frame's size.
1135 * Layout Parameters:: Size of parts of the frame, and
1136 enabling or disabling some parts.
1137 * Buffer Parameters:: Which buffers have been or should be shown.
1138 * Management Parameters:: Communicating with the window manager.
1139 * Cursor Parameters:: Controlling the cursor appearance.
1140 * Font and Color Parameters:: Fonts and colors for the frame text.
1143 @node Basic Parameters
1144 @subsubsection Basic Parameters
1146 These frame parameters give the most basic information about the
1147 frame. @code{title} and @code{name} are meaningful on all terminals.
1150 @vindex display, a frame parameter
1152 The display on which to open this frame. It should be a string of the
1153 form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the
1154 @env{DISPLAY} environment variable. @xref{Multiple Terminals}, for
1155 more details about display names.
1157 @vindex display-type, a frame parameter
1159 This parameter describes the range of possible colors that can be used
1160 in this frame. Its value is @code{color}, @code{grayscale} or
1163 @vindex title, a frame parameter
1165 If a frame has a non-@code{nil} title, it appears in the window
1166 system's title bar at the top of the frame, and also in the mode line
1167 of windows in that frame if @code{mode-line-frame-identification} uses
1168 @samp{%F} (@pxref{%-Constructs}). This is normally the case when
1169 Emacs is not using a window system, and can only display one frame at
1170 a time. @xref{Frame Titles}.
1172 @vindex name, a frame parameter
1174 The name of the frame. The frame name serves as a default for the frame
1175 title, if the @code{title} parameter is unspecified or @code{nil}. If
1176 you don't specify a name, Emacs sets the frame name automatically
1177 (@pxref{Frame Titles}).
1179 If you specify the frame name explicitly when you create the frame, the
1180 name is also used (instead of the name of the Emacs executable) when
1181 looking up X resources for the frame.
1184 If the frame name was specified explicitly when the frame was created,
1185 this parameter will be that name. If the frame wasn't explicitly
1186 named, this parameter will be @code{nil}.
1189 @node Position Parameters
1190 @subsubsection Position Parameters
1191 @cindex window position on display
1192 @cindex frame position
1194 Position parameters' values are measured in pixels. (Note that none
1195 of these parameters exist on TTY frames.)
1198 @vindex left, a frame parameter
1200 The position, in pixels, of the left (or right) edge of the frame with
1201 respect to the left (or right) edge of the screen. The value may be:
1205 A positive integer relates the left edge of the frame to the left edge
1206 of the screen. A negative integer relates the right frame edge to the
1209 @item @code{(+ @var{pos})}
1210 This specifies the position of the left frame edge relative to the left
1211 screen edge. The integer @var{pos} may be positive or negative; a
1212 negative value specifies a position outside the screen or on a monitor
1213 other than the primary one (for multi-monitor displays).
1215 @item @code{(- @var{pos})}
1216 This specifies the position of the right frame edge relative to the right
1217 screen edge. The integer @var{pos} may be positive or negative; a
1218 negative value specifies a position outside the screen or on a monitor
1219 other than the primary one (for multi-monitor displays).
1222 Some window managers ignore program-specified positions. If you want to
1223 be sure the position you specify is not ignored, specify a
1224 non-@code{nil} value for the @code{user-position} parameter as well.
1226 If the window manager refuses to align a frame at the left or top screen
1227 edge, combining position notation and @code{user-position} as in
1230 (modify-frame-parameters
1231 nil '((user-position . t) (left . (+ -4))))
1234 may help to override that.
1236 @vindex top, a frame parameter
1238 The screen position of the top (or bottom) edge, in pixels, with respect
1239 to the top (or bottom) edge of the screen. It works just like
1240 @code{left}, except vertically instead of horizontally.
1242 @vindex icon-left, a frame parameter
1244 The screen position of the left edge of the frame's icon, in pixels,
1245 counting from the left edge of the screen. This takes effect when the
1246 frame is iconified, if the window manager supports this feature. If
1247 you specify a value for this parameter, then you must also specify a
1248 value for @code{icon-top} and vice versa.
1250 @vindex icon-top, a frame parameter
1252 The screen position of the top edge of the frame's icon, in pixels,
1253 counting from the top edge of the screen. This takes effect when the
1254 frame is iconified, if the window manager supports this feature.
1256 @vindex user-position, a frame parameter
1258 When you create a frame and specify its screen position with the
1259 @code{left} and @code{top} parameters, use this parameter to say whether
1260 the specified position was user-specified (explicitly requested in some
1261 way by a human user) or merely program-specified (chosen by a program).
1262 A non-@code{nil} value says the position was user-specified.
1264 @cindex window positions and window managers
1265 Window managers generally heed user-specified positions, and some heed
1266 program-specified positions too. But many ignore program-specified
1267 positions, placing the window in a default fashion or letting the user
1268 place it with the mouse. Some window managers, including @code{twm},
1269 let the user specify whether to obey program-specified positions or
1272 When you call @code{make-frame}, you should specify a non-@code{nil}
1273 value for this parameter if the values of the @code{left} and @code{top}
1274 parameters represent the user's stated preference; otherwise, use
1279 @node Size Parameters
1280 @subsubsection Size Parameters
1281 @cindex window size on display
1283 Frame parameters specify frame sizes in character units. On
1284 graphical displays, the @code{default} face determines the actual
1285 pixel sizes of these character units (@pxref{Face Attributes}).
1288 @vindex height, a frame parameter
1290 The height of the frame's text area (@pxref{Frame Geometry}), in
1293 @vindex width, a frame parameter
1295 The width of the frame's text area (@pxref{Frame Geometry}), in
1298 @vindex user-size, a frame parameter
1300 This does for the size parameters @code{height} and @code{width} what
1301 the @code{user-position} parameter (@pxref{Position Parameters,
1302 user-position}) does for the position parameters @code{top} and
1305 @cindex fullboth frames
1306 @cindex fullheight frames
1307 @cindex fullwidth frames
1308 @cindex maximized frames
1309 @vindex fullscreen, a frame parameter
1311 This parameter specifies whether to maximize the frame's width, height
1312 or both. Its value can be @code{fullwidth}, @code{fullheight},
1313 @code{fullboth}, or @code{maximized}. A @dfn{fullwidth} frame is as
1314 wide as possible, a @dfn{fullheight} frame is as tall as possible, and
1315 a @dfn{fullboth} frame is both as wide and as tall as possible. A
1316 @dfn{maximized} frame is like a ``fullboth'' frame, except that it usually
1317 keeps its title bar and the buttons for resizing
1318 and closing the frame. Also, maximized frames typically avoid hiding
1319 any task bar or panels displayed on the desktop. A ``fullboth'' frame,
1320 on the other hand, usually omits the title bar and occupies the entire
1321 available screen space.
1323 Full-height and full-width frames are more similar to maximized
1324 frames in this regard. However, these typically display an external
1325 border which might be absent with maximized frames. Hence the heights
1326 of maximized and full-height frames and the widths of maximized and
1327 full-width frames often differ by a few pixels.
1329 With some window managers you may have to customize the variable
1330 @code{frame-resize-pixelwise} (@pxref{Size and Position}) in order to
1331 make a frame truly appear maximized or full-screen. Moreover,
1332 some window managers might not support smooth transition between the
1333 various full-screen or maximization states. Customizing the variable
1334 @code{x-frame-normalize-before-maximize} can help to overcome that.
1336 @vindex fullscreen-restore, a frame parameter
1337 @item fullscreen-restore
1338 This parameter specifies the desired fullscreen state of the frame
1339 after invoking the @code{toggle-frame-fullscreen} command (@pxref{Frame
1340 Commands,,, emacs, The GNU Emacs Manual}) in the ``fullboth'' state.
1341 Normally this parameter is installed automatically by that command when
1342 toggling the state to fullboth. If, however, you start Emacs in the
1343 ``fullboth'' state, you have to specify the desired behavior in your initial
1344 file as, for example
1347 (setq default-frame-alist
1348 '((fullscreen . fullboth) (fullscreen-restore . fullheight)))
1351 This will give a new frame full height after typing in it @key{F11} for
1356 @node Layout Parameters
1357 @subsubsection Layout Parameters
1358 @cindex layout parameters of frames
1359 @cindex frame layout parameters
1361 These frame parameters enable or disable various parts of the
1362 frame, or control their sizes.
1365 @vindex border-width, a frame parameter
1367 The width in pixels of the frame's border.
1369 @vindex internal-border-width, a frame parameter
1370 @item internal-border-width
1371 The distance in pixels between text (or fringe) and the frame's border.
1373 @vindex vertical-scroll-bars, a frame parameter
1374 @item vertical-scroll-bars
1375 Whether the frame has scroll bars for vertical scrolling, and which side
1376 of the frame they should be on. The possible values are @code{left},
1377 @code{right}, and @code{nil} for no scroll bars.
1379 @vindex horizontal-scroll-bars, a frame parameter
1380 @item horizontal-scroll-bars
1381 Whether the frame has scroll bars for horizontal scrolling (@code{t} and
1382 @code{bottom} mean yes, @code{nil} means no).
1384 @vindex scroll-bar-width, a frame parameter
1385 @item scroll-bar-width
1386 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
1387 use the default width.
1389 @vindex scroll-bar-height, a frame parameter
1390 @item scroll-bar-height
1391 The height of horizontal scroll bars, in pixels, or @code{nil} meaning
1392 to use the default height.
1394 @vindex left-fringe, a frame parameter
1395 @vindex right-fringe, a frame parameter
1398 The default width of the left and right fringes of windows in this
1399 frame (@pxref{Fringes}). If either of these is zero, that effectively
1400 removes the corresponding fringe.
1402 When you use @code{frame-parameter} to query the value of either of
1403 these two frame parameters, the return value is always an integer.
1404 When using @code{set-frame-parameter}, passing a @code{nil} value
1405 imposes an actual default value of 8 pixels.
1407 @vindex right-divider-width, a frame parameter
1408 @item right-divider-width
1409 The width (thickness) reserved for the right divider (@pxref{Window
1410 Dividers}) of any window on the frame, in pixels. A value of zero means
1411 to not draw right dividers.
1413 @vindex bottom-divider-width, a frame parameter
1414 @item bottom-divider-width
1415 The width (thickness) reserved for the bottom divider (@pxref{Window
1416 Dividers}) of any window on the frame, in pixels. A value of zero means
1417 to not draw bottom dividers.
1419 @vindex menu-bar-lines frame parameter
1420 @item menu-bar-lines
1421 The number of lines to allocate at the top of the frame for a menu
1422 bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
1423 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
1425 @vindex tool-bar-lines frame parameter
1426 @item tool-bar-lines
1427 The number of lines to use for the tool bar. The default is 1 if Tool
1428 Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The
1431 @vindex tool-bar-position frame parameter
1432 @item tool-bar-position
1433 The position of the tool bar. Currently only for the GTK tool bar.
1434 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
1435 The default is @code{top}.
1437 @vindex line-spacing, a frame parameter
1439 Additional space to leave below each text line, in pixels (a positive
1440 integer). @xref{Line Height}, for more information.
1443 @node Buffer Parameters
1444 @subsubsection Buffer Parameters
1445 @cindex frame, which buffers to display
1446 @cindex buffers to display on frame
1448 These frame parameters, meaningful on all kinds of terminals, deal
1449 with which buffers have been, or should, be displayed in the frame.
1452 @vindex minibuffer, a frame parameter
1454 Whether this frame has its own minibuffer. The value @code{t} means
1455 yes, @code{nil} means no, @code{only} means this frame is just a
1456 minibuffer. If the value is a minibuffer window (in some other
1457 frame), the frame uses that minibuffer.
1459 This frame parameter takes effect when the frame is created, and can
1460 not be changed afterwards.
1462 @vindex buffer-predicate, a frame parameter
1463 @item buffer-predicate
1464 The buffer-predicate function for this frame. The function
1465 @code{other-buffer} uses this predicate (from the selected frame) to
1466 decide which buffers it should consider, if the predicate is not
1467 @code{nil}. It calls the predicate with one argument, a buffer, once for
1468 each buffer; if the predicate returns a non-@code{nil} value, it
1469 considers that buffer.
1471 @vindex buffer-list, a frame parameter
1473 A list of buffers that have been selected in this frame, ordered
1474 most-recently-selected first.
1476 @vindex unsplittable, a frame parameter
1478 If non-@code{nil}, this frame's window is never split automatically.
1481 @node Management Parameters
1482 @subsubsection Window Management Parameters
1483 @cindex window manager interaction, and frame parameters
1485 The following frame parameters control various aspects of the
1486 frame's interaction with the window manager. They have no effect on
1490 @vindex visibility, a frame parameter
1492 The state of visibility of the frame. There are three possibilities:
1493 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
1494 iconified. @xref{Visibility of Frames}.
1496 @vindex auto-raise, a frame parameter
1498 If non-@code{nil}, Emacs automatically raises the frame when it is
1499 selected. Some window managers do not allow this.
1501 @vindex auto-lower, a frame parameter
1503 If non-@code{nil}, Emacs automatically lowers the frame when it is
1504 deselected. Some window managers do not allow this.
1506 @vindex icon-type, a frame parameter
1508 The type of icon to use for this frame. If the value is a string,
1509 that specifies a file containing a bitmap to use; @code{nil} specifies
1510 no icon (in which case the window manager decides what to show); any
1511 other non-@code{nil} value specifies the default Emacs icon.
1513 @vindex icon-name, a frame parameter
1515 The name to use in the icon for this frame, when and if the icon
1516 appears. If this is @code{nil}, the frame's title is used.
1518 @vindex window-id, a frame parameter
1520 The ID number which the graphical display uses for this frame. Emacs
1521 assigns this parameter when the frame is created; changing the
1522 parameter has no effect on the actual ID number.
1524 @vindex outer-window-id, a frame parameter
1525 @item outer-window-id
1526 The ID number of the outermost window-system window in which the frame
1527 exists. As with @code{window-id}, changing this parameter has no
1530 @vindex wait-for-wm, a frame parameter
1532 If non-@code{nil}, tell Xt to wait for the window manager to confirm
1533 geometry changes. Some window managers, including versions of Fvwm2
1534 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
1535 prevent hanging with those window managers.
1537 @vindex sticky, a frame parameter
1539 If non-@code{nil}, the frame is visible on all virtual desktops on systems
1540 with virtual desktops.
1543 @vindex parent-id, a frame parameter
1545 @c ??? Not yet working.
1546 The X window number of the window that should be the parent of this one.
1547 Specifying this lets you create an Emacs window inside some other
1548 application's window. (It is not certain this will be implemented; try
1549 it and see if it works.)
1553 @node Cursor Parameters
1554 @subsubsection Cursor Parameters
1555 @cindex cursor, and frame parameters
1557 This frame parameter controls the way the cursor looks.
1560 @vindex cursor-type, a frame parameter
1562 How to display the cursor. Legitimate values are:
1566 Display a filled box. (This is the default.)
1568 Display a hollow box.
1570 Don't display a cursor.
1572 Display a vertical bar between characters.
1573 @item (bar . @var{width})
1574 Display a vertical bar @var{width} pixels wide between characters.
1576 Display a horizontal bar.
1577 @item (hbar . @var{height})
1578 Display a horizontal bar @var{height} pixels high.
1583 The @code{cursor-type} frame parameter may be overridden by the
1584 variables @code{cursor-type} and
1585 @code{cursor-in-non-selected-windows}:
1588 This buffer-local variable controls how the cursor looks in a selected
1589 window showing the buffer. If its value is @code{t}, that means to
1590 use the cursor specified by the @code{cursor-type} frame parameter.
1591 Otherwise, the value should be one of the cursor types listed above,
1592 and it overrides the @code{cursor-type} frame parameter.
1595 @defopt cursor-in-non-selected-windows
1596 This buffer-local variable controls how the cursor looks in a window
1597 that is not selected. It supports the same values as the
1598 @code{cursor-type} frame parameter; also, @code{nil} means don't
1599 display a cursor in nonselected windows, and @code{t} (the default)
1600 means use a standard modification of the usual cursor type (solid box
1601 becomes hollow box, and bar becomes a narrower bar).
1604 @defopt x-stretch-cursor
1605 This variable controls the width of the block cursor displayed on
1606 extra-wide glyphs such as a tab or a stretch of white space. By
1607 default, the block cursor is only as wide as the font's default
1608 character, and will not cover all of the width of the glyph under it
1609 if that glyph is extra-wide. A non-@code{nil} value of this variable
1610 means draw the block cursor as wide as the glyph under it. The
1611 default value is @code{nil}.
1613 This variable has no effect on text-mode frames, since the text-mode
1614 cursor is drawn by the terminal out of Emacs's control.
1617 @defopt blink-cursor-alist
1618 This variable specifies how to blink the cursor. Each element has the
1619 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
1620 type equals @var{on-state} (comparing using @code{equal}), the
1621 corresponding @var{off-state} specifies what the cursor looks like
1622 when it blinks off. Both @var{on-state} and @var{off-state}
1623 should be suitable values for the @code{cursor-type} frame parameter.
1625 There are various defaults for how to blink each type of cursor, if
1626 the type is not mentioned as an @var{on-state} here. Changes in this
1627 variable do not take effect immediately, only when you specify the
1628 @code{cursor-type} frame parameter.
1631 @node Font and Color Parameters
1632 @subsubsection Font and Color Parameters
1633 @cindex font and color, frame parameters
1635 These frame parameters control the use of fonts and colors.
1638 @vindex font-backend, a frame parameter
1640 A list of symbols, specifying the @dfn{font backends} to use for
1641 drawing fonts in the frame, in order of priority. On X, there are
1642 currently two available font backends: @code{x} (the X core font
1643 driver) and @code{xft} (the Xft font driver). On MS-Windows, there are
1644 currently two available font backends: @code{gdi} and
1645 @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
1646 Manual}). On other systems, there is only one available font backend,
1647 so it does not make sense to modify this frame parameter.
1649 @vindex background-mode, a frame parameter
1650 @item background-mode
1651 This parameter is either @code{dark} or @code{light}, according
1652 to whether the background color is a light one or a dark one.
1654 @vindex tty-color-mode, a frame parameter
1655 @item tty-color-mode
1656 @cindex standard colors for character terminals
1657 This parameter overrides the terminal's color support as given by the
1658 system's terminal capabilities database in that this parameter's value
1659 specifies the color mode to use on a text terminal. The value can be
1660 either a symbol or a number. A number specifies the number of colors
1661 to use (and, indirectly, what commands to issue to produce each
1662 color). For example, @code{(tty-color-mode . 8)} specifies use of the
1663 ANSI escape sequences for 8 standard text colors. A value of -1 turns
1666 If the parameter's value is a symbol, it specifies a number through
1667 the value of @code{tty-color-mode-alist}, and the associated number is
1670 @vindex screen-gamma, a frame parameter
1672 @cindex gamma correction
1673 If this is a number, Emacs performs gamma correction which adjusts
1674 the brightness of all colors. The value should be the screen gamma of
1677 Usual PC monitors have a screen gamma of 2.2, so color values in
1678 Emacs, and in X windows generally, are calibrated to display properly
1679 on a monitor with that gamma value. If you specify 2.2 for
1680 @code{screen-gamma}, that means no correction is needed. Other values
1681 request correction, designed to make the corrected colors appear on
1682 your screen the way they would have appeared without correction on an
1683 ordinary monitor with a gamma value of 2.2.
1685 If your monitor displays colors too light, you should specify a
1686 @code{screen-gamma} value smaller than 2.2. This requests correction
1687 that makes colors darker. A screen gamma value of 1.5 may give good
1688 results for LCD color displays.
1690 @vindex alpha, a frame parameter
1692 @cindex opacity, frame
1693 @cindex transparency, frame
1694 @vindex frame-alpha-lower-limit
1695 This parameter specifies the opacity of the frame, on graphical
1696 displays that support variable opacity. It should be an integer
1697 between 0 and 100, where 0 means completely transparent and 100 means
1698 completely opaque. It can also have a @code{nil} value, which tells
1699 Emacs not to set the frame opacity (leaving it to the window manager).
1701 To prevent the frame from disappearing completely from view, the
1702 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
1703 If the value of the frame parameter is less than the value of this
1704 variable, Emacs uses the latter. By default,
1705 @code{frame-alpha-lower-limit} is 20.
1707 The @code{alpha} frame parameter can also be a cons cell
1708 @code{(@var{active} . @var{inactive})}, where @var{active} is the
1709 opacity of the frame when it is selected, and @var{inactive} is the
1710 opacity when it is not selected.
1713 The following frame parameters are semi-obsolete in that they are
1714 automatically equivalent to particular face attributes of particular
1715 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
1718 @vindex font, a frame parameter
1720 The name of the font for displaying text in the frame. This is a
1721 string, either a valid font name for your system or the name of an Emacs
1722 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
1723 attribute of the @code{default} face.
1725 @vindex foreground-color, a frame parameter
1726 @item foreground-color
1727 The color to use for the image of a character. It is equivalent to
1728 the @code{:foreground} attribute of the @code{default} face.
1730 @vindex background-color, a frame parameter
1731 @item background-color
1732 The color to use for the background of characters. It is equivalent to
1733 the @code{:background} attribute of the @code{default} face.
1735 @vindex mouse-color, a frame parameter
1737 The color for the mouse pointer. It is equivalent to the @code{:background}
1738 attribute of the @code{mouse} face.
1740 @vindex cursor-color, a frame parameter
1742 The color for the cursor that shows point. It is equivalent to the
1743 @code{:background} attribute of the @code{cursor} face.
1745 @vindex border-color, a frame parameter
1747 The color for the border of the frame. It is equivalent to the
1748 @code{:background} attribute of the @code{border} face.
1750 @vindex scroll-bar-foreground, a frame parameter
1751 @item scroll-bar-foreground
1752 If non-@code{nil}, the color for the foreground of scroll bars. It is
1753 equivalent to the @code{:foreground} attribute of the
1754 @code{scroll-bar} face.
1756 @vindex scroll-bar-background, a frame parameter
1757 @item scroll-bar-background
1758 If non-@code{nil}, the color for the background of scroll bars. It is
1759 equivalent to the @code{:background} attribute of the
1760 @code{scroll-bar} face.
1765 @subsection Geometry
1767 Here's how to examine the data in an X-style window geometry
1770 @defun x-parse-geometry geom
1771 @cindex geometry specification
1772 The function @code{x-parse-geometry} converts a standard X window
1773 geometry string to an alist that you can use as part of the argument to
1776 The alist describes which parameters were specified in @var{geom}, and
1777 gives the values specified for them. Each element looks like
1778 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
1779 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1781 For the size parameters, the value must be an integer. The position
1782 parameter names @code{left} and @code{top} are not totally accurate,
1783 because some values indicate the position of the right or bottom edges
1784 instead. The @var{value} possibilities for the position parameters are:
1785 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1786 as previously described (@pxref{Position Parameters}).
1791 (x-parse-geometry "35x70+0-0")
1792 @result{} ((height . 70) (width . 35)
1793 (top - 0) (left . 0))
1797 @node Terminal Parameters
1798 @section Terminal Parameters
1799 @cindex terminal parameters
1801 Each terminal has a list of associated parameters. These
1802 @dfn{terminal parameters} are mostly a convenient way of storage for
1803 terminal-local variables, but some terminal parameters have a special
1806 This section describes functions to read and change the parameter values
1807 of a terminal. They all accept as their argument either a terminal or
1808 a frame; the latter means use that frame's terminal. An argument of
1809 @code{nil} means the selected frame's terminal.
1811 @defun terminal-parameters &optional terminal
1812 This function returns an alist listing all the parameters of
1813 @var{terminal} and their values.
1816 @defun terminal-parameter terminal parameter
1817 This function returns the value of the parameter @var{parameter} (a
1818 symbol) of @var{terminal}. If @var{terminal} has no setting for
1819 @var{parameter}, this function returns @code{nil}.
1822 @defun set-terminal-parameter terminal parameter value
1823 This function sets the parameter @var{parameter} of @var{terminal} to the
1824 specified @var{value}, and returns the previous value of that
1828 Here's a list of a few terminal parameters that have a special
1832 @item background-mode
1833 The classification of the terminal's background color, either
1834 @code{light} or @code{dark}.
1835 @item normal-erase-is-backspace
1836 Value is either 1 or 0, depending on whether
1837 @code{normal-erase-is-backspace-mode} is turned on or off on this
1838 terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1839 @item terminal-initted
1840 After the terminal is initialized, this is set to the
1841 terminal-specific initialization function.
1842 @item tty-mode-set-strings
1843 When present, a list of strings containing escape sequences that Emacs
1844 will output while configuring a tty for rendering. Emacs emits these
1845 strings only when configuring a terminal: if you want to enable a mode
1846 on a terminal that is already active (for example, while in
1847 @code{tty-setup-hook}), explicitly output the necessary escape
1848 sequence using @code{send-string-to-terminal} in addition to adding
1849 the sequence to @code{tty-mode-set-strings}.
1850 @item tty-mode-reset-strings
1851 When present, a list of strings that undo the effects of the strings
1852 in @code{tty-mode-set-strings}. Emacs emits these strings when
1853 exiting, deleting a terminal, or suspending itself.
1857 @section Frame Titles
1860 Every frame has a @code{name} parameter; this serves as the default
1861 for the frame title which window systems typically display at the top of
1862 the frame. You can specify a name explicitly by setting the @code{name}
1865 Normally you don't specify the name explicitly, and Emacs computes the
1866 frame name automatically based on a template stored in the variable
1867 @code{frame-title-format}. Emacs recomputes the name each time the
1868 frame is redisplayed.
1870 @defvar frame-title-format
1871 This variable specifies how to compute a name for a frame when you have
1872 not explicitly specified one. The variable's value is actually a mode
1873 line construct, just like @code{mode-line-format}, except that the
1874 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
1878 @defvar icon-title-format
1879 This variable specifies how to compute the name for an iconified frame,
1880 when you have not explicitly specified the frame title. This title
1881 appears in the icon itself.
1884 @defvar multiple-frames
1885 This variable is set automatically by Emacs. Its value is @code{t} when
1886 there are two or more frames (not counting minibuffer-only frames or
1887 invisible frames). The default value of @code{frame-title-format} uses
1888 @code{multiple-frames} so as to put the buffer name in the frame title
1889 only when there is more than one frame.
1891 The value of this variable is not guaranteed to be accurate except
1892 while processing @code{frame-title-format} or
1893 @code{icon-title-format}.
1896 @node Deleting Frames
1897 @section Deleting Frames
1898 @cindex deleting frames
1900 A @dfn{live frame} is one that has not been deleted. When a frame
1901 is deleted, it is removed from its terminal display, although it may
1902 continue to exist as a Lisp object until there are no more references
1905 @deffn Command delete-frame &optional frame force
1906 @vindex delete-frame-functions
1907 This function deletes the frame @var{frame}. Unless @var{frame} is a
1908 tooltip, it first runs the hook @code{delete-frame-functions} (each
1909 function gets one argument, @var{frame}). By default, @var{frame} is
1912 A frame cannot be deleted as long as its minibuffer serves as surrogate
1913 minibuffer for another frame (@pxref{Minibuffers and Frames}).
1914 Normally, you cannot delete a frame if all other frames are invisible,
1915 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1918 @defun frame-live-p frame
1919 The function @code{frame-live-p} returns non-@code{nil} if the frame
1920 @var{frame} has not been deleted. The possible non-@code{nil} return
1921 values are like those of @code{framep}. @xref{Frames}.
1924 Some window managers provide a command to delete a window. These work
1925 by sending a special message to the program that operates the window.
1926 When Emacs gets one of these commands, it generates a
1927 @code{delete-frame} event, whose normal definition is a command that
1928 calls the function @code{delete-frame}. @xref{Misc Events}.
1930 @node Finding All Frames
1931 @section Finding All Frames
1932 @cindex frames, scanning all
1935 This function returns a list of all the live frames, i.e., those that
1936 have not been deleted. It is analogous to @code{buffer-list} for
1937 buffers, and includes frames on all terminals. The list that you get
1938 is newly created, so modifying the list doesn't have any effect on the
1942 @defun visible-frame-list
1943 This function returns a list of just the currently visible frames.
1944 @xref{Visibility of Frames}. Frames on text terminals always count as
1945 visible, even though only the selected one is actually displayed.
1948 @defun next-frame &optional frame minibuf
1949 This function lets you cycle conveniently through all the frames on
1950 the current display from an arbitrary starting point. It returns the
1951 next frame after @var{frame} in the cycle. If @var{frame} is
1952 omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
1955 The second argument, @var{minibuf}, says which frames to consider:
1959 Exclude minibuffer-only frames.
1960 @item @code{visible}
1961 Consider all visible frames.
1963 Consider all visible or iconified frames.
1965 Consider only the frames using that particular window as their
1968 Consider all frames.
1972 @defun previous-frame &optional frame minibuf
1973 Like @code{next-frame}, but cycles through all frames in the opposite
1977 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1980 @node Minibuffers and Frames
1981 @section Minibuffers and Frames
1983 Normally, each frame has its own minibuffer window at the bottom, which
1984 is used whenever that frame is selected. If the frame has a minibuffer,
1985 you can get it with @code{minibuffer-window} (@pxref{Definition of
1986 minibuffer-window}).
1988 @cindex frame without a minibuffer
1989 @cindex surrogate minibuffer frame
1990 However, you can also create a frame without a minibuffer. Such a frame
1991 must use the minibuffer window of some other frame. That other frame
1992 will serve as @dfn{surrogate minibuffer frame} for this frame and cannot
1993 be deleted via @code{delete-frame} (@pxref{Deleting Frames}) as long as
1996 When you create the frame, you can explicitly specify the minibuffer
1997 window to use (in some other frame). If you don't, then the minibuffer
1998 is found in the frame which is the value of the variable
1999 @code{default-minibuffer-frame}. Its value should be a frame that does
2002 If you use a minibuffer-only frame, you might want that frame to raise
2003 when you enter the minibuffer. If so, set the variable
2004 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
2006 @defvar default-minibuffer-frame
2007 This variable specifies the frame to use for the minibuffer window, by
2008 default. It does not affect existing frames. It is always local to
2009 the current terminal and cannot be buffer-local. @xref{Multiple
2014 @section Input Focus
2016 @c @cindex selected frame Duplicates selected-frame, same for selected-window.
2018 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
2019 window always resides on the selected frame.
2021 When Emacs displays its frames on several terminals (@pxref{Multiple
2022 Terminals}), each terminal has its own selected frame. But only one
2023 of these is @emph{the} selected frame: it's the frame that belongs
2024 to the terminal from which the most recent input came. That is, when
2025 Emacs runs a command that came from a certain terminal, the selected
2026 frame is the one of that terminal. Since Emacs runs only a single
2027 command at any given time, it needs to consider only one selected
2028 frame at a time; this frame is what we call @dfn{the selected frame}
2029 in this manual. The display on which the selected frame is shown is
2030 the @dfn{selected frame's display}.
2032 @defun selected-frame
2033 This function returns the selected frame.
2036 Some window systems and window managers direct keyboard input to the
2037 window object that the mouse is in; others require explicit clicks or
2038 commands to @dfn{shift the focus} to various window objects. Either
2039 way, Emacs automatically keeps track of which frame has the focus. To
2040 explicitly switch to a different frame from a Lisp function, call
2041 @code{select-frame-set-input-focus}.
2043 Lisp programs can also switch frames temporarily by calling the
2044 function @code{select-frame}. This does not alter the window system's
2045 concept of focus; rather, it escapes from the window manager's control
2046 until that control is somehow reasserted.
2048 When using a text terminal, only one frame can be displayed at a time
2049 on the terminal, so after a call to @code{select-frame}, the next
2050 redisplay actually displays the newly selected frame. This frame
2051 remains selected until a subsequent call to @code{select-frame}. Each
2052 frame on a text terminal has a number which appears in the mode line
2053 before the buffer name (@pxref{Mode Line Variables}).
2055 @defun select-frame-set-input-focus frame &optional norecord
2056 This function selects @var{frame}, raises it (should it happen to be
2057 obscured by other frames) and tries to give it the X server's focus.
2058 On a text terminal, the next redisplay displays the new frame on the
2059 entire terminal screen. The optional argument @var{norecord} has the
2060 same meaning as for @code{select-frame} (see below). The return value
2061 of this function is not significant.
2064 @deffn Command select-frame frame &optional norecord
2065 This function selects frame @var{frame}, temporarily disregarding the
2066 focus of the X server if any. The selection of @var{frame} lasts until
2067 the next time the user does something to select a different frame, or
2068 until the next time this function is called. (If you are using a
2069 window system, the previously selected frame may be restored as the
2070 selected frame after return to the command loop, because it still may
2071 have the window system's input focus.)
2073 The specified @var{frame} becomes the selected frame, and its terminal
2074 becomes the selected terminal. This function then calls
2075 @code{select-window} as a subroutine, passing the window selected
2076 within @var{frame} as its first argument and @var{norecord} as its
2077 second argument (hence, if @var{norecord} is non-@code{nil}, this
2078 avoids changing the order of recently selected windows nor the buffer
2079 list). @xref{Selecting Windows}.
2081 This function returns @var{frame}, or @code{nil} if @var{frame} has
2084 In general, you should never use @code{select-frame} in a way that
2085 could switch to a different terminal without switching back when
2089 Emacs cooperates with the window system by arranging to select frames as
2090 the server and window manager request. It does so by generating a
2091 special kind of input event, called a @dfn{focus} event, when
2092 appropriate. The command loop handles a focus event by calling
2093 @code{handle-switch-frame}. @xref{Focus Events}.
2095 @deffn Command handle-switch-frame frame
2096 This function handles a focus event by selecting frame @var{frame}.
2098 Focus events normally do their job by invoking this command.
2099 Don't call it for any other reason.
2102 @defun redirect-frame-focus frame &optional focus-frame
2103 This function redirects focus from @var{frame} to @var{focus-frame}.
2104 This means that @var{focus-frame} will receive subsequent keystrokes and
2105 events intended for @var{frame}. After such an event, the value of
2106 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
2107 events specifying @var{frame} will instead select @var{focus-frame}.
2109 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
2110 redirection for @var{frame}, which therefore once again receives its own
2113 One use of focus redirection is for frames that don't have minibuffers.
2114 These frames use minibuffers on other frames. Activating a minibuffer
2115 on another frame redirects focus to that frame. This puts the focus on
2116 the minibuffer's frame, where it belongs, even though the mouse remains
2117 in the frame that activated the minibuffer.
2119 Selecting a frame can also change focus redirections. Selecting frame
2120 @code{bar}, when @code{foo} had been selected, changes any redirections
2121 pointing to @code{foo} so that they point to @code{bar} instead. This
2122 allows focus redirection to work properly when the user switches from
2123 one frame to another using @code{select-window}.
2125 This means that a frame whose focus is redirected to itself is treated
2126 differently from a frame whose focus is not redirected.
2127 @code{select-frame} affects the former but not the latter.
2129 The redirection lasts until @code{redirect-frame-focus} is called to
2133 @defvar focus-in-hook
2134 This is a normal hook run when an Emacs frame gains input focus.
2137 @defvar focus-out-hook
2138 This is a normal hook run when an Emacs frame loses input focus.
2141 @defopt focus-follows-mouse
2142 This option is how you inform Emacs whether the window manager transfers
2143 focus when the user moves the mouse. Non-@code{nil} says that it does.
2144 When this is so, the command @code{other-frame} moves the mouse to a
2145 position consistent with the new selected frame.
2148 @node Visibility of Frames
2149 @section Visibility of Frames
2150 @cindex visible frame
2151 @cindex invisible frame
2152 @cindex iconified frame
2153 @cindex minimized frame
2154 @cindex frame visibility
2156 A frame on a graphical display may be @dfn{visible}, @dfn{invisible},
2157 or @dfn{iconified}. If it is visible, its contents are displayed in
2158 the usual manner. If it is iconified, its contents are not displayed,
2159 but there is a little icon somewhere to bring the frame back into view
2160 (some window managers refer to this state as @dfn{minimized} rather
2161 than @dfn{iconified}, but from Emacs' point of view they are the same
2162 thing). If a frame is invisible, it is not displayed at all.
2164 Visibility is meaningless on text terminals, since only the selected
2165 one is actually displayed in any case.
2167 @defun frame-visible-p frame
2168 This function returns the visibility status of frame @var{frame}. The
2169 value is @code{t} if @var{frame} is visible, @code{nil} if it is
2170 invisible, and @code{icon} if it is iconified.
2172 On a text terminal, all frames are considered visible for the
2173 purposes of this function, even though only one frame is displayed.
2174 @xref{Raising and Lowering}.
2177 @deffn Command iconify-frame &optional frame
2178 This function iconifies frame @var{frame}. If you omit @var{frame}, it
2179 iconifies the selected frame.
2182 @deffn Command make-frame-visible &optional frame
2183 This function makes frame @var{frame} visible. If you omit
2184 @var{frame}, it makes the selected frame visible. This does not raise
2185 the frame, but you can do that with @code{raise-frame} if you wish
2186 (@pxref{Raising and Lowering}).
2189 @deffn Command make-frame-invisible &optional frame force
2190 This function makes frame @var{frame} invisible. If you omit
2191 @var{frame}, it makes the selected frame invisible.
2193 Unless @var{force} is non-@code{nil}, this function refuses to make
2194 @var{frame} invisible if all other frames are invisible..
2197 The visibility status of a frame is also available as a frame
2198 parameter. You can read or change it as such. @xref{Management
2199 Parameters}. The user can also iconify and deiconify frames with the
2200 window manager. This happens below the level at which Emacs can exert
2201 any control, but Emacs does provide events that you can use to keep
2202 track of such changes. @xref{Misc Events}.
2204 @node Raising and Lowering
2205 @section Raising and Lowering Frames
2207 @cindex raising a frame
2208 @cindex lowering a frame
2209 Most window systems use a desktop metaphor. Part of this metaphor
2210 is the idea that system-level windows (e.g., Emacs frames) are
2211 stacked in a notional third dimension perpendicular to the screen
2212 surface. Where two overlap, the one higher up covers the one
2213 underneath. You can @dfn{raise} or @dfn{lower} a frame using the
2214 functions @code{raise-frame} and @code{lower-frame}.
2216 @deffn Command raise-frame &optional frame
2217 This function raises frame @var{frame} (default, the selected frame).
2218 If @var{frame} is invisible or iconified, this makes it visible.
2221 @deffn Command lower-frame &optional frame
2222 This function lowers frame @var{frame} (default, the selected frame).
2225 @defopt minibuffer-auto-raise
2226 If this is non-@code{nil}, activation of the minibuffer raises the frame
2227 that the minibuffer window is in.
2230 On window systems, you can also enable auto-raising (on frame
2231 selection) or auto-lowering (on frame deselection) using frame
2232 parameters. @xref{Management Parameters}.
2235 The concept of raising and lowering frames also applies to text
2236 terminal frames. On each text terminal, only the top frame is
2237 displayed at any one time.
2239 @defun tty-top-frame &optional terminal
2240 This function returns the top frame on @var{terminal}. @var{terminal}
2241 should be a terminal object, a frame (meaning that frame's terminal),
2242 or @code{nil} (meaning the selected frame's terminal). If it does not
2243 refer to a text terminal, the return value is @code{nil}.
2246 @node Frame Configurations
2247 @section Frame Configurations
2248 @cindex frame configuration
2250 A @dfn{frame configuration} records the current arrangement of frames,
2251 all their properties, and the window configuration of each one.
2252 (@xref{Window Configurations}.)
2254 @defun current-frame-configuration
2255 This function returns a frame configuration list that describes
2256 the current arrangement of frames and their contents.
2259 @defun set-frame-configuration configuration &optional nodelete
2260 This function restores the state of frames described in
2261 @var{configuration}. However, this function does not restore deleted
2264 Ordinarily, this function deletes all existing frames not listed in
2265 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
2266 unwanted frames are iconified instead.
2269 @node Mouse Tracking
2270 @section Mouse Tracking
2271 @cindex mouse tracking
2272 @c @cindex tracking the mouse Duplicates track-mouse
2274 Sometimes it is useful to @dfn{track} the mouse, which means to display
2275 something to indicate where the mouse is and move the indicator as the
2276 mouse moves. For efficient mouse tracking, you need a way to wait until
2277 the mouse actually moves.
2279 The convenient way to track the mouse is to ask for events to represent
2280 mouse motion. Then you can wait for motion by waiting for an event. In
2281 addition, you can easily handle any other sorts of events that may
2282 occur. That is useful, because normally you don't want to track the
2283 mouse forever---only until some other event, such as the release of a
2286 @defspec track-mouse body@dots{}
2287 This special form executes @var{body}, with generation of mouse motion
2288 events enabled. Typically, @var{body} would use @code{read-event} to
2289 read the motion events and modify the display accordingly. @xref{Motion
2290 Events}, for the format of mouse motion events.
2292 The value of @code{track-mouse} is that of the last form in @var{body}.
2293 You should design @var{body} to return when it sees the up-event that
2294 indicates the release of the button, or whatever kind of event means
2295 it is time to stop tracking.
2297 The @code{track-mouse} form causes Emacs to generate mouse motion
2298 events by binding the variable @code{track-mouse} to a
2299 non-@code{nil} value. If that variable has the special value
2300 @code{dragging}, it additionally instructs the display engine to
2301 refrain from changing the shape of the mouse pointer. This is
2302 desirable in Lisp programs that require mouse dragging across large
2303 portions of Emacs display, which might otherwise cause the mouse
2304 pointer to change its shape according to the display portion it hovers
2305 on (@pxref{Pointer Shape}). Therefore, Lisp programs that need the
2306 mouse pointer to retain its original shape during dragging should bind
2307 @code{track-mouse} to the value @code{dragging} at the beginning of
2311 The usual purpose of tracking mouse motion is to indicate on the screen
2312 the consequences of pushing or releasing a button at the current
2315 In many cases, you can avoid the need to track the mouse by using
2316 the @code{mouse-face} text property (@pxref{Special Properties}).
2317 That works at a much lower level and runs more smoothly than
2318 Lisp-level mouse tracking.
2321 @c These are not implemented yet.
2323 These functions change the screen appearance instantaneously. The
2324 effect is transient, only until the next ordinary Emacs redisplay. That
2325 is OK for mouse tracking, since it doesn't make sense for mouse tracking
2326 to change the text, and the body of @code{track-mouse} normally reads
2327 the events itself and does not do redisplay.
2329 @defun x-contour-region window beg end
2330 This function draws lines to make a box around the text from @var{beg}
2331 to @var{end}, in window @var{window}.
2334 @defun x-uncontour-region window beg end
2335 This function erases the lines that would make a box around the text
2336 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
2337 a contour that you previously made by calling @code{x-contour-region}.
2340 @defun x-draw-rectangle frame left top right bottom
2341 This function draws a hollow rectangle on frame @var{frame} with the
2342 specified edge coordinates, all measured in pixels from the inside top
2343 left corner. It uses the cursor color, the one used for indicating the
2347 @defun x-erase-rectangle frame left top right bottom
2348 This function erases a hollow rectangle on frame @var{frame} with the
2349 specified edge coordinates, all measured in pixels from the inside top
2350 left corner. Erasure means redrawing the text and background that
2351 normally belong in the specified rectangle.
2355 @node Mouse Position
2356 @section Mouse Position
2357 @cindex mouse position
2358 @cindex position of mouse
2360 The functions @code{mouse-position} and @code{set-mouse-position}
2361 give access to the current position of the mouse.
2363 @defun mouse-position
2364 This function returns a description of the position of the mouse. The
2365 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
2366 and @var{y} are integers giving the (possibly rounded) position in
2367 multiples of the default character size of @var{frame} (@pxref{Frame
2368 Font}) relative to the native position of @var{frame} (@pxref{Frame
2372 @defvar mouse-position-function
2373 If non-@code{nil}, the value of this variable is a function for
2374 @code{mouse-position} to call. @code{mouse-position} calls this
2375 function just before returning, with its normal return value as the
2376 sole argument, and it returns whatever this function returns to it.
2378 This abnormal hook exists for the benefit of packages like
2379 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
2382 @defun set-mouse-position frame x y
2383 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
2384 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
2385 giving the position in multiples of the default character size of
2386 @var{frame} (@pxref{Frame Font}) relative to the native position of
2387 @var{frame} (@pxref{Frame Geometry}).
2389 The resulting mouse position is constrained to the native frame of
2390 @var{frame}. If @var{frame} is not visible, this function does nothing.
2391 The return value is not significant.
2394 @defun mouse-pixel-position
2395 This function is like @code{mouse-position} except that it returns
2396 coordinates in units of pixels rather than units of characters.
2399 @defun set-mouse-pixel-position frame x y
2400 This function warps the mouse like @code{set-mouse-position} except that
2401 @var{x} and @var{y} are in units of pixels rather than units of
2404 The resulting mouse position is not constrained to the native frame of
2405 @var{frame}. If @var{frame} is not visible, this function does nothing.
2406 The return value is not significant.
2409 On a graphical terminal the following two functions allow the absolute
2410 position of the mouse cursor to be retrieved and set.
2412 @defun mouse-absolute-pixel-position
2413 This function returns a cons cell (@var{x} . @var{y}) of the coordinates
2414 of the mouse cursor position in pixels, relative to a position (0, 0) of
2415 the selected frame's display.
2418 @defun set-mouse-absolute-pixel-position x y
2419 This function moves the mouse cursor to the position (@var{x}, @var{y}).
2420 The coordinates @var{x} and @var{y} are interpreted in pixels relative
2421 to a position (0, 0) of the selected frame's display.
2424 The following function can tell whether the mouse cursor is currently
2427 @defun frame-pointer-visible-p &optional frame
2428 This predicate function returns non-@code{nil} if the mouse pointer
2429 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
2430 @var{frame} omitted or @code{nil} means the selected frame. This is
2431 useful when @code{make-pointer-invisible} is set to @code{t}: it
2432 allows you to know if the pointer has been hidden.
2433 @xref{Mouse Avoidance,,,emacs, The Emacs Manual}.
2439 @section Pop-Up Menus
2440 @cindex menus, popup
2442 A Lisp program can pop up a menu so that the user can choose an
2443 alternative with the mouse. On a text terminal, if the mouse is not
2444 available, the user can choose an alternative using the keyboard
2445 motion keys---@kbd{C-n}, @kbd{C-p}, or up- and down-arrow keys.
2447 @defun x-popup-menu position menu
2448 This function displays a pop-up menu and returns an indication of
2449 what selection the user makes.
2451 The argument @var{position} specifies where on the screen to put the
2452 top left corner of the menu. It can be either a mouse button event
2453 (which says to put the menu where the user actuated the button) or a
2457 ((@var{xoffset} @var{yoffset}) @var{window})
2461 where @var{xoffset} and @var{yoffset} are coordinates, measured in
2462 pixels, counting from the top left corner of @var{window}. @var{window}
2463 may be a window or a frame.
2465 If @var{position} is @code{t}, it means to use the current mouse
2466 position (or the top-left corner of the frame if the mouse is not
2467 available on a text terminal). If @var{position} is @code{nil}, it
2468 means to precompute the key binding equivalents for the keymaps
2469 specified in @var{menu}, without actually displaying or popping up the
2472 The argument @var{menu} says what to display in the menu. It can be a
2473 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
2474 return value is the list of events corresponding to the user's choice.
2475 This list has more than one element if the choice occurred in a
2476 submenu. (Note that @code{x-popup-menu} does not actually execute the
2477 command bound to that sequence of events.) On text terminals and
2478 toolkits that support menu titles, the title is taken from the prompt
2479 string of @var{menu} if @var{menu} is a keymap, or from the prompt
2480 string of the first keymap in @var{menu} if it is a list of keymaps
2481 (@pxref{Defining Menus}).
2483 Alternatively, @var{menu} can have the following form:
2486 (@var{title} @var{pane1} @var{pane2}...)
2490 where each pane is a list of form
2493 (@var{title} @var{item1} @var{item2}...)
2496 Each @var{item} should be a cons cell, @code{(@var{line} . @var{value})},
2497 where @var{line} is a string and @var{value} is the value to return if
2498 that @var{line} is chosen. Unlike in a menu keymap, a @code{nil}
2499 @var{value} does not make the menu item non-selectable.
2500 Alternatively, each @var{item} can be a string rather than a cons
2501 cell; this makes a non-selectable menu item.
2503 If the user gets rid of the menu without making a valid choice, for
2504 instance by clicking the mouse away from a valid choice or by typing
2505 @kbd{C-g}, then this normally results in a quit and
2506 @code{x-popup-menu} does not return. But if @var{position} is a mouse
2507 button event (indicating that the user invoked the menu with the
2508 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
2511 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
2512 if you could do the job with a prefix key defined with a menu keymap.
2513 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
2514 a} can see the individual items in that menu and provide help for them.
2515 If instead you implement the menu by defining a command that calls
2516 @code{x-popup-menu}, the help facilities cannot know what happens inside
2517 that command, so they cannot give any help for the menu's items.
2519 The menu bar mechanism, which lets you switch between submenus by
2520 moving the mouse, cannot look within the definition of a command to see
2521 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
2522 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
2523 an integrated fashion. This is why all menu bar submenus are
2524 implemented with menu keymaps within the parent menu, and never with
2525 @code{x-popup-menu}. @xref{Menu Bar}.
2527 If you want a menu bar submenu to have contents that vary, you should
2528 still use a menu keymap to implement it. To make the contents vary, add
2529 a hook function to @code{menu-bar-update-hook} to update the contents of
2530 the menu keymap as necessary.
2533 @section Dialog Boxes
2534 @cindex dialog boxes
2536 A dialog box is a variant of a pop-up menu---it looks a little
2537 different, it always appears in the center of a frame, and it has just
2538 one level and one or more buttons. The main use of dialog boxes is
2539 for asking questions that the user can answer with ``yes'', ``no'',
2540 and a few other alternatives. With a single button, they can also
2541 force the user to acknowledge important information. The functions
2542 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
2543 keyboard, when called from commands invoked by mouse clicks.
2545 @defun x-popup-dialog position contents &optional header
2546 This function displays a pop-up dialog box and returns an indication of
2547 what selection the user makes. The argument @var{contents} specifies
2548 the alternatives to offer; it has this format:
2551 (@var{title} (@var{string} . @var{value})@dots{})
2555 which looks like the list that specifies a single pane for
2556 @code{x-popup-menu}.
2558 The return value is @var{value} from the chosen alternative.
2560 As for @code{x-popup-menu}, an element of the list may be just a
2561 string instead of a cons cell @code{(@var{string} . @var{value})}.
2562 That makes a box that cannot be selected.
2564 If @code{nil} appears in the list, it separates the left-hand items from
2565 the right-hand items; items that precede the @code{nil} appear on the
2566 left, and items that follow the @code{nil} appear on the right. If you
2567 don't include a @code{nil} in the list, then approximately half the
2568 items appear on each side.
2570 Dialog boxes always appear in the center of a frame; the argument
2571 @var{position} specifies which frame. The possible values are as in
2572 @code{x-popup-menu}, but the precise coordinates or the individual
2573 window don't matter; only the frame matters.
2575 If @var{header} is non-@code{nil}, the frame title for the box is
2576 @samp{Information}, otherwise it is @samp{Question}. The former is used
2577 for @code{message-box} (@pxref{message-box}). (On text terminals, the
2578 box title is not displayed.)
2580 In some configurations, Emacs cannot display a real dialog box; so
2581 instead it displays the same items in a pop-up menu in the center of the
2584 If the user gets rid of the dialog box without making a valid choice,
2585 for instance using the window manager, then this produces a quit and
2586 @code{x-popup-dialog} does not return.
2590 @section Pointer Shape
2591 @cindex pointer shape
2592 @cindex mouse pointer shape
2594 You can specify the mouse pointer style for particular text or
2595 images using the @code{pointer} text property, and for images with the
2596 @code{:pointer} and @code{:map} image properties. The values you can
2597 use in these properties are @code{text} (or @code{nil}), @code{arrow},
2598 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
2599 @code{hourglass}. @code{text} stands for the usual mouse pointer
2600 style used over text.
2602 Over void parts of the window (parts that do not correspond to any
2603 of the buffer contents), the mouse pointer usually uses the
2604 @code{arrow} style, but you can specify a different style (one of
2605 those above) by setting @code{void-text-area-pointer}.
2607 @defopt void-text-area-pointer
2608 This variable specifies the mouse pointer style for void text areas.
2609 These include the areas after the end of a line or below the last line
2610 in the buffer. The default is to use the @code{arrow} (non-text)
2614 When using X, you can specify what the @code{text} pointer style
2615 really looks like by setting the variable @code{x-pointer-shape}.
2617 @defvar x-pointer-shape
2618 This variable specifies the pointer shape to use ordinarily in the
2619 Emacs frame, for the @code{text} pointer style.
2622 @defvar x-sensitive-text-pointer-shape
2623 This variable specifies the pointer shape to use when the mouse
2624 is over mouse-sensitive text.
2627 These variables affect newly created frames. They do not normally
2628 affect existing frames; however, if you set the mouse color of a
2629 frame, that also installs the current value of those two variables.
2630 @xref{Font and Color Parameters}.
2632 The values you can use, to specify either of these pointer shapes, are
2633 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
2634 @key{RET} x-pointer @key{RET}} to see a list of them.
2636 @node Window System Selections
2637 @section Window System Selections
2638 @cindex selection (for window systems)
2640 @cindex primary selection
2641 @cindex secondary selection
2643 In window systems, such as X, data can be transferred between
2644 different applications by means of @dfn{selections}. X defines an
2645 arbitrary number of @dfn{selection types}, each of which can store its
2646 own data; however, only three are commonly used: the @dfn{clipboard},
2647 @dfn{primary selection}, and @dfn{secondary selection}. Other window
2648 systems support only the clipboard. @xref{Cut and Paste,, Cut and
2649 Paste, emacs, The GNU Emacs Manual}, for Emacs commands that make use
2650 of these selections. This section documents the low-level functions
2651 for reading and setting window-system selections.
2653 @deffn Command gui-set-selection type data
2654 This function sets a window-system selection. It takes two arguments:
2655 a selection type @var{type}, and the value to assign to it, @var{data}.
2657 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
2658 @code{SECONDARY} or @code{CLIPBOARD}. These are symbols with
2659 upper-case names, in accord with X Window System conventions. If
2660 @var{type} is @code{nil}, that stands for @code{PRIMARY}.
2662 If @var{data} is @code{nil}, it means to clear out the selection.
2663 Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
2664 of two integers or list of two integers), an overlay, or a cons of two
2665 markers pointing to the same buffer. An overlay or a pair of markers
2666 stands for text in the overlay or between the markers. The argument
2667 @var{data} may also be a vector of valid non-vector selection values.
2669 This function returns @var{data}.
2672 @defun gui-get-selection &optional type data-type
2673 This function accesses selections set up by Emacs or by other
2674 programs. It takes two optional arguments, @var{type} and
2675 @var{data-type}. The default for @var{type}, the selection type, is
2678 The @var{data-type} argument specifies the form of data conversion to
2679 use, to convert the raw data obtained from another program into Lisp
2680 data. Meaningful values include @code{TEXT}, @code{STRING},
2681 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
2682 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
2683 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
2684 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
2685 @code{INTEGER}. (These are symbols with upper-case names in accord
2686 with X conventions.) The default for @var{data-type} is
2687 @code{STRING}. Window systems other than X usually support only a
2688 small subset of these types, in addition to @code{STRING}.
2691 @defopt selection-coding-system
2692 This variable specifies the coding system to use when reading and
2693 writing selections or the clipboard. @xref{Coding
2694 Systems}. The default is @code{compound-text-with-extensions}, which
2695 converts to the text representation that X11 normally uses.
2698 @cindex clipboard support (for MS-Windows)
2699 When Emacs runs on MS-Windows, it does not implement X selections in
2700 general, but it does support the clipboard. @code{gui-get-selection}
2701 and @code{gui-set-selection} on MS-Windows support the text data type
2702 only; if the clipboard holds other types of data, Emacs treats the
2703 clipboard as empty. The supported data type is @code{STRING}.
2705 For backward compatibility, there are obsolete aliases
2706 @code{x-get-selection} and @code{x-set-selection}, which were the
2707 names of @code{gui-get-selection} and @code{gui-set-selection} before
2711 @section Drag and Drop
2712 @cindex drag and drop
2714 @vindex x-dnd-test-function
2715 @vindex x-dnd-known-types
2716 When a user drags something from another application over Emacs, that other
2717 application expects Emacs to tell it if Emacs can handle the data that is
2718 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
2719 what to reply. The default value is @code{x-dnd-default-test-function}
2720 which accepts drops if the type of the data to be dropped is present in
2721 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
2722 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
2723 on some other criteria.
2725 @vindex x-dnd-types-alist
2726 If you want to change the way Emacs handles drop of different types
2727 or add a new type, customize @code{x-dnd-types-alist}. This requires
2728 detailed knowledge of what types other applications use for drag and
2731 @vindex dnd-protocol-alist
2732 When an URL is dropped on Emacs it may be a file, but it may also be
2733 another URL type (ftp, http, etc.). Emacs first checks
2734 @code{dnd-protocol-alist} to determine what to do with the URL@. If
2735 there is no match there and if @code{browse-url-browser-function} is
2736 an alist, Emacs looks for a match there. If no match is found the
2737 text for the URL is inserted. If you want to alter Emacs behavior,
2738 you can customize these variables.
2741 @section Color Names
2744 @cindex specify color
2745 @cindex numerical RGB color specification
2746 A color name is text (usually in a string) that specifies a color.
2747 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2748 are allowed; use @kbd{M-x list-colors-display} to see a list of
2749 defined names. You can also specify colors numerically in forms such
2750 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2751 @var{r} specifies the red level, @var{g} specifies the green level,
2752 and @var{b} specifies the blue level. You can use either one, two,
2753 three, or four hex digits for @var{r}; then you must use the same
2754 number of hex digits for all @var{g} and @var{b} as well, making
2755 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
2756 X Window System for more details about numerical RGB specification of
2759 These functions provide a way to determine which color names are
2760 valid, and what they look like. In some cases, the value depends on the
2761 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2762 meaning of the term ``selected frame''.
2764 To read user input of color names with completion, use
2765 @code{read-color} (@pxref{High-Level Completion, read-color}).
2767 @defun color-defined-p color &optional frame
2768 This function reports whether a color name is meaningful. It returns
2769 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
2770 which frame's display to ask about; if @var{frame} is omitted or
2771 @code{nil}, the selected frame is used.
2773 Note that this does not tell you whether the display you are using
2774 really supports that color. When using X, you can ask for any defined
2775 color on any kind of display, and you will get some result---typically,
2776 the closest it can do. To determine whether a frame can really display
2777 a certain color, use @code{color-supported-p} (see below).
2779 @findex x-color-defined-p
2780 This function used to be called @code{x-color-defined-p},
2781 and that name is still supported as an alias.
2784 @defun defined-colors &optional frame
2785 This function returns a list of the color names that are defined
2786 and supported on frame @var{frame} (default, the selected frame).
2787 If @var{frame} does not support colors, the value is @code{nil}.
2789 @findex x-defined-colors
2790 This function used to be called @code{x-defined-colors},
2791 and that name is still supported as an alias.
2794 @defun color-supported-p color &optional frame background-p
2795 This returns @code{t} if @var{frame} can really display the color
2796 @var{color} (or at least something close to it). If @var{frame} is
2797 omitted or @code{nil}, the question applies to the selected frame.
2799 Some terminals support a different set of colors for foreground and
2800 background. If @var{background-p} is non-@code{nil}, that means you are
2801 asking whether @var{color} can be used as a background; otherwise you
2802 are asking whether it can be used as a foreground.
2804 The argument @var{color} must be a valid color name.
2807 @defun color-gray-p color &optional frame
2808 This returns @code{t} if @var{color} is a shade of gray, as defined on
2809 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
2810 question applies to the selected frame. If @var{color} is not a valid
2811 color name, this function returns @code{nil}.
2814 @defun color-values color &optional frame
2816 This function returns a value that describes what @var{color} should
2817 ideally look like on @var{frame}. If @var{color} is defined, the
2818 value is a list of three integers, which give the amount of red, the
2819 amount of green, and the amount of blue. Each integer ranges in
2820 principle from 0 to 65535, but some displays may not use the full
2821 range. This three-element list is called the @dfn{rgb values} of the
2824 If @var{color} is not defined, the value is @code{nil}.
2827 (color-values "black")
2829 (color-values "white")
2830 @result{} (65280 65280 65280)
2831 (color-values "red")
2832 @result{} (65280 0 0)
2833 (color-values "pink")
2834 @result{} (65280 49152 51968)
2835 (color-values "hungry")
2839 The color values are returned for @var{frame}'s display. If
2840 @var{frame} is omitted or @code{nil}, the information is returned for
2841 the selected frame's display. If the frame cannot display colors, the
2842 value is @code{nil}.
2844 @findex x-color-values
2845 This function used to be called @code{x-color-values},
2846 and that name is still supported as an alias.
2849 @node Text Terminal Colors
2850 @section Text Terminal Colors
2851 @cindex colors on text terminals
2853 Text terminals usually support only a small number of colors, and
2854 the computer uses small integers to select colors on the terminal.
2855 This means that the computer cannot reliably tell what the selected
2856 color looks like; instead, you have to inform your application which
2857 small integers correspond to which colors. However, Emacs does know
2858 the standard set of colors and will try to use them automatically.
2860 The functions described in this section control how terminal colors
2863 Several of these functions use or return @dfn{rgb values}, described
2864 in @ref{Color Names}.
2866 These functions accept a display (either a frame or the name of a
2867 terminal) as an optional argument. We hope in the future to make
2868 Emacs support different colors on different text terminals; then this
2869 argument will specify which terminal to operate on (the default being
2870 the selected frame's terminal; @pxref{Input Focus}). At present,
2871 though, the @var{frame} argument has no effect.
2873 @defun tty-color-define name number &optional rgb frame
2874 This function associates the color name @var{name} with
2875 color number @var{number} on the terminal.
2877 The optional argument @var{rgb}, if specified, is an rgb value, a list
2878 of three numbers that specify what the color actually looks like.
2879 If you do not specify @var{rgb}, then this color cannot be used by
2880 @code{tty-color-approximate} to approximate other colors, because
2881 Emacs will not know what it looks like.
2884 @defun tty-color-clear &optional frame
2885 This function clears the table of defined colors for a text terminal.
2888 @defun tty-color-alist &optional frame
2889 This function returns an alist recording the known colors supported by
2892 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2893 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
2894 name, @var{number} is the number used to specify it to the terminal.
2895 If present, @var{rgb} is a list of three color values (for red, green,
2896 and blue) that says what the color actually looks like.
2899 @defun tty-color-approximate rgb &optional frame
2900 This function finds the closest color, among the known colors
2901 supported for @var{display}, to that described by the rgb value
2902 @var{rgb} (a list of color values). The return value is an element of
2903 @code{tty-color-alist}.
2906 @defun tty-color-translate color &optional frame
2907 This function finds the closest color to @var{color} among the known
2908 colors supported for @var{display} and returns its index (an integer).
2909 If the name @var{color} is not defined, the value is @code{nil}.
2913 @section X Resources
2915 This section describes some of the functions and variables for
2916 querying and using X resources, or their equivalent on your operating
2917 system. @xref{X Resources,, X Resources, emacs, The GNU Emacs
2918 Manual}, for more information about X resources.
2920 @defun x-get-resource attribute class &optional component subclass
2921 The function @code{x-get-resource} retrieves a resource value from the X
2922 Window defaults database.
2924 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2925 This function searches using a key of the form
2926 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2927 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2930 The optional arguments @var{component} and @var{subclass} add to the key
2931 and the class, respectively. You must specify both of them or neither.
2932 If you specify them, the key is
2933 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2934 @samp{Emacs.@var{class}.@var{subclass}}.
2937 @defvar x-resource-class
2938 This variable specifies the application name that @code{x-get-resource}
2939 should look up. The default value is @code{"Emacs"}. You can examine X
2940 resources for other application names by binding this
2941 variable to some other string, around a call to @code{x-get-resource}.
2944 @defvar x-resource-name
2945 This variable specifies the instance name that @code{x-get-resource}
2946 should look up. The default value is the name Emacs was invoked with,
2947 or the value specified with the @samp{-name} or @samp{-rn} switches.
2950 To illustrate some of the above, suppose that you have the line:
2953 xterm.vt100.background: yellow
2957 in your X resources file (whose name is usually @file{~/.Xdefaults}
2958 or @file{~/.Xresources}). Then:
2962 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2963 (x-get-resource "vt100.background" "VT100.Background"))
2967 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2968 (x-get-resource "background" "VT100" "vt100" "Background"))
2973 @defvar inhibit-x-resources
2974 If this variable is non-@code{nil}, Emacs does not look up X
2975 resources, and X resources do not have any effect when creating new
2979 @node Display Feature Testing
2980 @section Display Feature Testing
2981 @cindex display feature testing
2983 The functions in this section describe the basic capabilities of a
2984 particular display. Lisp programs can use them to adapt their behavior
2985 to what the display can do. For example, a program that ordinarily uses
2986 a popup menu could use the minibuffer if popup menus are not supported.
2988 The optional argument @var{display} in these functions specifies which
2989 display to ask the question about. It can be a display name, a frame
2990 (which designates the display that frame is on), or @code{nil} (which
2991 refers to the selected frame's display, @pxref{Input Focus}).
2993 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2994 obtain information about displays.
2996 @defun display-popup-menus-p &optional display
2997 This function returns @code{t} if popup menus are supported on
2998 @var{display}, @code{nil} if not. Support for popup menus requires
2999 that the mouse be available, since the menu is popped up by clicking
3000 the mouse on some portion of the Emacs display.
3003 @defun display-graphic-p &optional display
3004 This function returns @code{t} if @var{display} is a graphic display
3005 capable of displaying several frames and several different fonts at
3006 once. This is true for displays that use a window system such as X,
3007 and false for text terminals.
3010 @defun display-mouse-p &optional display
3011 @cindex mouse, availability
3012 This function returns @code{t} if @var{display} has a mouse available,
3016 @defun display-color-p &optional display
3017 @findex x-display-color-p
3018 This function returns @code{t} if the screen is a color screen.
3019 It used to be called @code{x-display-color-p}, and that name
3020 is still supported as an alias.
3023 @defun display-grayscale-p &optional display
3024 This function returns @code{t} if the screen can display shades of gray.
3025 (All color displays can do this.)
3028 @defun display-supports-face-attributes-p attributes &optional display
3029 @anchor{Display Face Attribute Testing}
3030 This function returns non-@code{nil} if all the face attributes in
3031 @var{attributes} are supported (@pxref{Face Attributes}).
3033 The definition of ``supported'' is somewhat heuristic, but basically
3034 means that a face containing all the attributes in @var{attributes},
3035 when merged with the default face for display, can be represented in a
3040 different in appearance than the default face, and
3043 close in spirit to what the attributes specify, if not exact.
3046 Point (2) implies that a @code{:weight black} attribute will be
3047 satisfied by any display that can display bold, as will
3048 @code{:foreground "yellow"} as long as some yellowish color can be
3049 displayed, but @code{:slant italic} will @emph{not} be satisfied by
3050 the tty display code's automatic substitution of a dim face for
3054 @defun display-selections-p &optional display
3055 This function returns @code{t} if @var{display} supports selections.
3056 Windowed displays normally support selections, but they may also be
3057 supported in some other cases.
3060 @defun display-images-p &optional display
3061 This function returns @code{t} if @var{display} can display images.
3062 Windowed displays ought in principle to handle images, but some
3063 systems lack the support for that. On a display that does not support
3064 images, Emacs cannot display a tool bar.
3067 @defun display-screens &optional display
3068 This function returns the number of screens associated with the display.
3071 @defun display-pixel-height &optional display
3072 This function returns the height of the screen in pixels.
3073 On a character terminal, it gives the height in characters.
3075 For graphical terminals, note that on multi-monitor setups this
3076 refers to the pixel height for all physical monitors associated with
3077 @var{display}. @xref{Multiple Terminals}.
3080 @defun display-pixel-width &optional display
3081 This function returns the width of the screen in pixels.
3082 On a character terminal, it gives the width in characters.
3084 For graphical terminals, note that on multi-monitor setups this
3085 refers to the pixel width for all physical monitors associated with
3086 @var{display}. @xref{Multiple Terminals}.
3089 @defun display-mm-height &optional display
3090 This function returns the height of the screen in millimeters,
3091 or @code{nil} if Emacs cannot get that information.
3093 For graphical terminals, note that on multi-monitor setups this
3094 refers to the height for all physical monitors associated with
3095 @var{display}. @xref{Multiple Terminals}.
3098 @defun display-mm-width &optional display
3099 This function returns the width of the screen in millimeters,
3100 or @code{nil} if Emacs cannot get that information.
3102 For graphical terminals, note that on multi-monitor setups this
3103 refers to the width for all physical monitors associated with
3104 @var{display}. @xref{Multiple Terminals}.
3107 @defopt display-mm-dimensions-alist
3108 This variable allows the user to specify the dimensions of graphical
3109 displays returned by @code{display-mm-height} and
3110 @code{display-mm-width} in case the system provides incorrect values.
3113 @cindex backing store
3114 @defun display-backing-store &optional display
3115 This function returns the backing store capability of the display.
3116 Backing store means recording the pixels of windows (and parts of
3117 windows) that are not exposed, so that when exposed they can be
3118 displayed very quickly.
3120 Values can be the symbols @code{always}, @code{when-mapped}, or
3121 @code{not-useful}. The function can also return @code{nil}
3122 when the question is inapplicable to a certain kind of display.
3125 @cindex SaveUnder feature
3126 @defun display-save-under &optional display
3127 This function returns non-@code{nil} if the display supports the
3128 SaveUnder feature. That feature is used by pop-up windows
3129 to save the pixels they obscure, so that they can pop down
3133 @defun display-planes &optional display
3134 This function returns the number of planes the display supports.
3135 This is typically the number of bits per pixel.
3136 For a tty display, it is log to base two of the number of colors supported.
3139 @defun display-visual-class &optional display
3140 This function returns the visual class for the screen. The value is
3141 one of the symbols @code{static-gray} (a limited, unchangeable number
3142 of grays), @code{gray-scale} (a full range of grays),
3143 @code{static-color} (a limited, unchangeable number of colors),
3144 @code{pseudo-color} (a limited number of colors), @code{true-color} (a
3145 full range of colors), and @code{direct-color} (a full range of
3149 @defun display-color-cells &optional display
3150 This function returns the number of color cells the screen supports.
3153 These functions obtain additional information about the window
3154 system in use where Emacs shows the specified @var{display}. (Their
3155 names begin with @code{x-} for historical reasons.)
3157 @defun x-server-version &optional display
3158 This function returns the list of version numbers of the GUI window
3159 system running on @var{display}, such as the X server on GNU and Unix
3160 systems. The value is a list of three integers: the major and minor
3161 version numbers of the protocol, and the distributor-specific release
3162 number of the window system software itself. On GNU and Unix systems,
3163 these are normally the version of the X protocol and the
3164 distributor-specific release number of the X server software. On
3165 MS-Windows, this is the version of the Windows OS.
3168 @defun x-server-vendor &optional display
3169 This function returns the vendor that provided the window system
3170 software (as a string). On GNU and Unix systems this really means
3171 whoever distributes the X server. On MS-Windows this is the vendor ID
3172 string of the Windows OS (Microsoft).
3174 When the developers of X labeled software distributors as
3175 ``vendors'', they showed their false assumption that no system could
3176 ever be developed and distributed noncommercially.
3180 @defvar x-no-window-manager
3181 This variable's value is @code{t} if no X window manager is in use.
3187 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
3188 width and height of an X Window frame, measured in pixels.