Fix buffer overflow in make-docfile
[emacs.git] / doc / lispref / frames.texi
blobbed7873fe3ff2ec629387483589c35694a9deb5f
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2017 Free Software
4 @c Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @node Frames
7 @chapter Frames
8 @cindex frame
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}.
21 @cindex terminal
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}.
26 @cindex text terminal
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}.
46 @defun framep object
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:
51 @table @code
52 @item t
53 The frame is displayed on a text terminal.
54 @item x
55 The frame is displayed on an X graphical terminal.
56 @item w32
57 The frame is displayed on a MS-Windows graphical terminal.
58 @item ns
59 The frame is displayed on a GNUstep or Macintosh Cocoa graphical
60 terminal.
61 @item pc
62 The frame is displayed on an MS-DOS terminal.
63 @end table
64 @end defun
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
69 selected frame.
70 @end defun
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.
78 @end defun
80 @cindex top-level frame
81 On a graphical terminal we distinguish two types of frames: A normal
82 @dfn{top-level frame} is a frame whose window-system window is a child
83 of the window-system's root window for that terminal.  A child frame is
84 a frame whose window-system window is the child of the window-system
85 window of another Emacs frame.  @xref{Child Frames}.
87 @menu
88 * Creating Frames::             Creating additional frames.
89 * Multiple Terminals::          Displaying on several different devices.
90 * Frame Geometry::              Geometric properties of frames.
91 * Frame Parameters::            Controlling frame size, position, font, etc.
92 * Terminal Parameters::         Parameters common for all frames on terminal.
93 * Frame Titles::                Automatic updating of frame titles.
94 * Deleting Frames::             Frames last until explicitly deleted.
95 * Finding All Frames::          How to examine all existing frames.
96 * Minibuffers and Frames::      How a frame finds the minibuffer to use.
97 * Input Focus::                 Specifying the selected frame.
98 * Visibility of Frames::        Frames may be visible or invisible, or icons.
99 * Raising and Lowering::        Raising, Lowering and Restacking Frames.
100 * Frame Configurations::        Saving the state of all frames.
101 * Child Frames::                Making a frame the child of another.
102 * Mouse Tracking::              Getting events that say when the mouse moves.
103 * Mouse Position::              Asking where the mouse is, or moving it.
104 * Pop-Up Menus::                Displaying a menu for the user to select from.
105 * Dialog Boxes::                Displaying a box to ask yes or no.
106 * Pointer Shape::               Specifying the shape of the mouse pointer.
107 * Window System Selections::    Transferring text to and from other X clients.
108 * Drag and Drop::               Internals of Drag-and-Drop implementation.
109 * Color Names::                 Getting the definitions of color names.
110 * Text Terminal Colors::        Defining colors for text terminals.
111 * Resources::                   Getting resource values from the server.
112 * Display Feature Testing::     Determining the features of a terminal.
113 @end menu
115 @node Creating Frames
116 @section Creating Frames
117 @cindex frame creation
119 To create a new frame, call the function @code{make-frame}.
121 @deffn Command make-frame &optional alist
122 This function creates and returns a new frame, displaying the current
123 buffer.
125 The @var{alist} argument is an alist that specifies frame parameters
126 for the new frame.  @xref{Frame Parameters}.  If you specify the
127 @code{terminal} parameter in @var{alist}, the new frame is created on
128 that terminal.  Otherwise, if you specify the @code{window-system}
129 frame parameter in @var{alist}, that determines whether the frame
130 should be displayed on a text terminal or a graphical terminal.
131 @xref{Window Systems}.  If neither is specified, the new frame is
132 created in the same terminal as the selected frame.
134 Any parameters not mentioned in @var{alist} default to the values in
135 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
136 parameters not specified there default from the X resources or its
137 equivalent on your operating system (@pxref{X Resources,, X Resources,
138 emacs, The GNU Emacs Manual}).  After the frame is created, Emacs
139 applies any parameters listed in @code{frame-inherited-parameters}
140 (see below) and not present in the argument, taking the values from
141 the frame that was selected when @code{make-frame} was called.
143 Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
144 window manager might position the frame differently than specified by
145 the positional parameters in @var{alist} (@pxref{Position
146 Parameters}).  For example, some window managers have a policy of
147 displaying the frame on the monitor that contains the largest part of
148 the window (a.k.a.@: the @dfn{dominating} monitor).
150 This function itself does not make the new frame the selected frame.
151 @xref{Input Focus}.  The previously selected frame remains selected.
152 On graphical terminals, however, the windowing system may select the
153 new frame for its own reasons.
154 @end deffn
156 @defvar before-make-frame-hook
157 A normal hook run by @code{make-frame} before it creates the frame.
158 @end defvar
160 @defvar after-make-frame-functions
161 An abnormal hook run by @code{make-frame} after it creates the frame.
162 Each function in @code{after-make-frame-functions} receives one argument, the
163 frame just created.
164 @end defvar
166 @defvar frame-inherited-parameters
167 This variable specifies the list of frame parameters that a newly
168 created frame inherits from the currently selected frame.  For each
169 parameter (a symbol) that is an element in the list and is not present
170 in the argument to @code{make-frame}, the function sets the value of
171 that parameter in the created frame to its value in the selected
172 frame.
173 @end defvar
175 @node Multiple Terminals
176 @section Multiple Terminals
177 @cindex multiple terminals
178 @cindex multi-tty
179 @cindex multiple X displays
180 @cindex displays, multiple
182   Emacs represents each terminal as a @dfn{terminal object} data type
183 (@pxref{Terminal Type}).  On GNU and Unix systems, Emacs can use
184 multiple terminals simultaneously in each session.  On other systems,
185 it can only use a single terminal.  Each terminal object has the
186 following attributes:
188 @itemize @bullet
189 @item
190 The name of the device used by the terminal (e.g., @samp{:0.0} or
191 @file{/dev/tty}).
193 @item
194 The terminal and keyboard coding systems used on the terminal.
195 @xref{Terminal I/O Encoding}.
197 @item
198 The kind of display associated with the terminal.  This is the symbol
199 returned by the function @code{terminal-live-p} (i.e., @code{x},
200 @code{t}, @code{w32}, @code{ns}, or @code{pc}).  @xref{Frames}.
202 @item
203 A list of terminal parameters.  @xref{Terminal Parameters}.
204 @end itemize
206   There is no primitive for creating terminal objects.  Emacs creates
207 them as needed, such as when you call @code{make-frame-on-display}
208 (described below).
210 @defun terminal-name &optional terminal
211 This function returns the file name of the device used by
212 @var{terminal}.  If @var{terminal} is omitted or @code{nil}, it
213 defaults to the selected frame's terminal.  @var{terminal} can also be
214 a frame, meaning that frame's terminal.
215 @end defun
217 @defun terminal-list
218 This function returns a list of all live terminal objects.
219 @end defun
221 @defun get-device-terminal device
222 This function returns a terminal whose device name is given by
223 @var{device}.  If @var{device} is a string, it can be either the file
224 name of a terminal device, or the name of an X display of the form
225 @samp{@var{host}:@var{server}.@var{screen}}.  If @var{device} is a
226 frame, this function returns that frame's terminal; @code{nil} means
227 the selected frame.  Finally, if @var{device} is a terminal object
228 that represents a live terminal, that terminal is returned.  The
229 function signals an error if its argument is none of the above.
230 @end defun
232 @defun delete-terminal &optional terminal force
233 This function deletes all frames on @var{terminal} and frees the
234 resources used by it.  It runs the abnormal hook
235 @code{delete-terminal-functions}, passing @var{terminal} as the
236 argument to each function.
238 If @var{terminal} is omitted or @code{nil}, it defaults to the
239 selected frame's terminal.  @var{terminal} can also be a frame,
240 meaning that frame's terminal.
242 Normally, this function signals an error if you attempt to delete the
243 sole active terminal, but if @var{force} is non-@code{nil}, you are
244 allowed to do so.  Emacs automatically calls this function when the
245 last frame on a terminal is deleted (@pxref{Deleting Frames}).
246 @end defun
248 @defvar delete-terminal-functions
249 An abnormal hook run by @code{delete-terminal}.  Each function
250 receives one argument, the @var{terminal} argument passed to
251 @code{delete-terminal}.  Due to technical details, the functions may
252 be called either just before the terminal is deleted, or just
253 afterwards.
254 @end defvar
256 @cindex terminal-local variables
257   A few Lisp variables are @dfn{terminal-local}; that is, they have a
258 separate binding for each terminal.  The binding in effect at any time
259 is the one for the terminal that the currently selected frame belongs
260 to.  These variables include @code{default-minibuffer-frame},
261 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
262 @code{system-key-alist}.  They are always terminal-local, and can
263 never be buffer-local (@pxref{Buffer-Local Variables}).
265   On GNU and Unix systems, each X display is a separate graphical
266 terminal.  When Emacs is started from within the X window system, it
267 uses the X display specified by the @env{DISPLAY} environment
268 variable, or by the @samp{--display} option (@pxref{Initial Options,,,
269 emacs, The GNU Emacs Manual}).  Emacs can connect to other X displays
270 via the command @code{make-frame-on-display}.  Each X display has its
271 own selected frame and its own minibuffer windows; however, only one
272 of those frames is @emph{the} selected frame at any given moment
273 (@pxref{Input Focus}).  Emacs can even connect to other text
274 terminals, by interacting with the @command{emacsclient} program.
275 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
277 @cindex X display names
278 @cindex display name on X
279   A single X server can handle more than one display.  Each X display
280 has a three-part name,
281 @samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}.  The
282 first part, @var{hostname}, specifies the name of the machine to which
283 the display is physically connected.  The second part,
284 @var{displaynumber}, is a zero-based number that identifies one or
285 more monitors connected to that machine that share a common keyboard
286 and pointing device (mouse, tablet, etc.).  The third part,
287 @var{screennumber}, identifies a zero-based screen number (a separate
288 monitor) that is part of a single monitor collection on that X server.
289 When you use two or more screens belonging to one server, Emacs knows
290 by the similarity in their names that they share a single keyboard.
292   Systems that don't use the X window system, such as MS-Windows,
293 don't support the notion of X displays, and have only one display on
294 each host.  The display name on these systems doesn't follow the above
295 3-part format; for example, the display name on MS-Windows systems is
296 a constant string @samp{w32}, and exists for compatibility, so that
297 you could pass it to functions that expect a display name.
299 @deffn Command make-frame-on-display display &optional parameters
300 This function creates and returns a new frame on @var{display}, taking
301 the other frame parameters from the alist @var{parameters}.
302 @var{display} should be the name of an X display (a string).
304 Before creating the frame, this function ensures that Emacs is set
305 up to display graphics.  For instance, if Emacs has not processed X
306 resources (e.g., if it was started on a text terminal), it does so at
307 this time.  In all other respects, this function behaves like
308 @code{make-frame} (@pxref{Creating Frames}).
309 @end deffn
311 @defun x-display-list
312 This function returns a list that indicates which X displays Emacs has
313 a connection to.  The elements of the list are strings, and each one
314 is a display name.
315 @end defun
317 @defun x-open-connection display &optional xrm-string must-succeed
318 This function opens a connection to the X display @var{display},
319 without creating a frame on that display.  Normally, Emacs Lisp
320 programs need not call this function, as @code{make-frame-on-display}
321 calls it automatically.  The only reason for calling it is to check
322 whether communication can be established with a given X display.
324 The optional argument @var{xrm-string}, if not @code{nil}, is a string
325 of resource names and values, in the same format used in the
326 @file{.Xresources} file.  @xref{X Resources,, X Resources, emacs, The
327 GNU Emacs Manual}.  These values apply to all Emacs frames created on
328 this display, overriding the resource values recorded in the X server.
329 Here's an example of what this string might look like:
331 @example
332 "*BorderWidth: 3\n*InternalBorder: 2\n"
333 @end example
335 If @var{must-succeed} is non-@code{nil}, failure to open the connection
336 terminates Emacs.  Otherwise, it is an ordinary Lisp error.
337 @end defun
339 @defun x-close-connection display
340 This function closes the connection to display @var{display}.  Before
341 you can do this, you must first delete all the frames that were open
342 on that display (@pxref{Deleting Frames}).
343 @end defun
345 @cindex multi-monitor
346   On some multi-monitor setups, a single X display outputs to more
347 than one physical monitor.  You can use the functions
348 @code{display-monitor-attributes-list} and @code{frame-monitor-attributes}
349 to obtain information about such setups.
351 @defun display-monitor-attributes-list &optional display
352 This function returns a list of physical monitor attributes on
353 @var{display}, which can be a display name (a string), a terminal, or
354 a frame; if omitted or @code{nil}, it defaults to the selected frame's
355 display.  Each element of the list is an association list,
356 representing the attributes of a physical monitor.  The first element
357 corresponds to the primary monitor.  The attribute keys and values
358 are:
360 @table @samp
361 @item geometry
362 Position of the top-left corner of the monitor's screen and its size,
363 in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}.  Note
364 that, if the monitor is not the primary monitor, some of the
365 coordinates might be negative.
367 @item workarea
368 Position of the top-left corner and size of the work area (usable
369 space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}.
370 This may be different from @samp{geometry} in that space occupied by
371 various window manager features (docks, taskbars, etc.)@: may be
372 excluded from the work area.  Whether or not such features actually
373 subtract from the work area depends on the platform and environment.
374 Again, if the monitor is not the primary monitor, some of the
375 coordinates might be negative.
377 @item mm-size
378 Width and height in millimeters as @samp{(@var{width} @var{height})}
380 @item frames
381 List of frames that this physical monitor dominates (see below).
383 @item name
384 Name of the physical monitor as @var{string}.
386 @item source
387 Source of the multi-monitor information as @var{string};
388 e.g., @samp{XRandr} or @samp{Xinerama}.
389 @end table
391 @var{x}, @var{y}, @var{width}, and @var{height} are integers.
392 @samp{name} and @samp{source} may be absent.
394 A frame is @dfn{dominated} by a physical monitor when either the
395 largest area of the frame resides in that monitor, or (if the frame
396 does not intersect any physical monitors) that monitor is the closest
397 to the frame.  Every (non-tooltip) frame (whether visible or not) in a
398 graphical display is dominated by exactly one physical monitor at a
399 time, though the frame can span multiple (or no) physical monitors.
401 Here's an example of the data produced by this function on a 2-monitor
402 display:
404 @lisp
405   (display-monitor-attributes-list)
406   @result{}
407   (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor}
408     (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height}
409     (mm-size 677 381)
410     (name . "DISPLAY1")
411     (frames #<frame emacs@@host *Messages* 0x11578c0>
412             #<frame emacs@@host *scratch* 0x114b838>))
413    ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor}
414     (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used}
415     (mm-size 593 370)
416     (name . "DISPLAY2")
417     (frames)))
418 @end lisp
420 @end defun
422 @defun frame-monitor-attributes &optional frame
423 This function returns the attributes of the physical monitor
424 dominating (see above) @var{frame}, which defaults to the selected frame.
425 @end defun
428 @node Frame Geometry
429 @section Frame Geometry
430 @cindex frame geometry
431 @cindex frame position
432 @cindex position of frame
433 @cindex frame size
434 @cindex size of frame
436 The geometry of a frame depends on the toolkit that was used to build
437 this instance of Emacs and the terminal that displays the frame.  This
438 chapter describes these dependencies and some of the functions to deal
439 with them.  Note that the @var{frame} argument of all of these functions
440 has to specify a live frame (@pxref{Deleting Frames}).  If omitted or
441 @code{nil}, it specifies the selected frame (@pxref{Input Focus}).
443 @menu
444 * Frame Layout::            Basic layout of frames.
445 * Frame Font::              The default font of a frame and how to set it.
446 * Frame Position::          The position of a frame on its display.
447 * Frame Size::              Specifying and retrieving a frame's size.
448 * Implied Frame Resizing::  Implied resizing of frames and how to prevent it.
449 @end menu
452 @node Frame Layout
453 @subsection Frame Layout
454 @cindex frame layout
455 @cindex layout of frame
457 A visible frame occupies a rectangular area on its terminal's display.
458 This area may contain a number of nested rectangles, each serving a
459 different purpose.  The drawing below sketches the layout of a frame on
460 a graphical terminal:
461 @smallexample
462 @group
464         <------------ Outer Frame Width ----------->
465         ____________________________________________
466      ^(0)  ________ External/Outer Border _______   |
467      | |  |_____________ Title Bar ______________|  |
468      | | (1)_____________ Menu Bar ______________|  | ^
469      | | (2)_____________ Tool Bar ______________|  | ^
470      | | (3) _________ Internal Border ________  |  | ^
471      | |  | |   ^                              | |  | |
472      | |  | |   |                              | |  | |
473 Outer  |  | | Inner                            | |  | Native
474 Frame  |  | | Frame                            | |  | Frame
475 Height |  | | Height                           | |  | Height
476      | |  | |   |                              | |  | |
477      | |  | |<--+--- Inner Frame Width ------->| |  | |
478      | |  | |   |                              | |  | |
479      | |  | |___v______________________________| |  | |
480      | |  |___________ Internal Border __________|  | v
481      v |___________ External/Outer Border __________|
482            <-------- Native Frame Width -------->
484 @end group
485 @end smallexample
487 In practice not all of the areas shown in the drawing will or may be
488 present.  The meaning of these areas is described below.
490 @table @samp
491 @item Outer Frame
492 @cindex outer frame
493 @cindex outer edges
494 @cindex outer width
495 @cindex outer height
496 @cindex outer size
497 The @dfn{outer frame} is a rectangle comprising all areas shown in the
498 drawing.  The edges of that rectangle are called the @dfn{outer edges}
499 of the frame.  Together, the @dfn{outer width} and @dfn{outer height} of
500 the frame specify the @dfn{outer size} of that rectangle.
502 Knowing the outer size of a frame is useful for fitting a frame into the
503 working area of its display (@pxref{Multiple Terminals}) or for placing
504 two frames adjacent to each other on the screen.  Usually, the outer
505 size of a frame is available only after the frame has been mapped (made
506 visible, @pxref{Visibility of Frames}) at least once.  For the initial
507 frame or a frame that has not been created yet, the outer size can be
508 only estimated or must be calculated from the window-system's or window
509 manager's defaults.  One workaround is to obtain the differences of the
510 outer and native (see below) sizes of a mapped frame and use them for
511 calculating the outer size of the new frame.
513 @cindex outer position
514 The position of the upper left corner of the outer frame (indicated by
515 @samp{(0)} in the drawing above) is the @dfn{outer position} of the
516 frame.  The outer position of a graphical frame is also referred to as
517 ``the position'' of the frame because it usually remains unchanged on
518 its display whenever the frame is resized or its layout is changed.
520 The outer position is specified by and can be set via the @code{left}
521 and @code{top} frame parameters (@pxref{Position Parameters}).  For a
522 normal, top-level frame these parameters usually represent its absolute
523 position (see below) with respect to its display's origin.  For a child
524 frame (@pxref{Child Frames}) these parameters represent its position
525 relative to the native position (see below) of its parent frame.  For
526 frames on text terminals the values of these parameters are meaningless
527 and always zero.
529 @item External Border
530 @cindex external border
531 The @dfn{external border} is part of the decorations supplied by the
532 window manager.  It is typically used for resizing the frame with the
533 mouse and is therefore not shown on ``fullboth'' and maximized frames
534 (@pxref{Size Parameters}).  Its width is determined by the window
535 manager and cannot be changed by Emacs' functions.
537 External borders don't exist on text terminal frames.  For graphical
538 frames, their display can be suppressed by setting the
539 @code{override-redirect} or @code{undecorated} frame parameter
540 (@pxref{Management Parameters}).
542 @item Outer Border
543 @cindex outer border
544 The @dfn{outer border} is a separate border whose width can be specified
545 with the @code{border-width} frame parameter (@pxref{Layout
546 Parameters}).  In practice, either the external or the outer border of a
547 frame are displayed but never both at the same time.  Usually, the outer
548 border is shown only for special frames that are not (fully) controlled
549 by the window manager like tooltip frames (@pxref{Tooltips}), child
550 frames (@pxref{Child Frames}) and @code{undecorated} or
551 @code{override-redirect} frames (@pxref{Management Parameters}).
553 Outer borders are never shown on text terminal frames and on frames
554 generated by GTK+ routines.  On MS-Windows, the outer border is emulated
555 with the help of a one pixel wide external border.  Non-toolkit builds
556 on X allow to change the color of the outer border by setting the
557 @code{border-color} frame parameter (@pxref{Layout Parameters}).
559 @item Title Bar
560 @cindex title bar
561 @cindex caption bar
562 The @dfn{title bar}, a.k.a.@ @dfn{caption bar}, is also part of the
563 window manager's decorations and typically displays the title of the
564 frame (@pxref{Frame Titles}) as well as buttons for minimizing,
565 maximizing and deleting the frame.  It can be also used for dragging
566 the frame with the mouse.  The title bar is usually not displayed for
567 fullboth (@pxref{Size Parameters}), tooltip (@pxref{Tooltips}) and
568 child frames (@pxref{Child Frames}) and doesn't exist for terminal
569 frames.  Display of the title bar can be suppressed by setting the
570 @code{override-redirect} or the @code{undecorated} frame parameters
571 (@pxref{Management Parameters}).
573 @item Menu Bar
574 @cindex internal menu bar
575 @cindex external menu bar
576 The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs
577 itself) or external (drawn by the toolkit).  Most builds (GTK+, Lucid,
578 Motif and MS-Windows) rely on an external menu bar.  NS also uses an
579 external menu bar which, however, is not part of the outer frame.
580 Non-toolkit builds can provide an internal menu bar.  On text terminal
581 frames, the menu bar is part of the frame's root window (@pxref{Windows
582 and Frames}).  As a rule, menu bars are never shown on child frames
583 (@pxref{Child Frames}).  Display of the menu bar can be suppressed by
584 setting the @code{menu-bar-lines} parameter (@pxref{Layout Parameters})
585 to zero.
587 Whether the menu bar is wrapped or truncated whenever its width
588 becomes too large to fit on its frame depends on the toolkit .
589 Usually, only Motif and MS-Windows builds can wrap the menu bar.  When
590 they (un-)wrap the menu bar, they try to keep the outer height of the
591 frame unchanged, so the native height of the frame (see below) will
592 change instead.
594 @item Tool Bar
595 @cindex internal tool bar
596 @cindex external tool bar
597 Like the menu bar, the tool bar (@pxref{Tool Bar}) can be either
598 internal (drawn by Emacs itself) or external (drawn by a toolkit).  The
599 GTK+ and NS builds have the tool bar drawn by the toolkit.  The
600 remaining builds use internal tool bars.  With GTK+ the tool bar can be
601 located on either side of the frame, immediately outside the internal
602 border, see below.  Tool bars are usually not shown for child frames
603 (@pxref{Child Frames}).  Display of the tool bar can be suppressed by
604 setting the @code{tool-bar-lines} parameter (@pxref{Layout
605 Parameters}) to zero.
607 If the variable @code{auto-resize-tool-bars} is non-@code{nil}, Emacs
608 wraps the internal tool bar when its width becomes too large for its
609 frame.  If and when Emacs (un-)wraps the internal tool bar, it by
610 default keeps the outer height of the frame unchanged, so the native
611 height of the frame (see below) will change instead.  Emacs built with
612 GTK+, on the other hand, never wraps the tool bar but may
613 automatically increase the outer width of a frame in order to
614 accommodate an overlong tool bar.
616 @item Native Frame
617 @cindex native frame
618 @cindex native edges
619 @cindex native width
620 @cindex native height
621 @cindex native size
622 The @dfn{native frame} is a rectangle located entirely within the outer
623 frame.  It excludes the areas occupied by an external or outer border,
624 the title bar and any external menu or tool bar.  The edges of the
625 native frame are called the @dfn{native edges} of the frame.  Together,
626 the @dfn{native width} and @dfn{native height} of a frame specify the
627 @dfn{native size} of the frame.
629 The native size of a frame is the size Emacs passes to the window-system
630 or window manager when creating or resizing the frame from within Emacs.
631 It is also the size Emacs receives from the window-system or window
632 manager whenever these resize the frame's window-system window, for
633 example, after maximizing the frame by clicking on the corresponding
634 button in the title bar or when dragging its external border with the
635 mouse.
637 @cindex native position
638 The position of the top left corner of the native frame specifies the
639 @dfn{native position} of the frame.  (1)--(3) in the drawing above
640 indicate that position for the various builds:
642 @itemize @w{}
643 @item (1) non-toolkit and terminal frames
645 @item (2) Lucid, Motif and MS-Windows frames
647 @item (3) GTK+ and NS frames
648 @end itemize
650 Accordingly, the native height of a frame may include the height of the
651 tool bar but not that of the menu bar (Lucid, Motif, MS-Windows) or
652 those of the menu bar and the tool bar (non-toolkit and text terminal
653 frames).
655 The native position of a frame is the reference position for functions
656 that set or return the current position of the mouse (@pxref{Mouse
657 Position}) and for functions dealing with the position of windows like
658 @code{window-edges}, @code{window-at} or @code{coordinates-in-window-p}
659 (@pxref{Coordinates and Windows}).  It also specifies the (0, 0) origin
660 for locating and positioning child frames within this frame
661 (@pxref{Child Frames}).
663 Note also that the native position of a frame usually remains unaltered
664 on its display when removing or adding the window manager decorations by
665 changing the frame's @code{override-redirect} or @code{undecorated}
666 parameter (@pxref{Management Parameters}).
668 @item Internal Border
669 The internal border is a border drawn by Emacs around the inner frame
670 (see below).  Its width is specified by the @code{internal-border-width}
671 frame parameter (@pxref{Layout Parameters}).  Its color is specified by
672 the background of the @code{internal-border} face.
674 @item Inner Frame
675 @cindex inner frame
676 @cindex inner edges
677 @cindex inner width
678 @cindex inner height
679 @cindex inner size
680 @cindex display area
681 The @dfn{inner frame} is the rectangle reserved for the frame's windows.
682 It's enclosed by the internal border which, however, is not part of the
683 inner frame.  Its edges are called the @dfn{inner edges} of the frame.
684 The @dfn{inner width} and @dfn{inner height} specify the @dfn{inner
685 size} of the rectangle.  The inner frame is sometimes also referred to
686 as the @dfn{display area} of the frame.
688 @cindex minibuffer-less frame
689 @cindex minibuffer-only frame
690 As a rule, the inner frame is subdivided into the frame's root window
691 (@pxref{Windows and Frames}) and the frame's minibuffer window
692 (@pxref{Minibuffer Windows}).  There are two notable exceptions to this
693 rule: A @dfn{minibuffer-less frame} contains a root window only and does
694 not contain a minibuffer window.  A @dfn{minibuffer-only frame} contains
695 only a minibuffer window which also serves as that frame's root window.
696 See @ref{Initial Parameters} for how to create such frame
697 configurations.
699 @item Text Area
700 @cindex text area
701 The @dfn{text area} of a frame is a somewhat fictitious area that can be
702 embedded in the native frame.  Its position is unspecified.  Its width
703 can be obtained by removing from that of the native width the widths of
704 the internal border, one vertical scroll bar, and one left and one right
705 fringe if they are specified for this frame, see @ref{Layout
706 Parameters}.  Its height can be obtained by removing from that of the
707 native height the widths of the internal border and the heights of the
708 frame's internal menu and tool bars and one horizontal scroll bar if
709 specified for this frame.
710 @end table
712 @cindex absolute position
713 @cindex absolute frame position
714 @cindex absolute edges
715 @cindex absolute frame edges
716 @cindex display origin
717 @cindex origin of display
718 The @dfn{absolute position} of a frame is given as a pair (X, Y) of
719 horizontal and vertical pixel offsets relative to an origin (0, 0) of
720 the frame's display.  Correspondingly, the @dfn{absolute edges} of a
721 frame are given as pixel offsets from that origin.
723   Note that with multiple monitors, the origin of the display does not
724 necessarily coincide with the top-left corner of the entire usable
725 display area of the terminal.  Hence the absolute position of a frame
726 can be negative in such an environment even when that frame is
727 completely visible.
729   By convention, vertical offsets increase ``downwards''.  This means
730 that the height of a frame is obtained by subtracting the offset of its
731 top edge from that of its bottom edge.  Horizontal offsets increase
732 ``rightwards'', as expected, so a frame's width is calculated by
733 subtracting the offset of its left edge from that of its right edge.
735   For a frame on a graphical terminal the following function returns the
736 sizes of the areas described above:
738 @defun frame-geometry &optional frame
739 This function returns geometric attributes of @var{frame}.  The return
740 value is an association list of the attributes listed below.  All
741 coordinate, height and width values are integers counting pixels.  Note
742 that if @var{frame} has not been mapped yet, (@pxref{Visibility of
743 Frames}) some of the return values may only represent approximations of
744 the actual values---those that can be seen after the frame has been
745 mapped.
747 @table @code
748 @item outer-position
749 A cons representing the absolute position of the outer @var{frame},
750 relative to the origin at position (0, 0) of @var{frame}'s display.
752 @item outer-size
753 A cons of the outer width and height of @var{frame}.
755 @item external-border-size
756 A cons of the horizontal and vertical width of @var{frame}'s external
757 borders as supplied by the window manager.  If the window manager
758 doesn't supply these values, Emacs will try to guess them from the
759 coordinates of the outer and inner frame.
761 @item outer-border-width
762 The width of the outer border of @var{frame}.  The value is meaningful
763 for non-GTK+ X builds only.
765 @item title-bar-size
766 A cons of the width and height of the title bar of @var{frame} as
767 supplied by the window manager or operating system.  If both of them are
768 zero, the frame has no title bar.  If only the width is zero, Emacs was
769 not able to retrieve the width information.
771 @item menu-bar-external
772 If non-@code{nil}, this means the menu bar is external (not part of the
773 native frame of @var{frame}).
775 @item menu-bar-size
776 A cons of the width and height of the menu bar of @var{frame}.
778 @item tool-bar-external
779 If non-@code{nil}, this means the tool bar is external (not part of the
780 native frame of @var{frame}).
782 @item tool-bar-position
783 This tells on which side the tool bar on @var{frame} is and can be one
784 of @code{left}, @code{top}, @code{right} or @code{bottom}.  The only
785 toolkit that currently supports a value other than @code{top} is GTK+.
787 @item tool-bar-size
788 A cons of the width and height of the tool bar of @var{frame}.
790 @item internal-border-width
791 The width of the internal border of @var{frame}.
792 @end table
793 @end defun
795 The following function can be used to retrieve the edges of the outer,
796 native and inner frame.
798 @defun frame-edges &optional frame type
799 This function returns the absolute edges of the outer, native or inner
800 frame of @var{frame}.  @var{frame} must be a live frame and defaults to
801 the selected one.  The returned list has the form @w{@code{(@var{left}
802 @var{top} @var{right} @var{bottom})}} where all values are in pixels
803 relative to the origin of @var{frame}'s display.  For terminal frames
804 the values returned for @var{left} and @var{top} are always zero.
806 Optional argument @var{type} specifies the type of the edges to return:
807 @code{outer-edges} means to return the outer edges of @var{frame},
808 @code{native-edges} (or @code{nil}) means to return its native edges and
809 @code{inner-edges} means to return its inner edges.
811 By convention, the pixels of the display at the values returned for
812 @var{left} and @var{top} are considered to be inside (part of)
813 @var{frame}.  Hence, if @var{left} and @var{top} are both zero, the
814 pixel at the display's origin is part of @var{frame}.  The pixels at
815 @var{bottom} and @var{right}, on the other hand, are considered to lie
816 immediately outside @var{frame}.  This means that if you have, for
817 example, two side-by-side frames positioned such that the right outer
818 edge of the frame on the left equals the left outer edge of the frame on
819 the right, the pixels at that edge show a part of the frame on the
820 right.
821 @end defun
824 @node Frame Font
825 @subsection Frame Font
826 @cindex default font
827 @cindex default character size
828 @cindex default character width
829 @cindex default width of character
830 @cindex default character height
831 @cindex default height of character
832 Each frame has a @dfn{default font} which specifies the default
833 character size for that frame.  This size is meant when retrieving or
834 changing the size of a frame in terms of columns or lines
835 (@pxref{Size Parameters}).  It is also used when resizing (@pxref{Window
836 Sizes}) or splitting (@pxref{Splitting Windows}) windows.
838 @cindex line height
839 @cindex column width
840 @cindex canonical character height
841 @cindex canonical character width
842 The terms @dfn{line height} and @dfn{canonical character height} are
843 sometimes used instead of ``default character height''.  Similarly, the
844 terms @dfn{column width} and @dfn{canonical character width} are used
845 instead of ``default character width''.
847 @defun frame-char-height &optional frame
848 @defunx frame-char-width &optional frame
849 These functions return the default height and width of a character in
850 @var{frame}, measured in pixels.  Together, these values establish the
851 size of the default font on @var{frame}.  The values depend on the
852 choice of font for @var{frame}, see @ref{Font and Color Parameters}.
853 @end defun
855 The default font can be also set directly with the following function:
857 @deffn Command set-frame-font font &optional keep-size frames
858 This sets the default font to @var{font}.  When called interactively, it
859 prompts for the name of a font, and uses that font on the selected
860 frame.  When called from Lisp, @var{font} should be a font name (a
861 string), a font object, font entity, or a font spec.
863 If the optional argument @var{keep-size} is @code{nil}, this keeps the
864 number of frame lines and columns fixed.  (If non-@code{nil}, the option
865 @code{frame-inhibit-implied-resize} described in the next section will
866 override this.)  If @var{keep-size} is non-@code{nil} (or with a prefix
867 argument), it tries to keep the size of the display area of the current
868 frame fixed by adjusting the number of lines and columns.
870 If the optional argument @var{frames} is @code{nil}, this applies the
871 font to the selected frame only.  If @var{frames} is non-@code{nil}, it
872 should be a list of frames to act upon, or @code{t} meaning all existing
873 and all future graphical frames.
874 @end deffn
877 @node Frame Position
878 @subsection Frame Position
879 @cindex frame position
880 @cindex position of frame
882 On graphical systems, the position of a normal top-level frame is
883 specified as the absolute position of its outer frame (@pxref{Frame
884 Geometry}).  The position of a child frame (@pxref{Child Frames}) is
885 specified via pixel offsets of its outer edges relative to the native
886 position of its parent frame.
888   You can access or change the position of a frame using the frame
889 parameters @code{left} and @code{top} (@pxref{Position Parameters}).
890 Here are two additional functions for working with the positions of an
891 existing, visible frame.  For both functions, the argument @var{frame}
892 must denote a live frame and defaults to the selected frame.
894 @defun frame-position &optional frame
895 For a normal, non-child frame this function returns a cons of the pixel
896 coordinates of its outer position (@pxref{Frame Layout}) with respect to
897 the origin @code{(0, 0)} of its display.  For a child frame
898 (@pxref{Child Frames}) this function returns the pixel coordinates of
899 its outer position with respect to an origin @code{(0, 0)} at the native
900 position of @var{frame}'s parent.
902 Negative values never indicate an offset from the right or bottom
903 edge of @var{frame}'s display or parent frame.  Rather, they mean that
904 @var{frame}'s outer position is on the left and/or above the origin of
905 its display or the native position of its parent frame.  This usually
906 means that @var{frame} is only partially visible (or completely
907 invisible).  However, on systems where the display's origin does not
908 coincide with its top-left corner, the frame may be visible on a
909 secondary monitor.
911 On a text terminal frame both values are zero.
912 @end defun
914 @defun set-frame-position frame x y
915 This function sets the outer frame position of @var{frame} to (@var{x},
916 @var{y}).  The latter arguments specify pixels and normally count from
917 the origin at the position (0, 0) of @var{frame}'s display.  For child
918 frames, they count from the native position of @var{frame}'s parent
919 frame.
921 Negative parameter values position the right edge of the outer frame by
922 @var{-x} pixels left from the right edge of the screen (or the parent
923 frame's native rectangle) and the bottom edge by @var{-y} pixels up from
924 the bottom edge of the screen (or the parent frame's native rectangle).
926 Note that negative values do not permit to align the right or bottom
927 edge of @var{frame} exactly at the right or bottom edge of its display
928 or parent frame.  Neither do they allow to specify a position that does
929 not lie within the edges of the display or parent frame.  The frame
930 parameters @code{left} and @code{top} (@pxref{Position Parameters})
931 allow to do that, but may still fail to provide good results for the
932 initial or a new frame.
934 This function has no effect on text terminal frames.
935 @end defun
937 @defvar move-frame-functions
938 @cindex frame position changes, a hook
939 This hook specifies the functions that are run when an Emacs frame is moved
940 (assigned a new position) by the window-system or window manager.  The
941 functions are run with one argument, the frame that moved.  For a child
942 frame (@pxref{Child Frames}), the functions are run only when the
943 position of the frame changes in relation to that of its parent frame.
944 @end defvar
947 @node Frame Size
948 @subsection Frame Size
949 @cindex frame size
950 @cindex text width of a frame
951 @cindex text height of a frame
952 @cindex text size of a frame
953 The canonical way to specify the @dfn{size of a frame} from within Emacs
954 is by specifying its @dfn{text size}---a tuple of the width and height
955 of the frame's text area (@pxref{Frame Layout}).  It can be measured
956 either in pixels or in terms of the frame's canonical character size
957 (@pxref{Frame Font}).
959   For frames with an internal menu or tool bar, the frame's native
960 height cannot be told exactly before the frame has been actually drawn.
961 This means that in general you cannot use the native size to specify the
962 initial size of a frame.  As soon as you know the native size of a
963 visible frame, you can calculate its outer size (@pxref{Frame Layout})
964 by adding in the remaining components from the return value of
965 @code{frame-geometry}.  For invisible frames or for frames that have
966 yet to be created, however, the outer size can only be estimated.  This
967 also means that calculating an exact initial position of a frame
968 specified via offsets from the right or bottom edge of the screen
969 (@pxref{Frame Position}) is impossible.
971   The text size of any frame can be set and retrieved with the help of
972 the @code{height} and @code{width} frame parameters (@pxref{Size
973 Parameters}).  The text size of the initial frame can be also set with
974 the help of an X-style geometry specification.  @xref{Emacs Invocation,,
975 Command Line Arguments for Emacs Invocation, emacs, The GNU Emacs
976 Manual}.  Below we list some functions to access and set the size of an
977 existing, visible frame.
979 @defun frame-text-height &optional frame
980 @defunx frame-text-width &optional frame
981 These functions return the height and width of the text area of
982 @var{frame} (@pxref{Frame Layout}), measured in pixels.  For a text
983 terminal, the results are in characters rather than pixels.
984 @end defun
986 @defun frame-height &optional frame
987 @defunx frame-width &optional frame
988 These functions return the height and width of the text area of
989 @var{frame}, measured in units of the default font height and width of
990 @var{frame} (@pxref{Frame Font}).  These functions are plain shorthands
991 for writing @code{(frame-parameter frame 'height)} and
992 @code{(frame-parameter frame 'width)}.
994 If the text area of @var{frame} measured in pixels is not a multiple of
995 its default font size, the values returned by these functions are
996 rounded down to the number of characters of the default font that fully
997 fit into the text area.
998 @end defun
1000 @defun frame-pixel-height &optional frame
1001 @defunx frame-pixel-width &optional frame
1002 These functions return the native width and height, see @ref{Frame
1003 Layout}) of @var{frame} in pixels.  For a text terminal, the results are
1004 in characters rather than pixels.
1005 @end defun
1007 On window systems that support it, Emacs tries by default to make the
1008 text size of a frame measured in pixels a multiple of the frame's
1009 character size.  This, however, usually means that a frame can be
1010 resized only in character size increments when dragging its external
1011 borders.  It also may break attempts to truly maximize the frame or
1012 making it ``fullheight'' or ``fullwidth'' (@pxref{Size Parameters})
1013 leaving some empty space below and/or on the right of the frame.  The
1014 following option may help in that case.
1016 @defopt frame-resize-pixelwise
1017 If this option is @code{nil} (the default), a frame's text pixel size is
1018 usually rounded to a multiple of the current values of that frame's
1019 @code{frame-char-height} and @code{frame-char-width} whenever the frame
1020 is resized.  If this is non-@code{nil}, no rounding occurs, hence frame
1021 sizes can increase/decrease by one pixel.
1023 Setting this variable usually causes the next resize operation to pass
1024 the corresponding size hints to the window manager.  This means that
1025 this variable should be set only in a user's initial file; applications
1026 should never bind it temporarily.
1028 The precise meaning of a value of @code{nil} for this option depends on
1029 the toolkit used.  Dragging the external border with the mouse is done
1030 character-wise provided the window manager is willing to process the
1031 corresponding size hints.  Calling @code{set-frame-size} (see below)
1032 with arguments that do not specify the frame size as an integer multiple
1033 of its character size, however, may: be ignored, cause a rounding
1034 (GTK+), or be accepted (Lucid, Motif, MS-Windows).
1036 With some window managers you may have to set this to non-@code{nil} in
1037 order to make a frame appear truly maximized or full-screen.
1038 @end defopt
1040 @defun set-frame-size frame width height &optional pixelwise
1041 This function sets the size of the text area of @var{frame}, measured in
1042 terms of the canonical height and width of a character on @var{frame}
1043 (@pxref{Frame Font}).
1045 The optional argument @var{pixelwise} non-@code{nil} means to measure
1046 the new width and height in units of pixels instead.  Note that if
1047 @code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
1048 truly honor the request if it does not increase/decrease the frame size
1049 to a multiple of its character size.
1050 @end defun
1052 @defun set-frame-height frame height &optional pretend pixelwise
1053 This function resizes the text area of @var{frame} to a height of
1054 @var{height} lines.  The sizes of existing windows in @var{frame} are
1055 altered proportionally to fit.
1057 If @var{pretend} is non-@code{nil}, then Emacs displays @var{height}
1058 lines of output in @var{frame}, but does not change its value for the
1059 actual height of the frame.  This is only useful on text terminals.
1060 Using a smaller height than the terminal actually implements may be
1061 useful to reproduce behavior observed on a smaller screen, or if the
1062 terminal malfunctions when using its whole screen.  Setting the frame
1063 height directly does not always work, because knowing the correct
1064 actual size may be necessary for correct cursor positioning on
1065 text terminals.
1067 The optional fourth argument @var{pixelwise} non-@code{nil} means that
1068 @var{frame} should be @var{height} pixels high.  Note that if
1069 @code{frame-resize-pixelwise} is @code{nil}, some window managers may
1070 refuse to truly honor the request if it does not increase/decrease the
1071 frame height to a multiple of its character height.
1072 @end defun
1074 @defun set-frame-width frame width &optional pretend pixelwise
1075 This function sets the width of the text area of @var{frame}, measured
1076 in characters.  The argument @var{pretend} has the same meaning as in
1077 @code{set-frame-height}.
1079 The optional fourth argument @var{pixelwise} non-@code{nil} means that
1080 @var{frame} should be @var{width} pixels wide.  Note that if
1081 @code{frame-resize-pixelwise} is @code{nil}, some window managers may
1082 refuse to fully honor the request if it does not increase/decrease the
1083 frame width to a multiple of its character width.
1084 @end defun
1086 None of these three functions will make a frame smaller than needed to
1087 display all of its windows together with their scroll bars, fringes,
1088 margins, dividers, mode and header lines.  This contrasts with requests
1089 by the window manager triggered, for example, by dragging the external
1090 border of a frame with the mouse.  Such requests are always honored by
1091 clipping, if necessary, portions that cannot be displayed at the right,
1092 bottom corner of the frame.  The parameters @code{min-width} and
1093 @code{min-height} (@pxref{Size Parameters}) can be used to obtain a
1094 similar behavior when changing the frame size from within Emacs.
1096 @cindex tracking frame size changes
1097   The abnormal hook @code{window-size-change-functions} (@pxref{Window
1098 Hooks}) tracks all changes of the inner size of a frame including those
1099 induced by request of the window-system or window manager.  To rule out
1100 false positives that might occur when changing only the sizes of a
1101 frame's windows without actually changing the size of the inner frame,
1102 use the following function.
1104 @defun frame-size-changed-p &optional frame
1105 This function returns non-@code{nil} when the inner width or height of
1106 @var{frame} has changed since @code{window-size-change-functions} was
1107 run the last time for @var{frame}.  It always returns @code{nil}
1108 immediately after running @code{window-size-change-functions} for
1109 @var{frame}.
1110 @end defun
1113 @node Implied Frame Resizing
1114 @subsection Implied Frame Resizing
1115 @cindex implied frame resizing
1116 @cindex implied resizing of frame
1118 By default, Emacs tries to keep the number of lines and columns of a
1119 frame's text area unaltered when, for example, adding or removing the
1120 menu bar, changing the default font or setting the width of the frame's
1121 scroll bars.  This means, however, that in such case Emacs must ask the
1122 window manager to resize the outer frame in order to accommodate the
1123 size change.  Note that wrapping a menu or tool bar usually does not
1124 resize the frame's outer size, hence this will alter the number of
1125 displayed lines.
1127   Occasionally, such @dfn{implied frame resizing} may be unwanted, for
1128 example, when the frame is maximized or made full-screen (where it's
1129 turned off by default).  In other cases you can disable implied resizing
1130 with the following option:
1132 @defopt frame-inhibit-implied-resize
1133 If this option is @code{nil}, changing font, menu bar, tool bar,
1134 internal borders, fringes or scroll bars of a specific frame may
1135 implicitly resize the frame's display area in order to preserve the
1136 number of columns or lines the frame displays.  If this option is
1137 non-@code{nil}, no implied resizing is done.
1139 The value of this option can be also a list of frame parameters.  In
1140 that case, implied resizing is inhibited when changing a parameter that
1141 appears in this list.  The frame parameters currently handled by this
1142 option are: @code{font}, @code{font-backend},
1143 @code{internal-border-width}, @code{menu-bar-lines} and
1144 @code{tool-bar-lines}.
1146 Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height},
1147 @code{vertical-scroll-bars}, @code{horizontal-scroll-bars},
1148 @code{left-fringe} and @code{right-fringe} frame parameters is handled
1149 as if the frame contained just one live window.  This means, for
1150 example, that removing vertical scroll bars on a frame containing
1151 several side by side windows will shrink the outer frame width by the
1152 width of one scroll bar provided this option is @code{nil} and keep it
1153 unchanged if this option is either @code{t} or a list containing
1154 @code{vertical-scroll-bars}.
1156 The default value is @code{'(tool-bar-lines)} for Lucid, Motif and
1157 MS-Windows (which means that adding/removing a tool bar there does not
1158 change the outer frame height), @code{nil} on all other window systems
1159 including GTK+ (which means that changing any of the parameters listed
1160 above may change the size of the outer frame), and @code{t} otherwise
1161 (which means the outer frame size never changes implicitly when there's
1162 no window system support).
1164 Note that when a frame is not large enough to accommodate a change of
1165 any of the parameters listed above, Emacs may try to enlarge the frame
1166 even if this option is non-@code{nil}.
1167 @end defopt
1170 @node Frame Parameters
1171 @section Frame Parameters
1172 @cindex frame parameters
1174   A frame has many parameters that control its appearance and behavior.
1175 Just what parameters a frame has depends on what display mechanism it
1176 uses.
1178   Frame parameters exist mostly for the sake of graphical displays.
1179 Most frame parameters have no effect when applied to a frame on a text
1180 terminal; only the @code{height}, @code{width}, @code{name},
1181 @code{title}, @code{menu-bar-lines}, @code{buffer-list} and
1182 @code{buffer-predicate} parameters do something special.  If the
1183 terminal supports colors, the parameters @code{foreground-color},
1184 @code{background-color}, @code{background-mode} and
1185 @code{display-type} are also meaningful.  If the terminal supports
1186 frame transparency, the parameter @code{alpha} is also meaningful.
1188 @menu
1189 * Parameter Access::       How to change a frame's parameters.
1190 * Initial Parameters::     Specifying frame parameters when you make a frame.
1191 * Window Frame Parameters:: List of frame parameters for window systems.
1192 * Geometry::               Parsing geometry specifications.
1193 @end menu
1195 @node Parameter Access
1196 @subsection Access to Frame Parameters
1198 These functions let you read and change the parameter values of a
1199 frame.
1201 @defun frame-parameter frame parameter
1202 This function returns the value of the parameter @var{parameter} (a
1203 symbol) of @var{frame}.  If @var{frame} is @code{nil}, it returns the
1204 selected frame's parameter.  If @var{frame} has no setting for
1205 @var{parameter}, this function returns @code{nil}.
1206 @end defun
1208 @defun frame-parameters &optional frame
1209 The function @code{frame-parameters} returns an alist listing all the
1210 parameters of @var{frame} and their values.  If @var{frame} is
1211 @code{nil} or omitted, this returns the selected frame's parameters
1212 @end defun
1214 @defun modify-frame-parameters frame alist
1215 This function alters the frame @var{frame} based on the elements of
1216 @var{alist}.  Each element of @var{alist} has the form
1217 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming
1218 a parameter.  If you don't mention a parameter in @var{alist}, its
1219 value doesn't change.  If @var{frame} is @code{nil}, it defaults to
1220 the selected frame.
1222 Some parameters are only meaningful for frames on certain kinds of
1223 display (@pxref{Frames}).  If @var{alist} includes parameters that are
1224 not meaningful for the @var{frame}'s display, this function will
1225 change its value in the frame's parameter list, but will otherwise
1226 ignore it.
1228 When @var{alist} specifies more than one parameter whose value can
1229 affect the new size of @var{frame}, the final size of the frame may
1230 differ according to the toolkit used.  For example, specifying that a
1231 frame should from now on have a menu and/or tool bar instead of none and
1232 simultaneously specifying the new height of the frame will inevitably
1233 lead to a recalculation of the frame's height.  Conceptually, in such
1234 case, this function will try to have the explicit height specification
1235 prevail.  It cannot be excluded, however, that the addition (or removal)
1236 of the menu or tool bar, when eventually performed by the toolkit, will
1237 defeat this intention.
1239 Sometimes, binding @code{frame-inhibit-implied-resize} (@pxref{Implied
1240 Frame Resizing}) to a non-@code{nil} value around calls to this function
1241 may fix the problem sketched here.  Sometimes, however, exactly such
1242 binding may be hit by the problem.
1243 @end defun
1245 @defun set-frame-parameter frame parm value
1246 This function sets the frame parameter @var{parm} to the specified
1247 @var{value}.  If @var{frame} is @code{nil}, it defaults to the selected
1248 frame.
1249 @end defun
1251 @defun modify-all-frames-parameters alist
1252 This function alters the frame parameters of all existing frames
1253 according to @var{alist}, then modifies @code{default-frame-alist}
1254 (and, if necessary, @code{initial-frame-alist}) to apply the same
1255 parameter values to frames that will be created henceforth.
1256 @end defun
1258 @node Initial Parameters
1259 @subsection Initial Frame Parameters
1260 @cindex parameters of initial frame
1262 You can specify the parameters for the initial startup frame by
1263 setting @code{initial-frame-alist} in your init file (@pxref{Init
1264 File}).
1266 @defopt initial-frame-alist
1267 This variable's value is an alist of parameter values used when
1268 creating the initial frame.  You can set this variable to specify the
1269 appearance of the initial frame without altering subsequent frames.
1270 Each element has the form:
1272 @example
1273 (@var{parameter} . @var{value})
1274 @end example
1276 Emacs creates the initial frame before it reads your init
1277 file.  After reading that file, Emacs checks @code{initial-frame-alist},
1278 and applies the parameter settings in the altered value to the already
1279 created initial frame.
1281 If these settings affect the frame geometry and appearance, you'll see
1282 the frame appear with the wrong ones and then change to the specified
1283 ones.  If that bothers you, you can specify the same geometry and
1284 appearance with X resources; those do take effect before the frame is
1285 created.  @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
1287 X resource settings typically apply to all frames.  If you want to
1288 specify some X resources solely for the sake of the initial frame, and
1289 you don't want them to apply to subsequent frames, here's how to achieve
1290 this.  Specify parameters in @code{default-frame-alist} to override the
1291 X resources for subsequent frames; then, to prevent these from affecting
1292 the initial frame, specify the same parameters in
1293 @code{initial-frame-alist} with values that match the X resources.
1294 @end defopt
1296 @cindex minibuffer-only frame
1297 If these parameters include @code{(minibuffer . nil)}, that indicates
1298 that the initial frame should have no minibuffer.  In this case, Emacs
1299 creates a separate @dfn{minibuffer-only frame} as well.
1301 @defopt minibuffer-frame-alist
1302 This variable's value is an alist of parameter values used when
1303 creating an initial minibuffer-only frame (i.e., the minibuffer-only
1304 frame that Emacs creates if @code{initial-frame-alist} specifies a
1305 frame with no minibuffer).
1306 @end defopt
1308 @defopt default-frame-alist
1309 This is an alist specifying default values of frame parameters for all
1310 Emacs frames---the first frame, and subsequent frames.  When using the X
1311 Window System, you can get the same results by means of X resources
1312 in many cases.
1314 Setting this variable does not affect existing frames.  Furthermore,
1315 functions that display a buffer in a separate frame may override the
1316 default parameters by supplying their own parameters.
1317 @end defopt
1319 If you invoke Emacs with command-line options that specify frame
1320 appearance, those options take effect by adding elements to either
1321 @code{initial-frame-alist} or @code{default-frame-alist}.  Options
1322 which affect just the initial frame, such as @samp{--geometry} and
1323 @samp{--maximized}, add to @code{initial-frame-alist}; the others add
1324 to @code{default-frame-alist}.  @pxref{Emacs Invocation,, Command Line
1325 Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
1327 @node Window Frame Parameters
1328 @subsection Window Frame Parameters
1329 @cindex frame parameters for windowed displays
1331   Just what parameters a frame has depends on what display mechanism
1332 it uses.  This section describes the parameters that have special
1333 meanings on some or all kinds of terminals.  Of these, @code{name},
1334 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
1335 @code{buffer-predicate} provide meaningful information in terminal
1336 frames, and @code{tty-color-mode} is meaningful only for frames on
1337 text terminals.
1339 @menu
1340 * Basic Parameters::            Parameters that are fundamental.
1341 * Position Parameters::         The position of the frame on the screen.
1342 * Size Parameters::             Frame's size.
1343 * Layout Parameters::           Size of parts of the frame, and
1344                                   enabling or disabling some parts.
1345 * Buffer Parameters::           Which buffers have been or should be shown.
1346 * Frame Interaction Parameters::  Parameters for interacting with other
1347                                   frames.
1348 * Management Parameters::       Communicating with the window manager.
1349 * Cursor Parameters::           Controlling the cursor appearance.
1350 * Font and Color Parameters::   Fonts and colors for the frame text.
1351 @end menu
1353 @node Basic Parameters
1354 @subsubsection Basic Parameters
1356   These frame parameters give the most basic information about the
1357 frame.  @code{title} and @code{name} are meaningful on all terminals.
1359 @table @code
1360 @vindex display, a frame parameter
1361 @item display
1362 The display on which to open this frame.  It should be a string of the
1363 form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the
1364 @env{DISPLAY} environment variable.  @xref{Multiple Terminals}, for
1365 more details about display names.
1367 @vindex display-type, a frame parameter
1368 @item display-type
1369 This parameter describes the range of possible colors that can be used
1370 in this frame.  Its value is @code{color}, @code{grayscale} or
1371 @code{mono}.
1373 @vindex title, a frame parameter
1374 @item title
1375 If a frame has a non-@code{nil} title, it appears in the window
1376 system's title bar at the top of the frame, and also in the mode line
1377 of windows in that frame if @code{mode-line-frame-identification} uses
1378 @samp{%F} (@pxref{%-Constructs}).  This is normally the case when
1379 Emacs is not using a window system, and can only display one frame at
1380 a time.  @xref{Frame Titles}.
1382 @vindex name, a frame parameter
1383 @item name
1384 The name of the frame.  The frame name serves as a default for the frame
1385 title, if the @code{title} parameter is unspecified or @code{nil}.  If
1386 you don't specify a name, Emacs sets the frame name automatically
1387 (@pxref{Frame Titles}).
1389 If you specify the frame name explicitly when you create the frame, the
1390 name is also used (instead of the name of the Emacs executable) when
1391 looking up X resources for the frame.
1393 @vindex explicit-name, a frame parameter
1394 @item explicit-name
1395 If the frame name was specified explicitly when the frame was created,
1396 this parameter will be that name.  If the frame wasn't explicitly
1397 named, this parameter will be @code{nil}.
1398 @end table
1401 @node Position Parameters
1402 @subsubsection Position Parameters
1403 @cindex window position on display
1404 @cindex frame position
1406 Parameters describing the X- and Y-offsets of a frame are always
1407 measured in pixels.  For normal, non-child frames they specify the
1408 frame's absolute outer position (@pxref{Frame Geometry}) with respect to
1409 its display's origin.  For a child frame (@pxref{Child Frames}) they
1410 specify the frame's outer position relative to the native position of
1411 the frame's parent frame.  (Note that none of these parameters is
1412 meaningful on TTY frames.)
1414 @table @code
1415 @vindex left, a frame parameter
1416 @item left
1417 The position, in pixels, of the left outer edge of the frame with
1418 respect to the left edge of the frame's display or parent frame.
1420 @table @asis
1421 @item an integer
1422 A positive integer always relates the left edge of the frame to the left
1423 edge of its display or parent frame.  A negative integer relates the
1424 right frame edge to the right edge of the display or parent frame.
1426 @item @code{(+ @var{pos})}
1427 This specifies the position of the left frame edge relative to the left
1428 edge of its display or parent frame.  The integer @var{pos} may be
1429 positive or negative; a negative value specifies a position outside the
1430 screen or parent frame or on a monitor other than the primary one (for
1431 multi-monitor displays).
1433 @item @code{(- @var{pos})}
1434 This specifies the position of the right frame edge relative to the
1435 right edge of the display or parent frame.  The integer @var{pos} may be
1436 positive or negative; a negative value specifies a position outside the
1437 screen or parent frame or on a monitor other than the primary one (for
1438 multi-monitor displays).
1439 @end table
1441 Some window managers ignore program-specified positions.  If you want to
1442 be sure the position you specify is not ignored, specify a
1443 non-@code{nil} value for the @code{user-position} parameter as in the
1444 following example:
1446 @example
1447 (modify-frame-parameters
1448   nil '((user-position . t) (left . (+ -4))))
1449 @end example
1451 In general, it is not a good idea to specify negative offsets to
1452 position a frame relative to the right or bottom edge of its display.
1453 Positioning the initial or a new frame is either not accurate (because
1454 the size of the outer frame is not yet fully known before the frame has
1455 been made visible) or will cause additional flicker (if the frame is
1456 repositioned after becoming visible).
1458   Note also, that negative offsets are not stored internally and are not
1459 returned by the function @code{frame-parameters}.  This means that the
1460 desktop saving routines will restore the frame from the positive offsets
1461 obtained by that function.
1463 @vindex top, a frame parameter
1464 @item top
1465 The screen position of the top (or bottom) edge, in pixels, with respect
1466 to the top (or bottom) edge of the display or parent frame.  It works
1467 just like @code{left}, except vertically instead of horizontally.
1469 @vindex icon-left, a frame parameter
1470 @item icon-left
1471 The screen position of the left edge of the frame's icon, in pixels,
1472 counting from the left edge of the screen.  This takes effect when the
1473 frame is iconified, if the window manager supports this feature.  If
1474 you specify a value for this parameter, then you must also specify a
1475 value for @code{icon-top} and vice versa.
1477 @vindex icon-top, a frame parameter
1478 @item icon-top
1479 The screen position of the top edge of the frame's icon, in pixels,
1480 counting from the top edge of the screen.  This takes effect when the
1481 frame is iconified, if the window manager supports this feature.
1483 @vindex user-position, a frame parameter
1484 @item user-position
1485 When you create a frame and specify its screen position with the
1486 @code{left} and @code{top} parameters, use this parameter to say whether
1487 the specified position was user-specified (explicitly requested in some
1488 way by a human user) or merely program-specified (chosen by a program).
1489 A non-@code{nil} value says the position was user-specified.
1491 @cindex window positions and window managers
1492 Window managers generally heed user-specified positions, and some heed
1493 program-specified positions too.  But many ignore program-specified
1494 positions, placing the window in a default fashion or letting the user
1495 place it with the mouse.  Some window managers, including @code{twm},
1496 let the user specify whether to obey program-specified positions or
1497 ignore them.
1499 When you call @code{make-frame}, you should specify a non-@code{nil}
1500 value for this parameter if the values of the @code{left} and @code{top}
1501 parameters represent the user's stated preference; otherwise, use
1502 @code{nil}.
1504 @vindex z-group, a frame parameter
1505 @item z-group
1506 This parameter specifies a relative position of the frame's
1507 window-system window in the stacking (Z-) order of the frame's display.
1509 If this is @code{above}, the frame's window-system window is displayed
1510 above all other window-system windows that do not have the @code{above}
1511 property set.  If this is nil, the frame's window is displayed below all
1512 windows that have the @code{above} property set and above all windows
1513 that have the @code{below} property set.  If this is @code{below}, the
1514 frame's window is displayed below all windows that do not have the
1515 @code{below} property set.
1517 To position the frame above or below a specific other frame use the
1518 function @code{frame-restack} (@pxref{Raising and Lowering}).
1519 @end table
1522 @node Size Parameters
1523 @subsubsection Size Parameters
1524 @cindex window size on display
1526   Frame parameters specify frame sizes in character units.  On
1527 graphical displays, the @code{default} face determines the actual
1528 pixel sizes of these character units (@pxref{Face Attributes}).
1530 @table @code
1531 @vindex width, a frame parameter
1532 @item width
1533 The width of the frame's text area (@pxref{Frame Geometry}), in
1534 characters.  The value can be also a cons cell of the symbol
1535 @code{text-pixels} and an integer denoting the width of the text area in
1536 pixels.
1538 @vindex height, a frame parameter
1539 @item height
1540 The height of the frame's text area (@pxref{Frame Geometry}), in
1541 characters.  The value can be also a cons cell of the symbol
1542 @code{text-pixels} and an integer denoting the height of the text area
1543 in pixels.
1545 @vindex user-size, a frame parameter
1546 @item user-size
1547 This does for the size parameters @code{height} and @code{width} what
1548 the @code{user-position} parameter (@pxref{Position Parameters,
1549 user-position}) does for the position parameters @code{top} and
1550 @code{left}.
1552 @vindex min-width, a frame parameter
1553 @item min-width
1554 This parameter specifies the minimum native width of the frame
1555 (@pxref{Frame Geometry}), in characters.  Normally, the functions that
1556 establish a frame's initial width or resize a frame horizontally make
1557 sure that all the frame's windows, vertical scroll bars, fringes,
1558 margins and vertical dividers can be displayed.  This parameter, if
1559 non-@code{nil} allows to make a frame narrower than that with the
1560 consequence that any components that do not fit on the frame will be
1561 clipped by the window manager.
1563 @vindex min-height, a frame parameter
1564 @item min-height
1565 This parameter specifies the minimum height of the native (@pxref{Frame
1566 Geometry}), in characters.  Normally, the functions that establish a
1567 frame's initial size or resize a frame make sure that all the frame's
1568 windows, horizontal scroll bars and dividers, mode and header lines, the
1569 echo area and the internal menu and tool bar can be displayed.  This
1570 parameter, if non-@code{nil} allows to make a frame smaller than that
1571 with the consequence that any components that do not fit on the frame
1572 will be clipped by the window-system or window manager.
1574 @cindex fullboth frames
1575 @cindex fullheight frames
1576 @cindex fullwidth frames
1577 @cindex maximized frames
1578 @vindex fullscreen, a frame parameter
1579 @item fullscreen
1580 This parameter specifies whether to maximize the frame's width, height
1581 or both.  Its value can be @code{fullwidth}, @code{fullheight},
1582 @code{fullboth}, or @code{maximized}.  A @dfn{fullwidth} frame is as
1583 wide as possible, a @dfn{fullheight} frame is as tall as possible, and
1584 a @dfn{fullboth} frame is both as wide and as tall as possible.  A
1585 @dfn{maximized} frame is like a ``fullboth'' frame, except that it usually
1586 keeps its title bar and the buttons for resizing
1587 and closing the frame.  Also, maximized frames typically avoid hiding
1588 any task bar or panels displayed on the desktop.  A ``fullboth'' frame,
1589 on the other hand, usually omits the title bar and occupies the entire
1590 available screen space.
1592 Full-height and full-width frames are more similar to maximized
1593 frames in this regard.  However, these typically display an external
1594 border which might be absent with maximized frames.  Hence the heights
1595 of maximized and full-height frames and the widths of maximized and
1596 full-width frames often differ by a few pixels.
1598 With some window managers you may have to customize the variable
1599 @code{frame-resize-pixelwise} (@pxref{Frame Size}) in order to make a
1600 frame truly appear maximized or full-screen.  Moreover, some window
1601 managers might not support smooth transition between the various
1602 full-screen or maximization states.  Customizing the variable
1603 @code{x-frame-normalize-before-maximize} can help to overcome that.
1605 @vindex fullscreen-restore, a frame parameter
1606 @item fullscreen-restore
1607 This parameter specifies the desired fullscreen state of the frame
1608 after invoking the @code{toggle-frame-fullscreen} command (@pxref{Frame
1609 Commands,,, emacs, The GNU Emacs Manual}) in the ``fullboth'' state.
1610 Normally this parameter is installed automatically by that command when
1611 toggling the state to fullboth.  If, however, you start Emacs in the
1612 ``fullboth'' state, you have to specify the desired behavior in your initial
1613 file as, for example
1615 @example
1616 (setq default-frame-alist
1617     '((fullscreen . fullboth) (fullscreen-restore . fullheight)))
1618 @end example
1620 This will give a new frame full height after typing in it @key{F11} for
1621 the first time.
1622 @end table
1625 @node Layout Parameters
1626 @subsubsection Layout Parameters
1627 @cindex layout parameters of frames
1628 @cindex frame layout parameters
1630   These frame parameters enable or disable various parts of the
1631 frame, or control their sizes.
1633 @table @code
1634 @vindex border-width, a frame parameter
1635 @item border-width
1636 The width in pixels of the frame's outer border (@pxref{Frame Geometry}).
1638 @vindex internal-border-width, a frame parameter
1639 @item internal-border-width
1640 The width in pixels of the frame's internal border (@pxref{Frame
1641 Geometry}).
1643 @vindex vertical-scroll-bars, a frame parameter
1644 @item vertical-scroll-bars
1645 Whether the frame has scroll bars for vertical scrolling, and which side
1646 of the frame they should be on.  The possible values are @code{left},
1647 @code{right}, and @code{nil} for no scroll bars.
1649 @vindex horizontal-scroll-bars, a frame parameter
1650 @item horizontal-scroll-bars
1651 Whether the frame has scroll bars for horizontal scrolling (@code{t} and
1652 @code{bottom} mean yes, @code{nil} means no).
1654 @vindex scroll-bar-width, a frame parameter
1655 @item scroll-bar-width
1656 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
1657 use the default width.
1659 @vindex scroll-bar-height, a frame parameter
1660 @item scroll-bar-height
1661 The height of horizontal scroll bars, in pixels, or @code{nil} meaning
1662 to use the default height.
1664 @vindex left-fringe, a frame parameter
1665 @vindex right-fringe, a frame parameter
1666 @item left-fringe
1667 @itemx right-fringe
1668 The default width of the left and right fringes of windows in this
1669 frame (@pxref{Fringes}).  If either of these is zero, that effectively
1670 removes the corresponding fringe.
1672 When you use @code{frame-parameter} to query the value of either of
1673 these two frame parameters, the return value is always an integer.
1674 When using @code{set-frame-parameter}, passing a @code{nil} value
1675 imposes an actual default value of 8 pixels.
1677 @vindex right-divider-width, a frame parameter
1678 @item right-divider-width
1679 The width (thickness) reserved for the right divider (@pxref{Window
1680 Dividers}) of any window on the frame, in pixels.  A value of zero means
1681 to not draw right dividers.
1683 @vindex bottom-divider-width, a frame parameter
1684 @item bottom-divider-width
1685 The width (thickness) reserved for the bottom divider (@pxref{Window
1686 Dividers}) of any window on the frame, in pixels.  A value of zero means
1687 to not draw bottom dividers.
1689 @vindex menu-bar-lines frame parameter
1690 @item menu-bar-lines
1691 The number of lines to allocate at the top of the frame for a menu bar.
1692 The default is one if Menu Bar mode is enabled and zero otherwise.
1693 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.  For an external menu
1694 bar, this value remains unchanged even when the menu bar wraps to two or
1695 more lines.  In that case, the @code{menu-bar-size} value returned by
1696 @code{frame-geometry} (@pxref{Frame Geometry}) allows to derive whether
1697 the menu bar actually occupies one or more lines.
1699 @vindex tool-bar-lines frame parameter
1700 @item tool-bar-lines
1701 The number of lines to use for the tool bar.  The default is one if Tool
1702 Bar mode is enabled and zero otherwise.  @xref{Tool Bars,,,emacs, The
1703 GNU Emacs Manual}.  This value may change whenever the tool bar wraps.
1705 @vindex tool-bar-position frame parameter
1706 @item tool-bar-position
1707 The position of the tool bar.  Currently only for the GTK tool bar.
1708 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
1709 The default is @code{top}.
1711 @vindex line-spacing, a frame parameter
1712 @item line-spacing
1713 Additional space to leave below each text line, in pixels (a positive
1714 integer).  @xref{Line Height}, for more information.
1715 @end table
1718 @node Buffer Parameters
1719 @subsubsection Buffer Parameters
1720 @cindex frame, which buffers to display
1721 @cindex buffers to display on frame
1723   These frame parameters, meaningful on all kinds of terminals, deal
1724 with which buffers have been, or should, be displayed in the frame.
1726 @table @code
1727 @vindex minibuffer, a frame parameter
1728 @item minibuffer
1729 Whether this frame has its own minibuffer.  The value @code{t} means
1730 yes, @code{nil} means no, @code{only} means this frame is just a
1731 minibuffer.  If the value is a minibuffer window (in some other
1732 frame), the frame uses that minibuffer.
1734 This frame parameter takes effect when the frame is created, and can
1735 not be changed afterwards.
1737 @vindex buffer-predicate, a frame parameter
1738 @item buffer-predicate
1739 The buffer-predicate function for this frame.  The function
1740 @code{other-buffer} uses this predicate (from the selected frame) to
1741 decide which buffers it should consider, if the predicate is not
1742 @code{nil}.  It calls the predicate with one argument, a buffer, once for
1743 each buffer; if the predicate returns a non-@code{nil} value, it
1744 considers that buffer.
1746 @vindex buffer-list, a frame parameter
1747 @item buffer-list
1748 A list of buffers that have been selected in this frame, ordered
1749 most-recently-selected first.
1751 @vindex unsplittable, a frame parameter
1752 @item unsplittable
1753 If non-@code{nil}, this frame's window is never split automatically.
1754 @end table
1756 @node Frame Interaction Parameters
1757 @subsubsection Frame Interaction Parameters
1758 @cindex frame interaction parameters
1759 @cindex interaction parameters between frames
1761 These parameters supply forms of interactions between different frames.
1763 @table @code
1764 @vindex parent-frame, a frame parameter
1765 @item parent-frame
1766 If non-@code{nil}, this means that this frame is a child frame
1767 (@pxref{Child Frames}), and this parameter specifies its parent frame.
1768 If nil, this means that this frame is a normal, top-level frame.
1770 @vindex delete-before, a frame parameter
1771 @item delete-before
1772 If non-@code{nil}, this parameter specifies another frame whose deletion
1773 will automatically trigger the deletion of this frame.  @xref{Deleting
1774 Frames}.
1776 @vindex mouse-wheel-frame, a frame parameter
1777 @item mouse-wheel-frame
1778 If non-@code{nil}, this parameter specifies the frame whose windows will
1779 be scrolled whenever the mouse wheel is scrolled with the mouse pointer
1780 hovering over this frame (@pxref{Mouse Commands,,, emacs, The GNU Emacs
1781 Manual}).
1783 @vindex no-other-frame, a frame parameter
1784 @item no-other-frame
1785 If this is non-@code{nil}, then this frame is not eligible as candidate
1786 for the functions @code{next-frame}, @code{previous-frame}
1787 (@pxref{Finding All Frames}) and @code{other-frame} (@pxref{Frame
1788 Commands,,, emacs, The GNU Emacs Manual}).
1789 @end table
1792 @node Management Parameters
1793 @subsubsection Window Management Parameters
1794 @cindex window manager interaction, and frame parameters
1796   The following frame parameters control various aspects of the
1797 frame's interaction with the window manager.  They have no effect on
1798 text terminals.
1800 @table @code
1801 @vindex visibility, a frame parameter
1802 @item visibility
1803 The state of visibility of the frame.  There are three possibilities:
1804 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
1805 iconified.  @xref{Visibility of Frames}.
1807 @vindex auto-raise, a frame parameter
1808 @item auto-raise
1809 If non-@code{nil}, Emacs automatically raises the frame when it is
1810 selected.  Some window managers do not allow this.
1812 @vindex auto-lower, a frame parameter
1813 @item auto-lower
1814 If non-@code{nil}, Emacs automatically lowers the frame when it is
1815 deselected.  Some window managers do not allow this.
1817 @vindex icon-type, a frame parameter
1818 @item icon-type
1819 The type of icon to use for this frame.  If the value is a string,
1820 that specifies a file containing a bitmap to use; @code{nil} specifies
1821 no icon (in which case the window manager decides what to show); any
1822 other non-@code{nil} value specifies the default Emacs icon.
1824 @vindex icon-name, a frame parameter
1825 @item icon-name
1826 The name to use in the icon for this frame, when and if the icon
1827 appears.  If this is @code{nil}, the frame's title is used.
1829 @vindex window-id, a frame parameter
1830 @item window-id
1831 The ID number which the graphical display uses for this frame.  Emacs
1832 assigns this parameter when the frame is created; changing the
1833 parameter has no effect on the actual ID number.
1835 @vindex outer-window-id, a frame parameter
1836 @item outer-window-id
1837 The ID number of the outermost window-system window in which the frame
1838 exists.  As with @code{window-id}, changing this parameter has no
1839 actual effect.
1841 @vindex wait-for-wm, a frame parameter
1842 @item wait-for-wm
1843 If non-@code{nil}, tell Xt to wait for the window manager to confirm
1844 geometry changes.  Some window managers, including versions of Fvwm2
1845 and KDE, fail to confirm, so Xt hangs.  Set this to @code{nil} to
1846 prevent hanging with those window managers.
1848 @vindex sticky, a frame parameter
1849 @item sticky
1850 If non-@code{nil}, the frame is visible on all virtual desktops on systems
1851 with virtual desktops.
1853 @vindex inhibit-double-buffering, a frame parameter
1854 @item inhibit-double-buffering
1855 If non-@code{nil}, the frame is drawn to the screen without double
1856 buffering.  Emacs normally attempts to use double buffering, where
1857 available, to reduce flicker.  Set this property if you experience
1858 display bugs or pine for that retro, flicker-y feeling.
1860 @vindex skip-taskbar, a frame parameter
1861 @item skip-taskbar
1862 If non-@code{nil}, this tells the window manager to remove the frame's
1863 icon from the taskbar associated with the frame's display and inhibit
1864 switching to the frame's window via the combination @kbd{Alt-@key{TAB}}.
1865 On MS-Windows, iconifying such a frame will "roll in" its window-system
1866 window at the bottom of the desktop.  Some window managers may not honor
1867 this parameter.
1869 @vindex no-focus-on-map, a frame parameter
1870 @item no-focus-on-map
1871 If non-@code{nil}, this means that the frame does not want to receive
1872 input focus when it is mapped (@pxref{Visibility of Frames}).  Some
1873 window managers may not honor this parameter.
1875 @vindex no-accept-focus, a frame parameter
1876 @item no-accept-focus
1877 If non-@code{nil}, this means that the frame does not want to receive
1878 input focus via explicit mouse clicks or when moving the mouse into it
1879 either via @code{focus-follows-mouse} (@pxref{Input Focus}) or
1880 @code{mouse-autoselect-window} (@pxref{Mouse Window Auto-selection}).
1881 This may have the unwanted side-effect that a user cannot scroll a
1882 non-selected frame with the mouse.  Some window managers may not honor
1883 this parameter.
1885 @vindex undecorated, a frame parameter
1886 @item undecorated
1887 If non-@code{nil}, this frame's window-system window is drawn without
1888 decorations, like the title, minimize/maximize boxes and external
1889 borders.  This usually means that the window cannot be dragged, resized,
1890 iconified, maximized or deleted with the mouse.  If nil, the frame's
1891 window is usually drawn with all the elements listed above unless their
1892 display has been suspended via window manager settings.
1894 Under X, Emacs uses the Motif window manager hints to turn off
1895 decorations.  Some window managers may not honor these hints.
1897 NS builds consider the tool bar to be a decoration, and therefore hide
1898 it on an undecorated frame.
1900 @vindex override-redirect, a frame parameter
1901 @item override-redirect
1902 @cindex override redirect frames
1903 If non-@code{nil}, this means that this is an @dfn{override redirect}
1904 frame---a frame not handled by window managers under X.  Override
1905 redirect frames have no window manager decorations, can be positioned
1906 and resized only via Emacs' positioning and resizing functions and are
1907 usually drawn on top of all other frames.
1909 @ignore
1910 @vindex parent-id, a frame parameter
1911 @item parent-id
1912 @c ??? Not yet working.
1913 The X window number of the window that should be the parent of this one.
1914 Specifying this lets you create an Emacs window inside some other
1915 application's window.  (It is not certain this will be implemented; try
1916 it and see if it works.)
1917 @end ignore
1918 @end table
1921 @node Cursor Parameters
1922 @subsubsection Cursor Parameters
1923 @cindex cursor, and frame parameters
1925   This frame parameter controls the way the cursor looks.
1927 @table @code
1928 @vindex cursor-type, a frame parameter
1929 @item cursor-type
1930 How to display the cursor.  Legitimate values are:
1932 @table @code
1933 @item box
1934 Display a filled box.  (This is the default.)
1935 @item hollow
1936 Display a hollow box.
1937 @item nil
1938 Don't display a cursor.
1939 @item bar
1940 Display a vertical bar between characters.
1941 @item (bar . @var{width})
1942 Display a vertical bar @var{width} pixels wide between characters.
1943 @item hbar
1944 Display a horizontal bar.
1945 @item (hbar . @var{height})
1946 Display a horizontal bar @var{height} pixels high.
1947 @end table
1948 @end table
1950 @vindex cursor-type
1951 The @code{cursor-type} frame parameter may be overridden by the
1952 variables @code{cursor-type} and
1953 @code{cursor-in-non-selected-windows}:
1955 @defvar cursor-type
1956 This buffer-local variable controls how the cursor looks in a selected
1957 window showing the buffer.  If its value is @code{t}, that means to
1958 use the cursor specified by the @code{cursor-type} frame parameter.
1959 Otherwise, the value should be one of the cursor types listed above,
1960 and it overrides the @code{cursor-type} frame parameter.
1961 @end defvar
1963 @defopt cursor-in-non-selected-windows
1964 This buffer-local variable controls how the cursor looks in a window
1965 that is not selected.  It supports the same values as the
1966 @code{cursor-type} frame parameter; also, @code{nil} means don't
1967 display a cursor in nonselected windows, and @code{t} (the default)
1968 means use a standard modification of the usual cursor type (solid box
1969 becomes hollow box, and bar becomes a narrower bar).
1970 @end defopt
1972 @defopt x-stretch-cursor
1973 This variable controls the width of the block cursor displayed on
1974 extra-wide glyphs such as a tab or a stretch of white space.  By
1975 default, the block cursor is only as wide as the font's default
1976 character, and will not cover all of the width of the glyph under it
1977 if that glyph is extra-wide.  A non-@code{nil} value of this variable
1978 means draw the block cursor as wide as the glyph under it.  The
1979 default value is @code{nil}.
1981 This variable has no effect on text-mode frames, since the text-mode
1982 cursor is drawn by the terminal out of Emacs's control.
1983 @end defopt
1985 @defopt blink-cursor-alist
1986 This variable specifies how to blink the cursor.  Each element has the
1987 form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
1988 type equals @var{on-state} (comparing using @code{equal}), the
1989 corresponding @var{off-state} specifies what the cursor looks like
1990 when it blinks off.  Both @var{on-state} and @var{off-state}
1991 should be suitable values for the @code{cursor-type} frame parameter.
1993 There are various defaults for how to blink each type of cursor, if
1994 the type is not mentioned as an @var{on-state} here.  Changes in this
1995 variable do not take effect immediately, only when you specify the
1996 @code{cursor-type} frame parameter.
1997 @end defopt
1999 @node Font and Color Parameters
2000 @subsubsection Font and Color Parameters
2001 @cindex font and color, frame parameters
2003   These frame parameters control the use of fonts and colors.
2005 @table @code
2006 @vindex font-backend, a frame parameter
2007 @item font-backend
2008 A list of symbols, specifying the @dfn{font backends} to use for
2009 drawing fonts in the frame, in order of priority.  On X, there are
2010 currently two available font backends: @code{x} (the X core font
2011 driver) and @code{xft} (the Xft font driver).  On MS-Windows, there are
2012 currently two available font backends: @code{gdi} and
2013 @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
2014 Manual}).  On other systems, there is only one available font backend,
2015 so it does not make sense to modify this frame parameter.
2017 @vindex background-mode, a frame parameter
2018 @item background-mode
2019 This parameter is either @code{dark} or @code{light}, according
2020 to whether the background color is a light one or a dark one.
2022 @vindex tty-color-mode, a frame parameter
2023 @item tty-color-mode
2024 @cindex standard colors for character terminals
2025 This parameter overrides the terminal's color support as given by the
2026 system's terminal capabilities database in that this parameter's value
2027 specifies the color mode to use on a text terminal.  The value can be
2028 either a symbol or a number.  A number specifies the number of colors
2029 to use (and, indirectly, what commands to issue to produce each
2030 color).  For example, @code{(tty-color-mode . 8)} specifies use of the
2031 ANSI escape sequences for 8 standard text colors.  A value of -1 turns
2032 off color support.
2034 If the parameter's value is a symbol, it specifies a number through
2035 the value of @code{tty-color-mode-alist}, and the associated number is
2036 used instead.
2038 @vindex screen-gamma, a frame parameter
2039 @item screen-gamma
2040 @cindex gamma correction
2041 If this is a number, Emacs performs gamma correction which adjusts
2042 the brightness of all colors.  The value should be the screen gamma of
2043 your display.
2045 Usual PC monitors have a screen gamma of 2.2, so color values in
2046 Emacs, and in X windows generally, are calibrated to display properly
2047 on a monitor with that gamma value.  If you specify 2.2 for
2048 @code{screen-gamma}, that means no correction is needed.  Other values
2049 request correction, designed to make the corrected colors appear on
2050 your screen the way they would have appeared without correction on an
2051 ordinary monitor with a gamma value of 2.2.
2053 If your monitor displays colors too light, you should specify a
2054 @code{screen-gamma} value smaller than 2.2.  This requests correction
2055 that makes colors darker.  A screen gamma value of 1.5 may give good
2056 results for LCD color displays.
2058 @vindex alpha, a frame parameter
2059 @item alpha
2060 @cindex opacity, frame
2061 @cindex transparency, frame
2062 @vindex frame-alpha-lower-limit
2063 This parameter specifies the opacity of the frame, on graphical
2064 displays that support variable opacity.  It should be an integer
2065 between 0 and 100, where 0 means completely transparent and 100 means
2066 completely opaque.  It can also have a @code{nil} value, which tells
2067 Emacs not to set the frame opacity (leaving it to the window manager).
2069 To prevent the frame from disappearing completely from view, the
2070 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
2071 If the value of the frame parameter is less than the value of this
2072 variable, Emacs uses the latter.  By default,
2073 @code{frame-alpha-lower-limit} is 20.
2075 The @code{alpha} frame parameter can also be a cons cell
2076 @code{(@var{active} . @var{inactive})}, where @var{active} is the
2077 opacity of the frame when it is selected, and @var{inactive} is the
2078 opacity when it is not selected.
2079 @end table
2081 The following frame parameters are semi-obsolete in that they are
2082 automatically equivalent to particular face attributes of particular
2083 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
2085 @table @code
2086 @vindex font, a frame parameter
2087 @item font
2088 The name of the font for displaying text in the frame.  This is a
2089 string, either a valid font name for your system or the name of an Emacs
2090 fontset (@pxref{Fontsets}).  It is equivalent to the @code{font}
2091 attribute of the @code{default} face.
2093 @vindex foreground-color, a frame parameter
2094 @item foreground-color
2095 The color to use for the image of a character.  It is equivalent to
2096 the @code{:foreground} attribute of the @code{default} face.
2098 @vindex background-color, a frame parameter
2099 @item background-color
2100 The color to use for the background of characters.  It is equivalent to
2101 the @code{:background} attribute of the @code{default} face.
2103 @vindex mouse-color, a frame parameter
2104 @item mouse-color
2105 The color for the mouse pointer.  It is equivalent to the @code{:background}
2106 attribute of the @code{mouse} face.
2108 @vindex cursor-color, a frame parameter
2109 @item cursor-color
2110 The color for the cursor that shows point.  It is equivalent to the
2111 @code{:background} attribute of the @code{cursor} face.
2113 @vindex border-color, a frame parameter
2114 @item border-color
2115 The color for the border of the frame.  It is equivalent to the
2116 @code{:background} attribute of the @code{border} face.
2118 @vindex scroll-bar-foreground, a frame parameter
2119 @item scroll-bar-foreground
2120 If non-@code{nil}, the color for the foreground of scroll bars.  It is
2121 equivalent to the @code{:foreground} attribute of the
2122 @code{scroll-bar} face.
2124 @vindex scroll-bar-background, a frame parameter
2125 @item scroll-bar-background
2126 If non-@code{nil}, the color for the background of scroll bars.  It is
2127 equivalent to the @code{:background} attribute of the
2128 @code{scroll-bar} face.
2129 @end table
2132 @node Geometry
2133 @subsection Geometry
2135   Here's how to examine the data in an X-style window geometry
2136 specification:
2138 @defun x-parse-geometry geom
2139 @cindex geometry specification
2140 The function @code{x-parse-geometry} converts a standard X window
2141 geometry string to an alist that you can use as part of the argument to
2142 @code{make-frame}.
2144 The alist describes which parameters were specified in @var{geom}, and
2145 gives the values specified for them.  Each element looks like
2146 @code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
2147 values are @code{left}, @code{top}, @code{width}, and @code{height}.
2149 For the size parameters, the value must be an integer.  The position
2150 parameter names @code{left} and @code{top} are not totally accurate,
2151 because some values indicate the position of the right or bottom edges
2152 instead.  The @var{value} possibilities for the position parameters are:
2153 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
2154 as previously described (@pxref{Position Parameters}).
2156 Here is an example:
2158 @example
2159 (x-parse-geometry "35x70+0-0")
2160      @result{} ((height . 70) (width . 35)
2161          (top - 0) (left . 0))
2162 @end example
2163 @end defun
2165 @node Terminal Parameters
2166 @section Terminal Parameters
2167 @cindex terminal parameters
2169   Each terminal has a list of associated parameters.  These
2170 @dfn{terminal parameters} are mostly a convenient way of storage for
2171 terminal-local variables, but some terminal parameters have a special
2172 meaning.
2174   This section describes functions to read and change the parameter values
2175 of a terminal.  They all accept as their argument either a terminal or
2176 a frame; the latter means use that frame's terminal.  An argument of
2177 @code{nil} means the selected frame's terminal.
2179 @defun terminal-parameters &optional terminal
2180 This function returns an alist listing all the parameters of
2181 @var{terminal} and their values.
2182 @end defun
2184 @defun terminal-parameter terminal parameter
2185 This function returns the value of the parameter @var{parameter} (a
2186 symbol) of @var{terminal}.  If @var{terminal} has no setting for
2187 @var{parameter}, this function returns @code{nil}.
2188 @end defun
2190 @defun set-terminal-parameter terminal parameter value
2191 This function sets the parameter @var{parameter} of @var{terminal} to the
2192 specified @var{value}, and returns the previous value of that
2193 parameter.
2194 @end defun
2196 Here's a list of a few terminal parameters that have a special
2197 meaning:
2199 @table @code
2200 @item background-mode
2201 The classification of the terminal's background color, either
2202 @code{light} or @code{dark}.
2203 @item normal-erase-is-backspace
2204 Value is either 1 or 0, depending on whether
2205 @code{normal-erase-is-backspace-mode} is turned on or off on this
2206 terminal.  @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
2207 @item terminal-initted
2208 After the terminal is initialized, this is set to the
2209 terminal-specific initialization function.
2210 @item tty-mode-set-strings
2211 When present, a list of strings containing escape sequences that Emacs
2212 will output while configuring a tty for rendering.  Emacs emits these
2213 strings only when configuring a terminal: if you want to enable a mode
2214 on a terminal that is already active (for example, while in
2215 @code{tty-setup-hook}), explicitly output the necessary escape
2216 sequence using @code{send-string-to-terminal} in addition to adding
2217 the sequence to @code{tty-mode-set-strings}.
2218 @item tty-mode-reset-strings
2219 When present, a list of strings that undo the effects of the strings
2220 in @code{tty-mode-set-strings}.  Emacs emits these strings when
2221 exiting, deleting a terminal, or suspending itself.
2222 @end table
2224 @node Frame Titles
2225 @section Frame Titles
2226 @cindex frame title
2228   Every frame has a @code{name} parameter; this serves as the default
2229 for the frame title which window systems typically display at the top of
2230 the frame.  You can specify a name explicitly by setting the @code{name}
2231 frame property.
2233   Normally you don't specify the name explicitly, and Emacs computes the
2234 frame name automatically based on a template stored in the variable
2235 @code{frame-title-format}.  Emacs recomputes the name each time the
2236 frame is redisplayed.
2238 @defvar frame-title-format
2239 This variable specifies how to compute a name for a frame when you have
2240 not explicitly specified one.  The variable's value is actually a mode
2241 line construct, just like @code{mode-line-format}, except that the
2242 @samp{%c} and @samp{%l} constructs are ignored.  @xref{Mode Line
2243 Data}.
2244 @end defvar
2246 @defvar icon-title-format
2247 This variable specifies how to compute the name for an iconified frame,
2248 when you have not explicitly specified the frame title.  This title
2249 appears in the icon itself.
2250 @end defvar
2252 @defvar multiple-frames
2253 This variable is set automatically by Emacs.  Its value is @code{t} when
2254 there are two or more frames (not counting minibuffer-only frames or
2255 invisible frames).  The default value of @code{frame-title-format} uses
2256 @code{multiple-frames} so as to put the buffer name in the frame title
2257 only when there is more than one frame.
2259 The value of this variable is not guaranteed to be accurate except
2260 while processing @code{frame-title-format} or
2261 @code{icon-title-format}.
2262 @end defvar
2264 @node Deleting Frames
2265 @section Deleting Frames
2266 @cindex deleting frames
2268 A @dfn{live frame} is one that has not been deleted.  When a frame is
2269 deleted, it is removed from its terminal display, although it may
2270 continue to exist as a Lisp object until there are no more references to
2273 @deffn Command delete-frame &optional frame force
2274 @vindex delete-frame-functions
2275 This function deletes the frame @var{frame}.  The argument @var{frame}
2276 must specify a live frame (see below) and defaults to the selected
2277 frame.
2279 It first deletes any child frame of @var{frame} (@pxref{Child Frames})
2280 and any frame whose @code{delete-before} frame parameter (@pxref{Frame
2281 Interaction Parameters}) specifies @var{frame}.  All such deletions are
2282 performed recursively; so this step makes sure that no other frames with
2283 @var{frame} as their ancestor will exist.  Then, unless @var{frame}
2284 specifies a tooltip, this function runs the hook
2285 @code{delete-frame-functions} (each function getting one argument,
2286 @var{frame}) before actually killing the frame.
2288 Note that a frame cannot be deleted as long as its minibuffer serves as
2289 surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}).
2290 Normally, you cannot delete a frame if all other frames are invisible,
2291 but if @var{force} is non-@code{nil}, then you are allowed to do so.
2292 @end deffn
2294 @defun frame-live-p frame
2295 This function returns non-@code{nil} if the frame @var{frame} has not
2296 been deleted.  The possible non-@code{nil} return values are like those
2297 of @code{framep}.  @xref{Frames}.
2298 @end defun
2300   Some window managers provide a command to delete a window.  These work
2301 by sending a special message to the program that operates the window.
2302 When Emacs gets one of these commands, it generates a
2303 @code{delete-frame} event, whose normal definition is a command that
2304 calls the function @code{delete-frame}.  @xref{Misc Events}.
2306 @deffn Command delete-other-frames &optional frame
2307 This command deletes all frames on @var{frame}'s terminal, except
2308 @var{frame}.  If @var{frame} uses another frame's minibuffer, that
2309 minibuffer frame is left untouched.  The argument @var{frame} must
2310 specify a live frame and defaults to the selected frame.  Internally,
2311 this command works by calling @code{delete-frame} with @var{force}
2312 @code{nil} for all frames that shall be deleted.
2314 This function does not delete any of @var{frame}'s child frames
2315 (@pxref{Child Frames}).  If @var{frame} is a child frame, it deletes
2316 @var{frame}'s siblings only.
2317 @end deffn
2320 @node Finding All Frames
2321 @section Finding All Frames
2322 @cindex frames, scanning all
2324 @defun frame-list
2325 This function returns a list of all the live frames, i.e., those that
2326 have not been deleted.  It is analogous to @code{buffer-list} for
2327 buffers, and includes frames on all terminals.  The list that you get
2328 is newly created, so modifying the list doesn't have any effect on the
2329 internals of Emacs.
2330 @end defun
2332 @defun visible-frame-list
2333 This function returns a list of just the currently visible frames.
2334 @xref{Visibility of Frames}.  Frames on text terminals always count as
2335 visible, even though only the selected one is actually displayed.
2336 @end defun
2338 @defun frame-list-z-order &optional display
2339 This function returns a list of Emacs' frames, in Z (stacking) order
2340 (@pxref{Raising and Lowering}).  The optional argument @var{display}
2341 specifies which display to poll.  @var{display} should be either a frame
2342 or a display name (a string).  If omitted or @code{nil}, that stands for
2343 the selected frame's display.  It returns @code{nil} if @var{display}
2344 contains no Emacs frame.
2346 Frames are listed from topmost (first) to bottommost (last).  As a
2347 special case, if @var{display} is non-@code{nil} and specifies a live
2348 frame, it returns the child frames of that frame in Z (stacking) order.
2350 This function is not meaningful on text terminals.
2351 @end defun
2353 @defun next-frame &optional frame minibuf
2354 This function lets you cycle conveniently through all the frames on a
2355 specific terminal from an arbitrary starting point.  It returns the
2356 frame following @var{frame}, in the list of all live frames, on
2357 @var{frame}'s terminal.  The argument @var{frame} must specify a live
2358 frame and defaults to the selected frame.  It never returns a frame
2359 whose @code{no-other-frame} parameter (@pxref{Frame Interaction
2360 Parameters}) is non-@code{nil}.
2362 The second argument, @var{minibuf}, says which frames to consider:
2364 @table @asis
2365 @item @code{nil}
2366 Exclude minibuffer-only frames.
2367 @item @code{visible}
2368 Consider all visible frames.
2369 @item 0
2370 Consider all visible or iconified frames.
2371 @item a window
2372 Consider only the frames using that particular window as their
2373 minibuffer.
2374 @item anything else
2375 Consider all frames.
2376 @end table
2377 @end defun
2379 @defun previous-frame &optional frame minibuf
2380 Like @code{next-frame}, but cycles through all frames in the opposite
2381 direction.
2382 @end defun
2384   See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
2385 Window Ordering}.
2387 @node Minibuffers and Frames
2388 @section Minibuffers and Frames
2390 Normally, each frame has its own minibuffer window at the bottom, which
2391 is used whenever that frame is selected.  You can get that window with
2392 the function @code{minibuffer-window} (@pxref{Minibuffer Windows}).
2394 @cindex frame without a minibuffer
2395 @cindex surrogate minibuffer frame
2396 However, you can also create a frame without a minibuffer.  Such a frame
2397 must use the minibuffer window of some other frame.  That other frame
2398 will serve as @dfn{surrogate minibuffer frame} for this frame and cannot
2399 be deleted via @code{delete-frame} (@pxref{Deleting Frames}) as long as
2400 this frame is live.
2402 When you create the frame, you can explicitly specify its minibuffer
2403 window (in some other frame) with the @code{minibuffer} frame parameter
2404 (@pxref{Buffer Parameters}).  If you don't, then the minibuffer is found
2405 in the frame which is the value of the variable
2406 @code{default-minibuffer-frame}.  Its value should be a frame that does
2407 have a minibuffer.
2409 If you use a minibuffer-only frame, you might want that frame to raise
2410 when you enter the minibuffer.  If so, set the variable
2411 @code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.
2413 @defvar default-minibuffer-frame
2414 This variable specifies the frame to use for the minibuffer window, by
2415 default.  It does not affect existing frames.  It is always local to
2416 the current terminal and cannot be buffer-local.  @xref{Multiple
2417 Terminals}.
2418 @end defvar
2421 @node Input Focus
2422 @section Input Focus
2423 @cindex input focus
2424 @cindex selected frame
2426 At any time, one frame in Emacs is the @dfn{selected frame}.  The
2427 selected window always resides on the selected frame.
2429 When Emacs displays its frames on several terminals (@pxref{Multiple
2430 Terminals}), each terminal has its own selected frame.  But only one
2431 of these is @emph{the} selected frame: it's the frame that belongs
2432 to the terminal from which the most recent input came.  That is, when
2433 Emacs runs a command that came from a certain terminal, the selected
2434 frame is the one of that terminal.  Since Emacs runs only a single
2435 command at any given time, it needs to consider only one selected
2436 frame at a time; this frame is what we call @dfn{the selected frame}
2437 in this manual.  The display on which the selected frame is shown is
2438 the @dfn{selected frame's display}.
2440 @defun selected-frame
2441 This function returns the selected frame.
2442 @end defun
2444 Some window systems and window managers direct keyboard input to the
2445 window object that the mouse is in; others require explicit clicks or
2446 commands to @dfn{shift the focus} to various window objects.  Either
2447 way, Emacs automatically keeps track of which frame has the focus.  To
2448 explicitly switch to a different frame from a Lisp function, call
2449 @code{select-frame-set-input-focus}.
2451 Lisp programs can also switch frames temporarily by calling the
2452 function @code{select-frame}.  This does not alter the window system's
2453 concept of focus; rather, it escapes from the window manager's control
2454 until that control is somehow reasserted.
2456 When using a text terminal, only one frame can be displayed at a time
2457 on the terminal, so after a call to @code{select-frame}, the next
2458 redisplay actually displays the newly selected frame.  This frame
2459 remains selected until a subsequent call to @code{select-frame}.  Each
2460 frame on a text terminal has a number which appears in the mode line
2461 before the buffer name (@pxref{Mode Line Variables}).
2463 @defun select-frame-set-input-focus frame &optional norecord
2464 This function selects @var{frame}, raises it (should it happen to be
2465 obscured by other frames) and tries to give it the X server's focus.
2466 On a text terminal, the next redisplay displays the new frame on the
2467 entire terminal screen.  The optional argument @var{norecord} has the
2468 same meaning as for @code{select-frame} (see below).  The return value
2469 of this function is not significant.
2470 @end defun
2472 Ideally, the function described next should focus a frame without also
2473 raising it above other frames.  Unfortunately, many window-systems or
2474 window managers may refuse to comply.
2476 @defun x-focus-frame &optional frame noactivate
2477 This function gives @var{frame} the focus of the X server without
2478 necessarily raising it.  @var{frame} @code{nil} means use the selected
2479 frame.  Under X, the optional argument @var{noactivate}, if
2480 non-@code{nil}, means to avoid making @var{frame}'s window-system window
2481 the ``active'' window which should insist a bit more on avoiding to
2482 raise @var{frame} above other frames.
2484 On MS-Windows the @var{noactivate} argument has no effect.  However, if
2485 @var{frame} is a child frame (@pxref{Child Frames}), this function
2486 usually focuses @var{frame} without raising it above other child
2487 frames.
2489 If there is no window system support, this function does nothing.
2490 @end defun
2492 @deffn Command select-frame frame &optional norecord
2493 This function selects frame @var{frame}, temporarily disregarding the
2494 focus of the X server if any.  The selection of @var{frame} lasts until
2495 the next time the user does something to select a different frame, or
2496 until the next time this function is called.  (If you are using a
2497 window system, the previously selected frame may be restored as the
2498 selected frame after return to the command loop, because it still may
2499 have the window system's input focus.)
2501 The specified @var{frame} becomes the selected frame, and its terminal
2502 becomes the selected terminal.  This function then calls
2503 @code{select-window} as a subroutine, passing the window selected
2504 within @var{frame} as its first argument and @var{norecord} as its
2505 second argument (hence, if @var{norecord} is non-@code{nil}, this
2506 avoids changing the order of recently selected windows and the buffer
2507 list).  @xref{Selecting Windows}.
2509 This function returns @var{frame}, or @code{nil} if @var{frame} has
2510 been deleted.
2512 In general, you should never use @code{select-frame} in a way that
2513 could switch to a different terminal without switching back when
2514 you're done.
2515 @end deffn
2517 Emacs cooperates with the window system by arranging to select frames as
2518 the server and window manager request.  It does so by generating a
2519 special kind of input event, called a @dfn{focus} event, when
2520 appropriate.  The command loop handles a focus event by calling
2521 @code{handle-switch-frame}.  @xref{Focus Events}.
2523 @deffn Command handle-switch-frame frame
2524 This function handles a focus event by selecting frame @var{frame}.
2526 Focus events normally do their job by invoking this command.
2527 Don't call it for any other reason.
2528 @end deffn
2530 @defun redirect-frame-focus frame &optional focus-frame
2531 This function redirects focus from @var{frame} to @var{focus-frame}.
2532 This means that @var{focus-frame} will receive subsequent keystrokes and
2533 events intended for @var{frame}.  After such an event, the value of
2534 @code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
2535 events specifying @var{frame} will instead select @var{focus-frame}.
2537 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
2538 redirection for @var{frame}, which therefore once again receives its own
2539 events.
2541 One use of focus redirection is for frames that don't have minibuffers.
2542 These frames use minibuffers on other frames.  Activating a minibuffer
2543 on another frame redirects focus to that frame.  This puts the focus on
2544 the minibuffer's frame, where it belongs, even though the mouse remains
2545 in the frame that activated the minibuffer.
2547 Selecting a frame can also change focus redirections.  Selecting frame
2548 @code{bar}, when @code{foo} had been selected, changes any redirections
2549 pointing to @code{foo} so that they point to @code{bar} instead.  This
2550 allows focus redirection to work properly when the user switches from
2551 one frame to another using @code{select-window}.
2553 This means that a frame whose focus is redirected to itself is treated
2554 differently from a frame whose focus is not redirected.
2555 @code{select-frame} affects the former but not the latter.
2557 The redirection lasts until @code{redirect-frame-focus} is called to
2558 change it.
2559 @end defun
2561 @defvar focus-in-hook
2562 This is a normal hook run when an Emacs frame gains input focus.  The
2563 frame gaining focus is selected when this hook is run.
2564 @end defvar
2566 @defvar focus-out-hook
2567 This is a normal hook run when an Emacs frame has lost input focus and
2568 no other Emacs frame has gained input focus instead.
2569 @end defvar
2571 @defopt focus-follows-mouse
2572 This option informs Emacs whether and how the window manager transfers
2573 focus when you move the mouse pointer into a frame.  It can have three
2574 meaningful values:
2576 @table @asis
2577 @item @code{nil}
2578 The default value @code{nil} should be used when your window manager
2579 follows a ``click-to-focus'' policy where you have to click the mouse
2580 inside of a frame in order for that frame to gain focus.
2582 @item @code{t}
2583 The value @code{t} should be used when your window manager has the focus
2584 automatically follow the position of the mouse pointer but a frame that
2585 gains focus is not raised automatically and may even remain occluded by
2586 other window-system windows.
2588 @item @code{auto-raise}
2589 The value @code{auto-raise} should be used when your window manager has
2590 the focus automatically follow the position of the mouse pointer and a
2591 frame that gains focus is raised automatically.
2592 @end table
2594 If this option is non-@code{nil}, Emacs moves the mouse pointer to the
2595 frame selected by @code{select-frame-set-input-focus}.  That function is
2596 used by a number of commands like, for example, @code{other-frame} and
2597 @code{pop-to-buffer}.
2599 The distinction between the values @code{t} and @code{auto-raise} is not
2600 needed for ``normal'' frames because the window manager usually takes
2601 care of raising them.  It is useful to automatically raise child frames
2602 via @code{mouse-autoselect-window} (@pxref{Mouse Window
2603 Auto-selection}).
2605 Note that this option does not distinguish ``sloppy'' focus (where the
2606 frame that previously had focus retains focus as long as the mouse
2607 pointer does not move into another window manager window) from
2608 ``strict'' focus (where a frame immediately loses focus when it's left
2609 by the mouse pointer).  Neither does it recognize whether your window
2610 manager supports delayed focusing or auto-raising where you can
2611 explicitly specify the time until a new frame gets focus or is
2612 auto-raised.
2614 You can supply a ``focus follows mouse'' policy for individual Emacs
2615 windows by customizing the variable @code{mouse-autoselect-window}
2616 (@pxref{Mouse Window Auto-selection}).
2617 @end defopt
2620 @node Visibility of Frames
2621 @section Visibility of Frames
2622 @cindex visible frame
2623 @cindex invisible frame
2624 @cindex iconified frame
2625 @cindex minimized frame
2626 @cindex frame visibility
2628 A frame on a graphical display may be @dfn{visible}, @dfn{invisible}, or
2629 @dfn{iconified}.  If it is visible, its contents are displayed in the
2630 usual manner.  If it is iconified, its contents are not displayed, but
2631 there is a little icon somewhere to bring the frame back into view (some
2632 window managers refer to this state as @dfn{minimized} rather than
2633 @dfn{iconified}, but from Emacs' point of view they are the same thing).
2634 If a frame is invisible, it is not displayed at all.
2636 @cindex mapped frame
2637 @cindex unmapped frame
2638   The concept of visibility is strongly related to that of (un-)mapped
2639 frames.  A frame (or, more precisely, its window-system window) is and
2640 becomes @dfn{mapped} when it is displayed for the first time and
2641 whenever it changes its state of visibility from @code{iconified} or
2642 @code{invisible} to @code{visible}.  Conversely, a frame is and becomes
2643 @dfn{unmapped} whenever it changes its status from @code{visible} to
2644 @code{iconified} or @code{invisible}.
2646   Visibility is meaningless on text terminals, since only the selected
2647 frame is actually displayed in any case.
2649 @defun frame-visible-p frame
2650 This function returns the visibility status of frame @var{frame}.  The
2651 value is @code{t} if @var{frame} is visible, @code{nil} if it is
2652 invisible, and @code{icon} if it is iconified.
2654 On a text terminal, all frames are considered visible for the
2655 purposes of this function, even though only one frame is displayed.
2656 @xref{Raising and Lowering}.
2657 @end defun
2659 @deffn Command iconify-frame &optional frame
2660 This function iconifies frame @var{frame}.  If you omit @var{frame}, it
2661 iconifies the selected frame.  This usually makes all child frames of
2662 @var{frame} (and their descendants) invisible (@pxref{Child Frames}).
2663 @end deffn
2665 @deffn Command make-frame-visible &optional frame
2666 This function makes frame @var{frame} visible.  If you omit @var{frame},
2667 it makes the selected frame visible.  This does not raise the frame, but
2668 you can do that with @code{raise-frame} if you wish (@pxref{Raising and
2669 Lowering}).
2671 Making a frame visible usually makes all its child frames (and their
2672 descendants) visible as well (@pxref{Child Frames}).
2673 @end deffn
2675 @deffn Command make-frame-invisible &optional frame force
2676 This function makes frame @var{frame} invisible.  If you omit
2677 @var{frame}, it makes the selected frame invisible.  Usually, this makes
2678 all child frames of @var{frame} (and their descendants) invisible too
2679 (@pxref{Child Frames}).
2681 Unless @var{force} is non-@code{nil}, this function refuses to make
2682 @var{frame} invisible if all other frames are invisible.
2683 @end deffn
2685   The visibility status of a frame is also available as a frame
2686 parameter.  You can read or change it as such.  @xref{Management
2687 Parameters}.  The user can also iconify and deiconify frames with the
2688 window manager.  This happens below the level at which Emacs can exert
2689 any control, but Emacs does provide events that you can use to keep
2690 track of such changes.  @xref{Misc Events}.
2692 @defun x-double-buffered-p &optional frame
2693 This function returns non-@code{nil} if @var{frame} is currently
2694 being rendered with double buffering.  @var{frame} defaults to the
2695 selected frame.
2696 @end defun
2699 @node Raising and Lowering
2700 @section Raising, Lowering and Restacking Frames
2702 @cindex raising a frame
2703 @cindex lowering a frame
2704 @cindex restacking a frame
2705 @cindex frame stacking order
2706 @cindex frame Z-order
2707 @cindex Z-order
2708   Most window systems use a desktop metaphor.  Part of this metaphor is
2709 the idea that system-level windows (representing, e.g., Emacs frames)
2710 are stacked in a notional third dimension perpendicular to the screen
2711 surface.  The order induced by stacking is total and usually referred to
2712 as stacking (or Z-) order.  Where the areas of two windows overlap, the
2713 one higher up in that order will (partially) cover the one underneath.
2715   You can @dfn{raise} a frame to the top of that order or @dfn{lower} a
2716 frame to its bottom by using the functions @code{raise-frame} and
2717 @code{lower-frame}.  You can @dfn{restack} a frame directly above or
2718 below another frame using the function @code{frame-restack}.
2720   Note that all functions described below will respect the adherence of
2721 frames (and all other window-system windows) to their respective z-group
2722 (@pxref{Position Parameters}).  For example, you usually cannot lower a
2723 frame below that of the desktop window and you cannot raise a frame
2724 whose @code{z-group} parameter is @code{nil} above the window-system's
2725 taskbar or tooltip window.
2727 @deffn Command raise-frame &optional frame
2728 This function raises frame @var{frame} (default, the selected frame)
2729 above all other frames belonging to the same or a lower z-group as
2730 @var{frame}.  If @var{frame} is invisible or iconified, this makes it
2731 visible.  If @var{frame} is a child frame (@pxref{Child Frames}), this
2732 raises @var{frame} above all other child frames of its parent.
2733 @end deffn
2735 @deffn Command lower-frame &optional frame
2736 This function lowers frame @var{frame} (default, the selected frame)
2737 below all other frames belonging to the same or a higher z-group as
2738 @var{frame}.  If @var{frame} is a child frame (@pxref{Child Frames}),
2739 this lowers @var{frame} below all other child frames of its parent.
2740 @end deffn
2742 @defun frame-restack frame1 frame2 &optional above
2743 This function restacks @var{frame1} below @var{frame2}.  This implies
2744 that if both frames are visible and their display areas overlap,
2745 @var{frame2} will (partially) obscure @var{frame1}.  If the optional
2746 third argument @var{above} is non-@code{nil}, this function restacks
2747 @var{frame1} above @var{frame2}.  This means that if both frames are
2748 visible and their display areas overlap, @var{frame1} will (partially)
2749 obscure @var{frame2}.
2751 Technically, this function may be thought of as an atomic action
2752 performed in two steps: The first step removes @var{frame1}'s
2753 window-system window from the display.  The second step reinserts
2754 @var{frame1}'s window into the display below (above if @var{above} is
2755 true) that of @var{frame2}.  Hence the position of @var{frame2} in its
2756 display's Z (stacking) order relative to all other frames excluding
2757 @var{frame1} remains unaltered.
2759 Some window managers may refuse to restack windows.
2760 @end defun
2762 Note that the effect of restacking will only hold as long as neither of
2763 the involved frames is iconified or made invisible.  You can use the
2764 @code{z-group} (@pxref{Position Parameters}) frame parameter to add a
2765 frame to a group of frames permanently shown above or below other
2766 frames.  As long as a frame belongs to one of these groups, restacking
2767 it will only affect its relative stacking position within that group.
2768 The effect of restacking frames belonging to different z-groups is
2769 undefined.  You can list frames in their current stacking order with the
2770 function @code{frame-list-z-order} (@pxref{Finding All Frames}).
2772 @defopt minibuffer-auto-raise
2773 If this is non-@code{nil}, activation of the minibuffer raises the frame
2774 that the minibuffer window is in.
2775 @end defopt
2777   On window systems, you can also enable auto-raising (on frame
2778 selection) or auto-lowering (on frame deselection) using frame
2779 parameters.  @xref{Management Parameters}.
2781 @cindex top frame
2782   The concept of raising and lowering frames also applies to text
2783 terminal frames.  On each text terminal, only the top frame is
2784 displayed at any one time.
2786 @defun tty-top-frame &optional terminal
2787 This function returns the top frame on @var{terminal}.  @var{terminal}
2788 should be a terminal object, a frame (meaning that frame's terminal),
2789 or @code{nil} (meaning the selected frame's terminal).  If it does not
2790 refer to a text terminal, the return value is @code{nil}.
2791 @end defun
2794 @node Frame Configurations
2795 @section Frame Configurations
2796 @cindex frame configuration
2798   A @dfn{frame configuration} records the current arrangement of frames,
2799 all their properties, and the window configuration of each one.
2800 (@xref{Window Configurations}.)
2802 @defun current-frame-configuration
2803 This function returns a frame configuration list that describes
2804 the current arrangement of frames and their contents.
2805 @end defun
2807 @defun set-frame-configuration configuration &optional nodelete
2808 This function restores the state of frames described in
2809 @var{configuration}.  However, this function does not restore deleted
2810 frames.
2812 Ordinarily, this function deletes all existing frames not listed in
2813 @var{configuration}.  But if @var{nodelete} is non-@code{nil}, the
2814 unwanted frames are iconified instead.
2815 @end defun
2818 @node Child Frames
2819 @section Child Frames
2820 @cindex child frames
2821 @cindex parent frames
2823 On some window-systems the @code{parent-frame} parameter (@pxref{Frame
2824 Interaction Parameters}) can be used to make a frame a child of the
2825 frame specified by that parameter.  The frame specified by that
2826 parameter will then be the frame's parent frame as long as the parameter
2827 is not changed or reset.  Technically, this makes the child frame's
2828 window-system window a child window of the parent frame's window-system
2829 window.
2831   The @code{parent-frame} parameter can be changed at any time.  Setting
2832 it to another frame ``reparents'' the child frame.  Setting it to
2833 another child frame makes the frame a ``nested'' child frame.  Setting
2834 it to @code{nil} restores the frame's status as a top-level frame---one
2835 whose window-system window is a child of its display's root window.
2837   Since child frames can be arbitrarily nested, a frame can be both a
2838 child and a parent frame.  Also, the relative roles of child and parent
2839 frame may be reversed at any time (though it's usually a good idea to
2840 keep the size of child frames sufficiently smaller than that of their
2841 parent).  An error will be signaled for the attempt to make a frame an
2842 ancestor of itself.
2844   A child frame is clipped at the native edges (@pxref{Frame Geometry})
2845 of its parent frame---everything outside these edges is invisible.  Its
2846 @code{left} and @code{top} parameters specify positions relative to the
2847 top-left corner of its parent's native frame.  When either of the frames
2848 is resized, the relative position of the child frame remains unaltered.
2849 Hence, resizing either of these frames can hide or reveal parts of the
2850 child frame.
2852   NS builds do not clip child frames at the parent frame's edges,
2853 allowing them to be positioned so they do not obscure the parent
2854 frame while still being visible themselves.
2856   Usually, moving a parent frame moves along all its child frames and
2857 their descendants as well, keeping their relative positions unaltered.
2858 The hook @code{move-frame-functions} (@pxref{Frame Position}) is run for
2859 a child frame only when the position of the child frame relative to its
2860 parent frame changes.  When a parent frame is resized, the child frame
2861 retains its position respective to the left and upper native edges of
2862 its parent.  In this case, the position respective to the lower or right
2863 native edge of the parent frame is usually lost.
2865   A visible child frame always appears on top of its parent frame thus
2866 obscuring parts of it, except on NS builds where it may be positioned
2867 beneath the parent.  This is comparable to the window-system window of
2868 a top-level frame which also always appears on top of its parent
2869 window---the desktop's root window.  When a parent frame is iconified
2870 or made invisible (@pxref{Visibility of Frames}), its child frames are
2871 made invisible.  When a parent frame is deiconified or made visible,
2872 its child frames are made visible.  When a parent frame is about to be
2873 deleted, (@pxref{Deleting Frames}) its child frames are recursively
2874 deleted before it.
2876   Whether a child frame can have a menu or tool bar is window-system or
2877 window manager dependent.  Most window-systems explicitly disallow menus
2878 bars for child frames.  It seems advisable to disable both, menu and
2879 tool bars, via the frame's initial parameters settings.
2881   Usually, child frames do not exhibit window manager decorations like a
2882 title bar or external borders (@pxref{Frame Geometry}).  When the child
2883 frame does not show a menu or tool bar, any other of the frame's borders
2884 (@pxref{Layout Parameters}) can be used instead of the external borders.
2886   In particular, under X (but not when building with GTK+), the frame's
2887 outer border can be used.  On MS-Windows, specifying a non-zero outer
2888 border width will show a one-pixel wide external border.  Under all
2889 window-systems, the internal border can be used.  In either case, it's
2890 advisable to disable a child frame's window manager decorations with the
2891 @code{undecorated} frame parameter @pxref{Management Parameters}).
2893   The behavior of child frames deviates from that of top-level frames in
2894 a number of other ways as well.  Here we sketch a few of them:
2896 @itemize @bullet
2897 @item
2898 The semantics of maximizing and iconifying child frames is highly
2899 window-system dependent.  As a rule, applications should never invoke
2900 these operations for child frames.
2902 @item
2903 Raising, lowering and restacking child frames (@pxref{Raising and
2904 Lowering}) or changing the @code{z-group} (@pxref{Position Parameters})
2905 of a child frame changes only the stacking order of child frames with
2906 the same parent.
2908 @item
2909 Many window-systems are not able to change the opacity (@pxref{Font and
2910 Color Parameters}) of child frames.
2912 @item
2913 Transferring focus from a child frame to an ancestor that is not its
2914 parent by clicking with the mouse in a visible part of that ancestor's
2915 window may fail with some window-systems.  You may have to click into
2916 the direct parent's window-system window first.
2918 @item
2919 Window managers might not bother to extend their focus follows mouse
2920 policy to child frames.  Customizing @code{mouse-autoselect-window} can
2921 help in this regard (@pxref{Mouse Window Auto-selection}).
2923 @item
2924 Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed to
2925 work on all window-systems.  Some will drop the object on the parent
2926 frame or on some ancestor instead.
2927 @end itemize
2929   The following two functions may be useful when working with child and
2930 parent frames:
2932 @defun frame-parent &optional frame
2933 This function returns the parent frame of @var{frame}.  The parent frame
2934 of @var{frame} is the Emacs frame whose window-system window is the
2935 parent window of @var{frame}'s window-system window.  If such a frame
2936 exists, @var{frame} is considered a child frame of that frame.
2938 This function returns @code{nil} if @var{frame} has no parent frame.
2939 @end defun
2941 @defun frame-ancestor-p &optional ancestor descendant
2942 This functions returns non-@code{nil} if @var{ancestor} is an ancestor
2943 of @var{descendant}.  @var{ancestor} is an ancestor of @var{descendant}
2944 when it is either @var{descendant}'s parent frame or it is an ancestor
2945 of @var{descendant}'s parent frame.  Both, @var{ancestor} and
2946 @var{descendant} must specify live frames and default to the selected
2947 frame.
2948 @end defun
2951 @node Mouse Tracking
2952 @section Mouse Tracking
2953 @cindex mouse tracking
2954 @c @cindex tracking the mouse   Duplicates track-mouse
2956   Sometimes it is useful to @dfn{track} the mouse, which means to display
2957 something to indicate where the mouse is and move the indicator as the
2958 mouse moves.  For efficient mouse tracking, you need a way to wait until
2959 the mouse actually moves.
2961   The convenient way to track the mouse is to ask for events to represent
2962 mouse motion.  Then you can wait for motion by waiting for an event.  In
2963 addition, you can easily handle any other sorts of events that may
2964 occur.  That is useful, because normally you don't want to track the
2965 mouse forever---only until some other event, such as the release of a
2966 button.
2968 @defspec track-mouse body@dots{}
2969 This special form executes @var{body}, with generation of mouse motion
2970 events enabled.  Typically, @var{body} would use @code{read-event} to
2971 read the motion events and modify the display accordingly.  @xref{Motion
2972 Events}, for the format of mouse motion events.
2974 The value of @code{track-mouse} is that of the last form in @var{body}.
2975 You should design @var{body} to return when it sees the up-event that
2976 indicates the release of the button, or whatever kind of event means
2977 it is time to stop tracking.
2979 The @code{track-mouse} form causes Emacs to generate mouse motion
2980 events by binding the variable @code{track-mouse} to a
2981 non-@code{nil} value.  If that variable has the special value
2982 @code{dragging}, it additionally instructs the display engine to
2983 refrain from changing the shape of the mouse pointer.  This is
2984 desirable in Lisp programs that require mouse dragging across large
2985 portions of Emacs display, which might otherwise cause the mouse
2986 pointer to change its shape according to the display portion it hovers
2987 on (@pxref{Pointer Shape}).  Therefore, Lisp programs that need the
2988 mouse pointer to retain its original shape during dragging should bind
2989 @code{track-mouse} to the value @code{dragging} at the beginning of
2990 their @var{body}.
2991 @end defspec
2993 The usual purpose of tracking mouse motion is to indicate on the screen
2994 the consequences of pushing or releasing a button at the current
2995 position.
2997 In many cases, you can avoid the need to track the mouse by using
2998 the @code{mouse-face} text property (@pxref{Special Properties}).
2999 That works at a much lower level and runs more smoothly than
3000 Lisp-level mouse tracking.
3002 @ignore
3003 @c These are not implemented yet.
3005 These functions change the screen appearance instantaneously.  The
3006 effect is transient, only until the next ordinary Emacs redisplay.  That
3007 is OK for mouse tracking, since it doesn't make sense for mouse tracking
3008 to change the text, and the body of @code{track-mouse} normally reads
3009 the events itself and does not do redisplay.
3011 @defun x-contour-region window beg end
3012 This function draws lines to make a box around the text from @var{beg}
3013 to @var{end}, in window @var{window}.
3014 @end defun
3016 @defun x-uncontour-region window beg end
3017 This function erases the lines that would make a box around the text
3018 from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
3019 a contour that you previously made by calling @code{x-contour-region}.
3020 @end defun
3022 @defun x-draw-rectangle frame left top right bottom
3023 This function draws a hollow rectangle on frame @var{frame} with the
3024 specified edge coordinates, all measured in pixels from the inside top
3025 left corner.  It uses the cursor color, the one used for indicating the
3026 location of point.
3027 @end defun
3029 @defun x-erase-rectangle frame left top right bottom
3030 This function erases a hollow rectangle on frame @var{frame} with the
3031 specified edge coordinates, all measured in pixels from the inside top
3032 left corner.  Erasure means redrawing the text and background that
3033 normally belong in the specified rectangle.
3034 @end defun
3035 @end ignore
3037 @node Mouse Position
3038 @section Mouse Position
3039 @cindex mouse position
3040 @cindex position of mouse
3042   The functions @code{mouse-position} and @code{set-mouse-position}
3043 give access to the current position of the mouse.
3045 @defun mouse-position
3046 This function returns a description of the position of the mouse.  The
3047 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
3048 and @var{y} are integers giving the (possibly rounded) position in
3049 multiples of the default character size of @var{frame} (@pxref{Frame
3050 Font}) relative to the native position of @var{frame} (@pxref{Frame
3051 Geometry}).
3052 @end defun
3054 @defvar mouse-position-function
3055 If non-@code{nil}, the value of this variable is a function for
3056 @code{mouse-position} to call.  @code{mouse-position} calls this
3057 function just before returning, with its normal return value as the
3058 sole argument, and it returns whatever this function returns to it.
3060 This abnormal hook exists for the benefit of packages like
3061 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
3062 @end defvar
3064 @defun set-mouse-position frame x y
3065 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
3066 frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
3067 giving the position in multiples of the default character size of
3068 @var{frame} (@pxref{Frame Font}) relative to the native position of
3069 @var{frame} (@pxref{Frame Geometry}).
3071 The resulting mouse position is constrained to the native frame of
3072 @var{frame}.  If @var{frame} is not visible, this function does nothing.
3073 The return value is not significant.
3074 @end defun
3076 @defun mouse-pixel-position
3077 This function is like @code{mouse-position} except that it returns
3078 coordinates in units of pixels rather than units of characters.
3079 @end defun
3081 @defun set-mouse-pixel-position frame x y
3082 This function warps the mouse like @code{set-mouse-position} except that
3083 @var{x} and @var{y} are in units of pixels rather than units of
3084 characters.
3086 The resulting mouse position is not constrained to the native frame of
3087 @var{frame}.  If @var{frame} is not visible, this function does nothing.
3088 The return value is not significant.
3089 @end defun
3091 On a graphical terminal the following two functions allow the absolute
3092 position of the mouse cursor to be retrieved and set.
3094 @defun mouse-absolute-pixel-position
3095 This function returns a cons cell (@var{x} . @var{y}) of the coordinates
3096 of the mouse cursor position in pixels, relative to a position (0, 0) of
3097 the selected frame's display.
3098 @end defun
3100 @defun set-mouse-absolute-pixel-position x y
3101 This function moves the mouse cursor to the position (@var{x}, @var{y}).
3102 The coordinates @var{x} and @var{y} are interpreted in pixels relative
3103 to a position (0, 0) of the selected frame's display.
3104 @end defun
3106 The following function can tell whether the mouse cursor is currently
3107 visible on a frame:
3109 @defun frame-pointer-visible-p &optional frame
3110 This predicate function returns non-@code{nil} if the mouse pointer
3111 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
3112 @var{frame} omitted or @code{nil} means the selected frame.  This is
3113 useful when @code{make-pointer-invisible} is set to @code{t}: it
3114 allows you to know if the pointer has been hidden.
3115 @xref{Mouse Avoidance,,,emacs, The Emacs Manual}.
3116 @end defun
3118 @need 3000
3120 @node Pop-Up Menus
3121 @section Pop-Up Menus
3122 @cindex menus, popup
3124   A Lisp program can pop up a menu so that the user can choose an
3125 alternative with the mouse.  On a text terminal, if the mouse is not
3126 available, the user can choose an alternative using the keyboard
3127 motion keys---@kbd{C-n}, @kbd{C-p}, or up- and down-arrow keys.
3129 @defun x-popup-menu position menu
3130 This function displays a pop-up menu and returns an indication of
3131 what selection the user makes.
3133 The argument @var{position} specifies where on the screen to put the
3134 top left corner of the menu.  It can be either a mouse button event
3135 (which says to put the menu where the user actuated the button) or a
3136 list of this form:
3138 @example
3139 ((@var{xoffset} @var{yoffset}) @var{window})
3140 @end example
3142 @noindent
3143 where @var{xoffset} and @var{yoffset} are coordinates, measured in
3144 pixels, counting from the top left corner of @var{window}.  @var{window}
3145 may be a window or a frame.
3147 If @var{position} is @code{t}, it means to use the current mouse
3148 position (or the top-left corner of the frame if the mouse is not
3149 available on a text terminal).  If @var{position} is @code{nil}, it
3150 means to precompute the key binding equivalents for the keymaps
3151 specified in @var{menu}, without actually displaying or popping up the
3152 menu.
3154 The argument @var{menu} says what to display in the menu.  It can be a
3155 keymap or a list of keymaps (@pxref{Menu Keymaps}).  In this case, the
3156 return value is the list of events corresponding to the user's choice.
3157 This list has more than one element if the choice occurred in a
3158 submenu.  (Note that @code{x-popup-menu} does not actually execute the
3159 command bound to that sequence of events.)  On text terminals and
3160 toolkits that support menu titles, the title is taken from the prompt
3161 string of @var{menu} if @var{menu} is a keymap, or from the prompt
3162 string of the first keymap in @var{menu} if it is a list of keymaps
3163 (@pxref{Defining Menus}).
3165 Alternatively, @var{menu} can have the following form:
3167 @example
3168 (@var{title} @var{pane1} @var{pane2}...)
3169 @end example
3171 @noindent
3172 where each pane is a list of form
3174 @example
3175 (@var{title} @var{item1} @var{item2}...)
3176 @end example
3178 Each @var{item} should be a cons cell, @code{(@var{line} . @var{value})},
3179 where @var{line} is a string and @var{value} is the value to return if
3180 that @var{line} is chosen.  Unlike in a menu keymap, a @code{nil}
3181 @var{value} does not make the menu item non-selectable.
3182 Alternatively, each @var{item} can be a string rather than a cons
3183 cell; this makes a non-selectable menu item.
3185 If the user gets rid of the menu without making a valid choice, for
3186 instance by clicking the mouse away from a valid choice or by typing
3187 @kbd{C-g}, then this normally results in a quit and
3188 @code{x-popup-menu} does not return.  But if @var{position} is a mouse
3189 button event (indicating that the user invoked the menu with the
3190 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
3191 @end defun
3193   @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
3194 if you could do the job with a prefix key defined with a menu keymap.
3195 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
3196 a} can see the individual items in that menu and provide help for them.
3197 If instead you implement the menu by defining a command that calls
3198 @code{x-popup-menu}, the help facilities cannot know what happens inside
3199 that command, so they cannot give any help for the menu's items.
3201   The menu bar mechanism, which lets you switch between submenus by
3202 moving the mouse, cannot look within the definition of a command to see
3203 that it calls @code{x-popup-menu}.  Therefore, if you try to implement a
3204 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
3205 an integrated fashion.  This is why all menu bar submenus are
3206 implemented with menu keymaps within the parent menu, and never with
3207 @code{x-popup-menu}.  @xref{Menu Bar}.
3209   If you want a menu bar submenu to have contents that vary, you should
3210 still use a menu keymap to implement it.  To make the contents vary, add
3211 a hook function to @code{menu-bar-update-hook} to update the contents of
3212 the menu keymap as necessary.
3214 @node Dialog Boxes
3215 @section Dialog Boxes
3216 @cindex dialog boxes
3218   A dialog box is a variant of a pop-up menu---it looks a little
3219 different, it always appears in the center of a frame, and it has just
3220 one level and one or more buttons.  The main use of dialog boxes is
3221 for asking questions that the user can answer with ``yes'', ``no'',
3222 and a few other alternatives.  With a single button, they can also
3223 force the user to acknowledge important information.  The functions
3224 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
3225 keyboard, when called from commands invoked by mouse clicks.
3227 @defun x-popup-dialog position contents &optional header
3228 This function displays a pop-up dialog box and returns an indication of
3229 what selection the user makes.  The argument @var{contents} specifies
3230 the alternatives to offer; it has this format:
3232 @example
3233 (@var{title} (@var{string} . @var{value})@dots{})
3234 @end example
3236 @noindent
3237 which looks like the list that specifies a single pane for
3238 @code{x-popup-menu}.
3240 The return value is @var{value} from the chosen alternative.
3242 As for @code{x-popup-menu}, an element of the list may be just a
3243 string instead of a cons cell @code{(@var{string} . @var{value})}.
3244 That makes a box that cannot be selected.
3246 If @code{nil} appears in the list, it separates the left-hand items from
3247 the right-hand items; items that precede the @code{nil} appear on the
3248 left, and items that follow the @code{nil} appear on the right.  If you
3249 don't include a @code{nil} in the list, then approximately half the
3250 items appear on each side.
3252 Dialog boxes always appear in the center of a frame; the argument
3253 @var{position} specifies which frame.  The possible values are as in
3254 @code{x-popup-menu}, but the precise coordinates or the individual
3255 window don't matter; only the frame matters.
3257 If @var{header} is non-@code{nil}, the frame title for the box is
3258 @samp{Information}, otherwise it is @samp{Question}.  The former is used
3259 for @code{message-box} (@pxref{message-box}).  (On text terminals, the
3260 box title is not displayed.)
3262 In some configurations, Emacs cannot display a real dialog box; so
3263 instead it displays the same items in a pop-up menu in the center of the
3264 frame.
3266 If the user gets rid of the dialog box without making a valid choice,
3267 for instance using the window manager, then this produces a quit and
3268 @code{x-popup-dialog} does not return.
3269 @end defun
3271 @node Pointer Shape
3272 @section Pointer Shape
3273 @cindex pointer shape
3274 @cindex mouse pointer shape
3276   You can specify the mouse pointer style for particular text or
3277 images using the @code{pointer} text property, and for images with the
3278 @code{:pointer} and @code{:map} image properties.  The values you can
3279 use in these properties are @code{text} (or @code{nil}), @code{arrow},
3280 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
3281 @code{hourglass}.  @code{text} stands for the usual mouse pointer
3282 style used over text.
3284   Over void parts of the window (parts that do not correspond to any
3285 of the buffer contents), the mouse pointer usually uses the
3286 @code{arrow} style, but you can specify a different style (one of
3287 those above) by setting @code{void-text-area-pointer}.
3289 @defopt void-text-area-pointer
3290 This variable specifies the mouse pointer style for void text areas.
3291 These include the areas after the end of a line or below the last line
3292 in the buffer.  The default is to use the @code{arrow} (non-text)
3293 pointer style.
3294 @end defopt
3296   When using X, you can specify what the @code{text} pointer style
3297 really looks like by setting the variable @code{x-pointer-shape}.
3299 @defvar x-pointer-shape
3300 This variable specifies the pointer shape to use ordinarily in the
3301 Emacs frame, for the @code{text} pointer style.
3302 @end defvar
3304 @defvar x-sensitive-text-pointer-shape
3305 This variable specifies the pointer shape to use when the mouse
3306 is over mouse-sensitive text.
3307 @end defvar
3309   These variables affect newly created frames.  They do not normally
3310 affect existing frames; however, if you set the mouse color of a
3311 frame, that also installs the current value of those two variables.
3312 @xref{Font and Color Parameters}.
3314   The values you can use, to specify either of these pointer shapes, are
3315 defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
3316 @key{RET} x-pointer @key{RET}} to see a list of them.
3318 @node Window System Selections
3319 @section Window System Selections
3320 @cindex selection (for window systems)
3321 @cindex clipboard
3322 @cindex primary selection
3323 @cindex secondary selection
3325   In window systems, such as X, data can be transferred between
3326 different applications by means of @dfn{selections}.  X defines an
3327 arbitrary number of @dfn{selection types}, each of which can store its
3328 own data; however, only three are commonly used: the @dfn{clipboard},
3329 @dfn{primary selection}, and @dfn{secondary selection}.  Other window
3330 systems support only the clipboard.  @xref{Cut and Paste,, Cut and
3331 Paste, emacs, The GNU Emacs Manual}, for Emacs commands that make use
3332 of these selections.  This section documents the low-level functions
3333 for reading and setting window-system selections.
3335 @deffn Command gui-set-selection type data
3336 This function sets a window-system selection.  It takes two arguments:
3337 a selection type @var{type}, and the value to assign to it, @var{data}.
3339 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
3340 @code{SECONDARY} or @code{CLIPBOARD}.  These are symbols with
3341 upper-case names, in accord with X Window System conventions.  If
3342 @var{type} is @code{nil}, that stands for @code{PRIMARY}.
3344 If @var{data} is @code{nil}, it means to clear out the selection.
3345 Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
3346 of two integers or list of two integers), an overlay, or a cons of two
3347 markers pointing to the same buffer.  An overlay or a pair of markers
3348 stands for text in the overlay or between the markers.  The argument
3349 @var{data} may also be a vector of valid non-vector selection values.
3351 This function returns @var{data}.
3352 @end deffn
3354 @defun gui-get-selection &optional type data-type
3355 This function accesses selections set up by Emacs or by other
3356 programs.  It takes two optional arguments, @var{type} and
3357 @var{data-type}.  The default for @var{type}, the selection type, is
3358 @code{PRIMARY}.
3360 The @var{data-type} argument specifies the form of data conversion to
3361 use, to convert the raw data obtained from another program into Lisp
3362 data.  Meaningful values include @code{TEXT}, @code{STRING},
3363 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
3364 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
3365 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
3366 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
3367 @code{INTEGER}.  (These are symbols with upper-case names in accord
3368 with X conventions.)  The default for @var{data-type} is
3369 @code{STRING}.  Window systems other than X usually support only a
3370 small subset of these types, in addition to @code{STRING}.
3371 @end defun
3373 @defopt selection-coding-system
3374 This variable specifies the coding system to use when reading and
3375 writing selections or the clipboard.  @xref{Coding
3376 Systems}.  The default is @code{compound-text-with-extensions}, which
3377 converts to the text representation that X11 normally uses.
3378 @end defopt
3380 @cindex clipboard support (for MS-Windows)
3381 When Emacs runs on MS-Windows, it does not implement X selections in
3382 general, but it does support the clipboard.  @code{gui-get-selection}
3383 and @code{gui-set-selection} on MS-Windows support the text data type
3384 only; if the clipboard holds other types of data, Emacs treats the
3385 clipboard as empty.  The supported data type is @code{STRING}.
3387 For backward compatibility, there are obsolete aliases
3388 @code{x-get-selection} and @code{x-set-selection}, which were the
3389 names of @code{gui-get-selection} and @code{gui-set-selection} before
3390 Emacs 25.1.
3392 @node Drag and Drop
3393 @section Drag and Drop
3394 @cindex drag and drop
3396 @vindex x-dnd-test-function
3397 @vindex x-dnd-known-types
3398   When a user drags something from another application over Emacs, that other
3399 application expects Emacs to tell it if Emacs can handle the data that is
3400 dragged.  The variable @code{x-dnd-test-function} is used by Emacs to determine
3401 what to reply.  The default value is @code{x-dnd-default-test-function}
3402 which accepts drops if the type of the data to be dropped is present in
3403 @code{x-dnd-known-types}.  You can customize @code{x-dnd-test-function} and/or
3404 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
3405 on some other criteria.
3407 @vindex x-dnd-types-alist
3408   If you want to change the way Emacs handles drop of different types
3409 or add a new type, customize @code{x-dnd-types-alist}.  This requires
3410 detailed knowledge of what types other applications use for drag and
3411 drop.
3413 @vindex dnd-protocol-alist
3414   When an URL is dropped on Emacs it may be a file, but it may also be
3415 another URL type (ftp, http, etc.).  Emacs first checks
3416 @code{dnd-protocol-alist} to determine what to do with the URL@.  If
3417 there is no match there and if @code{browse-url-browser-function} is
3418 an alist, Emacs looks for a match there.  If no match is found the
3419 text for the URL is inserted.  If you want to alter Emacs behavior,
3420 you can customize these variables.
3422 @node Color Names
3423 @section Color Names
3425 @cindex color names
3426 @cindex specify color
3427 @cindex numerical RGB color specification
3428   A color name is text (usually in a string) that specifies a color.
3429 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
3430 are allowed; use @kbd{M-x list-colors-display} to see a list of
3431 defined names.  You can also specify colors numerically in forms such
3432 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
3433 @var{r} specifies the red level, @var{g} specifies the green level,
3434 and @var{b} specifies the blue level.  You can use either one, two,
3435 three, or four hex digits for @var{r}; then you must use the same
3436 number of hex digits for all @var{g} and @var{b} as well, making
3437 either 3, 6, 9 or 12 hex digits in all.  (See the documentation of the
3438 X Window System for more details about numerical RGB specification of
3439 colors.)
3441   These functions provide a way to determine which color names are
3442 valid, and what they look like.  In some cases, the value depends on the
3443 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
3444 meaning of the term ``selected frame''.
3446   To read user input of color names with completion, use
3447 @code{read-color} (@pxref{High-Level Completion, read-color}).
3449 @defun color-defined-p color &optional frame
3450 This function reports whether a color name is meaningful.  It returns
3451 @code{t} if so; otherwise, @code{nil}.  The argument @var{frame} says
3452 which frame's display to ask about; if @var{frame} is omitted or
3453 @code{nil}, the selected frame is used.
3455 Note that this does not tell you whether the display you are using
3456 really supports that color.  When using X, you can ask for any defined
3457 color on any kind of display, and you will get some result---typically,
3458 the closest it can do.  To determine whether a frame can really display
3459 a certain color, use @code{color-supported-p} (see below).
3461 @findex x-color-defined-p
3462 This function used to be called @code{x-color-defined-p},
3463 and that name is still supported as an alias.
3464 @end defun
3466 @defun defined-colors &optional frame
3467 This function returns a list of the color names that are defined
3468 and supported on frame @var{frame} (default, the selected frame).
3469 If @var{frame} does not support colors, the value is @code{nil}.
3471 @findex x-defined-colors
3472 This function used to be called @code{x-defined-colors},
3473 and that name is still supported as an alias.
3474 @end defun
3476 @defun color-supported-p color &optional frame background-p
3477 This returns @code{t} if @var{frame} can really display the color
3478 @var{color} (or at least something close to it).  If @var{frame} is
3479 omitted or @code{nil}, the question applies to the selected frame.
3481 Some terminals support a different set of colors for foreground and
3482 background.  If @var{background-p} is non-@code{nil}, that means you are
3483 asking whether @var{color} can be used as a background; otherwise you
3484 are asking whether it can be used as a foreground.
3486 The argument @var{color} must be a valid color name.
3487 @end defun
3489 @defun color-gray-p color &optional frame
3490 This returns @code{t} if @var{color} is a shade of gray, as defined on
3491 @var{frame}'s display.  If @var{frame} is omitted or @code{nil}, the
3492 question applies to the selected frame.  If @var{color} is not a valid
3493 color name, this function returns @code{nil}.
3494 @end defun
3496 @defun color-values color &optional frame
3497 @cindex rgb value
3498 This function returns a value that describes what @var{color} should
3499 ideally look like on @var{frame}.  If @var{color} is defined, the
3500 value is a list of three integers, which give the amount of red, the
3501 amount of green, and the amount of blue.  Each integer ranges in
3502 principle from 0 to 65535, but some displays may not use the full
3503 range.  This three-element list is called the @dfn{rgb values} of the
3504 color.
3506 If @var{color} is not defined, the value is @code{nil}.
3508 @example
3509 (color-values "black")
3510      @result{} (0 0 0)
3511 (color-values "white")
3512      @result{} (65280 65280 65280)
3513 (color-values "red")
3514      @result{} (65280 0 0)
3515 (color-values "pink")
3516      @result{} (65280 49152 51968)
3517 (color-values "hungry")
3518      @result{} nil
3519 @end example
3521 The color values are returned for @var{frame}'s display.  If
3522 @var{frame} is omitted or @code{nil}, the information is returned for
3523 the selected frame's display.  If the frame cannot display colors, the
3524 value is @code{nil}.
3526 @findex x-color-values
3527 This function used to be called @code{x-color-values},
3528 and that name is still supported as an alias.
3529 @end defun
3531 @node Text Terminal Colors
3532 @section Text Terminal Colors
3533 @cindex colors on text terminals
3535   Text terminals usually support only a small number of colors, and
3536 the computer uses small integers to select colors on the terminal.
3537 This means that the computer cannot reliably tell what the selected
3538 color looks like; instead, you have to inform your application which
3539 small integers correspond to which colors.  However, Emacs does know
3540 the standard set of colors and will try to use them automatically.
3542   The functions described in this section control how terminal colors
3543 are used by Emacs.
3545   Several of these functions use or return @dfn{rgb values}, described
3546 in @ref{Color Names}.
3548   These functions accept a display (either a frame or the name of a
3549 terminal) as an optional argument.  We hope in the future to make
3550 Emacs support different colors on different text terminals; then this
3551 argument will specify which terminal to operate on (the default being
3552 the selected frame's terminal; @pxref{Input Focus}).  At present,
3553 though, the @var{frame} argument has no effect.
3555 @defun tty-color-define name number &optional rgb frame
3556 This function associates the color name @var{name} with
3557 color number @var{number} on the terminal.
3559 The optional argument @var{rgb}, if specified, is an rgb value, a list
3560 of three numbers that specify what the color actually looks like.
3561 If you do not specify @var{rgb}, then this color cannot be used by
3562 @code{tty-color-approximate} to approximate other colors, because
3563 Emacs will not know what it looks like.
3564 @end defun
3566 @defun tty-color-clear &optional frame
3567 This function clears the table of defined colors for a text terminal.
3568 @end defun
3570 @defun tty-color-alist &optional frame
3571 This function returns an alist recording the known colors supported by
3572 a text terminal.
3574 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
3575 or @code{(@var{name} @var{number})}.  Here, @var{name} is the color
3576 name, @var{number} is the number used to specify it to the terminal.
3577 If present, @var{rgb} is a list of three color values (for red, green,
3578 and blue) that says what the color actually looks like.
3579 @end defun
3581 @defun tty-color-approximate rgb &optional frame
3582 This function finds the closest color, among the known colors
3583 supported for @var{display}, to that described by the rgb value
3584 @var{rgb} (a list of color values).  The return value is an element of
3585 @code{tty-color-alist}.
3586 @end defun
3588 @defun tty-color-translate color &optional frame
3589 This function finds the closest color to @var{color} among the known
3590 colors supported for @var{display} and returns its index (an integer).
3591 If the name @var{color} is not defined, the value is @code{nil}.
3592 @end defun
3594 @node Resources
3595 @section X Resources
3597 This section describes some of the functions and variables for
3598 querying and using X resources, or their equivalent on your operating
3599 system.  @xref{X Resources,, X Resources, emacs, The GNU Emacs
3600 Manual}, for more information about X resources.
3602 @defun x-get-resource attribute class &optional component subclass
3603 The function @code{x-get-resource} retrieves a resource value from the X
3604 Window defaults database.
3606 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
3607 This function searches using a key of the form
3608 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
3609 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
3610 the class.
3612 The optional arguments @var{component} and @var{subclass} add to the key
3613 and the class, respectively.  You must specify both of them or neither.
3614 If you specify them, the key is
3615 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
3616 @samp{Emacs.@var{class}.@var{subclass}}.
3617 @end defun
3619 @defvar x-resource-class
3620 This variable specifies the application name that @code{x-get-resource}
3621 should look up.  The default value is @code{"Emacs"}.  You can examine X
3622 resources for other application names by binding this
3623 variable to some other string, around a call to @code{x-get-resource}.
3624 @end defvar
3626 @defvar x-resource-name
3627 This variable specifies the instance name that @code{x-get-resource}
3628 should look up.  The default value is the name Emacs was invoked with,
3629 or the value specified with the @samp{-name} or @samp{-rn} switches.
3630 @end defvar
3632 To illustrate some of the above, suppose that you have the line:
3634 @example
3635 xterm.vt100.background: yellow
3636 @end example
3638 @noindent
3639 in your X resources file (whose name is usually @file{~/.Xdefaults}
3640 or @file{~/.Xresources}).  Then:
3642 @example
3643 @group
3644 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
3645   (x-get-resource "vt100.background" "VT100.Background"))
3646      @result{} "yellow"
3647 @end group
3648 @group
3649 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
3650   (x-get-resource "background" "VT100" "vt100" "Background"))
3651      @result{} "yellow"
3652 @end group
3653 @end example
3655 @defvar inhibit-x-resources
3656 If this variable is non-@code{nil}, Emacs does not look up X
3657 resources, and X resources do not have any effect when creating new
3658 frames.
3659 @end defvar
3661 @node Display Feature Testing
3662 @section Display Feature Testing
3663 @cindex display feature testing
3665   The functions in this section describe the basic capabilities of a
3666 particular display.  Lisp programs can use them to adapt their behavior
3667 to what the display can do.  For example, a program that ordinarily uses
3668 a popup menu could use the minibuffer if popup menus are not supported.
3670   The optional argument @var{display} in these functions specifies which
3671 display to ask the question about.  It can be a display name, a frame
3672 (which designates the display that frame is on), or @code{nil} (which
3673 refers to the selected frame's display, @pxref{Input Focus}).
3675   @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
3676 obtain information about displays.
3678 @defun display-popup-menus-p &optional display
3679 This function returns @code{t} if popup menus are supported on
3680 @var{display}, @code{nil} if not.  Support for popup menus requires
3681 that the mouse be available, since the menu is popped up by clicking
3682 the mouse on some portion of the Emacs display.
3683 @end defun
3685 @defun display-graphic-p &optional display
3686 This function returns @code{t} if @var{display} is a graphic display
3687 capable of displaying several frames and several different fonts at
3688 once.  This is true for displays that use a window system such as X,
3689 and false for text terminals.
3690 @end defun
3692 @defun display-mouse-p &optional display
3693 @cindex mouse, availability
3694 This function returns @code{t} if @var{display} has a mouse available,
3695 @code{nil} if not.
3696 @end defun
3698 @defun display-color-p &optional display
3699 @findex x-display-color-p
3700 This function returns @code{t} if the screen is a color screen.
3701 It used to be called @code{x-display-color-p}, and that name
3702 is still supported as an alias.
3703 @end defun
3705 @defun display-grayscale-p &optional display
3706 This function returns @code{t} if the screen can display shades of gray.
3707 (All color displays can do this.)
3708 @end defun
3710 @defun display-supports-face-attributes-p attributes &optional display
3711 @anchor{Display Face Attribute Testing}
3712 This function returns non-@code{nil} if all the face attributes in
3713 @var{attributes} are supported (@pxref{Face Attributes}).
3715 The definition of ``supported'' is somewhat heuristic, but basically
3716 means that a face containing all the attributes in @var{attributes},
3717 when merged with the default face for display, can be represented in a
3718 way that's
3720 @enumerate
3721 @item
3722 different in appearance than the default face, and
3724 @item
3725 close in spirit to what the attributes specify, if not exact.
3726 @end enumerate
3728 Point (2) implies that a @code{:weight black} attribute will be
3729 satisfied by any display that can display bold, as will
3730 @code{:foreground "yellow"} as long as some yellowish color can be
3731 displayed, but @code{:slant italic} will @emph{not} be satisfied by
3732 the tty display code's automatic substitution of a dim face for
3733 italic.
3734 @end defun
3736 @defun display-selections-p &optional display
3737 This function returns @code{t} if @var{display} supports selections.
3738 Windowed displays normally support selections, but they may also be
3739 supported in some other cases.
3740 @end defun
3742 @defun display-images-p &optional display
3743 This function returns @code{t} if @var{display} can display images.
3744 Windowed displays ought in principle to handle images, but some
3745 systems lack the support for that.  On a display that does not support
3746 images, Emacs cannot display a tool bar.
3747 @end defun
3749 @defun display-screens &optional display
3750 This function returns the number of screens associated with the display.
3751 @end defun
3753 @defun display-pixel-height &optional display
3754 This function returns the height of the screen in pixels.
3755 On a character terminal, it gives the height in characters.
3757 For graphical terminals, note that on multi-monitor setups this
3758 refers to the pixel height for all physical monitors associated with
3759 @var{display}.  @xref{Multiple Terminals}.
3760 @end defun
3762 @defun display-pixel-width &optional display
3763 This function returns the width of the screen in pixels.
3764 On a character terminal, it gives the width in characters.
3766 For graphical terminals, note that on multi-monitor setups this
3767 refers to the pixel width for all physical monitors associated with
3768 @var{display}.  @xref{Multiple Terminals}.
3769 @end defun
3771 @defun display-mm-height &optional display
3772 This function returns the height of the screen in millimeters,
3773 or @code{nil} if Emacs cannot get that information.
3775 For graphical terminals, note that on multi-monitor setups this
3776 refers to the height for all physical monitors associated with
3777 @var{display}.  @xref{Multiple Terminals}.
3778 @end defun
3780 @defun display-mm-width &optional display
3781 This function returns the width of the screen in millimeters,
3782 or @code{nil} if Emacs cannot get that information.
3784 For graphical terminals, note that on multi-monitor setups this
3785 refers to the width for all physical monitors associated with
3786 @var{display}.  @xref{Multiple Terminals}.
3787 @end defun
3789 @defopt display-mm-dimensions-alist
3790 This variable allows the user to specify the dimensions of graphical
3791 displays returned by @code{display-mm-height} and
3792 @code{display-mm-width} in case the system provides incorrect values.
3793 @end defopt
3795 @cindex backing store
3796 @defun display-backing-store &optional display
3797 This function returns the backing store capability of the display.
3798 Backing store means recording the pixels of windows (and parts of
3799 windows) that are not exposed, so that when exposed they can be
3800 displayed very quickly.
3802 Values can be the symbols @code{always}, @code{when-mapped}, or
3803 @code{not-useful}.  The function can also return @code{nil}
3804 when the question is inapplicable to a certain kind of display.
3805 @end defun
3807 @cindex SaveUnder feature
3808 @defun display-save-under &optional display
3809 This function returns non-@code{nil} if the display supports the
3810 SaveUnder feature.  That feature is used by pop-up windows
3811 to save the pixels they obscure, so that they can pop down
3812 quickly.
3813 @end defun
3815 @defun display-planes &optional display
3816 This function returns the number of planes the display supports.
3817 This is typically the number of bits per pixel.
3818 For a tty display, it is log to base two of the number of colors supported.
3819 @end defun
3821 @defun display-visual-class &optional display
3822 This function returns the visual class for the screen.  The value is
3823 one of the symbols @code{static-gray} (a limited, unchangeable number
3824 of grays), @code{gray-scale} (a full range of grays),
3825 @code{static-color} (a limited, unchangeable number of colors),
3826 @code{pseudo-color} (a limited number of colors), @code{true-color} (a
3827 full range of colors), and @code{direct-color} (a full range of
3828 colors).
3829 @end defun
3831 @defun display-color-cells &optional display
3832 This function returns the number of color cells the screen supports.
3833 @end defun
3835   These functions obtain additional information about the window
3836 system in use where Emacs shows the specified @var{display}.  (Their
3837 names begin with @code{x-} for historical reasons.)
3839 @defun x-server-version &optional display
3840 This function returns the list of version numbers of the GUI window
3841 system running on @var{display}, such as the X server on GNU and Unix
3842 systems.  The value is a list of three integers: the major and minor
3843 version numbers of the protocol, and the distributor-specific release
3844 number of the window system software itself.  On GNU and Unix systems,
3845 these are normally the version of the X protocol and the
3846 distributor-specific release number of the X server software.  On
3847 MS-Windows, this is the version of the Windows OS.
3848 @end defun
3850 @defun x-server-vendor &optional display
3851 This function returns the vendor that provided the window system
3852 software (as a string).  On GNU and Unix systems this really means
3853 whoever distributes the X server.  On MS-Windows this is the vendor ID
3854 string of the Windows OS (Microsoft).
3856 When the developers of X labeled software distributors as
3857 ``vendors'', they showed their false assumption that no system could
3858 ever be developed and distributed noncommercially.
3859 @end defun
3861 @ignore
3862 @defvar x-no-window-manager
3863 This variable's value is @code{t} if no X window manager is in use.
3864 @end defvar
3865 @end ignore