Conflate Qnil and Qunbound for `symbol-function'.
[emacs.git] / doc / lispref / frames.texi
blob846dfbaf17cfcbcd8001276fed5f731c7fc75f41
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @node Frames
6 @chapter Frames
7 @cindex frame
9   A @dfn{frame} is a screen object that contains one or more Emacs
10 windows (@pxref{Windows}).  It is the kind of object called a
11 ``window'' in the terminology of graphical environments; but we can't
12 call it a ``window'' here, because Emacs uses that word in a different
13 way.  In Emacs Lisp, a @dfn{frame object} is a Lisp object that
14 represents a frame on the screen.  @xref{Frame Type}.
16   A frame initially contains a single main window and/or a minibuffer
17 window; you can subdivide the main window vertically or horizontally
18 into smaller windows.  @xref{Splitting Windows}.
20 @cindex terminal
21   A @dfn{terminal} is a display device capable of displaying one or
22 more Emacs frames.  In Emacs Lisp, a @dfn{terminal object} is a Lisp
23 object that represents a terminal.  @xref{Terminal Type}.
25 @cindex text terminal
26 @cindex graphical terminal
27 @cindex graphical display
28   There are two classes of terminals: @dfn{text terminals} and
29 @dfn{graphical terminals}.  Text terminals are non-graphics-capable
30 displays, including @command{xterm} and other terminal emulators.  On
31 a text terminal, each Emacs frame occupies the terminal's entire
32 screen; although you can create additional frames and switch between
33 them, the terminal only shows one frame at a time.  Graphical
34 terminals, on the other hand, are managed by graphical display systems
35 such as the X Window System, which allow Emacs to show multiple frames
36 simultaneously on the same display.
38   On GNU and Unix systems, you can create additional frames on any
39 available terminal, within a single Emacs session, regardless of
40 whether Emacs was started on a text or graphical terminal.  Emacs can
41 display on both graphical and text terminals simultaneously.  This
42 comes in handy, for instance, when you connect to the same session
43 from several remote locations.  @xref{Multiple Terminals}.
45 @defun framep object
46 This predicate returns a non-@code{nil} value if @var{object} is a
47 frame, and @code{nil} otherwise.  For a frame, the value indicates which
48 kind of display the frame uses:
50 @table @code
51 @item t
52 The frame is displayed on a text terminal.
53 @item x
54 The frame is displayed on an X graphical terminal.
55 @item w32
56 The frame is displayed on a MS-Windows graphical terminal.
57 @item ns
58 The frame is displayed on a GNUstep or Macintosh Cocoa graphical
59 terminal.
60 @item pc
61 The frame is displayed on an MS-DOS terminal.
62 @end table
63 @end defun
65 @defun frame-terminal &optional frame
66 This function returns the terminal object that displays @var{frame}.
67 If @var{frame} is @code{nil} or unspecified, it defaults to the
68 selected frame.
69 @end defun
71 @defun terminal-live-p object
72 This predicate returns a non-@code{nil} value if @var{object} is a
73 terminal that is live (i.e.@: not deleted), and @code{nil} otherwise.
74 For live terminals, the return value indicates what kind of frames are
75 displayed on that terminal; the list of possible values is the same as
76 for @code{framep} above.
77 @end defun
79 @menu
80 * Creating Frames::             Creating additional frames.
81 * Multiple Terminals::          Displaying on several different devices.
82 * Frame Parameters::            Controlling frame size, position, font, etc.
83 * Terminal Parameters::         Parameters common for all frames on terminal.
84 * Frame Titles::                Automatic updating of frame titles.
85 * Deleting Frames::             Frames last until explicitly deleted.
86 * Finding All Frames::          How to examine all existing frames.
87 * Minibuffers and Frames::      How a frame finds the minibuffer to use.
88 * Input Focus::                 Specifying the selected frame.
89 * Visibility of Frames::        Frames may be visible or invisible, or icons.
90 * Raising and Lowering::        Raising a frame makes it hide other windows;
91                                   lowering it makes the others hide it.
92 * Frame Configurations::        Saving the state of all frames.
93 * Mouse Tracking::              Getting events that say when the mouse moves.
94 * Mouse Position::              Asking where the mouse is, or moving it.
95 * Pop-Up Menus::                Displaying a menu for the user to select from.
96 * Dialog Boxes::                Displaying a box to ask yes or no.
97 * Pointer Shape::               Specifying the shape of the mouse pointer.
98 * Window System Selections::    Transferring text to and from other X clients.
99 * Drag and Drop::               Internals of Drag-and-Drop implementation.
100 * Color Names::                 Getting the definitions of color names.
101 * Text Terminal Colors::        Defining colors for text terminals.
102 * Resources::                   Getting resource values from the server.
103 * Display Feature Testing::     Determining the features of a terminal.
104 @end menu
106 @node Creating Frames
107 @section Creating Frames
109 To create a new frame, call the function @code{make-frame}.
111 @deffn Command make-frame &optional alist
112 This function creates and returns a new frame, displaying the current
113 buffer.
115 The @var{alist} argument is an alist that specifies frame parameters
116 for the new frame.  @xref{Frame Parameters}.  If you specify the
117 @code{terminal} parameter in @var{alist}, the new frame is created on
118 that terminal.  Otherwise, if you specify the @code{window-system}
119 frame parameter in @var{alist}, that determines whether the frame
120 should be displayed on a text terminal or a graphical terminal.
121 @xref{Window Systems}.  If neither is specified, the new frame is
122 created in the same terminal as the selected frame.
124 Any parameters not mentioned in @var{alist} default to the values in
125 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
126 parameters not specified there default from the X resources or its
127 equivalent on your operating system (@pxref{X Resources,, X Resources,
128 emacs, The GNU Emacs Manual}).  After the frame is created, Emacs
129 applies any parameters listed in @code{frame-inherited-parameters}
130 (see below) and not present in the argument, taking the values from
131 the frame that was selected when @code{make-frame} was called.
133 This function itself does not make the new frame the selected frame.
134 @xref{Input Focus}.  The previously selected frame remains selected.
135 On graphical terminals, however, the windowing system may select the
136 new frame for its own reasons.
137 @end deffn
139 @defvar before-make-frame-hook
140 A normal hook run by @code{make-frame} before it creates the frame.
141 @end defvar
143 @defvar after-make-frame-functions
144 An abnormal hook run by @code{make-frame} after it creates the frame.
145 Each function in @code{after-make-frame-functions} receives one argument, the
146 frame just created.
147 @end defvar
149 @defvar frame-inherited-parameters
150 This variable specifies the list of frame parameters that a newly
151 created frame inherits from the currently selected frame.  For each
152 parameter (a symbol) that is an element in the list and is not present
153 in the argument to @code{make-frame}, the function sets the value of
154 that parameter in the created frame to its value in the selected
155 frame.
156 @end defvar
158 @node Multiple Terminals
159 @section Multiple Terminals
160 @cindex multiple terminals
161 @cindex multi-tty
162 @cindex multiple X displays
163 @cindex displays, multiple
165   Emacs represents each terminal as a @dfn{terminal object} data type
166 (@pxref{Terminal Type}).  On GNU and Unix systems, Emacs can use
167 multiple terminals simultaneously in each session.  On other systems,
168 it can only use a single terminal.  Each terminal object has the
169 following attributes:
171 @itemize @bullet
172 @item
173 The name of the device used by the terminal (e.g.@: @samp{:0.0} or
174 @file{/dev/tty}).
176 @item
177 The terminal and keyboard coding systems used on the terminal.
178 @xref{Terminal I/O Encoding}.
180 @item
181 The kind of display associated with the terminal.  This is the symbol
182 returned by the function @code{terminal-live-p} (i.e.@: @code{x},
183 @code{t}, @code{w32}, @code{ns}, or @code{pc}).  @xref{Frames}.
185 @item
186 A list of terminal parameters.  @xref{Terminal Parameters}.
187 @end itemize
189   There is no primitive for creating terminal objects.  Emacs creates
190 them as needed, such as when you call @code{make-frame-on-display}
191 (described below).
193 @defun terminal-name &optional terminal
194 This function returns the file name of the device used by
195 @var{terminal}.  If @var{terminal} is omitted or @code{nil}, it
196 defaults to the selected frame's terminal.  @var{terminal} can also be
197 a frame, meaning that frame's terminal.
198 @end defun
200 @defun terminal-list
201 This function returns a list of all live terminal objects.
202 @end defun
204 @defun get-device-terminal device
205 This function returns a terminal whose device name is given by
206 @var{device}.  If @var{device} is a string, it can be either the file
207 name of a terminal device, or the name of an X display of the form
208 @samp{@var{host}:@var{server}.@var{screen}}.  If @var{device} is a
209 frame, this function returns that frame's terminal; @code{nil} means
210 the selected frame.  Finally, if @var{device} is a terminal object
211 that represents a live terminal, that terminal is returned.  The
212 function signals an error if its argument is none of the above.
213 @end defun
215 @defun delete-terminal &optional terminal force
216 This function deletes all frames on @var{terminal} and frees the
217 resources used by it.  It runs the abnormal hook
218 @code{delete-terminal-functions}, passing @var{terminal} as the
219 argument to each function.
221 If @var{terminal} is omitted or @code{nil}, it defaults to the
222 selected frame's terminal.  @var{terminal} can also be a frame,
223 meaning that frame's terminal.
225 Normally, this function signals an error if you attempt to delete the
226 sole active terminal, but if @var{force} is non-@code{nil}, you are
227 allowed to do so.  Emacs automatically calls this function when the
228 last frame on a terminal is deleted (@pxref{Deleting Frames}).
229 @end defun
231 @defvar delete-terminal-functions
232 An abnormal hook run by @code{delete-terminal}.  Each function
233 receives one argument, the @var{terminal} argument passed to
234 @code{delete-terminal}.  Due to technical details, the functions may
235 be called either just before the terminal is deleted, or just
236 afterwards.
237 @end defvar
239 @cindex terminal-local variables
240   A few Lisp variables are @dfn{terminal-local}; that is, they have a
241 separate binding for each terminal.  The binding in effect at any time
242 is the one for the terminal that the currently selected frame belongs
243 to.  These variables include @code{default-minibuffer-frame},
244 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
245 @code{system-key-alist}.  They are always terminal-local, and can
246 never be buffer-local (@pxref{Buffer-Local Variables}).
248   On GNU and Unix systems, each X display is a separate graphical
249 terminal.  When Emacs is started from within the X window system, it
250 uses the X display specified by the @env{DISPLAY} environment
251 variable, or by the @samp{--display} option (@pxref{Initial Options,,,
252 emacs, The GNU Emacs Manual}).  Emacs can connect to other X displays
253 via the command @code{make-frame-on-display}.  Each X display has its
254 own selected frame and its own minibuffer windows; however, only one
255 of those frames is ``@emph{the} selected frame'' at any given moment
256 (@pxref{Input Focus}).  Emacs can even connect to other text
257 terminals, by interacting with the @command{emacsclient} program.
258 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
260   A single X server can handle more than one display.  Each X display
261 has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
262 The first two parts, @var{host} and @var{server}, identify the X
263 server; the third part, @var{screen}, identifies a screen number on
264 that X server.  When you use two or more screens belonging to one
265 server, Emacs knows by the similarity in their names that they share a
266 single keyboard.
268   On some ``multi-monitor'' setups, a single X display outputs to more
269 than one physical monitor.  Currently, there is no way for Emacs to
270 distinguish between the different physical monitors.
272 @deffn Command make-frame-on-display display &optional parameters
273 This function creates and returns a new frame on @var{display}, taking
274 the other frame parameters from the alist @var{parameters}.
275 @var{display} should be the name of an X display (a string).
277 Before creating the frame, this function ensures that Emacs is ``set
278 up'' to display graphics.  For instance, if Emacs has not processed X
279 resources (e.g.@: if it was started on a text terminal), it does so at
280 this time.  In all other respects, this function behaves like
281 @code{make-frame} (@pxref{Creating Frames}).
282 @end deffn
284 @defun x-display-list
285 This function returns a list that indicates which X displays Emacs has
286 a connection to.  The elements of the list are strings, and each one
287 is a display name.
288 @end defun
290 @defun x-open-connection display &optional xrm-string must-succeed
291 This function opens a connection to the X display @var{display},
292 without creating a frame on that display.  Normally, Emacs Lisp
293 programs need not call this function, as @code{make-frame-on-display}
294 calls it automatically.  The only reason for calling it is to check
295 whether communication can be established with a given X display.
297 The optional argument @var{xrm-string}, if not @code{nil}, is a string
298 of resource names and values, in the same format used in the
299 @file{.Xresources} file.  @xref{X Resources,, X Resources, emacs, The
300 GNU Emacs Manual}.  These values apply to all Emacs frames created on
301 this display, overriding the resource values recorded in the X server.
302 Here's an example of what this string might look like:
304 @example
305 "*BorderWidth: 3\n*InternalBorder: 2\n"
306 @end example
308 If @var{must-succeed} is non-@code{nil}, failure to open the connection
309 terminates Emacs.  Otherwise, it is an ordinary Lisp error.
310 @end defun
312 @defun x-close-connection display
313 This function closes the connection to display @var{display}.  Before
314 you can do this, you must first delete all the frames that were open
315 on that display (@pxref{Deleting Frames}).
316 @end defun
318 @node Frame Parameters
319 @section Frame Parameters
320 @cindex frame parameters
322   A frame has many parameters that control its appearance and behavior.
323 Just what parameters a frame has depends on what display mechanism it
324 uses.
326   Frame parameters exist mostly for the sake of graphical displays.
327 Most frame parameters have no effect when applied to a frame on a text
328 terminal; only the @code{height}, @code{width}, @code{name},
329 @code{title}, @code{menu-bar-lines}, @code{buffer-list} and
330 @code{buffer-predicate} parameters do something special.  If the
331 terminal supports colors, the parameters @code{foreground-color},
332 @code{background-color}, @code{background-mode} and
333 @code{display-type} are also meaningful.  If the terminal supports
334 frame transparency, the parameter @code{alpha} is also meaningful.
336 @menu
337 * Parameter Access::       How to change a frame's parameters.
338 * Initial Parameters::     Specifying frame parameters when you make a frame.
339 * Window Frame Parameters:: List of frame parameters for window systems.
340 * Size and Position::      Changing the size and position of a frame.
341 * Geometry::               Parsing geometry specifications.
342 @end menu
344 @node Parameter Access
345 @subsection Access to Frame Parameters
347 These functions let you read and change the parameter values of a
348 frame.
350 @defun frame-parameter frame parameter
351 This function returns the value of the parameter @var{parameter} (a
352 symbol) of @var{frame}.  If @var{frame} is @code{nil}, it returns the
353 selected frame's parameter.  If @var{frame} has no setting for
354 @var{parameter}, this function returns @code{nil}.
355 @end defun
357 @defun frame-parameters &optional frame
358 The function @code{frame-parameters} returns an alist listing all the
359 parameters of @var{frame} and their values.  If @var{frame} is
360 @code{nil} or omitted, this returns the selected frame's parameters
361 @end defun
363 @defun modify-frame-parameters frame alist
364 This function alters the parameters of frame @var{frame} based on the
365 elements of @var{alist}.  Each element of @var{alist} has the form
366 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
367 parameter.  If you don't mention a parameter in @var{alist}, its value
368 doesn't change.  If @var{frame} is @code{nil}, it defaults to the selected
369 frame.
370 @end defun
372 @defun set-frame-parameter frame parm value
373 This function sets the frame parameter @var{parm} to the specified
374 @var{value}.  If @var{frame} is @code{nil}, it defaults to the
375 selected frame.
376 @end defun
378 @defun modify-all-frames-parameters alist
379 This function alters the frame parameters of all existing frames
380 according to @var{alist}, then modifies @code{default-frame-alist}
381 (and, if necessary, @code{initial-frame-alist}) to apply the same
382 parameter values to frames that will be created henceforth.
383 @end defun
385 @node Initial Parameters
386 @subsection Initial Frame Parameters
388 You can specify the parameters for the initial startup frame by
389 setting @code{initial-frame-alist} in your init file (@pxref{Init
390 File}).
392 @defopt initial-frame-alist
393 This variable's value is an alist of parameter values used when
394 creating the initial frame.  You can set this variable to specify the
395 appearance of the initial frame without altering subsequent frames.
396 Each element has the form:
398 @example
399 (@var{parameter} . @var{value})
400 @end example
402 Emacs creates the initial frame before it reads your init
403 file.  After reading that file, Emacs checks @code{initial-frame-alist},
404 and applies the parameter settings in the altered value to the already
405 created initial frame.
407 If these settings affect the frame geometry and appearance, you'll see
408 the frame appear with the wrong ones and then change to the specified
409 ones.  If that bothers you, you can specify the same geometry and
410 appearance with X resources; those do take effect before the frame is
411 created.  @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
413 X resource settings typically apply to all frames.  If you want to
414 specify some X resources solely for the sake of the initial frame, and
415 you don't want them to apply to subsequent frames, here's how to achieve
416 this.  Specify parameters in @code{default-frame-alist} to override the
417 X resources for subsequent frames; then, to prevent these from affecting
418 the initial frame, specify the same parameters in
419 @code{initial-frame-alist} with values that match the X resources.
420 @end defopt
422 @cindex minibuffer-only frame
423 If these parameters include @code{(minibuffer . nil)}, that indicates
424 that the initial frame should have no minibuffer.  In this case, Emacs
425 creates a separate @dfn{minibuffer-only frame} as well.
427 @defopt minibuffer-frame-alist
428 This variable's value is an alist of parameter values used when
429 creating an initial minibuffer-only frame (i.e.@: the minibuffer-only
430 frame that Emacs creates if @code{initial-frame-alist} specifies a
431 frame with no minibuffer).
432 @end defopt
434 @defopt default-frame-alist
435 This is an alist specifying default values of frame parameters for all
436 Emacs frames---the first frame, and subsequent frames.  When using the X
437 Window System, you can get the same results by means of X resources
438 in many cases.
440 Setting this variable does not affect existing frames.  Furthermore,
441 functions that display a buffer in a separate frame may override the
442 default parameters by supplying their own parameters.
443 @end defopt
445 If you invoke Emacs with command-line options that specify frame
446 appearance, those options take effect by adding elements to either
447 @code{initial-frame-alist} or @code{default-frame-alist}.  Options
448 which affect just the initial frame, such as @samp{-geometry} and
449 @samp{--maximized}, add to @code{initial-frame-alist}; the others add
450 to @code{default-frame-alist}.  @pxref{Emacs Invocation,, Command Line
451 Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
453 @node Window Frame Parameters
454 @subsection Window Frame Parameters
455 @cindex frame parameters for windowed displays
457   Just what parameters a frame has depends on what display mechanism
458 it uses.  This section describes the parameters that have special
459 meanings on some or all kinds of terminals.  Of these, @code{name},
460 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
461 @code{buffer-predicate} provide meaningful information in terminal
462 frames, and @code{tty-color-mode} is meaningful only for frames on
463 text terminals.
465 @menu
466 * Basic Parameters::            Parameters that are fundamental.
467 * Position Parameters::         The position of the frame on the screen.
468 * Size Parameters::             Frame's size.
469 * Layout Parameters::           Size of parts of the frame, and
470                                   enabling or disabling some parts.
471 * Buffer Parameters::           Which buffers have been or should be shown.
472 * Management Parameters::       Communicating with the window manager.
473 * Cursor Parameters::           Controlling the cursor appearance.
474 * Font and Color Parameters::   Fonts and colors for the frame text.
475 @end menu
477 @node Basic Parameters
478 @subsubsection Basic Parameters
480   These frame parameters give the most basic information about the
481 frame.  @code{title} and @code{name} are meaningful on all terminals.
483 @table @code
484 @vindex display, a frame parameter
485 @item display
486 The display on which to open this frame.  It should be a string of the
487 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
488 @env{DISPLAY} environment variable.
490 @vindex display-type, a frame parameter
491 @item display-type
492 This parameter describes the range of possible colors that can be used
493 in this frame.  Its value is @code{color}, @code{grayscale} or
494 @code{mono}.
496 @vindex title, a frame parameter
497 @item title
498 If a frame has a non-@code{nil} title, it appears in the window
499 system's title bar at the top of the frame, and also in the mode line
500 of windows in that frame if @code{mode-line-frame-identification} uses
501 @samp{%F} (@pxref{%-Constructs}).  This is normally the case when
502 Emacs is not using a window system, and can only display one frame at
503 a time.  @xref{Frame Titles}.
505 @vindex name, a frame parameter
506 @item name
507 The name of the frame.  The frame name serves as a default for the frame
508 title, if the @code{title} parameter is unspecified or @code{nil}.  If
509 you don't specify a name, Emacs sets the frame name automatically
510 (@pxref{Frame Titles}).
512 If you specify the frame name explicitly when you create the frame, the
513 name is also used (instead of the name of the Emacs executable) when
514 looking up X resources for the frame.
516 @item explicit-name
517 If the frame name was specified explicitly when the frame was created,
518 this parameter will be that name.  If the frame wasn't explicitly
519 named, this parameter will be @code{nil}.
520 @end table
522 @node Position Parameters
523 @subsubsection Position Parameters
524 @cindex window position on display
526   Position parameters' values are normally measured in pixels, but on
527 text terminals they count characters or lines instead.
529 @table @code
530 @vindex left, a frame parameter
531 @item left
532 The position, in pixels, of the left (or right) edge of the frame with
533 respect to the left (or right) edge of the screen.  The value may be:
535 @table @asis
536 @item an integer
537 A positive integer relates the left edge of the frame to the left edge
538 of the screen.  A negative integer relates the right frame edge to the
539 right screen edge.
541 @item @code{(+ @var{pos})}
542 This specifies the position of the left frame edge relative to the left
543 screen edge.  The integer @var{pos} may be positive or negative; a
544 negative value specifies a position outside the screen.
546 @item @code{(- @var{pos})}
547 This specifies the position of the right frame edge relative to the right
548 screen edge.  The integer @var{pos} may be positive or negative; a
549 negative value specifies a position outside the screen.
550 @end table
552 Some window managers ignore program-specified positions.  If you want to
553 be sure the position you specify is not ignored, specify a
554 non-@code{nil} value for the @code{user-position} parameter as well.
556 @vindex top, a frame parameter
557 @item top
558 The screen position of the top (or bottom) edge, in pixels, with respect
559 to the top (or bottom) edge of the screen.  It works just like
560 @code{left}, except vertically instead of horizontally.
562 @vindex icon-left, a frame parameter
563 @item icon-left
564 The screen position of the left edge of the frame's icon, in pixels,
565 counting from the left edge of the screen.  This takes effect when the
566 frame is iconified, if the window manager supports this feature.  If
567 you specify a value for this parameter, then you must also specify a
568 value for @code{icon-top} and vice versa.
570 @vindex icon-top, a frame parameter
571 @item icon-top
572 The screen position of the top edge of the frame's icon, in pixels,
573 counting from the top edge of the screen.  This takes effect when the
574 frame is iconified, if the window manager supports this feature.
576 @vindex user-position, a frame parameter
577 @item user-position
578 When you create a frame and specify its screen position with the
579 @code{left} and @code{top} parameters, use this parameter to say whether
580 the specified position was user-specified (explicitly requested in some
581 way by a human user) or merely program-specified (chosen by a program).
582 A non-@code{nil} value says the position was user-specified.
584 @cindex window positions and window managers
585 Window managers generally heed user-specified positions, and some heed
586 program-specified positions too.  But many ignore program-specified
587 positions, placing the window in a default fashion or letting the user
588 place it with the mouse.  Some window managers, including @code{twm},
589 let the user specify whether to obey program-specified positions or
590 ignore them.
592 When you call @code{make-frame}, you should specify a non-@code{nil}
593 value for this parameter if the values of the @code{left} and @code{top}
594 parameters represent the user's stated preference; otherwise, use
595 @code{nil}.
596 @end table
598 @node Size Parameters
599 @subsubsection Size Parameters
600 @cindex window size on display
602   Frame parameters specify frame sizes in character units.  On
603 graphical displays, the @code{default} face determines the actual
604 pixel sizes of these character units (@pxref{Face Attributes}).
606 @table @code
607 @vindex height, a frame parameter
608 @item height
609 The height of the frame contents, in characters.  (To get the height in
610 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
612 @vindex width, a frame parameter
613 @item width
614 The width of the frame contents, in characters.  (To get the width in
615 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
617 @vindex user-size, a frame parameter
618 @item user-size
619 This does for the size parameters @code{height} and @code{width} what
620 the @code{user-position} parameter (@pxref{Position Parameters,
621 user-position}) does for the position parameters @code{top} and
622 @code{left}.
624 @cindex full-screen frames
625 @vindex fullscreen, a frame parameter
626 @item fullscreen
627 Specify that width, height or both shall be maximized.  The value
628 @code{fullwidth} specifies that width shall be as wide as possible.
629 The value @code{fullheight} specifies that height shall be as tall as
630 possible.  The value @code{fullboth} specifies that both the width and
631 the height shall be set to the size of the screen.  The value
632 @code{maximized} specifies that the frame shall be maximized.  The
633 difference between @code{maximized} and @code{fullboth} is that the
634 former still has window manager decorations while the latter really
635 covers the whole screen.
636 @end table
638 @node Layout Parameters
639 @subsubsection Layout Parameters
640 @cindex layout parameters of frames
641 @cindex frame layout parameters
643   These frame parameters enable or disable various parts of the
644 frame, or control their sizes.
646 @table @code
647 @vindex border-width, a frame parameter
648 @item border-width
649 The width in pixels of the frame's border.
651 @vindex internal-border-width, a frame parameter
652 @item internal-border-width
653 The distance in pixels between text (or fringe) and the frame's border.
655 @vindex vertical-scroll-bars, a frame parameter
656 @item vertical-scroll-bars
657 Whether the frame has scroll bars for vertical scrolling, and which side
658 of the frame they should be on.  The possible values are @code{left},
659 @code{right}, and @code{nil} for no scroll bars.
661 @ignore
662 @vindex horizontal-scroll-bars, a frame parameter
663 @item horizontal-scroll-bars
664 Whether the frame has scroll bars for horizontal scrolling
665 (non-@code{nil} means yes).  Horizontal scroll bars are not currently
666 implemented.
667 @end ignore
669 @vindex scroll-bar-width, a frame parameter
670 @item scroll-bar-width
671 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
672 use the default width.
674 @vindex left-fringe, a frame parameter
675 @vindex right-fringe, a frame parameter
676 @item left-fringe
677 @itemx right-fringe
678 The default width of the left and right fringes of windows in this
679 frame (@pxref{Fringes}).  If either of these is zero, that effectively
680 removes the corresponding fringe.
682 When you use @code{frame-parameter} to query the value of either of
683 these two frame parameters, the return value is always an integer.
684 When using @code{set-frame-parameter}, passing a @code{nil} value
685 imposes an actual default value of 8 pixels.
687 The combined fringe widths must add up to an integral number of
688 columns, so the actual default fringe widths for the frame, as
689 reported by @code{frame-parameter}, may be larger than what you
690 specify.  Any extra width is distributed evenly between the left and
691 right fringe.  However, you can force one fringe or the other to a
692 precise width by specifying that width as a negative integer.  If both
693 widths are negative, only the left fringe gets the specified width.
695 @vindex menu-bar-lines frame parameter
696 @item menu-bar-lines
697 The number of lines to allocate at the top of the frame for a menu
698 bar.  The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
699 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
701 @vindex tool-bar-lines frame parameter
702 @item tool-bar-lines
703 The number of lines to use for the tool bar.  The default is 1 if Tool
704 Bar mode is enabled, and 0 otherwise.  @xref{Tool Bars,,,emacs, The
705 GNU Emacs Manual}.
707 @vindex tool-bar-position frame parameter
708 @item tool-bar-position
709 The position of the tool bar.  Currently only for the GTK tool bar.
710 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
711 The default is  @code{top}.
713 @vindex line-spacing, a frame parameter
714 @item line-spacing
715 Additional space to leave below each text line, in pixels (a positive
716 integer).  @xref{Line Height}, for more information.
717 @end table
719 @node Buffer Parameters
720 @subsubsection Buffer Parameters
722   These frame parameters, meaningful on all kinds of terminals, deal
723 with which buffers have been, or should, be displayed in the frame.
725 @table @code
726 @vindex minibuffer, a frame parameter
727 @item minibuffer
728 Whether this frame has its own minibuffer.  The value @code{t} means
729 yes, @code{nil} means no, @code{only} means this frame is just a
730 minibuffer.  If the value is a minibuffer window (in some other
731 frame), the frame uses that minibuffer.
733 This frame parameter takes effect when the frame is created, and can
734 not be changed afterwards.
736 @vindex buffer-predicate, a frame parameter
737 @item buffer-predicate
738 The buffer-predicate function for this frame.  The function
739 @code{other-buffer} uses this predicate (from the selected frame) to
740 decide which buffers it should consider, if the predicate is not
741 @code{nil}.  It calls the predicate with one argument, a buffer, once for
742 each buffer; if the predicate returns a non-@code{nil} value, it
743 considers that buffer.
745 @vindex buffer-list, a frame parameter
746 @item buffer-list
747 A list of buffers that have been selected in this frame, ordered
748 most-recently-selected first.
750 @vindex unsplittable, a frame parameter
751 @item unsplittable
752 If non-@code{nil}, this frame's window is never split automatically.
753 @end table
755 @node Management Parameters
756 @subsubsection Window Management Parameters
757 @cindex window manager interaction, and frame parameters
759   The following frame parameters control various aspects of the
760 frame's interaction with the window manager.  They have no effect on
761 text terminals.
763 @table @code
764 @vindex visibility, a frame parameter
765 @item visibility
766 The state of visibility of the frame.  There are three possibilities:
767 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
768 iconified.  @xref{Visibility of Frames}.
770 @vindex auto-raise, a frame parameter
771 @item auto-raise
772 If non-@code{nil}, Emacs automatically raises the frame when it is
773 selected.  Some window managers do not allow this.
775 @vindex auto-lower, a frame parameter
776 @item auto-lower
777 If non-@code{nil}, Emacs automatically lowers the frame when it is
778 deselected.  Some window managers do not allow this.
780 @vindex icon-type, a frame parameter
781 @item icon-type
782 The type of icon to use for this frame.  If the value is a string,
783 that specifies a file containing a bitmap to use; @code{nil} specifies
784 no icon (in which case the window manager decides what to show); any
785 other non-@code{nil} value specifies the default Emacs icon.
787 @vindex icon-name, a frame parameter
788 @item icon-name
789 The name to use in the icon for this frame, when and if the icon
790 appears.  If this is @code{nil}, the frame's title is used.
792 @vindex window-id, a frame parameter
793 @item window-id
794 The ID number which the graphical display uses for this frame.  Emacs
795 assigns this parameter when the frame is created; changing the
796 parameter has no effect on the actual ID number.
798 @vindex outer-window-id, a frame parameter
799 @item outer-window-id
800 The ID number of the outermost window-system window in which the frame
801 exists.  As with @code{window-id}, changing this parameter has no
802 actual effect.
804 @vindex wait-for-wm, a frame parameter
805 @item wait-for-wm
806 If non-@code{nil}, tell Xt to wait for the window manager to confirm
807 geometry changes.  Some window managers, including versions of Fvwm2
808 and KDE, fail to confirm, so Xt hangs.  Set this to @code{nil} to
809 prevent hanging with those window managers.
811 @vindex sticky, a frame parameter
812 @item sticky
813 If non-@code{nil}, the frame is visible on all virtual desktops on systems
814 with virtual desktops.
816 @ignore
817 @vindex parent-id, a frame parameter
818 @item parent-id
819 @c ??? Not yet working.
820 The X window number of the window that should be the parent of this one.
821 Specifying this lets you create an Emacs window inside some other
822 application's window.  (It is not certain this will be implemented; try
823 it and see if it works.)
824 @end ignore
825 @end table
827 @node Cursor Parameters
828 @subsubsection Cursor Parameters
829 @cindex cursor, and frame parameters
831   This frame parameter controls the way the cursor looks.
833 @table @code
834 @vindex cursor-type, a frame parameter
835 @item cursor-type
836 How to display the cursor.  Legitimate values are:
838 @table @code
839 @item box
840 Display a filled box.  (This is the default.)
841 @item hollow
842 Display a hollow box.
843 @item nil
844 Don't display a cursor.
845 @item bar
846 Display a vertical bar between characters.
847 @item (bar . @var{width})
848 Display a vertical bar @var{width} pixels wide between characters.
849 @item hbar
850 Display a horizontal bar.
851 @item (hbar . @var{height})
852 Display a horizontal bar @var{height} pixels high.
853 @end table
854 @end table
856 @vindex cursor-type
857 The @code{cursor-type} frame parameter may be overridden by the
858 variables @code{cursor-type} and
859 @code{cursor-in-non-selected-windows}:
861 @defvar cursor-type
862 This buffer-local variable controls how the cursor looks in a selected
863 window showing the buffer.  If its value is @code{t}, that means to
864 use the cursor specified by the @code{cursor-type} frame parameter.
865 Otherwise, the value should be one of the cursor types listed above,
866 and it overrides the @code{cursor-type} frame parameter.
867 @end defvar
869 @defopt cursor-in-non-selected-windows
870 This buffer-local variable controls how the cursor looks in a window
871 that is not selected.  It supports the same values as the
872 @code{cursor-type} frame parameter; also, @code{nil} means don't
873 display a cursor in nonselected windows, and @code{t} (the default)
874 means use a standard modification of the usual cursor type (solid box
875 becomes hollow box, and bar becomes a narrower bar).
876 @end defopt
878 @defopt blink-cursor-alist
879 This variable specifies how to blink the cursor.  Each element has the
880 form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
881 type equals @var{on-state} (comparing using @code{equal}), the
882 corresponding @var{off-state} specifies what the cursor looks like
883 when it blinks ``off''.  Both @var{on-state} and @var{off-state}
884 should be suitable values for the @code{cursor-type} frame parameter.
886 There are various defaults for how to blink each type of cursor, if
887 the type is not mentioned as an @var{on-state} here.  Changes in this
888 variable do not take effect immediately, only when you specify the
889 @code{cursor-type} frame parameter.
890 @end defopt
892 @node Font and Color Parameters
893 @subsubsection Font and Color Parameters
894 @cindex font and color, frame parameters
896   These frame parameters control the use of fonts and colors.
898 @table @code
899 @vindex font-backend, a frame parameter
900 @item font-backend
901 A list of symbols, specifying the @dfn{font backends} to use for
902 drawing fonts in the frame, in order of priority.  On X, there are
903 currently two available font backends: @code{x} (the X core font
904 driver) and @code{xft} (the Xft font driver).  On Windows, there are
905 currently two available font backends: @code{gdi} and
906 @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
907 Manual}).  On other systems, there is only one available font backend,
908 so it does not make sense to modify this frame parameter.
910 @vindex background-mode, a frame parameter
911 @item background-mode
912 This parameter is either @code{dark} or @code{light}, according
913 to whether the background color is a light one or a dark one.
915 @vindex tty-color-mode, a frame parameter
916 @item tty-color-mode
917 @cindex standard colors for character terminals
918 This parameter overrides the terminal's color support as given by the
919 system's terminal capabilities database in that this parameter's value
920 specifies the color mode to use on a text terminal.  The value can be
921 either a symbol or a number.  A number specifies the number of colors
922 to use (and, indirectly, what commands to issue to produce each
923 color).  For example, @code{(tty-color-mode . 8)} specifies use of the
924 ANSI escape sequences for 8 standard text colors.  A value of -1 turns
925 off color support.
927 If the parameter's value is a symbol, it specifies a number through
928 the value of @code{tty-color-mode-alist}, and the associated number is
929 used instead.
931 @vindex screen-gamma, a frame parameter
932 @item screen-gamma
933 @cindex gamma correction
934 If this is a number, Emacs performs ``gamma correction'' which adjusts
935 the brightness of all colors.  The value should be the screen gamma of
936 your display, a floating point number.
938 Usual PC monitors have a screen gamma of 2.2, so color values in
939 Emacs, and in X windows generally, are calibrated to display properly
940 on a monitor with that gamma value.  If you specify 2.2 for
941 @code{screen-gamma}, that means no correction is needed.  Other values
942 request correction, designed to make the corrected colors appear on
943 your screen the way they would have appeared without correction on an
944 ordinary monitor with a gamma value of 2.2.
946 If your monitor displays colors too light, you should specify a
947 @code{screen-gamma} value smaller than 2.2.  This requests correction
948 that makes colors darker.  A screen gamma value of 1.5 may give good
949 results for LCD color displays.
951 @vindex alpha, a frame parameter
952 @item alpha
953 @cindex opacity, frame
954 @cindex transparency, frame
955 @vindex frame-alpha-lower-limit
956 This parameter specifies the opacity of the frame, on graphical
957 displays that support variable opacity.  It should be an integer
958 between 0 and 100, where 0 means completely transparent and 100 means
959 completely opaque.  It can also have a @code{nil} value, which tells
960 Emacs not to set the frame opacity (leaving it to the window manager).
962 To prevent the frame from disappearing completely from view, the
963 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
964 If the value of the frame parameter is less than the value of this
965 variable, Emacs uses the latter.  By default,
966 @code{frame-alpha-lower-limit} is 20.
968 The @code{alpha} frame parameter can also be a cons cell
969 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
970 opacity of the frame when it is selected, and @samp{inactive} is the
971 opacity when it is not selected.
972 @end table
974 The following frame parameters are semi-obsolete in that they are
975 automatically equivalent to particular face attributes of particular
976 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
978 @table @code
979 @vindex font, a frame parameter
980 @item font
981 The name of the font for displaying text in the frame.  This is a
982 string, either a valid font name for your system or the name of an Emacs
983 fontset (@pxref{Fontsets}).  It is equivalent to the @code{font}
984 attribute of the @code{default} face.
986 @vindex foreground-color, a frame parameter
987 @item foreground-color
988 The color to use for the image of a character.  It is equivalent to
989 the @code{:foreground} attribute of the @code{default} face.
991 @vindex background-color, a frame parameter
992 @item background-color
993 The color to use for the background of characters.  It is equivalent to
994 the @code{:background} attribute of the @code{default} face.
996 @vindex mouse-color, a frame parameter
997 @item mouse-color
998 The color for the mouse pointer.  It is equivalent to the @code{:background}
999 attribute of the @code{mouse} face.
1001 @vindex cursor-color, a frame parameter
1002 @item cursor-color
1003 The color for the cursor that shows point.  It is equivalent to the
1004 @code{:background} attribute of the @code{cursor} face.
1006 @vindex border-color, a frame parameter
1007 @item border-color
1008 The color for the border of the frame.  It is equivalent to the
1009 @code{:background} attribute of the @code{border} face.
1011 @vindex scroll-bar-foreground, a frame parameter
1012 @item scroll-bar-foreground
1013 If non-@code{nil}, the color for the foreground of scroll bars.  It is
1014 equivalent to the @code{:foreground} attribute of the
1015 @code{scroll-bar} face.
1017 @vindex scroll-bar-background, a frame parameter
1018 @item scroll-bar-background
1019 If non-@code{nil}, the color for the background of scroll bars.  It is
1020 equivalent to the @code{:background} attribute of the
1021 @code{scroll-bar} face.
1022 @end table
1024 @node Size and Position
1025 @subsection Frame Size And Position
1026 @cindex size of frame
1027 @cindex screen size
1028 @cindex frame size
1029 @cindex resize frame
1031   You can read or change the size and position of a frame using the
1032 frame parameters @code{left}, @code{top}, @code{height}, and
1033 @code{width}.  Whatever geometry parameters you don't specify are chosen
1034 by the window manager in its usual fashion.
1036   Here are some special features for working with sizes and positions.
1037 (For the precise meaning of ``selected frame'' used by these functions,
1038 see @ref{Input Focus}.)
1040 @defun set-frame-position frame left top
1041 This function sets the position of the top left corner of @var{frame} to
1042 @var{left} and @var{top}.  These arguments are measured in pixels, and
1043 normally count from the top left corner of the screen.
1045 Negative parameter values position the bottom edge of the window up from
1046 the bottom edge of the screen, or the right window edge to the left of
1047 the right edge of the screen.  It would probably be better if the values
1048 were always counted from the left and top, so that negative arguments
1049 would position the frame partly off the top or left edge of the screen,
1050 but it seems inadvisable to change that now.
1051 @end defun
1053 @defun frame-height &optional frame
1054 @defunx frame-width &optional frame
1055 These functions return the height and width of @var{frame}, measured in
1056 lines and columns.  If you don't supply @var{frame}, they use the
1057 selected frame.
1058 @end defun
1060 @defun frame-pixel-height &optional frame
1061 @defunx frame-pixel-width &optional frame
1062 These functions return the height and width of the main display area
1063 of @var{frame}, measured in pixels.  If you don't supply @var{frame},
1064 they use the selected frame.  For a text terminal, the results are in
1065 characters rather than pixels.
1067 These values include the internal borders, and windows' scroll bars
1068 and fringes (which belong to individual windows, not to the frame
1069 itself).  The exact value of the heights depends on the window-system
1070 and toolkit in use.  With GTK+, the height does not include any tool
1071 bar or menu bar.  With the Motif or Lucid toolkits, it includes the
1072 tool bar but not the menu bar.  In a graphical version with no
1073 toolkit, it includes both the tool bar and menu bar.  For a text
1074 terminal, the result includes the menu bar.
1075 @end defun
1077 @defun frame-char-height &optional frame
1078 @defunx frame-char-width &optional frame
1079 These functions return the height and width of a character in
1080 @var{frame}, measured in pixels.  The values depend on the choice of
1081 font.  If you don't supply @var{frame}, these functions use the selected
1082 frame.
1083 @end defun
1085 @defun set-frame-size frame cols rows
1086 This function sets the size of @var{frame}, measured in characters;
1087 @var{cols} and @var{rows} specify the new width and height.
1089 To set the size based on values measured in pixels, use
1090 @code{frame-char-height} and @code{frame-char-width} to convert
1091 them to units of characters.
1092 @end defun
1094 @defun set-frame-height frame lines &optional pretend
1095 This function resizes @var{frame} to a height of @var{lines} lines.  The
1096 sizes of existing windows in @var{frame} are altered proportionally to
1097 fit.
1099 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
1100 lines of output in @var{frame}, but does not change its value for the
1101 actual height of the frame.  This is only useful on text terminals.
1102 Using a smaller height than the terminal actually implements may be
1103 useful to reproduce behavior observed on a smaller screen, or if the
1104 terminal malfunctions when using its whole screen.  Setting the frame
1105 height ``for real'' does not always work, because knowing the correct
1106 actual size may be necessary for correct cursor positioning on
1107 text terminals.
1108 @end defun
1110 @defun set-frame-width frame width &optional pretend
1111 This function sets the width of @var{frame}, measured in characters.
1112 The argument @var{pretend} has the same meaning as in
1113 @code{set-frame-height}.
1114 @end defun
1116 @c FIXME?  Belongs more in Emacs manual than here?
1117 @c But eg fit-window-to-buffer is in this manual.
1118 @deffn Command fit-frame-to-buffer &optional frame max-height min-height
1119 This command adjusts the height of @var{frame} (the default is the
1120 selected frame) to fit its contents.  The optional arguments
1121 @var{max-height} and @var{min-height} specify the maximum and minimum
1122 new frame heights, respectively.
1124 @vindex fit-frame-to-buffer-bottom-margin
1125 The default minimum height corresponds to @code{window-min-height}.
1126 The default maximum height is the screen height below the current top
1127 position of the frame, minus any margin specified by the option
1128 @code{fit-frame-to-buffer-bottom-margin}.
1129 @end deffn
1131 @node Geometry
1132 @subsection Geometry
1134   Here's how to examine the data in an X-style window geometry
1135 specification:
1137 @defun x-parse-geometry geom
1138 @cindex geometry specification
1139 The function @code{x-parse-geometry} converts a standard X window
1140 geometry string to an alist that you can use as part of the argument to
1141 @code{make-frame}.
1143 The alist describes which parameters were specified in @var{geom}, and
1144 gives the values specified for them.  Each element looks like
1145 @code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
1146 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1148 For the size parameters, the value must be an integer.  The position
1149 parameter names @code{left} and @code{top} are not totally accurate,
1150 because some values indicate the position of the right or bottom edges
1151 instead.  The @var{value} possibilities for the position parameters are:
1152 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1153 as previously described (@pxref{Position Parameters}).
1155 Here is an example:
1157 @example
1158 (x-parse-geometry "35x70+0-0")
1159      @result{} ((height . 70) (width . 35)
1160          (top - 0) (left . 0))
1161 @end example
1162 @end defun
1164 @node Terminal Parameters
1165 @section Terminal Parameters
1166 @cindex terminal parameters
1168   Each terminal has a list of associated parameters.  These
1169 @dfn{terminal parameters} are mostly a convenient way of storage for
1170 terminal-local variables, but some terminal parameters have a special
1171 meaning.
1173   This section describes functions to read and change the parameter values
1174 of a terminal.  They all accept as their argument either a terminal or
1175 a frame; the latter means use that frame's terminal.  An argument of
1176 @code{nil} means the selected frame's terminal.
1178 @defun terminal-parameters &optional terminal
1179 This function returns an alist listing all the parameters of
1180 @var{terminal} and their values.
1181 @end defun
1183 @defun terminal-parameter terminal parameter
1184 This function returns the value of the parameter @var{parameter} (a
1185 symbol) of @var{terminal}.  If @var{terminal} has no setting for
1186 @var{parameter}, this function returns @code{nil}.
1187 @end defun
1189 @defun set-terminal-parameter terminal parameter value
1190 This function sets the parameter @var{parm} of @var{terminal} to the
1191 specified @var{value}, and returns the previous value of that
1192 parameter.
1193 @end defun
1195 Here's a list of a few terminal parameters that have a special
1196 meaning:
1198 @table @code
1199 @item background-mode
1200 The classification of the terminal's background color, either
1201 @code{light} or @code{dark}.
1202 @item normal-erase-is-backspace
1203 Value is either 1 or 0, depending on whether
1204 @code{normal-erase-is-backspace-mode} is turned on or off on this
1205 terminal.  @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1206 @item terminal-initted
1207 After the terminal is initialized, this is set to the
1208 terminal-specific initialization function.
1209 @end table
1211 @node Frame Titles
1212 @section Frame Titles
1213 @cindex frame title
1215   Every frame has a @code{name} parameter; this serves as the default
1216 for the frame title which window systems typically display at the top of
1217 the frame.  You can specify a name explicitly by setting the @code{name}
1218 frame property.
1220   Normally you don't specify the name explicitly, and Emacs computes the
1221 frame name automatically based on a template stored in the variable
1222 @code{frame-title-format}.  Emacs recomputes the name each time the
1223 frame is redisplayed.
1225 @defvar frame-title-format
1226 This variable specifies how to compute a name for a frame when you have
1227 not explicitly specified one.  The variable's value is actually a mode
1228 line construct, just like @code{mode-line-format}, except that the
1229 @samp{%c} and @samp{%l} constructs are ignored.  @xref{Mode Line
1230 Data}.
1231 @end defvar
1233 @defvar icon-title-format
1234 This variable specifies how to compute the name for an iconified frame,
1235 when you have not explicitly specified the frame title.  This title
1236 appears in the icon itself.
1237 @end defvar
1239 @defvar multiple-frames
1240 This variable is set automatically by Emacs.  Its value is @code{t} when
1241 there are two or more frames (not counting minibuffer-only frames or
1242 invisible frames).  The default value of @code{frame-title-format} uses
1243 @code{multiple-frames} so as to put the buffer name in the frame title
1244 only when there is more than one frame.
1246 The value of this variable is not guaranteed to be accurate except
1247 while processing @code{frame-title-format} or
1248 @code{icon-title-format}.
1249 @end defvar
1251 @node Deleting Frames
1252 @section Deleting Frames
1253 @cindex deleting frames
1255   A @dfn{live frame} is one that has not been deleted.  When a frame
1256 is deleted, it is removed from its terminal display, although it may
1257 continue to exist as a Lisp object until there are no more references
1258 to it.
1260 @deffn Command delete-frame &optional frame force
1261 @vindex delete-frame-functions
1262 This function deletes the frame @var{frame}.  Unless @var{frame} is a
1263 tooltip, it first runs the hook @code{delete-frame-functions} (each
1264 function gets one argument, @var{frame}).  By default, @var{frame} is
1265 the selected frame.
1267 A frame cannot be deleted if its minibuffer is used by other frames.
1268 Normally, you cannot delete a frame if all other frames are invisible,
1269 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1270 @end deffn
1272 @defun frame-live-p frame
1273 The function @code{frame-live-p} returns non-@code{nil} if the frame
1274 @var{frame} has not been deleted.  The possible non-@code{nil} return
1275 values are like those of @code{framep}.  @xref{Frames}.
1276 @end defun
1278   Some window managers provide a command to delete a window.  These work
1279 by sending a special message to the program that operates the window.
1280 When Emacs gets one of these commands, it generates a
1281 @code{delete-frame} event, whose normal definition is a command that
1282 calls the function @code{delete-frame}.  @xref{Misc Events}.
1284 @node Finding All Frames
1285 @section Finding All Frames
1286 @cindex frames, scanning all
1288 @defun frame-list
1289 This function returns a list of all the live frames, i.e.@: those that
1290 have not been deleted.  It is analogous to @code{buffer-list} for
1291 buffers, and includes frames on all terminals.  The list that you get
1292 is newly created, so modifying the list doesn't have any effect on the
1293 internals of Emacs.
1294 @end defun
1296 @defun visible-frame-list
1297 This function returns a list of just the currently visible frames.
1298 @xref{Visibility of Frames}.  Frames on text terminals always count as
1299 ``visible'', even though only the selected one is actually displayed.
1300 @end defun
1302 @defun next-frame &optional frame minibuf
1303 This function lets you cycle conveniently through all the frames on
1304 the current display from an arbitrary starting point.  It returns the
1305 ``next'' frame after @var{frame} in the cycle.  If @var{frame} is
1306 omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
1307 Focus}).
1309 The second argument, @var{minibuf}, says which frames to consider:
1311 @table @asis
1312 @item @code{nil}
1313 Exclude minibuffer-only frames.
1314 @item @code{visible}
1315 Consider all visible frames.
1316 @item 0
1317 Consider all visible or iconified frames.
1318 @item a window
1319 Consider only the frames using that particular window as their
1320 minibuffer.
1321 @item anything else
1322 Consider all frames.
1323 @end table
1324 @end defun
1326 @defun previous-frame &optional frame minibuf
1327 Like @code{next-frame}, but cycles through all frames in the opposite
1328 direction.
1329 @end defun
1331   See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1332 Window Ordering}.
1334 @node Minibuffers and Frames
1335 @section Minibuffers and Frames
1337 Normally, each frame has its own minibuffer window at the bottom, which
1338 is used whenever that frame is selected.  If the frame has a minibuffer,
1339 you can get it with @code{minibuffer-window} (@pxref{Definition of
1340 minibuffer-window}).
1342 However, you can also create a frame with no minibuffer.  Such a frame
1343 must use the minibuffer window of some other frame.  When you create the
1344 frame, you can explicitly specify the minibuffer window to use (in some
1345 other frame).  If you don't, then the minibuffer is found in the frame
1346 which is the value of the variable @code{default-minibuffer-frame}.  Its
1347 value should be a frame that does have a minibuffer.
1349 If you use a minibuffer-only frame, you might want that frame to raise
1350 when you enter the minibuffer.  If so, set the variable
1351 @code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.
1353 @defvar default-minibuffer-frame
1354 This variable specifies the frame to use for the minibuffer window, by
1355 default.  It does not affect existing frames.  It is always local to
1356 the current terminal and cannot be buffer-local.  @xref{Multiple
1357 Terminals}.
1358 @end defvar
1360 @node Input Focus
1361 @section Input Focus
1362 @cindex input focus
1363 @c @cindex selected frame    Duplicates selected-frame
1365 At any time, one frame in Emacs is the @dfn{selected frame}.  The selected
1366 window always resides on the selected frame.
1368 When Emacs displays its frames on several terminals (@pxref{Multiple
1369 Terminals}), each terminal has its own selected frame.  But only one
1370 of these is ``@emph{the} selected frame'': it's the frame that belongs
1371 to the terminal from which the most recent input came.  That is, when
1372 Emacs runs a command that came from a certain terminal, the selected
1373 frame is the one of that terminal.  Since Emacs runs only a single
1374 command at any given time, it needs to consider only one selected
1375 frame at a time; this frame is what we call @dfn{the selected frame}
1376 in this manual.  The display on which the selected frame is shown is
1377 the @dfn{selected frame's display}.
1379 @defun selected-frame
1380 This function returns the selected frame.
1381 @end defun
1383 Some window systems and window managers direct keyboard input to the
1384 window object that the mouse is in; others require explicit clicks or
1385 commands to @dfn{shift the focus} to various window objects.  Either
1386 way, Emacs automatically keeps track of which frame has the focus.  To
1387 explicitly switch to a different frame from a Lisp function, call
1388 @code{select-frame-set-input-focus}.
1390 Lisp programs can also switch frames ``temporarily'' by calling the
1391 function @code{select-frame}.  This does not alter the window system's
1392 concept of focus; rather, it escapes from the window manager's control
1393 until that control is somehow reasserted.
1395 When using a text terminal, only one frame can be displayed at a time
1396 on the terminal, so after a call to @code{select-frame}, the next
1397 redisplay actually displays the newly selected frame.  This frame
1398 remains selected until a subsequent call to @code{select-frame}.  Each
1399 frame on a text terminal has a number which appears in the mode line
1400 before the buffer name (@pxref{Mode Line Variables}).
1402 @defun select-frame-set-input-focus frame &optional norecord
1403 This function selects @var{frame}, raises it (should it happen to be
1404 obscured by other frames) and tries to give it the X server's focus.
1405 On a text terminal, the next redisplay displays the new frame on the
1406 entire terminal screen.  The optional argument @var{norecord} has the
1407 same meaning as for @code{select-frame} (see below).  The return value
1408 of this function is not significant.
1409 @end defun
1411 @deffn Command select-frame frame &optional norecord
1412 This function selects frame @var{frame}, temporarily disregarding the
1413 focus of the X server if any.  The selection of @var{frame} lasts until
1414 the next time the user does something to select a different frame, or
1415 until the next time this function is called.  (If you are using a
1416 window system, the previously selected frame may be restored as the
1417 selected frame after return to the command loop, because it still may
1418 have the window system's input focus.)
1420 The specified @var{frame} becomes the selected frame, and its terminal
1421 becomes the selected terminal.  This function then calls
1422 @code{select-window} as a subroutine, passing the window selected
1423 within @var{frame} as its first argument and @var{norecord} as its
1424 second argument (hence, if @var{norecord} is non-@code{nil}, this
1425 avoids changing the order of recently selected windows nor the buffer
1426 list).  @xref{Selecting Windows}.
1428 This function returns @var{frame}, or @code{nil} if @var{frame} has
1429 been deleted.
1431 In general, you should never use @code{select-frame} in a way that
1432 could switch to a different terminal without switching back when
1433 you're done.
1434 @end deffn
1436 Emacs cooperates with the window system by arranging to select frames as
1437 the server and window manager request.  It does so by generating a
1438 special kind of input event, called a @dfn{focus} event, when
1439 appropriate.  The command loop handles a focus event by calling
1440 @code{handle-switch-frame}.  @xref{Focus Events}.
1442 @deffn Command handle-switch-frame frame
1443 This function handles a focus event by selecting frame @var{frame}.
1445 Focus events normally do their job by invoking this command.
1446 Don't call it for any other reason.
1447 @end deffn
1449 @defun redirect-frame-focus frame &optional focus-frame
1450 This function redirects focus from @var{frame} to @var{focus-frame}.
1451 This means that @var{focus-frame} will receive subsequent keystrokes and
1452 events intended for @var{frame}.  After such an event, the value of
1453 @code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
1454 events specifying @var{frame} will instead select @var{focus-frame}.
1456 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1457 redirection for @var{frame}, which therefore once again receives its own
1458 events.
1460 One use of focus redirection is for frames that don't have minibuffers.
1461 These frames use minibuffers on other frames.  Activating a minibuffer
1462 on another frame redirects focus to that frame.  This puts the focus on
1463 the minibuffer's frame, where it belongs, even though the mouse remains
1464 in the frame that activated the minibuffer.
1466 Selecting a frame can also change focus redirections.  Selecting frame
1467 @code{bar}, when @code{foo} had been selected, changes any redirections
1468 pointing to @code{foo} so that they point to @code{bar} instead.  This
1469 allows focus redirection to work properly when the user switches from
1470 one frame to another using @code{select-window}.
1472 This means that a frame whose focus is redirected to itself is treated
1473 differently from a frame whose focus is not redirected.
1474 @code{select-frame} affects the former but not the latter.
1476 The redirection lasts until @code{redirect-frame-focus} is called to
1477 change it.
1478 @end defun
1480 @defopt focus-follows-mouse
1481 This option is how you inform Emacs whether the window manager transfers
1482 focus when the user moves the mouse.  Non-@code{nil} says that it does.
1483 When this is so, the command @code{other-frame} moves the mouse to a
1484 position consistent with the new selected frame.
1485 @end defopt
1487 @node Visibility of Frames
1488 @section Visibility of Frames
1489 @cindex visible frame
1490 @cindex invisible frame
1491 @cindex iconified frame
1492 @cindex minimized frame
1493 @cindex frame visibility
1495 A frame on a graphical display may be @dfn{visible}, @dfn{invisible},
1496 or @dfn{iconified}.  If it is visible, its contents are displayed in
1497 the usual manner.  If it is iconified, its contents are not displayed,
1498 but there is a little icon somewhere to bring the frame back into view
1499 (some window managers refer to this state as @dfn{minimized} rather
1500 than @dfn{iconified}, but from Emacs' point of view they are the same
1501 thing).  If a frame is invisible, it is not displayed at all.
1503   Visibility is meaningless on text terminals, since only the selected
1504 one is actually displayed in any case.
1506 @defun frame-visible-p frame
1507 This function returns the visibility status of frame @var{frame}.  The
1508 value is @code{t} if @var{frame} is visible, @code{nil} if it is
1509 invisible, and @code{icon} if it is iconified.
1511 On a text terminal, all frames are considered ``visible'' for the
1512 purposes of this function, even though only one frame is displayed.
1513 @xref{Raising and Lowering}.
1514 @end defun
1516 @deffn Command iconify-frame &optional frame
1517 This function iconifies frame @var{frame}.  If you omit @var{frame}, it
1518 iconifies the selected frame.
1519 @end deffn
1521 @deffn Command make-frame-visible &optional frame
1522 This function makes frame @var{frame} visible.  If you omit
1523 @var{frame}, it makes the selected frame visible.  This does not raise
1524 the frame, but you can do that with @code{raise-frame} if you wish
1525 (@pxref{Raising and Lowering}).
1526 @end deffn
1528 @deffn Command make-frame-invisible &optional frame force
1529 This function makes frame @var{frame} invisible.  If you omit
1530 @var{frame}, it makes the selected frame invisible.
1532 Unless @var{force} is non-@code{nil}, this function refuses to make
1533 @var{frame} invisible if all other frames are invisible..
1534 @end deffn
1536   The visibility status of a frame is also available as a frame
1537 parameter.  You can read or change it as such.  @xref{Management
1538 Parameters}.  The user can also iconify and deiconify frames with the
1539 window manager.  This happens below the level at which Emacs can exert
1540 any control, but Emacs does provide events that you can use to keep
1541 track of such changes.  @xref{Misc Events}.
1543 @node Raising and Lowering
1544 @section Raising and Lowering Frames
1546 @cindex raising a frame
1547 @cindex lowering a frame
1548   Most window systems use a desktop metaphor.  Part of this metaphor
1549 is the idea that system-level windows (e.g.@: Emacs frames) are
1550 stacked in a notional third dimension perpendicular to the screen
1551 surface.  Where two overlap, the one higher up covers the one
1552 underneath.  You can @dfn{raise} or @dfn{lower} a frame using the
1553 functions @code{raise-frame} and @code{lower-frame}.
1555 @deffn Command raise-frame &optional frame
1556 This function raises frame @var{frame} (default, the selected frame).
1557 If @var{frame} is invisible or iconified, this makes it visible.
1558 @end deffn
1560 @deffn Command lower-frame &optional frame
1561 This function lowers frame @var{frame} (default, the selected frame).
1562 @end deffn
1564 @defopt minibuffer-auto-raise
1565 If this is non-@code{nil}, activation of the minibuffer raises the frame
1566 that the minibuffer window is in.
1567 @end defopt
1569   On window systems, you can also enable auto-raising (on frame
1570 selection) or auto-lowering (on frame deselection) using frame
1571 parameters.  @xref{Management Parameters}.
1573 @cindex top frame
1574   The concept of raising and lowering frames also applies to text
1575 terminal frames.  On each text terminal, only the top frame is
1576 displayed at any one time.
1578 @defun tty-top-frame terminal
1579 This function returns the top frame on @var{terminal}.  @var{terminal}
1580 should be a terminal object, a frame (meaning that frame's terminal),
1581 or @code{nil} (meaning the selected frame's terminal).  If it does not
1582 refer to a text terminal, the return value is @code{nil}.
1583 @end defun
1585 @node Frame Configurations
1586 @section Frame Configurations
1587 @cindex frame configuration
1589   A @dfn{frame configuration} records the current arrangement of frames,
1590 all their properties, and the window configuration of each one.
1591 (@xref{Window Configurations}.)
1593 @defun current-frame-configuration
1594 This function returns a frame configuration list that describes
1595 the current arrangement of frames and their contents.
1596 @end defun
1598 @defun set-frame-configuration configuration &optional nodelete
1599 This function restores the state of frames described in
1600 @var{configuration}.  However, this function does not restore deleted
1601 frames.
1603 Ordinarily, this function deletes all existing frames not listed in
1604 @var{configuration}.  But if @var{nodelete} is non-@code{nil}, the
1605 unwanted frames are iconified instead.
1606 @end defun
1608 @node Mouse Tracking
1609 @section Mouse Tracking
1610 @cindex mouse tracking
1611 @c @cindex tracking the mouse   Duplicates track-mouse
1613   Sometimes it is useful to @dfn{track} the mouse, which means to display
1614 something to indicate where the mouse is and move the indicator as the
1615 mouse moves.  For efficient mouse tracking, you need a way to wait until
1616 the mouse actually moves.
1618   The convenient way to track the mouse is to ask for events to represent
1619 mouse motion.  Then you can wait for motion by waiting for an event.  In
1620 addition, you can easily handle any other sorts of events that may
1621 occur.  That is useful, because normally you don't want to track the
1622 mouse forever---only until some other event, such as the release of a
1623 button.
1625 @defspec track-mouse body@dots{}
1626 This special form executes @var{body}, with generation of mouse motion
1627 events enabled.  Typically, @var{body} would use @code{read-event} to
1628 read the motion events and modify the display accordingly.  @xref{Motion
1629 Events}, for the format of mouse motion events.
1631 The value of @code{track-mouse} is that of the last form in @var{body}.
1632 You should design @var{body} to return when it sees the up-event that
1633 indicates the release of the button, or whatever kind of event means
1634 it is time to stop tracking.
1635 @end defspec
1637 The usual purpose of tracking mouse motion is to indicate on the screen
1638 the consequences of pushing or releasing a button at the current
1639 position.
1641 In many cases, you can avoid the need to track the mouse by using
1642 the @code{mouse-face} text property (@pxref{Special Properties}).
1643 That works at a much lower level and runs more smoothly than
1644 Lisp-level mouse tracking.
1646 @ignore
1647 @c These are not implemented yet.
1649 These functions change the screen appearance instantaneously.  The
1650 effect is transient, only until the next ordinary Emacs redisplay.  That
1651 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1652 to change the text, and the body of @code{track-mouse} normally reads
1653 the events itself and does not do redisplay.
1655 @defun x-contour-region window beg end
1656 This function draws lines to make a box around the text from @var{beg}
1657 to @var{end}, in window @var{window}.
1658 @end defun
1660 @defun x-uncontour-region window beg end
1661 This function erases the lines that would make a box around the text
1662 from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
1663 a contour that you previously made by calling @code{x-contour-region}.
1664 @end defun
1666 @defun x-draw-rectangle frame left top right bottom
1667 This function draws a hollow rectangle on frame @var{frame} with the
1668 specified edge coordinates, all measured in pixels from the inside top
1669 left corner.  It uses the cursor color, the one used for indicating the
1670 location of point.
1671 @end defun
1673 @defun x-erase-rectangle frame left top right bottom
1674 This function erases a hollow rectangle on frame @var{frame} with the
1675 specified edge coordinates, all measured in pixels from the inside top
1676 left corner.  Erasure means redrawing the text and background that
1677 normally belong in the specified rectangle.
1678 @end defun
1679 @end ignore
1681 @node Mouse Position
1682 @section Mouse Position
1683 @cindex mouse position
1684 @cindex position of mouse
1686   The functions @code{mouse-position} and @code{set-mouse-position}
1687 give access to the current position of the mouse.
1689 @defun mouse-position
1690 This function returns a description of the position of the mouse.  The
1691 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1692 and @var{y} are integers giving the position in characters relative to
1693 the top left corner of the inside of @var{frame}.
1694 @end defun
1696 @defvar mouse-position-function
1697 If non-@code{nil}, the value of this variable is a function for
1698 @code{mouse-position} to call.  @code{mouse-position} calls this
1699 function just before returning, with its normal return value as the
1700 sole argument, and it returns whatever this function returns to it.
1702 This abnormal hook exists for the benefit of packages like
1703 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1704 @end defvar
1706 @defun set-mouse-position frame x y
1707 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1708 frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
1709 giving the position in characters relative to the top left corner of the
1710 inside of @var{frame}.  If @var{frame} is not visible, this function
1711 does nothing.  The return value is not significant.
1712 @end defun
1714 @defun mouse-pixel-position
1715 This function is like @code{mouse-position} except that it returns
1716 coordinates in units of pixels rather than units of characters.
1717 @end defun
1719 @defun set-mouse-pixel-position frame x y
1720 This function warps the mouse like @code{set-mouse-position} except that
1721 @var{x} and @var{y} are in units of pixels rather than units of
1722 characters.  These coordinates are not required to be within the frame.
1724 If @var{frame} is not visible, this function does nothing.  The return
1725 value is not significant.
1726 @end defun
1728 @defun frame-pointer-visible-p &optional frame
1729 This predicate function returns non-@code{nil} if the mouse pointer
1730 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
1731 @var{frame} omitted or @code{nil} means the selected frame.  This is
1732 useful when @code{make-pointer-invisible} is set to @code{t}: it
1733 allows to know if the pointer has been hidden.
1734 @xref{Mouse Avoidance,,,emacs, The Emacs Manual}.
1735 @end defun
1737 @need 3000
1739 @node Pop-Up Menus
1740 @section Pop-Up Menus
1742   When using a window system, a Lisp program can pop up a menu so that
1743 the user can choose an alternative with the mouse.
1745 @defun x-popup-menu position menu
1746 This function displays a pop-up menu and returns an indication of
1747 what selection the user makes.
1749 The argument @var{position} specifies where on the screen to put the
1750 top left corner of the menu.  It can be either a mouse button event
1751 (which says to put the menu where the user actuated the button) or a
1752 list of this form:
1754 @example
1755 ((@var{xoffset} @var{yoffset}) @var{window})
1756 @end example
1758 @noindent
1759 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1760 pixels, counting from the top left corner of @var{window}.  @var{window}
1761 may be a window or a frame.
1763 If @var{position} is @code{t}, it means to use the current mouse
1764 position.  If @var{position} is @code{nil}, it means to precompute the
1765 key binding equivalents for the keymaps specified in @var{menu},
1766 without actually displaying or popping up the menu.
1768 The argument @var{menu} says what to display in the menu.  It can be a
1769 keymap or a list of keymaps (@pxref{Menu Keymaps}).  In this case, the
1770 return value is the list of events corresponding to the user's choice.
1771 This list has more than one element if the choice occurred in a
1772 submenu.  (Note that @code{x-popup-menu} does not actually execute the
1773 command bound to that sequence of events.)  On toolkits that support
1774 menu titles, the title is taken from the prompt string of @var{menu}
1775 if @var{menu} is a keymap, or from the prompt string of the first
1776 keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
1777 Menus}).
1779 Alternatively, @var{menu} can have the following form:
1781 @example
1782 (@var{title} @var{pane1} @var{pane2}...)
1783 @end example
1785 @noindent
1786 where each pane is a list of form
1788 @example
1789 (@var{title} @var{item1} @var{item2}...)
1790 @end example
1792 Each @var{item} should be a cons cell, @code{(@var{line} . @var{value})},
1793 where @var{line} is a string and @var{value} is the value to return if
1794 that @var{line} is chosen.  Unlike in a menu keymap, a @code{nil}
1795 @var{value} does not make the menu item non-selectable.
1796 Alternatively, each @var{item} can be a string rather than a cons
1797 cell; this makes a non-selectable menu item.
1799 If the user gets rid of the menu without making a valid choice, for
1800 instance by clicking the mouse away from a valid choice or by typing
1801 keyboard input, then this normally results in a quit and
1802 @code{x-popup-menu} does not return.  But if @var{position} is a mouse
1803 button event (indicating that the user invoked the menu with the
1804 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1805 @end defun
1807   @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1808 if you could do the job with a prefix key defined with a menu keymap.
1809 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1810 a} can see the individual items in that menu and provide help for them.
1811 If instead you implement the menu by defining a command that calls
1812 @code{x-popup-menu}, the help facilities cannot know what happens inside
1813 that command, so they cannot give any help for the menu's items.
1815   The menu bar mechanism, which lets you switch between submenus by
1816 moving the mouse, cannot look within the definition of a command to see
1817 that it calls @code{x-popup-menu}.  Therefore, if you try to implement a
1818 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1819 an integrated fashion.  This is why all menu bar submenus are
1820 implemented with menu keymaps within the parent menu, and never with
1821 @code{x-popup-menu}.  @xref{Menu Bar}.
1823   If you want a menu bar submenu to have contents that vary, you should
1824 still use a menu keymap to implement it.  To make the contents vary, add
1825 a hook function to @code{menu-bar-update-hook} to update the contents of
1826 the menu keymap as necessary.
1828 @node Dialog Boxes
1829 @section Dialog Boxes
1830 @cindex dialog boxes
1832   A dialog box is a variant of a pop-up menu---it looks a little
1833 different, it always appears in the center of a frame, and it has just
1834 one level and one or more buttons.  The main use of dialog boxes is
1835 for asking questions that the user can answer with ``yes'', ``no'',
1836 and a few other alternatives.  With a single button, they can also
1837 force the user to acknowledge important information.  The functions
1838 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1839 keyboard, when called from commands invoked by mouse clicks.
1841 @defun x-popup-dialog position contents &optional header
1842 This function displays a pop-up dialog box and returns an indication of
1843 what selection the user makes.  The argument @var{contents} specifies
1844 the alternatives to offer; it has this format:
1846 @example
1847 (@var{title} (@var{string} . @var{value})@dots{})
1848 @end example
1850 @noindent
1851 which looks like the list that specifies a single pane for
1852 @code{x-popup-menu}.
1854 The return value is @var{value} from the chosen alternative.
1856 As for @code{x-popup-menu}, an element of the list may be just a
1857 string instead of a cons cell @code{(@var{string} . @var{value})}.
1858 That makes a box that cannot be selected.
1860 If @code{nil} appears in the list, it separates the left-hand items from
1861 the right-hand items; items that precede the @code{nil} appear on the
1862 left, and items that follow the @code{nil} appear on the right.  If you
1863 don't include a @code{nil} in the list, then approximately half the
1864 items appear on each side.
1866 Dialog boxes always appear in the center of a frame; the argument
1867 @var{position} specifies which frame.  The possible values are as in
1868 @code{x-popup-menu}, but the precise coordinates or the individual
1869 window don't matter; only the frame matters.
1871 If @var{header} is non-@code{nil}, the frame title for the box is
1872 @samp{Information}, otherwise it is @samp{Question}.  The former is used
1873 for @code{message-box} (@pxref{message-box}).
1875 In some configurations, Emacs cannot display a real dialog box; so
1876 instead it displays the same items in a pop-up menu in the center of the
1877 frame.
1879 If the user gets rid of the dialog box without making a valid choice,
1880 for instance using the window manager, then this produces a quit and
1881 @code{x-popup-dialog} does not return.
1882 @end defun
1884 @node Pointer Shape
1885 @section Pointer Shape
1886 @cindex pointer shape
1887 @cindex mouse pointer shape
1889   You can specify the mouse pointer style for particular text or
1890 images using the @code{pointer} text property, and for images with the
1891 @code{:pointer} and @code{:map} image properties.  The values you can
1892 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1893 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1894 @code{hourglass}.  @code{text} stands for the usual mouse pointer
1895 style used over text.
1897   Over void parts of the window (parts that do not correspond to any
1898 of the buffer contents), the mouse pointer usually uses the
1899 @code{arrow} style, but you can specify a different style (one of
1900 those above) by setting @code{void-text-area-pointer}.
1902 @defopt void-text-area-pointer
1903 This variable specifies the mouse pointer style for void text areas.
1904 These include the areas after the end of a line or below the last line
1905 in the buffer.  The default is to use the @code{arrow} (non-text)
1906 pointer style.
1907 @end defopt
1909   When using X, you can specify what the @code{text} pointer style
1910 really looks like by setting the variable @code{x-pointer-shape}.
1912 @defvar x-pointer-shape
1913 This variable specifies the pointer shape to use ordinarily in the
1914 Emacs frame, for the @code{text} pointer style.
1915 @end defvar
1917 @defvar x-sensitive-text-pointer-shape
1918 This variable specifies the pointer shape to use when the mouse
1919 is over mouse-sensitive text.
1920 @end defvar
1922   These variables affect newly created frames.  They do not normally
1923 affect existing frames; however, if you set the mouse color of a
1924 frame, that also installs the current value of those two variables.
1925 @xref{Font and Color Parameters}.
1927   The values you can use, to specify either of these pointer shapes, are
1928 defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
1929 @key{RET} x-pointer @key{RET}} to see a list of them.
1931 @node Window System Selections
1932 @section Window System Selections
1933 @cindex selection (for window systems)
1934 @cindex clipboard
1935 @cindex primary selection
1936 @cindex secondary selection
1938   In the X window system, data can be transferred between different
1939 applications by means of @dfn{selections}.  X defines an arbitrary
1940 number of @dfn{selection types}, each of which can store its own data;
1941 however, only three are commonly used: the @dfn{clipboard},
1942 @dfn{primary selection}, and @dfn{secondary selection}.  @xref{Cut and
1943 Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
1944 commands that make use of these selections.  This section documents
1945 the low-level functions for reading and setting X selections.
1947 @deffn Command x-set-selection type data
1948 This function sets an X selection.  It takes two arguments: a
1949 selection type @var{type}, and the value to assign to it, @var{data}.
1951 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
1952 @code{SECONDARY} or @code{CLIPBOARD}.  These are symbols with
1953 upper-case names, in accord with X Window System conventions.  If
1954 @var{type} is @code{nil}, that stands for @code{PRIMARY}.
1956 If @var{data} is @code{nil}, it means to clear out the selection.
1957 Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
1958 of two integers or list of two integers), an overlay, or a cons of two
1959 markers pointing to the same buffer.  An overlay or a pair of markers
1960 stands for text in the overlay or between the markers.  The argument
1961 @var{data} may also be a vector of valid non-vector selection values.
1963 This function returns @var{data}.
1964 @end deffn
1966 @defun x-get-selection &optional type data-type
1967 This function accesses selections set up by Emacs or by other X
1968 clients.  It takes two optional arguments, @var{type} and
1969 @var{data-type}.  The default for @var{type}, the selection type, is
1970 @code{PRIMARY}.
1972 The @var{data-type} argument specifies the form of data conversion to
1973 use, to convert the raw data obtained from another X client into Lisp
1974 data.  Meaningful values include @code{TEXT}, @code{STRING},
1975 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1976 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1977 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1978 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
1979 @code{INTEGER}.  (These are symbols with upper-case names in accord
1980 with X conventions.)  The default for @var{data-type} is
1981 @code{STRING}.
1982 @end defun
1984 @defopt selection-coding-system
1985 This variable specifies the coding system to use when reading and
1986 writing selections or the clipboard.  @xref{Coding
1987 Systems}.  The default is @code{compound-text-with-extensions}, which
1988 converts to the text representation that X11 normally uses.
1989 @end defopt
1991 @cindex clipboard support (for MS-Windows)
1992 When Emacs runs on MS-Windows, it does not implement X selections in
1993 general, but it does support the clipboard.  @code{x-get-selection}
1994 and @code{x-set-selection} on MS-Windows support the text data type
1995 only; if the clipboard holds other types of data, Emacs treats the
1996 clipboard as empty.
1998 @node Drag and Drop
1999 @section Drag and Drop
2001 @vindex x-dnd-test-function
2002 @vindex x-dnd-known-types
2003   When a user drags something from another application over Emacs, that other
2004 application expects Emacs to tell it if Emacs can handle the data that is
2005 dragged.  The variable @code{x-dnd-test-function} is used by Emacs to determine
2006 what to reply.  The default value is @code{x-dnd-default-test-function}
2007 which accepts drops if the type of the data to be dropped is present in
2008 @code{x-dnd-known-types}.  You can customize @code{x-dnd-test-function} and/or
2009 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
2010 on some other criteria.
2012 @vindex x-dnd-types-alist
2013   If you want to change the way Emacs handles drop of different types
2014 or add a new type, customize @code{x-dnd-types-alist}.  This requires
2015 detailed knowledge of what types other applications use for drag and
2016 drop.
2018 @vindex dnd-protocol-alist
2019   When an URL is dropped on Emacs it may be a file, but it may also be
2020 another URL type (ftp, http, etc.).  Emacs first checks
2021 @code{dnd-protocol-alist} to determine what to do with the URL.  If
2022 there is no match there and if @code{browse-url-browser-function} is
2023 an alist, Emacs looks for a match there.  If no match is found the
2024 text for the URL is inserted.  If you want to alter Emacs behavior,
2025 you can customize these variables.
2027 @node Color Names
2028 @section Color Names
2030 @cindex color names
2031 @cindex specify color
2032 @cindex numerical RGB color specification
2033   A color name is text (usually in a string) that specifies a color.
2034 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2035 are allowed; use @kbd{M-x list-colors-display} to see a list of
2036 defined names.  You can also specify colors numerically in forms such
2037 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2038 @var{r} specifies the red level, @var{g} specifies the green level,
2039 and @var{b} specifies the blue level.  You can use either one, two,
2040 three, or four hex digits for @var{r}; then you must use the same
2041 number of hex digits for all @var{g} and @var{b} as well, making
2042 either 3, 6, 9 or 12 hex digits in all.  (See the documentation of the
2043 X Window System for more details about numerical RGB specification of
2044 colors.)
2046   These functions provide a way to determine which color names are
2047 valid, and what they look like.  In some cases, the value depends on the
2048 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2049 meaning of the term ``selected frame''.
2051   To read user input of color names with completion, use
2052 @code{read-color} (@pxref{High-Level Completion, read-color}).
2054 @defun color-defined-p color &optional frame
2055 This function reports whether a color name is meaningful.  It returns
2056 @code{t} if so; otherwise, @code{nil}.  The argument @var{frame} says
2057 which frame's display to ask about; if @var{frame} is omitted or
2058 @code{nil}, the selected frame is used.
2060 Note that this does not tell you whether the display you are using
2061 really supports that color.  When using X, you can ask for any defined
2062 color on any kind of display, and you will get some result---typically,
2063 the closest it can do.  To determine whether a frame can really display
2064 a certain color, use @code{color-supported-p} (see below).
2066 @findex x-color-defined-p
2067 This function used to be called @code{x-color-defined-p},
2068 and that name is still supported as an alias.
2069 @end defun
2071 @defun defined-colors &optional frame
2072 This function returns a list of the color names that are defined
2073 and supported on frame @var{frame} (default, the selected frame).
2074 If @var{frame} does not support colors, the value is @code{nil}.
2076 @findex x-defined-colors
2077 This function used to be called @code{x-defined-colors},
2078 and that name is still supported as an alias.
2079 @end defun
2081 @defun color-supported-p color &optional frame background-p
2082 This returns @code{t} if @var{frame} can really display the color
2083 @var{color} (or at least something close to it).  If @var{frame} is
2084 omitted or @code{nil}, the question applies to the selected frame.
2086 Some terminals support a different set of colors for foreground and
2087 background.  If @var{background-p} is non-@code{nil}, that means you are
2088 asking whether @var{color} can be used as a background; otherwise you
2089 are asking whether it can be used as a foreground.
2091 The argument @var{color} must be a valid color name.
2092 @end defun
2094 @defun color-gray-p color &optional frame
2095 This returns @code{t} if @var{color} is a shade of gray, as defined on
2096 @var{frame}'s display.  If @var{frame} is omitted or @code{nil}, the
2097 question applies to the selected frame.  If @var{color} is not a valid
2098 color name, this function returns @code{nil}.
2099 @end defun
2101 @defun color-values color &optional frame
2102 @cindex rgb value
2103 This function returns a value that describes what @var{color} should
2104 ideally look like on @var{frame}.  If @var{color} is defined, the
2105 value is a list of three integers, which give the amount of red, the
2106 amount of green, and the amount of blue.  Each integer ranges in
2107 principle from 0 to 65535, but some displays may not use the full
2108 range.  This three-element list is called the @dfn{rgb values} of the
2109 color.
2111 If @var{color} is not defined, the value is @code{nil}.
2113 @example
2114 (color-values "black")
2115      @result{} (0 0 0)
2116 (color-values "white")
2117      @result{} (65280 65280 65280)
2118 (color-values "red")
2119      @result{} (65280 0 0)
2120 (color-values "pink")
2121      @result{} (65280 49152 51968)
2122 (color-values "hungry")
2123      @result{} nil
2124 @end example
2126 The color values are returned for @var{frame}'s display.  If
2127 @var{frame} is omitted or @code{nil}, the information is returned for
2128 the selected frame's display.  If the frame cannot display colors, the
2129 value is @code{nil}.
2131 @findex x-color-values
2132 This function used to be called @code{x-color-values},
2133 and that name is still supported as an alias.
2134 @end defun
2136 @node Text Terminal Colors
2137 @section Text Terminal Colors
2138 @cindex colors on text terminals
2140   Text terminals usually support only a small number of colors, and
2141 the computer uses small integers to select colors on the terminal.
2142 This means that the computer cannot reliably tell what the selected
2143 color looks like; instead, you have to inform your application which
2144 small integers correspond to which colors.  However, Emacs does know
2145 the standard set of colors and will try to use them automatically.
2147   The functions described in this section control how terminal colors
2148 are used by Emacs.
2150   Several of these functions use or return @dfn{rgb values}, described
2151 in @ref{Color Names}.
2153   These functions accept a display (either a frame or the name of a
2154 terminal) as an optional argument.  We hope in the future to make
2155 Emacs support different colors on different text terminals; then this
2156 argument will specify which terminal to operate on (the default being
2157 the selected frame's terminal; @pxref{Input Focus}).  At present,
2158 though, the @var{frame} argument has no effect.
2160 @defun tty-color-define name number &optional rgb frame
2161 This function associates the color name @var{name} with
2162 color number @var{number} on the terminal.
2164 The optional argument @var{rgb}, if specified, is an rgb value, a list
2165 of three numbers that specify what the color actually looks like.
2166 If you do not specify @var{rgb}, then this color cannot be used by
2167 @code{tty-color-approximate} to approximate other colors, because
2168 Emacs will not know what it looks like.
2169 @end defun
2171 @defun tty-color-clear &optional frame
2172 This function clears the table of defined colors for a text terminal.
2173 @end defun
2175 @defun tty-color-alist &optional frame
2176 This function returns an alist recording the known colors supported by
2177 a text terminal.
2179 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2180 or @code{(@var{name} @var{number})}.  Here, @var{name} is the color
2181 name, @var{number} is the number used to specify it to the terminal.
2182 If present, @var{rgb} is a list of three color values (for red, green,
2183 and blue) that says what the color actually looks like.
2184 @end defun
2186 @defun tty-color-approximate rgb &optional frame
2187 This function finds the closest color, among the known colors
2188 supported for @var{display}, to that described by the rgb value
2189 @var{rgb} (a list of color values).  The return value is an element of
2190 @code{tty-color-alist}.
2191 @end defun
2193 @defun tty-color-translate color &optional frame
2194 This function finds the closest color to @var{color} among the known
2195 colors supported for @var{display} and returns its index (an integer).
2196 If the name @var{color} is not defined, the value is @code{nil}.
2197 @end defun
2199 @node Resources
2200 @section X Resources
2202 This section describes some of the functions and variables for
2203 querying and using X resources, or their equivalent on your operating
2204 system.  @xref{X Resources,, X Resources, emacs, The GNU Emacs
2205 Manual}, for more information about X resources.
2207 @defun x-get-resource attribute class &optional component subclass
2208 The function @code{x-get-resource} retrieves a resource value from the X
2209 Window defaults database.
2211 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2212 This function searches using a key of the form
2213 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2214 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2215 the class.
2217 The optional arguments @var{component} and @var{subclass} add to the key
2218 and the class, respectively.  You must specify both of them or neither.
2219 If you specify them, the key is
2220 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2221 @samp{Emacs.@var{class}.@var{subclass}}.
2222 @end defun
2224 @defvar x-resource-class
2225 This variable specifies the application name that @code{x-get-resource}
2226 should look up.  The default value is @code{"Emacs"}.  You can examine X
2227 resources for application names other than ``Emacs'' by binding this
2228 variable to some other string, around a call to @code{x-get-resource}.
2229 @end defvar
2231 @defvar x-resource-name
2232 This variable specifies the instance name that @code{x-get-resource}
2233 should look up.  The default value is the name Emacs was invoked with,
2234 or the value specified with the @samp{-name} or @samp{-rn} switches.
2235 @end defvar
2237 To illustrate some of the above, suppose that you have the line:
2239 @example
2240 xterm.vt100.background: yellow
2241 @end example
2243 @noindent
2244 in your X resources file (whose name is usually @file{~/.Xdefaults}
2245 or @file{~/.Xresources}).  Then:
2247 @example
2248 @group
2249 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2250   (x-get-resource "vt100.background" "VT100.Background"))
2251      @result{} "yellow"
2252 @end group
2253 @group
2254 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2255   (x-get-resource "background" "VT100" "vt100" "Background"))
2256      @result{} "yellow"
2257 @end group
2258 @end example
2260 @defvar inhibit-x-resources
2261 If this variable is non-@code{nil}, Emacs does not look up X
2262 resources, and X resources do not have any effect when creating new
2263 frames.
2264 @end defvar
2266 @node Display Feature Testing
2267 @section Display Feature Testing
2268 @cindex display feature testing
2270   The functions in this section describe the basic capabilities of a
2271 particular display.  Lisp programs can use them to adapt their behavior
2272 to what the display can do.  For example, a program that ordinarily uses
2273 a popup menu could use the minibuffer if popup menus are not supported.
2275   The optional argument @var{display} in these functions specifies which
2276 display to ask the question about.  It can be a display name, a frame
2277 (which designates the display that frame is on), or @code{nil} (which
2278 refers to the selected frame's display, @pxref{Input Focus}).
2280   @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2281 obtain information about displays.
2283 @defun display-popup-menus-p &optional display
2284 This function returns @code{t} if popup menus are supported on
2285 @var{display}, @code{nil} if not.  Support for popup menus requires that
2286 the mouse be available, since the user cannot choose menu items without
2287 a mouse.
2288 @end defun
2290 @defun display-graphic-p &optional display
2291 This function returns @code{t} if @var{display} is a graphic display
2292 capable of displaying several frames and several different fonts at
2293 once.  This is true for displays that use a window system such as X,
2294 and false for text terminals.
2295 @end defun
2297 @defun display-mouse-p &optional display
2298 @cindex mouse, availability
2299 This function returns @code{t} if @var{display} has a mouse available,
2300 @code{nil} if not.
2301 @end defun
2303 @defun display-color-p &optional display
2304 @findex x-display-color-p
2305 This function returns @code{t} if the screen is a color screen.
2306 It used to be called @code{x-display-color-p}, and that name
2307 is still supported as an alias.
2308 @end defun
2310 @defun display-grayscale-p &optional display
2311 This function returns @code{t} if the screen can display shades of gray.
2312 (All color displays can do this.)
2313 @end defun
2315 @defun display-supports-face-attributes-p attributes &optional display
2316 @anchor{Display Face Attribute Testing}
2317 This function returns non-@code{nil} if all the face attributes in
2318 @var{attributes} are supported (@pxref{Face Attributes}).
2320 The definition of `supported' is somewhat heuristic, but basically
2321 means that a face containing all the attributes in @var{attributes},
2322 when merged with the default face for display, can be represented in a
2323 way that's
2325 @enumerate
2326 @item
2327 different in appearance than the default face, and
2329 @item
2330 `close in spirit' to what the attributes specify, if not exact.
2331 @end enumerate
2333 Point (2) implies that a @code{:weight black} attribute will be
2334 satisfied by any display that can display bold, as will
2335 @code{:foreground "yellow"} as long as some yellowish color can be
2336 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2337 the tty display code's automatic substitution of a `dim' face for
2338 italic.
2339 @end defun
2341 @defun display-selections-p &optional display
2342 This function returns @code{t} if @var{display} supports selections.
2343 Windowed displays normally support selections, but they may also be
2344 supported in some other cases.
2345 @end defun
2347 @defun display-images-p &optional display
2348 This function returns @code{t} if @var{display} can display images.
2349 Windowed displays ought in principle to handle images, but some
2350 systems lack the support for that.  On a display that does not support
2351 images, Emacs cannot display a tool bar.
2352 @end defun
2354 @defun display-screens &optional display
2355 This function returns the number of screens associated with the display.
2356 @end defun
2358 @defun display-pixel-height &optional display
2359 This function returns the height of the screen in pixels.
2360 On a character terminal, it gives the height in characters.
2362 For graphical terminals, note that on ``multi-monitor'' setups this
2363 refers to the pixel width for all physical monitors associated with
2364 @var{display}.  @xref{Multiple Terminals}.
2365 @end defun
2367 @defun display-pixel-width &optional display
2368 This function returns the width of the screen in pixels.
2369 On a character terminal, it gives the width in characters.
2371 For graphical terminals, note that on ``multi-monitor'' setups this
2372 refers to the pixel width for all physical monitors associated with
2373 @var{display}.  @xref{Multiple Terminals}.
2374 @end defun
2376 @defun display-mm-height &optional display
2377 This function returns the height of the screen in millimeters,
2378 or @code{nil} if Emacs cannot get that information.
2379 @end defun
2381 @defun display-mm-width &optional display
2382 This function returns the width of the screen in millimeters,
2383 or @code{nil} if Emacs cannot get that information.
2384 @end defun
2386 @defopt display-mm-dimensions-alist
2387 This variable allows the user to specify the dimensions of graphical
2388 displays returned by @code{display-mm-height} and
2389 @code{display-mm-width} in case the system provides incorrect values.
2390 @end defopt
2392 @defun display-backing-store &optional display
2393 This function returns the backing store capability of the display.
2394 Backing store means recording the pixels of windows (and parts of
2395 windows) that are not exposed, so that when exposed they can be
2396 displayed very quickly.
2398 Values can be the symbols @code{always}, @code{when-mapped}, or
2399 @code{not-useful}.  The function can also return @code{nil}
2400 when the question is inapplicable to a certain kind of display.
2401 @end defun
2403 @defun display-save-under &optional display
2404 This function returns non-@code{nil} if the display supports the
2405 SaveUnder feature.  That feature is used by pop-up windows
2406 to save the pixels they obscure, so that they can pop down
2407 quickly.
2408 @end defun
2410 @defun display-planes &optional display
2411 This function returns the number of planes the display supports.
2412 This is typically the number of bits per pixel.
2413 For a tty display, it is log to base two of the number of colors supported.
2414 @end defun
2416 @defun display-visual-class &optional display
2417 This function returns the visual class for the screen.  The value is
2418 one of the symbols @code{static-gray} (a limited, unchangeable number
2419 of grays), @code{gray-scale} (a full range of grays),
2420 @code{static-color} (a limited, unchangeable number of colors),
2421 @code{pseudo-color} (a limited number of colors), @code{true-color} (a
2422 full range of colors), and @code{direct-color} (a full range of
2423 colors).
2424 @end defun
2426 @defun display-color-cells &optional display
2427 This function returns the number of color cells the screen supports.
2428 @end defun
2430   These functions obtain additional information specifically
2431 about X displays.
2433 @defun x-server-version &optional display
2434 This function returns the list of version numbers of the X server
2435 running the display.  The value is a list of three integers: the major
2436 and minor version numbers of the X protocol, and the
2437 distributor-specific release number of the X server software itself.
2438 @end defun
2440 @defun x-server-vendor &optional display
2441 This function returns the ``vendor'' that provided the X server
2442 software (as a string).  Really this means whoever distributes the X
2443 server.
2445 When the developers of X labeled software distributors as
2446 ``vendors'', they showed their false assumption that no system could
2447 ever be developed and distributed noncommercially.
2448 @end defun
2450 @ignore
2451 @defvar x-no-window-manager
2452 This variable's value is @code{t} if no X window manager is in use.
2453 @end defvar
2454 @end ignore
2456 @ignore
2457 @item
2458 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2459 width and height of an X Window frame, measured in pixels.
2460 @end ignore