* doc/emacs/frames.texi (Input Focus): Fix doc for select-frame-set-input-focus.
[emacs.git] / doc / lispref / frames.texi
blob27303637e42a69be03087da1e9db299daa3d8690
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
4 @c   Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/frames
7 @node Frames, Positions, Windows, Top
8 @chapter Frames
9 @cindex frame
11   A @dfn{frame} is a screen object that contains one or more Emacs
12 windows (@pxref{Windows}).  It is the kind of object called a
13 ``window'' in the terminology of graphical environments; but we can't
14 call it a ``window'' here, because Emacs uses that word in a different
15 way.  In Emacs Lisp, a @dfn{frame object} is a Lisp object that
16 represents a frame on the screen.  @xref{Frame Type}.
18   A frame initially contains a single main window and/or a minibuffer
19 window; you can subdivide the main window vertically or horizontally
20 into smaller windows.  @xref{Splitting Windows}.
22 @cindex terminal
23   A @dfn{terminal} is a display device capable of displaying one or
24 more Emacs frames.  In Emacs Lisp, a @dfn{terminal object} is a Lisp
25 object that represents a terminal.  @xref{Terminal Type}.
27 @cindex terminal frame
28 @cindex window frame
29   There are two classes of terminals: text-only terminals and
30 graphical terminals.  Text-only terminals are non-graphics-capable
31 display devices, including ``terminal emulators'' such as xterm.  On
32 text-only terminals, each frame occupies the entire terminal screen;
33 although you can create additional frames and switch between them,
34 only one frame can be shown at any given time.  We refer to frames on
35 text-only terminals as @dfn{terminal frames}.  Graphical terminals, on
36 the other hand, are graphics-capable windowing systems, such as the X
37 Window System.  On a graphical terminal, Emacs can display multiple
38 frames simultaneously.  We refer to such frames as @dfn{window
39 frames}.
41   On GNU and Unix systems, you can create additional frames on any
42 available terminal, within a single Emacs session, regardless of
43 whether Emacs was started on a text-only or graphical terminal.  Emacs
44 can display on both graphical and text-only terminals simultaneously.
45 This comes in handy, for instance, when you connect to the same
46 session from several remote locations.  @xref{Multiple Terminals}.
48 @defun framep object
49 This predicate returns a non-@code{nil} value if @var{object} is a
50 frame, and @code{nil} otherwise.  For a frame, the value indicates which
51 kind of display the frame uses:
53 @table @code
54 @item x
55 The frame is displayed in an X window.
56 @item t
57 A terminal frame on a character display.
58 @item w32
59 The frame is displayed on MS-Windows 9X/NT.
60 @item ns
61 The frame is displayed on a GNUstep or Macintosh Cocoa display.
62 @item pc
63 The frame is displayed on an MS-DOS terminal.
64 @end table
65 @end defun
67 @defun frame-terminal &optional frame
68 This function returns the terminal object that displays @var{frame}.
69 If @var{frame} is @code{nil} or unspecified, it defaults to the
70 selected frame.
71 @end defun
73 @defun terminal-live-p object
74 This predicate returns a non-@code{nil} value if @var{object} is a
75 terminal that is alive (i.e.@: was not deleted), and @code{nil}
76 otherwise.  For live terminals, the return value indicates what kind
77 of frames are displayed on that terminal; the list of possible values
78 is the same as for @code{framep} above.
79 @end defun
81 @menu
82 * Creating Frames::             Creating additional frames.
83 * Multiple Terminals::          Displaying on several different devices.
84 * Frame Parameters::            Controlling frame size, position, font, etc.
85 * Terminal Parameters::         Parameters common for all frames on terminal.
86 * Frame Titles::                Automatic updating of frame titles.
87 * Deleting Frames::             Frames last until explicitly deleted.
88 * Finding All Frames::          How to examine all existing frames.
89 * Minibuffers and Frames::      How a frame finds the minibuffer to use.
90 * Input Focus::                 Specifying the selected frame.
91 * Visibility of Frames::        Frames may be visible or invisible, or icons.
92 * Raising and Lowering::        Raising a frame makes it hide other windows;
93                                   lowering it makes the others hide it.
94 * Frame Configurations::        Saving the state of all frames.
95 * Mouse Tracking::              Getting events that say when the mouse moves.
96 * Mouse Position::              Asking where the mouse is, or moving it.
97 * Pop-Up Menus::                Displaying a menu for the user to select from.
98 * Dialog Boxes::                Displaying a box to ask yes or no.
99 * Pointer Shape::               Specifying the shape of the mouse pointer.
100 * Window System Selections::    Transferring text to and from other X clients.
101 * Drag and Drop::               Internals of Drag-and-Drop implementation.
102 * Color Names::                 Getting the definitions of color names.
103 * Text Terminal Colors::        Defining colors for text-only terminals.
104 * Resources::                   Getting resource values from the server.
105 * Display Feature Testing::     Determining the features of a terminal.
106 @end menu
108 @node Creating Frames
109 @section Creating Frames
111 To create a new frame, call the function @code{make-frame}.
113 @defun make-frame &optional alist
114 This function creates and returns a new frame, displaying the current
115 buffer.
117 The @var{alist} argument is an alist that specifies frame parameters
118 for the new frame.  @xref{Frame Parameters}.  If you specify the
119 @code{terminal} parameter in @var{alist}, the new frame is created on
120 that terminal.  Otherwise, if you specify the @code{window-system}
121 frame parameter in @var{alist}, that determines whether the frame
122 should be displayed on a text-only or graphical terminal.
123 @xref{Window Systems}.  If neither is specified, the new frame is
124 created in the same terminal as the selected frame.
126 Any parameters not mentioned in @var{alist} default to the values in
127 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
128 parameters not specified there default from the X resources or its
129 equivalent on your operating system (@pxref{X Resources,, X Resources,
130 emacs, The GNU Emacs Manual}).  After the frame is created, Emacs
131 applies any parameters listed in @code{frame-inherited-parameters}
132 (see below) and not present in the argument, taking the values from
133 the frame that was selected when @code{make-frame} was called.
135 This function itself does not make the new frame the selected frame.
136 @xref{Input Focus}.  The previously selected frame remains selected.
137 On graphical terminals, however, the windowing system may select the
138 new frame for its own reasons.
139 @end defun
141 @defvar before-make-frame-hook
142 A normal hook run by @code{make-frame} before it creates the frame.
143 @end defvar
145 @defvar after-make-frame-functions
146 An abnormal hook run by @code{make-frame} after it creates the frame.
147 Each function in @code{after-make-frame-functions} receives one argument, the
148 frame just created.
149 @end defvar
151 @defvar frame-inherited-parameters
152 This variable specifies the list of frame parameters that a newly
153 created frame inherits from the currently selected frame.  For each
154 parameter (a symbol) that is an element in the list and is not present
155 in the argument to @code{make-frame}, the function sets the value of
156 that parameter in the created frame to its value in the selected
157 frame.
158 @end defvar
160 @node Multiple Terminals
161 @section Multiple Terminals
162 @cindex multiple terminals
163 @cindex multi-tty
164 @cindex multiple X displays
165 @cindex displays, multiple
167   Emacs represents each terminal, whether graphical or text-only, as a
168 @dfn{terminal object} data type (@pxref{Terminal Type}).  On GNU and
169 Unix systems, Emacs can use multiple terminals simultaneously in each
170 session.  On other systems, it can only use a single terminal.  Each
171 terminal object has the following attributes:
173 @itemize @bullet
174 @item
175 The name of the device used by the terminal (e.g., @samp{:0.0} or
176 @file{/dev/tty}).
178 @item
179 The terminal and keyboard coding systems used on the terminal.
180 @xref{Terminal I/O Encoding}.
182 @item
183 The kind of display associated with the terminal.  This is the symbol
184 returned by the function @code{terminal-live-p} (i.e., @code{x},
185 @code{t}, @code{w32}, @code{ns}, or @code{pc}).  @xref{Frames}.
187 @item
188 A list of terminal parameters.  @xref{Terminal Parameters}.
189 @end itemize
191   There is no primitive for creating terminal objects.  Emacs creates
192 them as needed, such as when you call @code{make-frame-on-display}
193 (which is described below).
195 @defun terminal-name &optional terminal
196 This function returns the file name of the device used by
197 @var{terminal}.  If @var{terminal} is omitted or @code{nil}, it
198 defaults to the selected frame's terminal.  @var{terminal} can also be
199 a frame, meaning that frame's terminal.
200 @end defun
202 @defun terminal-list
203 This function returns a list of all terminal objects currently in use.
204 @end defun
206 @defun get-device-terminal device
207 This function returns a terminal whose device name is given by
208 @var{device}.  If @var{device} is a string, it can be either the file
209 name of a terminal device, or the name of an X display of the form
210 @samp{@var{host}:@var{server}.@var{screen}}.  If @var{device} is a
211 frame, this function returns that frame's terminal; @code{nil} means
212 the selected frame.  Finally, if @var{device} is a terminal object
213 that represents a live terminal, that terminal is returned.  The
214 function signals an error if its argument is none of the above.
215 @end defun
217 @defun delete-terminal &optional terminal force
218 This function deletes all frames on @var{terminal} and frees the
219 resources used by it.  It runs the abnormal hook
220 @code{delete-terminal-functions}, passing @var{terminal} as the
221 argument to each function.
223 If @var{terminal} is omitted or @code{nil}, it defaults to the
224 selected frame's terminal.  @var{terminal} can also be a frame,
225 meaning that frame's terminal.
227 Normally, this function signals an error if you attempt to delete the
228 sole active terminal, but if @var{force} is non-@code{nil}, you are
229 allowed to do so.  Emacs automatically calls this function when the
230 last frame on a terminal is deleted (@pxref{Deleting Frames}).
231 @end defun
233 @defvar delete-terminal-functions
234 An abnormal hook run by @code{delete-terminal}.  Each function
235 receives one argument, the @var{terminal} argument passed to
236 @code{delete-terminal}.  Due to technical details, the functions may
237 be called either just before the terminal is deleted, or just
238 afterwards.
239 @end defvar
241 @cindex terminal-local variables
242   A few Lisp variables are @dfn{terminal-local}; that is, they have a
243 separate binding for each terminal.  The binding in effect at any time
244 is the one for the terminal that the currently selected frame belongs
245 to.  These variables include @code{default-minibuffer-frame},
246 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
247 @code{system-key-alist}.  They are always terminal-local, and can
248 never be buffer-local (@pxref{Buffer-Local Variables}).
250   On GNU and Unix systems, each X display is a separate graphical
251 terminal.  When Emacs is started from within the X window system, it
252 uses the X display chosen with the @code{DISPLAY} environment
253 variable, or with the @samp{--display} option.  @xref{Initial
254 Options,,, emacs, The GNU Emacs Manual}.  Emacs can connect to other X
255 displays via the command @code{make-frame-on-display}.  Each X display
256 has its own selected frame and its own minibuffer windows; however,
257 only one of those frames is ``@emph{the} selected frame'' at any given
258 moment (@pxref{Input Focus}).  Emacs can even connect to other
259 text-only terminals, by interacting with the @command{emacsclient}
260 program.  @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
262   A single X server can handle more than one display.  Each X display
263 has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
264 The first two parts, @var{host} and @var{server}, identify the X
265 server; the third part, @var{screen}, identifies a screen number on
266 that X server.  When you use two or more screens belonging to one
267 server, Emacs knows by the similarity in their names that they share a
268 single keyboard.
270   On some ``multi-monitor'' setups, a single X display outputs to more
271 than one monitor.  Currently, there is no way for Emacs to distinguish
272 between the different physical monitors.
274 @deffn Command make-frame-on-display display &optional parameters
275 This function creates and returns a new frame on @var{display}, taking
276 the other frame parameters from the alist @var{parameters}.
277 @var{display} should be the name of an X display (a string).
279 Before creating the frame, this function ensures that Emacs is ``set
280 up'' to display graphics.  For instance, if Emacs has not processed X
281 resources (e.g., if it was started on a text-only terminal), it does
282 so at this time.  In all other respects, this function behaves like
283 @code{make-frame} (@pxref{Creating Frames}).
284 @end deffn
286 @defun x-display-list
287 This function returns a list that indicates which X displays Emacs has
288 a connection to.  The elements of the list are strings, and each one
289 is a display name.
290 @end defun
292 @defun x-open-connection display &optional xrm-string must-succeed
293 This function opens a connection to the X display @var{display},
294 without creating a frame on that display.  Normally, Emacs Lisp
295 programs need not call this function, as @code{make-frame-on-display}
296 calls it automatically.  The only reason for calling it is to check
297 whether communication can be established with a given X display.
299 The optional argument @var{xrm-string}, if not @code{nil}, is a string
300 of resource names and values, in the same format used in the
301 @file{.Xresources} file.  @xref{X Resources,, X Resources, emacs, The
302 GNU Emacs Manual}.  These values apply to all Emacs frames created on
303 this display, overriding the resource values recorded in the X server.
304 Here's an example of what this string might look like:
306 @example
307 "*BorderWidth: 3\n*InternalBorder: 2\n"
308 @end example
310 If @var{must-succeed} is non-@code{nil}, failure to open the connection
311 terminates Emacs.  Otherwise, it is an ordinary Lisp error.
312 @end defun
314 @defun x-close-connection display
315 This function closes the connection to display @var{display}.  Before
316 you can do this, you must first delete all the frames that were open
317 on that display (@pxref{Deleting Frames}).
318 @end defun
320 @node Frame Parameters
321 @section Frame Parameters
322 @cindex frame parameters
324   A frame has many parameters that control its appearance and behavior.
325 Just what parameters a frame has depends on what display mechanism it
326 uses.
328   Frame parameters exist mostly for the sake of window systems.  A
329 terminal frame has a few parameters, mostly for compatibility's sake;
330 only the @code{height}, @code{width}, @code{name}, @code{title},
331 @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
332 parameters do something special.  If the terminal supports colors, the
333 parameters @code{foreground-color}, @code{background-color},
334 @code{background-mode} and @code{display-type} are also meaningful.
335 If the terminal supports frame transparency, the parameter
336 @code{alpha} is also meaningful.
338 @menu
339 * Parameter Access::       How to change a frame's parameters.
340 * Initial Parameters::     Specifying frame parameters when you make a frame.
341 * Window Frame Parameters:: List of frame parameters for window systems.
342 * Size and Position::      Changing the size and position of a frame.
343 * Geometry::               Parsing geometry specifications.
344 @end menu
346 @node Parameter Access
347 @subsection Access to Frame Parameters
349 These functions let you read and change the parameter values of a
350 frame.
352 @defun frame-parameter frame parameter
353 This function returns the value of the parameter @var{parameter} (a
354 symbol) of @var{frame}.  If @var{frame} is @code{nil}, it returns the
355 selected frame's parameter.  If @var{frame} has no setting for
356 @var{parameter}, this function returns @code{nil}.
357 @end defun
359 @defun frame-parameters &optional frame
360 The function @code{frame-parameters} returns an alist listing all the
361 parameters of @var{frame} and their values.  If @var{frame} is
362 @code{nil} or omitted, this returns the selected frame's parameters
363 @end defun
365 @defun modify-frame-parameters frame alist
366 This function alters the parameters of frame @var{frame} based on the
367 elements of @var{alist}.  Each element of @var{alist} has the form
368 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
369 parameter.  If you don't mention a parameter in @var{alist}, its value
370 doesn't change.  If @var{frame} is @code{nil}, it defaults to the selected
371 frame.
372 @end defun
374 @defun set-frame-parameter frame parm value
375 This function sets the frame parameter @var{parm} to the specified
376 @var{value}.  If @var{frame} is @code{nil}, it defaults to the
377 selected frame.
378 @end defun
380 @defun modify-all-frames-parameters alist
381 This function alters the frame parameters of all existing frames
382 according to @var{alist}, then modifies @code{default-frame-alist}
383 (and, if necessary, @code{initial-frame-alist}) to apply the same
384 parameter values to frames that will be created henceforth.
385 @end defun
387 @node Initial Parameters
388 @subsection Initial Frame Parameters
390 You can specify the parameters for the initial startup frame
391 by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
393 @defopt initial-frame-alist
394 This variable's value is an alist of parameter values used when creating
395 the initial window frame.  You can set this variable to specify the
396 appearance of the initial frame without altering subsequent frames.
397 Each element has the form:
399 @example
400 (@var{parameter} . @var{value})
401 @end example
403 Emacs creates the initial frame before it reads your init
404 file.  After reading that file, Emacs checks @code{initial-frame-alist},
405 and applies the parameter settings in the altered value to the already
406 created initial frame.
408 If these settings affect the frame geometry and appearance, you'll see
409 the frame appear with the wrong ones and then change to the specified
410 ones.  If that bothers you, you can specify the same geometry and
411 appearance with X resources; those do take effect before the frame is
412 created.  @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
414 X resource settings typically apply to all frames.  If you want to
415 specify some X resources solely for the sake of the initial frame, and
416 you don't want them to apply to subsequent frames, here's how to achieve
417 this.  Specify parameters in @code{default-frame-alist} to override the
418 X resources for subsequent frames; then, to prevent these from affecting
419 the initial frame, specify the same parameters in
420 @code{initial-frame-alist} with values that match the X resources.
421 @end defopt
423 If these parameters specify a separate minibuffer-only frame with
424 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
425 one for you.
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.  This is the
430 minibuffer-only frame that Emacs creates if @code{initial-frame-alist}
431 specifies a 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.
441 @end defopt
443 Functions that display a buffer in a separate frame can override the
444 default parameters by supplying their own parameters.  @xref{Definition
445 of special-display-frame-alist}.
447 If you use options that specify window appearance when you invoke Emacs,
448 they take effect by adding elements to @code{default-frame-alist}.  One
449 exception is @samp{-geometry}, which adds the specified position to
450 @code{initial-frame-alist} instead.  @xref{Emacs Invocation,, Command
451 Line 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 @emph{only} in
463 terminal frames.
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 @code{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-only 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 @emph{of the frame's icon}, in
565 pixels, counting from the left edge of the screen.  This takes effect if
566 and when the frame is iconified.
568 If you specify a value for this parameter, then you must also specify
569 a value for @code{icon-top} and vice versa.  The window manager may
570 ignore these two parameters.
572 @vindex icon-top, a frame parameter
573 @item icon-top
574 The screen position of the top edge @emph{of the frame's icon}, in
575 pixels, counting from the top edge of the screen.  This takes effect if
576 and when the frame is iconified.
578 @vindex user-position, a frame parameter
579 @item user-position
580 When you create a frame and specify its screen position with the
581 @code{left} and @code{top} parameters, use this parameter to say whether
582 the specified position was user-specified (explicitly requested in some
583 way by a human user) or merely program-specified (chosen by a program).
584 A non-@code{nil} value says the position was user-specified.
586 @cindex window positions and window managers
587 Window managers generally heed user-specified positions, and some heed
588 program-specified positions too.  But many ignore program-specified
589 positions, placing the window in a default fashion or letting the user
590 place it with the mouse.  Some window managers, including @code{twm},
591 let the user specify whether to obey program-specified positions or
592 ignore them.
594 When you call @code{make-frame}, you should specify a non-@code{nil}
595 value for this parameter if the values of the @code{left} and @code{top}
596 parameters represent the user's stated preference; otherwise, use
597 @code{nil}.
598 @end table
600 @node Size Parameters
601 @subsubsection Size Parameters
602 @cindex window size on display
604   Size parameters' values are normally measured in pixels, but on
605 text-only terminals they count characters or lines instead.
607 @table @code
608 @vindex height, a frame parameter
609 @item height
610 The height of the frame contents, in characters.  (To get the height in
611 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
613 @vindex width, a frame parameter
614 @item width
615 The width of the frame contents, in characters.  (To get the width in
616 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
618 @vindex user-size, a frame parameter
619 @item user-size
620 This does for the size parameters @code{height} and @code{width} what
621 the @code{user-position} parameter (@pxref{Position Parameters,
622 user-position}) does for the position parameters @code{top} and
623 @code{left}.
625 @cindex full-screen frames
626 @vindex fullscreen, a frame parameter
627 @item fullscreen
628 Specify that width, height or both shall be maximized.  The value
629 @code{fullwidth} specifies that width shall be as wide as possible.
630 The value @code{fullheight} specifies that height shall be as tall as
631 possible.  The value @code{fullboth} specifies that both the width and
632 the height shall be set to the size of the screen.  The value
633 @code{maximized} specifies that the frame shall be maximized.  The
634 difference between @code{maximized} and @code{fullboth} is that the
635 former still has window manager decorations while the latter really
636 covers the whole screen.
637 @end table
639 @node Layout Parameters
640 @subsubsection Layout Parameters
641 @cindex layout parameters of frames
642 @cindex frame layout parameters
644   These frame parameters enable or disable various parts of the
645 frame, or control their sizes.
647 @table @code
648 @vindex border-width, a frame parameter
649 @item border-width
650 The width in pixels of the frame's border.
652 @vindex internal-border-width, a frame parameter
653 @item internal-border-width
654 The distance in pixels between text (or fringe) and the frame's border.
656 @vindex vertical-scroll-bars, a frame parameter
657 @item vertical-scroll-bars
658 Whether the frame has scroll bars for vertical scrolling, and which side
659 of the frame they should be on.  The possible values are @code{left},
660 @code{right}, and @code{nil} for no scroll bars.
662 @ignore
663 @vindex horizontal-scroll-bars, a frame parameter
664 @item horizontal-scroll-bars
665 Whether the frame has scroll bars for horizontal scrolling
666 (non-@code{nil} means yes).  Horizontal scroll bars are not currently
667 implemented.
668 @end ignore
670 @vindex scroll-bar-width, a frame parameter
671 @item scroll-bar-width
672 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
673 use the default width.
675 @vindex left-fringe, a frame parameter
676 @vindex right-fringe, a frame parameter
677 @item left-fringe
678 @itemx right-fringe
679 The default width of the left and right fringes of windows in this
680 frame (@pxref{Fringes}).  If either of these is zero, that effectively
681 removes the corresponding fringe.
683 When you use @code{frame-parameter} to query the value of either of
684 these two frame parameters, the return value is always an integer.
685 When using @code{set-frame-parameter}, passing a @code{nil} value
686 imposes an actual default value of 8 pixels.
688 The combined fringe widths must add up to an integral number of
689 columns, so the actual default fringe widths for the frame, as
690 reported by @code{frame-parameter}, may be larger than what you
691 specify.  Any extra width is distributed evenly between the left and
692 right fringe.  However, you can force one fringe or the other to a
693 precise width by specifying that width as a negative integer.  If both
694 widths are negative, only the left fringe gets the specified width.
696 @vindex menu-bar-lines frame parameter
697 @item menu-bar-lines
698 The number of lines to allocate at the top of the frame for a menu
699 bar.  The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
700 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
702 @vindex tool-bar-lines frame parameter
703 @item tool-bar-lines
704 The number of lines to use for the tool bar.  The default is 1 if Tool
705 Bar mode is enabled, and 0 otherwise.  @xref{Tool Bars,,,emacs, The
706 GNU Emacs Manual}.
708 @vindex tool-bar-position frame parameter
709 @item tool-bar-position
710 The position of the tool bar.  Currently only for the GTK tool bar.
711 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
712 The default is  @code{top}.
714 @vindex line-spacing, a frame parameter
715 @item line-spacing
716 Additional space to leave below each text line, in pixels (a positive
717 integer).  @xref{Line Height}, for more information.
718 @end table
720 @node Buffer Parameters
721 @subsubsection Buffer Parameters
723   These frame parameters, meaningful on all kinds of terminals, deal
724 with which buffers have been, or should, be displayed in the frame.
726 @table @code
727 @vindex minibuffer, a frame parameter
728 @item minibuffer
729 Whether this frame has its own minibuffer.  The value @code{t} means
730 yes, @code{nil} means no, @code{only} means this frame is just a
731 minibuffer.  If the value is a minibuffer window (in some other
732 frame), the frame uses that minibuffer.
734 This frame parameter takes effect when the frame is created, and can
735 not be changed afterwards.
737 @vindex buffer-predicate, a frame parameter
738 @item buffer-predicate
739 The buffer-predicate function for this frame.  The function
740 @code{other-buffer} uses this predicate (from the selected frame) to
741 decide which buffers it should consider, if the predicate is not
742 @code{nil}.  It calls the predicate with one argument, a buffer, once for
743 each buffer; if the predicate returns a non-@code{nil} value, it
744 considers that buffer.
746 @vindex buffer-list, a frame parameter
747 @item buffer-list
748 A list of buffers that have been selected in this frame, ordered
749 most-recently-selected first.
751 @vindex unsplittable, a frame parameter
752 @item unsplittable
753 If non-@code{nil}, this frame's window is never split automatically.
754 @end table
756 @node Management Parameters
757 @subsubsection Window Management Parameters
758 @cindex window manager interaction, and frame parameters
760   These frame parameters, meaningful only on window system displays,
761 interact with the window manager.
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 Whether selecting the frame raises it (non-@code{nil} means yes).
774 @vindex auto-lower, a frame parameter
775 @item auto-lower
776 Whether deselecting the frame lowers it (non-@code{nil} means yes).
778 @vindex icon-type, a frame parameter
779 @item icon-type
780 The type of icon to use for this frame.  If the value is a string,
781 that specifies a file containing a bitmap to use; @code{nil} specifies
782 no icon (in which case the window manager decides what to show); any
783 other non-@code{nil} value specifies the default Emacs icon.
785 @vindex icon-name, a frame parameter
786 @item icon-name
787 The name to use in the icon for this frame, when and if the icon
788 appears.  If this is @code{nil}, the frame's title is used.
790 @vindex window-id, a frame parameter
791 @item window-id
792 The number of the window-system window used by the frame
793 to contain the actual Emacs windows.
795 @vindex outer-window-id, a frame parameter
796 @item outer-window-id
797 The number of the outermost window-system window used for the whole frame.
799 @vindex wait-for-wm, a frame parameter
800 @item wait-for-wm
801 If non-@code{nil}, tell Xt to wait for the window manager to confirm
802 geometry changes.  Some window managers, including versions of Fvwm2
803 and KDE, fail to confirm, so Xt hangs.  Set this to @code{nil} to
804 prevent hanging with those window managers.
806 @vindex sticky, a frame parameter
807 @item sticky
808 If non-@code{nil}, the frame is visible on all virtual desktops on systems
809 with virtual desktops.
811 @ignore
812 @vindex parent-id, a frame parameter
813 @item parent-id
814 @c ??? Not yet working.
815 The X window number of the window that should be the parent of this one.
816 Specifying this lets you create an Emacs window inside some other
817 application's window.  (It is not certain this will be implemented; try
818 it and see if it works.)
819 @end ignore
820 @end table
822 @node Cursor Parameters
823 @subsubsection Cursor Parameters
824 @cindex cursor, and frame parameters
826   This frame parameter controls the way the cursor looks.
828 @table @code
829 @vindex cursor-type, a frame parameter
830 @item cursor-type
831 How to display the cursor.  Legitimate values are:
833 @table @code
834 @item box
835 Display a filled box.  (This is the default.)
836 @item hollow
837 Display a hollow box.
838 @item nil
839 Don't display a cursor.
840 @item bar
841 Display a vertical bar between characters.
842 @item (bar . @var{width})
843 Display a vertical bar @var{width} pixels wide between characters.
844 @item hbar
845 Display a horizontal bar.
846 @item (hbar . @var{height})
847 Display a horizontal bar @var{height} pixels high.
848 @end table
849 @end table
851 @vindex cursor-type
852 The buffer-local variable @code{cursor-type} overrides the value of
853 the @code{cursor-type} frame parameter, but if it is @code{t}, that
854 means to use the cursor specified for the frame.
856 @defopt blink-cursor-alist
857 This variable specifies how to blink the cursor.  Each element has the
858 form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
859 type equals @var{on-state} (comparing using @code{equal}), the
860 corresponding @var{off-state} specifies what the cursor looks like
861 when it blinks ``off.''  Both @var{on-state} and @var{off-state}
862 should be suitable values for the @code{cursor-type} frame parameter.
864 There are various defaults for how to blink each type of cursor, if
865 the type is not mentioned as an @var{on-state} here.  Changes in this
866 variable do not take effect immediately, only when you specify the
867 @code{cursor-type} frame parameter.
868 @end defopt
870 @defopt cursor-in-non-selected-windows
871 This variable controls how the cursor looks in a window that is not
872 selected.  It supports the same values as the @code{cursor-type} frame
873 parameter; also, @code{nil} means don't display a cursor in
874 nonselected windows, and @code{t} (the default) means use a standard
875 modification of the usual cursor type (solid box becomes hollow box,
876 and bar becomes a narrower bar).
877 @end defopt
879 @node Font and Color Parameters
880 @subsubsection Font and Color Parameters
881 @cindex font and color, frame parameters
883   These frame parameters control the use of fonts and colors.
885 @table @code
886 @vindex font-backend, a frame parameter
887 @item font-backend
888 A list of symbols, specifying the @dfn{font backends} to use for
889 drawing fonts in the frame, in order of priority.  On X, there are
890 currently two available font backends: @code{x} (the X core font
891 driver) and @code{xft} (the Xft font driver).  On Windows, there are
892 currently two available font backends: @code{gdi} and
893 @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
894 Manual}).  On other systems, there is only one available font backend,
895 so it does not make sense to modify this frame parameter.
897 @vindex background-mode, a frame parameter
898 @item background-mode
899 This parameter is either @code{dark} or @code{light}, according
900 to whether the background color is a light one or a dark one.
902 @vindex tty-color-mode, a frame parameter
903 @item tty-color-mode
904 @cindex standard colors for character terminals
905 This parameter overrides the terminal's color support as given by the
906 system's terminal capabilities database in that this parameter's value
907 specifies the color mode to use in terminal frames.  The value can be
908 either a symbol or a number.  A number specifies the number of colors
909 to use (and, indirectly, what commands to issue to produce each
910 color).  For example, @code{(tty-color-mode . 8)} specifies use of the
911 ANSI escape sequences for 8 standard text colors.  A value of -1 turns
912 off color support.
914 If the parameter's value is a symbol, it specifies a number through
915 the value of @code{tty-color-mode-alist}, and the associated number is
916 used instead.
918 @vindex screen-gamma, a frame parameter
919 @item screen-gamma
920 @cindex gamma correction
921 If this is a number, Emacs performs ``gamma correction'' which adjusts
922 the brightness of all colors.  The value should be the screen gamma of
923 your display, a floating point number.
925 Usual PC monitors have a screen gamma of 2.2, so color values in
926 Emacs, and in X windows generally, are calibrated to display properly
927 on a monitor with that gamma value.  If you specify 2.2 for
928 @code{screen-gamma}, that means no correction is needed.  Other values
929 request correction, designed to make the corrected colors appear on
930 your screen the way they would have appeared without correction on an
931 ordinary monitor with a gamma value of 2.2.
933 If your monitor displays colors too light, you should specify a
934 @code{screen-gamma} value smaller than 2.2.  This requests correction
935 that makes colors darker.  A screen gamma value of 1.5 may give good
936 results for LCD color displays.
938 @vindex alpha, a frame parameter
939 @item alpha
940 @cindex opacity, frame
941 @cindex transparency, frame
942 @vindex frame-alpha-lower-limit
943 This parameter specifies the opacity of the frame, on graphical
944 displays that support variable opacity.  It should be an integer
945 between 0 and 100, where 0 means completely transparent and 100 means
946 completely opaque.  It can also have a @code{nil} value, which tells
947 Emacs not to set the frame opacity (leaving it to the window manager).
949 To prevent the frame from disappearing completely from view, the
950 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
951 If the value of the frame parameter is less than the value of this
952 variable, Emacs uses the latter.  By default,
953 @code{frame-alpha-lower-limit} is 20.
955 The @code{alpha} frame parameter can also be a cons cell
956 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
957 opacity of the frame when it is selected, and @samp{inactive} is the
958 opacity when it is not selected.
959 @end table
961 The following frame parameters are semi-obsolete in that they are
962 automatically equivalent to particular face attributes of particular
963 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
965 @table @code
966 @vindex font, a frame parameter
967 @item font
968 The name of the font for displaying text in the frame.  This is a
969 string, either a valid font name for your system or the name of an Emacs
970 fontset (@pxref{Fontsets}).  It is equivalent to the @code{font}
971 attribute of the @code{default} face.
973 @vindex foreground-color, a frame parameter
974 @item foreground-color
975 The color to use for the image of a character.  It is equivalent to
976 the @code{:foreground} attribute of the @code{default} face.
978 @vindex background-color, a frame parameter
979 @item background-color
980 The color to use for the background of characters.  It is equivalent to
981 the @code{:background} attribute of the @code{default} face.
983 @vindex mouse-color, a frame parameter
984 @item mouse-color
985 The color for the mouse pointer.  It is equivalent to the @code{:background}
986 attribute of the @code{mouse} face.
988 @vindex cursor-color, a frame parameter
989 @item cursor-color
990 The color for the cursor that shows point.  It is equivalent to the
991 @code{:background} attribute of the @code{cursor} face.
993 @vindex border-color, a frame parameter
994 @item border-color
995 The color for the border of the frame.  It is equivalent to the
996 @code{:background} attribute of the @code{border} face.
998 @vindex scroll-bar-foreground, a frame parameter
999 @item scroll-bar-foreground
1000 If non-@code{nil}, the color for the foreground of scroll bars.  It is
1001 equivalent to the @code{:foreground} attribute of the
1002 @code{scroll-bar} face.
1004 @vindex scroll-bar-background, a frame parameter
1005 @item scroll-bar-background
1006 If non-@code{nil}, the color for the background of scroll bars.  It is
1007 equivalent to the @code{:background} attribute of the
1008 @code{scroll-bar} face.
1009 @end table
1011 @node Size and Position
1012 @subsection Frame Size And Position
1013 @cindex size of frame
1014 @cindex screen size
1015 @cindex frame size
1016 @cindex resize frame
1018   You can read or change the size and position of a frame using the
1019 frame parameters @code{left}, @code{top}, @code{height}, and
1020 @code{width}.  Whatever geometry parameters you don't specify are chosen
1021 by the window manager in its usual fashion.
1023   Here are some special features for working with sizes and positions.
1024 (For the precise meaning of ``selected frame'' used by these functions,
1025 see @ref{Input Focus}.)
1027 @defun set-frame-position frame left top
1028 This function sets the position of the top left corner of @var{frame} to
1029 @var{left} and @var{top}.  These arguments are measured in pixels, and
1030 normally count from the top left corner of the screen.
1032 Negative parameter values position the bottom edge of the window up from
1033 the bottom edge of the screen, or the right window edge to the left of
1034 the right edge of the screen.  It would probably be better if the values
1035 were always counted from the left and top, so that negative arguments
1036 would position the frame partly off the top or left edge of the screen,
1037 but it seems inadvisable to change that now.
1038 @end defun
1040 @defun frame-height &optional frame
1041 @defunx frame-width &optional frame
1042 These functions return the height and width of @var{frame}, measured in
1043 lines and columns.  If you don't supply @var{frame}, they use the
1044 selected frame.
1045 @end defun
1047 @defun frame-pixel-height &optional frame
1048 @defunx frame-pixel-width &optional frame
1049 These functions return the height and width of the main display area
1050 of @var{frame}, measured in pixels.  If you don't supply @var{frame},
1051 they use the selected frame.  For a text-only terminal, the results are
1052 in characters rather than pixels.
1054 These values include the internal borders, and windows' scroll bars and
1055 fringes (which belong to individual windows, not to the frame itself).
1056 The exact value of the heights depends on the window-system and toolkit
1057 in use.  With Gtk+, the height does not include any tool bar or menu
1058 bar.  With the Motif or Lucid toolkits, it includes the tool bar but
1059 not the menu bar.  In a graphical version with no toolkit, it includes
1060 both the tool bar and menu bar.  For a text-only terminal, the result
1061 includes the menu bar.
1062 @end defun
1064 @defun frame-char-height &optional frame
1065 @defunx frame-char-width &optional frame
1066 These functions return the height and width of a character in
1067 @var{frame}, measured in pixels.  The values depend on the choice of
1068 font.  If you don't supply @var{frame}, these functions use the selected
1069 frame.
1070 @end defun
1072 @defun set-frame-size frame cols rows
1073 This function sets the size of @var{frame}, measured in characters;
1074 @var{cols} and @var{rows} specify the new width and height.
1076 To set the size based on values measured in pixels, use
1077 @code{frame-char-height} and @code{frame-char-width} to convert
1078 them to units of characters.
1079 @end defun
1081 @defun set-frame-height frame lines &optional pretend
1082 This function resizes @var{frame} to a height of @var{lines} lines.  The
1083 sizes of existing windows in @var{frame} are altered proportionally to
1084 fit.
1086 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
1087 lines of output in @var{frame}, but does not change its value for the
1088 actual height of the frame.  This is only useful for a terminal frame.
1089 Using a smaller height than the terminal actually implements may be
1090 useful to reproduce behavior observed on a smaller screen, or if the
1091 terminal malfunctions when using its whole screen.  Setting the frame
1092 height ``for real'' does not always work, because knowing the correct
1093 actual size may be necessary for correct cursor positioning on a
1094 terminal frame.
1095 @end defun
1097 @defun set-frame-width frame width &optional pretend
1098 This function sets the width of @var{frame}, measured in characters.
1099 The argument @var{pretend} has the same meaning as in
1100 @code{set-frame-height}.
1101 @end defun
1103 @findex set-screen-height
1104 @findex set-screen-width
1105   The older functions @code{set-screen-height} and
1106 @code{set-screen-width} were used to specify the height and width of the
1107 screen, in Emacs versions that did not support multiple frames.  They
1108 are semi-obsolete, but still work; they apply to the selected frame.
1110 @node Geometry
1111 @subsection Geometry
1113   Here's how to examine the data in an X-style window geometry
1114 specification:
1116 @defun x-parse-geometry geom
1117 @cindex geometry specification
1118 The function @code{x-parse-geometry} converts a standard X window
1119 geometry string to an alist that you can use as part of the argument to
1120 @code{make-frame}.
1122 The alist describes which parameters were specified in @var{geom}, and
1123 gives the values specified for them.  Each element looks like
1124 @code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
1125 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1127 For the size parameters, the value must be an integer.  The position
1128 parameter names @code{left} and @code{top} are not totally accurate,
1129 because some values indicate the position of the right or bottom edges
1130 instead.  The @var{value} possibilities for the position parameters are:
1131 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1132 as previously described (@pxref{Position Parameters}).
1134 Here is an example:
1136 @example
1137 (x-parse-geometry "35x70+0-0")
1138      @result{} ((height . 70) (width . 35)
1139          (top - 0) (left . 0))
1140 @end example
1141 @end defun
1143 @node Terminal Parameters
1144 @section Terminal Parameters
1145 @cindex terminal parameters
1147   Each terminal has a list of associated parameters.  These
1148 @dfn{terminal parameters} are mostly a convenient way of storage for
1149 terminal-local variables, but some terminal parameters have a special
1150 meaning.
1152   This section describes functions to read and change the parameter values
1153 of a terminal.  They all accept as their argument either a terminal or
1154 a frame; the latter means use that frame's terminal.  An argument of
1155 @code{nil} means the selected frame's terminal.
1157 @defun terminal-parameters &optional terminal
1158 This function returns an alist listing all the parameters of
1159 @var{terminal} and their values.
1160 @end defun
1162 @defun terminal-parameter terminal parameter
1163 This function returns the value of the parameter @var{parameter} (a
1164 symbol) of @var{terminal}.  If @var{terminal} has no setting for
1165 @var{parameter}, this function returns @code{nil}.
1166 @end defun
1168 @defun set-terminal-parameter terminal parameter value
1169 This function sets the parameter @var{parm} of @var{terminal} to the
1170 specified @var{value}, and returns the previous value of that
1171 parameter.
1172 @end defun
1174 Here's a list of a few terminal parameters that have a special
1175 meaning:
1177 @table @code
1178 @item background-mode
1179 The classification of the terminal's background color, either
1180 @code{light} or @code{dark}.
1181 @item normal-erase-is-backspace
1182 Value is either 1 or 0, depending on whether
1183 @code{normal-erase-is-backspace-mode} is turned on or off on this
1184 terminal.  @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1185 @item terminal-initted
1186 After the terminal is initialized, this is set to the
1187 terminal-specific initialization function.
1188 @end table
1190 @node Frame Titles
1191 @section Frame Titles
1192 @cindex frame title
1194   Every frame has a @code{name} parameter; this serves as the default
1195 for the frame title which window systems typically display at the top of
1196 the frame.  You can specify a name explicitly by setting the @code{name}
1197 frame property.
1199   Normally you don't specify the name explicitly, and Emacs computes the
1200 frame name automatically based on a template stored in the variable
1201 @code{frame-title-format}.  Emacs recomputes the name each time the
1202 frame is redisplayed.
1204 @defvar frame-title-format
1205 This variable specifies how to compute a name for a frame when you have
1206 not explicitly specified one.  The variable's value is actually a mode
1207 line construct, just like @code{mode-line-format}, except that the
1208 @samp{%c} and @samp{%l} constructs are ignored.  @xref{Mode Line
1209 Data}.
1210 @end defvar
1212 @defvar icon-title-format
1213 This variable specifies how to compute the name for an iconified frame,
1214 when you have not explicitly specified the frame title.  This title
1215 appears in the icon itself.
1216 @end defvar
1218 @defvar multiple-frames
1219 This variable is set automatically by Emacs.  Its value is @code{t} when
1220 there are two or more frames (not counting minibuffer-only frames or
1221 invisible frames).  The default value of @code{frame-title-format} uses
1222 @code{multiple-frames} so as to put the buffer name in the frame title
1223 only when there is more than one frame.
1225 The value of this variable is not guaranteed to be accurate except
1226 while processing @code{frame-title-format} or
1227 @code{icon-title-format}.
1228 @end defvar
1230 @node Deleting Frames
1231 @section Deleting Frames
1232 @cindex deleting frames
1234 Frames remain potentially visible until you explicitly @dfn{delete}
1235 them.  A deleted frame cannot appear on the screen, but continues to
1236 exist as a Lisp object until there are no references to it.
1238 @deffn Command delete-frame &optional frame force
1239 @vindex delete-frame-functions
1240 This function deletes the frame @var{frame}.  Unless @var{frame} is a
1241 tooltip, it first runs the hook @code{delete-frame-functions} (each
1242 function gets one argument, @var{frame}).  By default, @var{frame} is
1243 the selected frame.
1245 A frame cannot be deleted if its minibuffer is used by other frames.
1246 Normally, you cannot delete a frame if all other frames are invisible,
1247 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1248 @end deffn
1250 @defun frame-live-p frame
1251 The function @code{frame-live-p} returns non-@code{nil} if the frame
1252 @var{frame} has not been deleted.  The possible non-@code{nil} return
1253 values are like those of @code{framep}.  @xref{Frames}.
1254 @end defun
1256   Some window managers provide a command to delete a window.  These work
1257 by sending a special message to the program that operates the window.
1258 When Emacs gets one of these commands, it generates a
1259 @code{delete-frame} event, whose normal definition is a command that
1260 calls the function @code{delete-frame}.  @xref{Misc Events}.
1262 @node Finding All Frames
1263 @section Finding All Frames
1264 @cindex frames, scanning all
1266 @defun frame-list
1267 The function @code{frame-list} returns a list of all the live frames,
1268 i.e.@: those that have not been deleted.  It is analogous to
1269 @code{buffer-list} for buffers, and includes frames on all terminals.
1270 The list that you get is newly created, so modifying the list doesn't
1271 have any effect on the internals of Emacs.
1272 @end defun
1274 @defun visible-frame-list
1275 This function returns a list of just the currently visible frames.
1276 @xref{Visibility of Frames}.  (Terminal frames always count as
1277 ``visible,'' even though only the selected one is actually displayed.)
1278 @end defun
1280 @defun next-frame &optional frame minibuf
1281 The function @code{next-frame} lets you cycle conveniently through all
1282 the frames on the current display from an arbitrary starting point.  It
1283 returns the ``next'' frame after @var{frame} in the cycle.  If
1284 @var{frame} is omitted or @code{nil}, it defaults to the selected frame
1285 (@pxref{Input Focus}).
1287 The second argument, @var{minibuf}, says which frames to consider:
1289 @table @asis
1290 @item @code{nil}
1291 Exclude minibuffer-only frames.
1292 @item @code{visible}
1293 Consider all visible frames.
1294 @item 0
1295 Consider all visible or iconified frames.
1296 @item a window
1297 Consider only the frames using that particular window as their
1298 minibuffer.
1299 @item anything else
1300 Consider all frames.
1301 @end table
1302 @end defun
1304 @defun previous-frame &optional frame minibuf
1305 Like @code{next-frame}, but cycles through all frames in the opposite
1306 direction.
1307 @end defun
1309   See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1310 Window Ordering}.
1312 @node Minibuffers and Frames
1313 @section Minibuffers and Frames
1315 Normally, each frame has its own minibuffer window at the bottom, which
1316 is used whenever that frame is selected.  If the frame has a minibuffer,
1317 you can get it with @code{minibuffer-window} (@pxref{Definition of
1318 minibuffer-window}).
1320 However, you can also create a frame with no minibuffer.  Such a frame
1321 must use the minibuffer window of some other frame.  When you create the
1322 frame, you can explicitly specify the minibuffer window to use (in some
1323 other frame).  If you don't, then the minibuffer is found in the frame
1324 which is the value of the variable @code{default-minibuffer-frame}.  Its
1325 value should be a frame that does have a minibuffer.
1327 If you use a minibuffer-only frame, you might want that frame to raise
1328 when you enter the minibuffer.  If so, set the variable
1329 @code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.
1331 @defvar default-minibuffer-frame
1332 This variable specifies the frame to use for the minibuffer window, by
1333 default.  It does not affect existing frames.  It is always local to
1334 the current terminal and cannot be buffer-local.  @xref{Multiple
1335 Terminals}.
1336 @end defvar
1338 @node Input Focus
1339 @section Input Focus
1340 @cindex input focus
1341 @c @cindex selected frame    Duplicates selected-frame
1343 At any time, one frame in Emacs is the @dfn{selected frame}.  The selected
1344 window always resides on the selected frame.
1346 When Emacs displays its frames on several terminals (@pxref{Multiple
1347 Terminals}), each terminal has its own selected frame.  But only one
1348 of these is ``@emph{the} selected frame'': it's the frame that belongs
1349 to the terminal from which the most recent input came.  That is, when
1350 Emacs runs a command that came from a certain terminal, the selected
1351 frame is the one of that terminal.  Since Emacs runs only a single
1352 command at any given time, it needs to consider only one selected
1353 frame at a time; this frame is what we call @dfn{the selected frame}
1354 in this manual.  The display on which the selected frame is shown is
1355 the @dfn{selected frame's display}.
1357 @defun selected-frame
1358 This function returns the selected frame.
1359 @end defun
1361 Some window systems and window managers direct keyboard input to the
1362 window object that the mouse is in; others require explicit clicks or
1363 commands to @dfn{shift the focus} to various window objects.  Either
1364 way, Emacs automatically keeps track of which frame has the focus.  To
1365 explicitly switch to a different frame from a Lisp function, call
1366 @code{select-frame-set-input-focus}.
1368 Lisp programs can also switch frames ``temporarily'' by calling the
1369 function @code{select-frame}.  This does not alter the window system's
1370 concept of focus; rather, it escapes from the window manager's control
1371 until that control is somehow reasserted.
1373 When using a text-only terminal, only one frame can be displayed at a
1374 time on the terminal, so after a call to @code{select-frame}, the next
1375 redisplay actually displays the newly selected frame.  This frame
1376 remains selected until a subsequent call to @code{select-frame}.  Each
1377 terminal frame has a number which appears in the mode line before the
1378 buffer name (@pxref{Mode Line Variables}).
1380 @defun select-frame-set-input-focus frame &optional norecord
1381 This function selects @var{frame}, raises it (should it happen to be
1382 obscured by other frames) and tries to give it the X server's focus.
1383 On a text-only terminal, the next redisplay displays the new frame on
1384 the entire terminal screen.  The optional argument @var{norecord} has
1385 the same meaning as for @code{select-frame} (see below).  The return
1386 value of this function is not significant.
1387 @end defun
1389 @defun select-frame frame &optional norecord
1390 This function selects frame @var{frame}, temporarily disregarding the
1391 focus of the X server if any.  The selection of @var{frame} lasts until
1392 the next time the user does something to select a different frame, or
1393 until the next time this function is called.  (If you are using a
1394 window system, the previously selected frame may be restored as the
1395 selected frame after return to the command loop, because it still may
1396 have the window system's input focus.)
1398 The specified @var{frame} becomes the selected frame, and its terminal
1399 becomes the selected terminal.  This function then calls
1400 @code{select-window} as a subroutine, passing the window selected
1401 within @var{frame} as its first argument and @var{norecord} as its
1402 second argument (hence, if @var{norecord} is non-@code{nil}, this
1403 avoids changing the order of recently selected windows nor the buffer
1404 list).  @xref{Selecting Windows}.
1406 This function returns @var{frame}, or @code{nil} if @var{frame} has
1407 been deleted.
1409 In general, you should never use @code{select-frame} in a way that
1410 could switch to a different terminal without switching back when
1411 you're done.
1412 @end defun
1414 Emacs cooperates with the window system by arranging to select frames as
1415 the server and window manager request.  It does so by generating a
1416 special kind of input event, called a @dfn{focus} event, when
1417 appropriate.  The command loop handles a focus event by calling
1418 @code{handle-switch-frame}.  @xref{Focus Events}.
1420 @deffn Command handle-switch-frame frame
1421 This function handles a focus event by selecting frame @var{frame}.
1423 Focus events normally do their job by invoking this command.
1424 Don't call it for any other reason.
1425 @end deffn
1427 @defun redirect-frame-focus frame &optional focus-frame
1428 This function redirects focus from @var{frame} to @var{focus-frame}.
1429 This means that @var{focus-frame} will receive subsequent keystrokes and
1430 events intended for @var{frame}.  After such an event, the value of
1431 @code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
1432 events specifying @var{frame} will instead select @var{focus-frame}.
1434 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1435 redirection for @var{frame}, which therefore once again receives its own
1436 events.
1438 One use of focus redirection is for frames that don't have minibuffers.
1439 These frames use minibuffers on other frames.  Activating a minibuffer
1440 on another frame redirects focus to that frame.  This puts the focus on
1441 the minibuffer's frame, where it belongs, even though the mouse remains
1442 in the frame that activated the minibuffer.
1444 Selecting a frame can also change focus redirections.  Selecting frame
1445 @code{bar}, when @code{foo} had been selected, changes any redirections
1446 pointing to @code{foo} so that they point to @code{bar} instead.  This
1447 allows focus redirection to work properly when the user switches from
1448 one frame to another using @code{select-window}.
1450 This means that a frame whose focus is redirected to itself is treated
1451 differently from a frame whose focus is not redirected.
1452 @code{select-frame} affects the former but not the latter.
1454 The redirection lasts until @code{redirect-frame-focus} is called to
1455 change it.
1456 @end defun
1458 @defopt focus-follows-mouse
1459 This option is how you inform Emacs whether the window manager transfers
1460 focus when the user moves the mouse.  Non-@code{nil} says that it does.
1461 When this is so, the command @code{other-frame} moves the mouse to a
1462 position consistent with the new selected frame.
1463 @end defopt
1465 @node Visibility of Frames
1466 @section Visibility of Frames
1467 @cindex visible frame
1468 @cindex invisible frame
1469 @cindex iconified frame
1470 @cindex frame visibility
1472 A window frame may be @dfn{visible}, @dfn{invisible}, or
1473 @dfn{iconified}.  If it is visible, you can see its contents, unless
1474 other windows cover it.  If it is iconified, the frame's contents do
1475 not appear on the screen, but an icon does.  (Note: because of the
1476 way in which some window managers implement the concept of multiple
1477 workspaces, or desktops, all frames on other workspaces may appear to
1478 Emacs to be iconified.)  If the frame is invisible, it doesn't show on
1479 the screen, not even as an icon.
1481 Visibility is meaningless for terminal frames, since only the selected
1482 one is actually displayed in any case.
1484 @deffn Command make-frame-visible &optional frame
1485 This function makes frame @var{frame} visible.  If you omit
1486 @var{frame}, it makes the selected frame visible.  This does not raise
1487 the frame, but you can do that with @code{raise-frame} if you wish
1488 (@pxref{Raising and Lowering}).
1489 @end deffn
1491 @deffn Command make-frame-invisible &optional frame force
1492 This function makes frame @var{frame} invisible.  If you omit
1493 @var{frame}, it makes the selected frame invisible.
1495 Unless @var{force} is non-@code{nil}, this function refuses to make
1496 @var{frame} invisible if all other frames are invisible..
1497 @end deffn
1499 @deffn Command iconify-frame &optional frame
1500 This function iconifies frame @var{frame}.  If you omit @var{frame}, it
1501 iconifies the selected frame.
1502 @end deffn
1504 @defun frame-visible-p frame
1505 This returns the visibility status of frame @var{frame}.  The value is
1506 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
1507 @code{icon} if it is iconified.
1509 On a text-only terminal, all frames are considered visible, whether
1510 they are currently being displayed or not, and this function returns
1511 @code{t} for all frames.
1512 @end defun
1514   The visibility status of a frame is also available as a frame
1515 parameter.  You can read or change it as such.  @xref{Management
1516 Parameters}.
1518   The user can iconify and deiconify frames with the window manager.
1519 This happens below the level at which Emacs can exert any control, but
1520 Emacs does provide events that you can use to keep track of such
1521 changes.  @xref{Misc Events}.
1523 @node Raising and Lowering
1524 @section Raising and Lowering Frames
1526   Most window systems use a desktop metaphor.  Part of this metaphor is
1527 the idea that windows are stacked in a notional third dimension
1528 perpendicular to the screen surface, and thus ordered from ``highest''
1529 to ``lowest.''  Where two windows overlap, the one higher up covers
1530 the one underneath.  Even a window at the bottom of the stack can be
1531 seen if no other window overlaps it.
1533 @c @cindex raising a frame  redundant with raise-frame
1534 @cindex lowering a frame
1535   A window's place in this ordering is not fixed; in fact, users tend
1536 to change the order frequently.  @dfn{Raising} a window means moving
1537 it ``up,'' to the top of the stack.  @dfn{Lowering} a window means
1538 moving it to the bottom of the stack.  This motion is in the notional
1539 third dimension only, and does not change the position of the window
1540 on the screen.
1542   With Emacs, frames constitute the windows in the metaphor sketched
1543 above. You can raise and lower frames using these functions:
1545 @deffn Command raise-frame &optional frame
1546 This function raises frame @var{frame} (default, the selected frame).
1547 If @var{frame} is invisible or iconified, this makes it visible.
1548 @end deffn
1550 @deffn Command lower-frame &optional frame
1551 This function lowers frame @var{frame} (default, the selected frame).
1552 @end deffn
1554 @defopt minibuffer-auto-raise
1555 If this is non-@code{nil}, activation of the minibuffer raises the frame
1556 that the minibuffer window is in.
1557 @end defopt
1559 You can also enable auto-raise (raising automatically when a frame is
1560 selected) or auto-lower (lowering automatically when it is deselected)
1561 for any frame using frame parameters.  @xref{Management Parameters}.
1563 @node Frame Configurations
1564 @section Frame Configurations
1565 @cindex frame configuration
1567   A @dfn{frame configuration} records the current arrangement of frames,
1568 all their properties, and the window configuration of each one.
1569 (@xref{Window Configurations}.)
1571 @defun current-frame-configuration
1572 This function returns a frame configuration list that describes
1573 the current arrangement of frames and their contents.
1574 @end defun
1576 @defun set-frame-configuration configuration &optional nodelete
1577 This function restores the state of frames described in
1578 @var{configuration}.  However, this function does not restore deleted
1579 frames.
1581 Ordinarily, this function deletes all existing frames not listed in
1582 @var{configuration}.  But if @var{nodelete} is non-@code{nil}, the
1583 unwanted frames are iconified instead.
1584 @end defun
1586 @node Mouse Tracking
1587 @section Mouse Tracking
1588 @cindex mouse tracking
1589 @c @cindex tracking the mouse   Duplicates track-mouse
1591   Sometimes it is useful to @dfn{track} the mouse, which means to display
1592 something to indicate where the mouse is and move the indicator as the
1593 mouse moves.  For efficient mouse tracking, you need a way to wait until
1594 the mouse actually moves.
1596   The convenient way to track the mouse is to ask for events to represent
1597 mouse motion.  Then you can wait for motion by waiting for an event.  In
1598 addition, you can easily handle any other sorts of events that may
1599 occur.  That is useful, because normally you don't want to track the
1600 mouse forever---only until some other event, such as the release of a
1601 button.
1603 @defspec track-mouse body@dots{}
1604 This special form executes @var{body}, with generation of mouse motion
1605 events enabled.  Typically, @var{body} would use @code{read-event} to
1606 read the motion events and modify the display accordingly.  @xref{Motion
1607 Events}, for the format of mouse motion events.
1609 The value of @code{track-mouse} is that of the last form in @var{body}.
1610 You should design @var{body} to return when it sees the up-event that
1611 indicates the release of the button, or whatever kind of event means
1612 it is time to stop tracking.
1613 @end defspec
1615 The usual purpose of tracking mouse motion is to indicate on the screen
1616 the consequences of pushing or releasing a button at the current
1617 position.
1619 In many cases, you can avoid the need to track the mouse by using
1620 the @code{mouse-face} text property (@pxref{Special Properties}).
1621 That works at a much lower level and runs more smoothly than
1622 Lisp-level mouse tracking.
1624 @ignore
1625 @c These are not implemented yet.
1627 These functions change the screen appearance instantaneously.  The
1628 effect is transient, only until the next ordinary Emacs redisplay.  That
1629 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1630 to change the text, and the body of @code{track-mouse} normally reads
1631 the events itself and does not do redisplay.
1633 @defun x-contour-region window beg end
1634 This function draws lines to make a box around the text from @var{beg}
1635 to @var{end}, in window @var{window}.
1636 @end defun
1638 @defun x-uncontour-region window beg end
1639 This function erases the lines that would make a box around the text
1640 from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
1641 a contour that you previously made by calling @code{x-contour-region}.
1642 @end defun
1644 @defun x-draw-rectangle frame left top right bottom
1645 This function draws a hollow rectangle on frame @var{frame} with the
1646 specified edge coordinates, all measured in pixels from the inside top
1647 left corner.  It uses the cursor color, the one used for indicating the
1648 location of point.
1649 @end defun
1651 @defun x-erase-rectangle frame left top right bottom
1652 This function erases a hollow rectangle on frame @var{frame} with the
1653 specified edge coordinates, all measured in pixels from the inside top
1654 left corner.  Erasure means redrawing the text and background that
1655 normally belong in the specified rectangle.
1656 @end defun
1657 @end ignore
1659 @node Mouse Position
1660 @section Mouse Position
1661 @cindex mouse position
1662 @cindex position of mouse
1664   The functions @code{mouse-position} and @code{set-mouse-position}
1665 give access to the current position of the mouse.
1667 @defun mouse-position
1668 This function returns a description of the position of the mouse.  The
1669 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1670 and @var{y} are integers giving the position in characters relative to
1671 the top left corner of the inside of @var{frame}.
1672 @end defun
1674 @defvar mouse-position-function
1675 If non-@code{nil}, the value of this variable is a function for
1676 @code{mouse-position} to call.  @code{mouse-position} calls this
1677 function just before returning, with its normal return value as the
1678 sole argument, and it returns whatever this function returns to it.
1680 This abnormal hook exists for the benefit of packages like
1681 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1682 @end defvar
1684 @defun set-mouse-position frame x y
1685 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1686 frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
1687 giving the position in characters relative to the top left corner of the
1688 inside of @var{frame}.  If @var{frame} is not visible, this function
1689 does nothing.  The return value is not significant.
1690 @end defun
1692 @defun mouse-pixel-position
1693 This function is like @code{mouse-position} except that it returns
1694 coordinates in units of pixels rather than units of characters.
1695 @end defun
1697 @defun set-mouse-pixel-position frame x y
1698 This function warps the mouse like @code{set-mouse-position} except that
1699 @var{x} and @var{y} are in units of pixels rather than units of
1700 characters.  These coordinates are not required to be within the frame.
1702 If @var{frame} is not visible, this function does nothing.  The return
1703 value is not significant.
1704 @end defun
1706 @defun frame-pointer-visible-p &optional frame
1707 This predicate function returns non-@code{nil} if the mouse pointer
1708 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
1709 @var{frame} omitted or @code{nil} means the selected frame.  This is
1710 useful when @code{make-pointer-invisible} is set to @code{t}: it
1711 allows to know if the pointer has been hidden.
1712 @xref{Mouse Avoidance,,,emacs}.
1713 @end defun
1715 @need 3000
1717 @node Pop-Up Menus
1718 @section Pop-Up Menus
1720   When using a window system, a Lisp program can pop up a menu so that
1721 the user can choose an alternative with the mouse.
1723 @defun x-popup-menu position menu
1724 This function displays a pop-up menu and returns an indication of
1725 what selection the user makes.
1727 The argument @var{position} specifies where on the screen to put the
1728 top left corner of the menu.  It can be either a mouse button event
1729 (which says to put the menu where the user actuated the button) or a
1730 list of this form:
1732 @example
1733 ((@var{xoffset} @var{yoffset}) @var{window})
1734 @end example
1736 @noindent
1737 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1738 pixels, counting from the top left corner of @var{window}.  @var{window}
1739 may be a window or a frame.
1741 If @var{position} is @code{t}, it means to use the current mouse
1742 position.  If @var{position} is @code{nil}, it means to precompute the
1743 key binding equivalents for the keymaps specified in @var{menu},
1744 without actually displaying or popping up the menu.
1746 The argument @var{menu} says what to display in the menu.  It can be a
1747 keymap or a list of keymaps (@pxref{Menu Keymaps}).  In this case, the
1748 return value is the list of events corresponding to the user's choice.
1749 This list has more than one element if the choice occurred in a
1750 submenu.  (Note that @code{x-popup-menu} does not actually execute the
1751 command bound to that sequence of events.)  On toolkits that support
1752 menu titles, the title is taken from the prompt string of @var{menu}
1753 if @var{menu} is a keymap, or from the prompt string of the first
1754 keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
1755 Menus}).
1757 Alternatively, @var{menu} can have the following form:
1759 @example
1760 (@var{title} @var{pane1} @var{pane2}...)
1761 @end example
1763 @noindent
1764 where each pane is a list of form
1766 @example
1767 (@var{title} @var{item1} @var{item2}...)
1768 @end example
1770 Each item should normally be a cons cell @code{(@var{line} . @var{value})},
1771 where @var{line} is a string, and @var{value} is the value to return if
1772 that @var{line} is chosen.  An item can also be a string; this makes a
1773 non-selectable line in the menu.
1775 If the user gets rid of the menu without making a valid choice, for
1776 instance by clicking the mouse away from a valid choice or by typing
1777 keyboard input, then this normally results in a quit and
1778 @code{x-popup-menu} does not return.  But if @var{position} is a mouse
1779 button event (indicating that the user invoked the menu with the
1780 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1781 @end defun
1783   @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1784 if you could do the job with a prefix key defined with a menu keymap.
1785 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1786 a} can see the individual items in that menu and provide help for them.
1787 If instead you implement the menu by defining a command that calls
1788 @code{x-popup-menu}, the help facilities cannot know what happens inside
1789 that command, so they cannot give any help for the menu's items.
1791   The menu bar mechanism, which lets you switch between submenus by
1792 moving the mouse, cannot look within the definition of a command to see
1793 that it calls @code{x-popup-menu}.  Therefore, if you try to implement a
1794 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1795 an integrated fashion.  This is why all menu bar submenus are
1796 implemented with menu keymaps within the parent menu, and never with
1797 @code{x-popup-menu}.  @xref{Menu Bar}.
1799   If you want a menu bar submenu to have contents that vary, you should
1800 still use a menu keymap to implement it.  To make the contents vary, add
1801 a hook function to @code{menu-bar-update-hook} to update the contents of
1802 the menu keymap as necessary.
1804 @node Dialog Boxes
1805 @section Dialog Boxes
1806 @cindex dialog boxes
1808   A dialog box is a variant of a pop-up menu---it looks a little
1809 different, it always appears in the center of a frame, and it has just
1810 one level and one or more buttons.  The main use of dialog boxes is
1811 for asking questions that the user can answer with ``yes,'' ``no,''
1812 and a few other alternatives.  With a single button, they can also
1813 force the user to acknowledge important information.  The functions
1814 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1815 keyboard, when called from commands invoked by mouse clicks.
1817 @defun x-popup-dialog position contents &optional header
1818 This function displays a pop-up dialog box and returns an indication of
1819 what selection the user makes.  The argument @var{contents} specifies
1820 the alternatives to offer; it has this format:
1822 @example
1823 (@var{title} (@var{string} . @var{value})@dots{})
1824 @end example
1826 @noindent
1827 which looks like the list that specifies a single pane for
1828 @code{x-popup-menu}.
1830 The return value is @var{value} from the chosen alternative.
1832 As for @code{x-popup-menu}, an element of the list may be just a
1833 string instead of a cons cell @code{(@var{string} . @var{value})}.
1834 That makes a box that cannot be selected.
1836 If @code{nil} appears in the list, it separates the left-hand items from
1837 the right-hand items; items that precede the @code{nil} appear on the
1838 left, and items that follow the @code{nil} appear on the right.  If you
1839 don't include a @code{nil} in the list, then approximately half the
1840 items appear on each side.
1842 Dialog boxes always appear in the center of a frame; the argument
1843 @var{position} specifies which frame.  The possible values are as in
1844 @code{x-popup-menu}, but the precise coordinates or the individual
1845 window don't matter; only the frame matters.
1847 If @var{header} is non-@code{nil}, the frame title for the box is
1848 @samp{Information}, otherwise it is @samp{Question}.  The former is used
1849 for @code{message-box} (@pxref{message-box}).
1851 In some configurations, Emacs cannot display a real dialog box; so
1852 instead it displays the same items in a pop-up menu in the center of the
1853 frame.
1855 If the user gets rid of the dialog box without making a valid choice,
1856 for instance using the window manager, then this produces a quit and
1857 @code{x-popup-dialog} does not return.
1858 @end defun
1860 @node Pointer Shape
1861 @section Pointer Shape
1862 @cindex pointer shape
1863 @cindex mouse pointer shape
1865   You can specify the mouse pointer style for particular text or
1866 images using the @code{pointer} text property, and for images with the
1867 @code{:pointer} and @code{:map} image properties.  The values you can
1868 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1869 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1870 @code{hourglass}.  @code{text} stands for the usual mouse pointer
1871 style used over text.
1873   Over void parts of the window (parts that do not correspond to any
1874 of the buffer contents), the mouse pointer usually uses the
1875 @code{arrow} style, but you can specify a different style (one of
1876 those above) by setting @code{void-text-area-pointer}.
1878 @defvar void-text-area-pointer
1879 This variable specifies the mouse pointer style for void text areas.
1880 These include the areas after the end of a line or below the last line
1881 in the buffer.  The default is to use the @code{arrow} (non-text)
1882 pointer style.
1883 @end defvar
1885   When using X, you can specify what the @code{text} pointer style
1886 really looks like by setting the variable @code{x-pointer-shape}.
1888 @defvar x-pointer-shape
1889 This variable specifies the pointer shape to use ordinarily in the
1890 Emacs frame, for the @code{text} pointer style.
1891 @end defvar
1893 @defvar x-sensitive-text-pointer-shape
1894 This variable specifies the pointer shape to use when the mouse
1895 is over mouse-sensitive text.
1896 @end defvar
1898   These variables affect newly created frames.  They do not normally
1899 affect existing frames; however, if you set the mouse color of a
1900 frame, that also installs the current value of those two variables.
1901 @xref{Font and Color Parameters}.
1903   The values you can use, to specify either of these pointer shapes, are
1904 defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
1905 @key{RET} x-pointer @key{RET}} to see a list of them.
1907 @node Window System Selections
1908 @section Window System Selections
1909 @cindex selection (for window systems)
1910 @cindex clipboard
1911 @cindex primary selection
1912 @cindex secondary selection
1914   In the X window system, data can be transferred between different
1915 applications by means of @dfn{selections}.  X defines an arbitrary
1916 number of @dfn{selection types}, each of which can store its own data;
1917 however, only three are commonly used: the @dfn{clipboard},
1918 @dfn{primary selection}, and @dfn{secondary selection}.  @xref{Cut and
1919 Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
1920 commands that make use of these selections.  This section documents
1921 the low-level functions for reading and setting X selections.
1923 @deffn Command x-set-selection type data
1924 This function sets an X selection.  It takes two arguments: a
1925 selection type @var{type}, and the value to assign to it, @var{data}.
1927 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
1928 @code{SECONDARY} or @code{CLIPBOARD}.  These are symbols with
1929 upper-case names, in accord with X Window System conventions.  If
1930 @var{type} is @code{nil}, that stands for @code{PRIMARY}.
1932 If @var{data} is @code{nil}, it means to clear out the selection.
1933 Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
1934 of two integers or list of two integers), an overlay, or a cons of two
1935 markers pointing to the same buffer.  An overlay or a pair of markers
1936 stands for text in the overlay or between the markers.  The argument
1937 @var{data} may also be a vector of valid non-vector selection values.
1939 This function returns @var{data}.
1940 @end deffn
1942 @defun x-get-selection &optional type data-type
1943 This function accesses selections set up by Emacs or by other X
1944 clients.  It takes two optional arguments, @var{type} and
1945 @var{data-type}.  The default for @var{type}, the selection type, is
1946 @code{PRIMARY}.
1948 The @var{data-type} argument specifies the form of data conversion to
1949 use, to convert the raw data obtained from another X client into Lisp
1950 data.  Meaningful values include @code{TEXT}, @code{STRING},
1951 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1952 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1953 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1954 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
1955 @code{INTEGER}.  (These are symbols with upper-case names in accord
1956 with X conventions.)  The default for @var{data-type} is
1957 @code{STRING}.
1958 @end defun
1960 @defopt selection-coding-system
1961 This variable specifies the coding system to use when reading and
1962 writing selections or the clipboard.  @xref{Coding
1963 Systems}.  The default is @code{compound-text-with-extensions}, which
1964 converts to the text representation that X11 normally uses.
1965 @end defopt
1967 @cindex clipboard support (for MS-Windows)
1968 When Emacs runs on MS-Windows, it does not implement X selections in
1969 general, but it does support the clipboard.  @code{x-get-selection}
1970 and @code{x-set-selection} on MS-Windows support the text data type
1971 only; if the clipboard holds other types of data, Emacs treats the
1972 clipboard as empty.
1974 @node Drag and Drop
1975 @section Drag and Drop
1977 @vindex x-dnd-test-function
1978 @vindex x-dnd-known-types
1979   When a user drags something from another application over Emacs, that other
1980 application expects Emacs to tell it if Emacs can handle the data that is
1981 dragged.  The variable @code{x-dnd-test-function} is used by Emacs to determine
1982 what to reply.  The default value is @code{x-dnd-default-test-function}
1983 which accepts drops if the type of the data to be dropped is present in
1984 @code{x-dnd-known-types}.  You can customize @code{x-dnd-test-function} and/or
1985 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
1986 on some other criteria.
1988 @vindex x-dnd-types-alist
1989   If you want to change the way Emacs handles drop of different types
1990 or add a new type, customize @code{x-dnd-types-alist}.  This requires
1991 detailed knowledge of what types other applications use for drag and
1992 drop.
1994 @vindex dnd-protocol-alist
1995   When an URL is dropped on Emacs it may be a file, but it may also be
1996 another URL type (ftp, http, etc.).  Emacs first checks
1997 @code{dnd-protocol-alist} to determine what to do with the URL.  If
1998 there is no match there and if @code{browse-url-browser-function} is
1999 an alist, Emacs looks for a match there.  If no match is found the
2000 text for the URL is inserted.  If you want to alter Emacs behavior,
2001 you can customize these variables.
2003 @node Color Names
2004 @section Color Names
2006 @cindex color names
2007 @cindex specify color
2008 @cindex numerical RGB color specification
2009   A color name is text (usually in a string) that specifies a color.
2010 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2011 are allowed; use @kbd{M-x list-colors-display} to see a list of
2012 defined names.  You can also specify colors numerically in forms such
2013 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2014 @var{r} specifies the red level, @var{g} specifies the green level,
2015 and @var{b} specifies the blue level.  You can use either one, two,
2016 three, or four hex digits for @var{r}; then you must use the same
2017 number of hex digits for all @var{g} and @var{b} as well, making
2018 either 3, 6, 9 or 12 hex digits in all.  (See the documentation of the
2019 X Window System for more details about numerical RGB specification of
2020 colors.)
2022   These functions provide a way to determine which color names are
2023 valid, and what they look like.  In some cases, the value depends on the
2024 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2025 meaning of the term ``selected frame.''
2027   To read user input of color names with completion, use
2028 @code{read-color} (@pxref{High-Level Completion, read-color}).
2030 @defun color-defined-p color &optional frame
2031 This function reports whether a color name is meaningful.  It returns
2032 @code{t} if so; otherwise, @code{nil}.  The argument @var{frame} says
2033 which frame's display to ask about; if @var{frame} is omitted or
2034 @code{nil}, the selected frame is used.
2036 Note that this does not tell you whether the display you are using
2037 really supports that color.  When using X, you can ask for any defined
2038 color on any kind of display, and you will get some result---typically,
2039 the closest it can do.  To determine whether a frame can really display
2040 a certain color, use @code{color-supported-p} (see below).
2042 @findex x-color-defined-p
2043 This function used to be called @code{x-color-defined-p},
2044 and that name is still supported as an alias.
2045 @end defun
2047 @defun defined-colors &optional frame
2048 This function returns a list of the color names that are defined
2049 and supported on frame @var{frame} (default, the selected frame).
2050 If @var{frame} does not support colors, the value is @code{nil}.
2052 @findex x-defined-colors
2053 This function used to be called @code{x-defined-colors},
2054 and that name is still supported as an alias.
2055 @end defun
2057 @defun color-supported-p color &optional frame background-p
2058 This returns @code{t} if @var{frame} can really display the color
2059 @var{color} (or at least something close to it).  If @var{frame} is
2060 omitted or @code{nil}, the question applies to the selected frame.
2062 Some terminals support a different set of colors for foreground and
2063 background.  If @var{background-p} is non-@code{nil}, that means you are
2064 asking whether @var{color} can be used as a background; otherwise you
2065 are asking whether it can be used as a foreground.
2067 The argument @var{color} must be a valid color name.
2068 @end defun
2070 @defun color-gray-p color &optional frame
2071 This returns @code{t} if @var{color} is a shade of gray, as defined on
2072 @var{frame}'s display.  If @var{frame} is omitted or @code{nil}, the
2073 question applies to the selected frame.  If @var{color} is not a valid
2074 color name, this function returns @code{nil}.
2075 @end defun
2077 @defun color-values color &optional frame
2078 @cindex rgb value
2079 This function returns a value that describes what @var{color} should
2080 ideally look like on @var{frame}.  If @var{color} is defined, the
2081 value is a list of three integers, which give the amount of red, the
2082 amount of green, and the amount of blue.  Each integer ranges in
2083 principle from 0 to 65535, but some displays may not use the full
2084 range.  This three-element list is called the @dfn{rgb values} of the
2085 color.
2087 If @var{color} is not defined, the value is @code{nil}.
2089 @example
2090 (color-values "black")
2091      @result{} (0 0 0)
2092 (color-values "white")
2093      @result{} (65280 65280 65280)
2094 (color-values "red")
2095      @result{} (65280 0 0)
2096 (color-values "pink")
2097      @result{} (65280 49152 51968)
2098 (color-values "hungry")
2099      @result{} nil
2100 @end example
2102 The color values are returned for @var{frame}'s display.  If
2103 @var{frame} is omitted or @code{nil}, the information is returned for
2104 the selected frame's display.  If the frame cannot display colors, the
2105 value is @code{nil}.
2107 @findex x-color-values
2108 This function used to be called @code{x-color-values},
2109 and that name is still supported as an alias.
2110 @end defun
2112 @node Text Terminal Colors
2113 @section Text Terminal Colors
2114 @cindex colors on text-only terminals
2116   Text-only terminals usually support only a small number of colors,
2117 and the computer uses small integers to select colors on the terminal.
2118 This means that the computer cannot reliably tell what the selected
2119 color looks like; instead, you have to inform your application which
2120 small integers correspond to which colors.  However, Emacs does know
2121 the standard set of colors and will try to use them automatically.
2123   The functions described in this section control how terminal colors
2124 are used by Emacs.
2126   Several of these functions use or return @dfn{rgb values}, described
2127 in @ref{Color Names}.
2129   These functions accept a display (either a frame or the name of a
2130 terminal) as an optional argument.  We hope in the future to make
2131 Emacs support different colors on different text-only terminals; then
2132 this argument will specify which terminal to operate on (the default
2133 being the selected frame's terminal; @pxref{Input Focus}).  At
2134 present, though, the @var{frame} argument has no effect.
2136 @defun tty-color-define name number &optional rgb frame
2137 This function associates the color name @var{name} with
2138 color number @var{number} on the terminal.
2140 The optional argument @var{rgb}, if specified, is an rgb value, a list
2141 of three numbers that specify what the color actually looks like.
2142 If you do not specify @var{rgb}, then this color cannot be used by
2143 @code{tty-color-approximate} to approximate other colors, because
2144 Emacs will not know what it looks like.
2145 @end defun
2147 @defun tty-color-clear &optional frame
2148 This function clears the table of defined colors for a text-only terminal.
2149 @end defun
2151 @defun tty-color-alist &optional frame
2152 This function returns an alist recording the known colors supported by a
2153 text-only terminal.
2155 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2156 or @code{(@var{name} @var{number})}.  Here, @var{name} is the color
2157 name, @var{number} is the number used to specify it to the terminal.
2158 If present, @var{rgb} is a list of three color values (for red, green,
2159 and blue) that says what the color actually looks like.
2160 @end defun
2162 @defun tty-color-approximate rgb &optional frame
2163 This function finds the closest color, among the known colors
2164 supported for @var{display}, to that described by the rgb value
2165 @var{rgb} (a list of color values).  The return value is an element of
2166 @code{tty-color-alist}.
2167 @end defun
2169 @defun tty-color-translate color &optional frame
2170 This function finds the closest color to @var{color} among the known
2171 colors supported for @var{display} and returns its index (an integer).
2172 If the name @var{color} is not defined, the value is @code{nil}.
2173 @end defun
2175 @node Resources
2176 @section X Resources
2178 This section describes some of the functions and variables for
2179 querying and using X resources, or their equivalent on your operating
2180 system.  @xref{X Resources,, X Resources, emacs, The GNU Emacs
2181 Manual}, for more information about X resources.
2183 @defun x-get-resource attribute class &optional component subclass
2184 The function @code{x-get-resource} retrieves a resource value from the X
2185 Window defaults database.
2187 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2188 This function searches using a key of the form
2189 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2190 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2191 the class.
2193 The optional arguments @var{component} and @var{subclass} add to the key
2194 and the class, respectively.  You must specify both of them or neither.
2195 If you specify them, the key is
2196 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2197 @samp{Emacs.@var{class}.@var{subclass}}.
2198 @end defun
2200 @defvar x-resource-class
2201 This variable specifies the application name that @code{x-get-resource}
2202 should look up.  The default value is @code{"Emacs"}.  You can examine X
2203 resources for application names other than ``Emacs'' by binding this
2204 variable to some other string, around a call to @code{x-get-resource}.
2205 @end defvar
2207 @defvar x-resource-name
2208 This variable specifies the instance name that @code{x-get-resource}
2209 should look up.  The default value is the name Emacs was invoked with,
2210 or the value specified with the @samp{-name} or @samp{-rn} switches.
2211 @end defvar
2213 To illustrate some of the above, suppose that you have the line:
2215 @example
2216 xterm.vt100.background: yellow
2217 @end example
2219 @noindent
2220 in your X resources file (whose name is usually @file{~/.Xdefaults}
2221 or @file{~/.Xresources}).  Then:
2223 @example
2224 @group
2225 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2226   (x-get-resource "vt100.background" "VT100.Background"))
2227      @result{} "yellow"
2228 @end group
2229 @group
2230 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2231   (x-get-resource "background" "VT100" "vt100" "Background"))
2232      @result{} "yellow"
2233 @end group
2234 @end example
2236 @defvar inhibit-x-resources
2237 If this variable is non-@code{nil}, Emacs does not look up X
2238 resources, and X resources do not have any effect when creating new
2239 frames.
2240 @end defvar
2242 @node Display Feature Testing
2243 @section Display Feature Testing
2244 @cindex display feature testing
2246   The functions in this section describe the basic capabilities of a
2247 particular display.  Lisp programs can use them to adapt their behavior
2248 to what the display can do.  For example, a program that ordinarily uses
2249 a popup menu could use the minibuffer if popup menus are not supported.
2251   The optional argument @var{display} in these functions specifies which
2252 display to ask the question about.  It can be a display name, a frame
2253 (which designates the display that frame is on), or @code{nil} (which
2254 refers to the selected frame's display, @pxref{Input Focus}).
2256   @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2257 obtain information about displays.
2259 @defun display-popup-menus-p &optional display
2260 This function returns @code{t} if popup menus are supported on
2261 @var{display}, @code{nil} if not.  Support for popup menus requires that
2262 the mouse be available, since the user cannot choose menu items without
2263 a mouse.
2264 @end defun
2266 @defun display-graphic-p &optional display
2267 This function returns @code{t} if @var{display} is a graphic display
2268 capable of displaying several frames and several different fonts at
2269 once.  This is true for displays that use a window system such as X, and
2270 false for text-only terminals.
2271 @end defun
2273 @defun display-mouse-p &optional display
2274 @cindex mouse, availability
2275 This function returns @code{t} if @var{display} has a mouse available,
2276 @code{nil} if not.
2277 @end defun
2279 @defun display-color-p &optional display
2280 @findex x-display-color-p
2281 This function returns @code{t} if the screen is a color screen.
2282 It used to be called @code{x-display-color-p}, and that name
2283 is still supported as an alias.
2284 @end defun
2286 @defun display-grayscale-p &optional display
2287 This function returns @code{t} if the screen can display shades of gray.
2288 (All color displays can do this.)
2289 @end defun
2291 @defun display-supports-face-attributes-p attributes &optional display
2292 @anchor{Display Face Attribute Testing}
2293 This function returns non-@code{nil} if all the face attributes in
2294 @var{attributes} are supported (@pxref{Face Attributes}).
2296 The definition of `supported' is somewhat heuristic, but basically
2297 means that a face containing all the attributes in @var{attributes},
2298 when merged with the default face for display, can be represented in a
2299 way that's
2301 @enumerate
2302 @item
2303 different in appearance than the default face, and
2305 @item
2306 `close in spirit' to what the attributes specify, if not exact.
2307 @end enumerate
2309 Point (2) implies that a @code{:weight black} attribute will be
2310 satisfied by any display that can display bold, as will
2311 @code{:foreground "yellow"} as long as some yellowish color can be
2312 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2313 the tty display code's automatic substitution of a `dim' face for
2314 italic.
2315 @end defun
2317 @defun display-selections-p &optional display
2318 This function returns @code{t} if @var{display} supports selections.
2319 Windowed displays normally support selections, but they may also be
2320 supported in some other cases.
2321 @end defun
2323 @defun display-images-p &optional display
2324 This function returns @code{t} if @var{display} can display images.
2325 Windowed displays ought in principle to handle images, but some
2326 systems lack the support for that.  On a display that does not support
2327 images, Emacs cannot display a tool bar.
2328 @end defun
2330 @defun display-screens &optional display
2331 This function returns the number of screens associated with the display.
2332 @end defun
2334 @defun display-pixel-height &optional display
2335 This function returns the height of the screen in pixels.
2336 On a character terminal, it gives the height in characters.
2338 For graphical terminals, note that on ``multi-monitor'' setups this
2339 refers to the pixel width for all physical monitors associated with
2340 @var{display}.  @xref{Multiple Terminals}.
2341 @end defun
2343 @defun display-pixel-width &optional display
2344 This function returns the width of the screen in pixels.
2345 On a character terminal, it gives the width in characters.
2347 For graphical terminals, note that on ``multi-monitor'' setups this
2348 refers to the pixel width for all physical monitors associated with
2349 @var{display}.  @xref{Multiple Terminals}.
2350 @end defun
2352 @defun display-mm-height &optional display
2353 This function returns the height of the screen in millimeters,
2354 or @code{nil} if Emacs cannot get that information.
2355 @end defun
2357 @defun display-mm-width &optional display
2358 This function returns the width of the screen in millimeters,
2359 or @code{nil} if Emacs cannot get that information.
2360 @end defun
2362 @defopt display-mm-dimensions-alist
2363 This variable allows the user to specify the dimensions of graphical
2364 displays returned by @code{display-mm-height} and
2365 @code{display-mm-width} in case the system provides incorrect values.
2366 @end defopt
2368 @defun display-backing-store &optional display
2369 This function returns the backing store capability of the display.
2370 Backing store means recording the pixels of windows (and parts of
2371 windows) that are not exposed, so that when exposed they can be
2372 displayed very quickly.
2374 Values can be the symbols @code{always}, @code{when-mapped}, or
2375 @code{not-useful}.  The function can also return @code{nil}
2376 when the question is inapplicable to a certain kind of display.
2377 @end defun
2379 @defun display-save-under &optional display
2380 This function returns non-@code{nil} if the display supports the
2381 SaveUnder feature.  That feature is used by pop-up windows
2382 to save the pixels they obscure, so that they can pop down
2383 quickly.
2384 @end defun
2386 @defun display-planes &optional display
2387 This function returns the number of planes the display supports.
2388 This is typically the number of bits per pixel.
2389 For a tty display, it is log to base two of the number of colors supported.
2390 @end defun
2392 @defun display-visual-class &optional display
2393 This function returns the visual class for the screen.  The value is
2394 one of the symbols @code{static-gray} (a limited, unchangeable number
2395 of grays), @code{gray-scale} (a full range of grays),
2396 @code{static-color} (a limited, unchangeable number of colors),
2397 @code{pseudo-color} (a limited number of colors), @code{true-color} (a
2398 full range of colors), and @code{direct-color} (a full range of
2399 colors).
2400 @end defun
2402 @defun display-color-cells &optional display
2403 This function returns the number of color cells the screen supports.
2404 @end defun
2406   These functions obtain additional information specifically
2407 about X displays.
2409 @defun x-server-version &optional display
2410 This function returns the list of version numbers of the X server
2411 running the display.  The value is a list of three integers: the major
2412 and minor version numbers of the X protocol, and the
2413 distributor-specific release number of the X server software itself.
2414 @end defun
2416 @defun x-server-vendor &optional display
2417 This function returns the ``vendor'' that provided the X server
2418 software (as a string).  Really this means whoever distributes the X
2419 server.
2421 When the developers of X labeled software distributors as
2422 ``vendors,'' they showed their false assumption that no system could
2423 ever be developed and distributed noncommercially.
2424 @end defun
2426 @ignore
2427 @defvar x-no-window-manager
2428 This variable's value is @code{t} if no X window manager is in use.
2429 @end defvar
2430 @end ignore
2432 @ignore
2433 @item
2434 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2435 width and height of an X Window frame, measured in pixels.
2436 @end ignore