* admin/notes/bzr (Commit emails): New section.
[emacs.git] / doc / lispref / frames.texi
blob01d2d1d6c452e41a7344f92f9c5d13040b075089
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
4 @c Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @node Frames
7 @chapter Frames
8 @cindex frame
10   A @dfn{frame} is a screen object that contains one or more Emacs
11 windows (@pxref{Windows}).  It is the kind of object called a
12 ``window'' in the terminology of graphical environments; but we can't
13 call it a ``window'' here, because Emacs uses that word in a different
14 way.  In Emacs Lisp, a @dfn{frame object} is a Lisp object that
15 represents a frame on the screen.  @xref{Frame Type}.
17   A frame initially contains a single main window and/or a minibuffer
18 window; you can subdivide the main window vertically or horizontally
19 into smaller windows.  @xref{Splitting Windows}.
21 @cindex terminal
22   A @dfn{terminal} is a display device capable of displaying one or
23 more Emacs frames.  In Emacs Lisp, a @dfn{terminal object} is a Lisp
24 object that represents a terminal.  @xref{Terminal Type}.
26 @cindex text terminal
27 @cindex graphical terminal
28 @cindex graphical display
29   There are two classes of terminals: @dfn{text terminals} and
30 @dfn{graphical terminals}.  Text terminals are non-graphics-capable
31 displays, including @command{xterm} and other terminal emulators.  On
32 a text terminal, each Emacs frame occupies the terminal's entire
33 screen; although you can create additional frames and switch between
34 them, the terminal only shows one frame at a time.  Graphical
35 terminals, on the other hand, are managed by graphical display systems
36 such as the X Window System, which allow Emacs to show multiple frames
37 simultaneously on the same display.
39   On GNU and Unix systems, you can create additional frames on any
40 available terminal, within a single Emacs session, regardless of
41 whether Emacs was started on a text or graphical terminal.  Emacs can
42 display on both graphical and text terminals simultaneously.  This
43 comes in handy, for instance, when you connect to the same session
44 from several remote locations.  @xref{Multiple Terminals}.
46 @defun framep object
47 This predicate returns a non-@code{nil} value if @var{object} is a
48 frame, and @code{nil} otherwise.  For a frame, the value indicates which
49 kind of display the frame uses:
51 @table @code
52 @item t
53 The frame is displayed on a text terminal.
54 @item x
55 The frame is displayed on an X graphical terminal.
56 @item w32
57 The frame is displayed on a MS-Windows graphical terminal.
58 @item ns
59 The frame is displayed on a GNUstep or Macintosh Cocoa graphical
60 terminal.
61 @item pc
62 The frame is displayed on an MS-DOS terminal.
63 @end table
64 @end defun
66 @defun frame-terminal &optional frame
67 This function returns the terminal object that displays @var{frame}.
68 If @var{frame} is @code{nil} or unspecified, it defaults to the
69 selected frame.
70 @end defun
72 @defun terminal-live-p object
73 This predicate returns a non-@code{nil} value if @var{object} is a
74 terminal that is live (i.e., not deleted), and @code{nil} otherwise.
75 For live terminals, the return value indicates what kind of frames are
76 displayed on that terminal; the list of possible values is the same as
77 for @code{framep} above.
78 @end defun
80 @menu
81 * Creating Frames::             Creating additional frames.
82 * Multiple Terminals::          Displaying on several different devices.
83 * Frame Parameters::            Controlling frame size, position, font, etc.
84 * Terminal Parameters::         Parameters common for all frames on terminal.
85 * Frame Titles::                Automatic updating of frame titles.
86 * Deleting Frames::             Frames last until explicitly deleted.
87 * Finding All Frames::          How to examine all existing frames.
88 * Minibuffers and Frames::      How a frame finds the minibuffer to use.
89 * Input Focus::                 Specifying the selected frame.
90 * Visibility of Frames::        Frames may be visible or invisible, or icons.
91 * Raising and Lowering::        Raising a frame makes it hide other windows;
92                                   lowering it makes the others hide it.
93 * Frame Configurations::        Saving the state of all frames.
94 * Mouse Tracking::              Getting events that say when the mouse moves.
95 * Mouse Position::              Asking where the mouse is, or moving it.
96 * Pop-Up Menus::                Displaying a menu for the user to select from.
97 * Dialog Boxes::                Displaying a box to ask yes or no.
98 * Pointer Shape::               Specifying the shape of the mouse pointer.
99 * Window System Selections::    Transferring text to and from other X clients.
100 * Drag and Drop::               Internals of Drag-and-Drop implementation.
101 * Color Names::                 Getting the definitions of color names.
102 * Text Terminal Colors::        Defining colors for text terminals.
103 * Resources::                   Getting resource values from the server.
104 * Display Feature Testing::     Determining the features of a terminal.
105 @end menu
107 @node Creating Frames
108 @section Creating Frames
110 To create a new frame, call the function @code{make-frame}.
112 @deffn Command make-frame &optional alist
113 This function creates and returns a new frame, displaying the current
114 buffer.
116 The @var{alist} argument is an alist that specifies frame parameters
117 for the new frame.  @xref{Frame Parameters}.  If you specify the
118 @code{terminal} parameter in @var{alist}, the new frame is created on
119 that terminal.  Otherwise, if you specify the @code{window-system}
120 frame parameter in @var{alist}, that determines whether the frame
121 should be displayed on a text terminal or a graphical terminal.
122 @xref{Window Systems}.  If neither is specified, the new frame is
123 created in the same terminal as the selected frame.
125 Any parameters not mentioned in @var{alist} default to the values in
126 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
127 parameters not specified there default from the X resources or its
128 equivalent on your operating system (@pxref{X Resources,, X Resources,
129 emacs, The GNU Emacs Manual}).  After the frame is created, Emacs
130 applies any parameters listed in @code{frame-inherited-parameters}
131 (see below) and not present in the argument, taking the values from
132 the frame that was selected when @code{make-frame} was called.
134 This function itself does not make the new frame the selected frame.
135 @xref{Input Focus}.  The previously selected frame remains selected.
136 On graphical terminals, however, the windowing system may select the
137 new frame for its own reasons.
138 @end deffn
140 @defvar before-make-frame-hook
141 A normal hook run by @code{make-frame} before it creates the frame.
142 @end defvar
144 @defvar after-make-frame-functions
145 An abnormal hook run by @code{make-frame} after it creates the frame.
146 Each function in @code{after-make-frame-functions} receives one argument, the
147 frame just created.
148 @end defvar
150 @defvar frame-inherited-parameters
151 This variable specifies the list of frame parameters that a newly
152 created frame inherits from the currently selected frame.  For each
153 parameter (a symbol) that is an element in the list and is not present
154 in the argument to @code{make-frame}, the function sets the value of
155 that parameter in the created frame to its value in the selected
156 frame.
157 @end defvar
159 @node Multiple Terminals
160 @section Multiple Terminals
161 @cindex multiple terminals
162 @cindex multi-tty
163 @cindex multiple X displays
164 @cindex displays, multiple
166   Emacs represents each terminal as a @dfn{terminal object} data type
167 (@pxref{Terminal Type}).  On GNU and Unix systems, Emacs can use
168 multiple terminals simultaneously in each session.  On other systems,
169 it can only use a single terminal.  Each terminal object has the
170 following attributes:
172 @itemize @bullet
173 @item
174 The name of the device used by the terminal (e.g., @samp{:0.0} or
175 @file{/dev/tty}).
177 @item
178 The terminal and keyboard coding systems used on the terminal.
179 @xref{Terminal I/O Encoding}.
181 @item
182 The kind of display associated with the terminal.  This is the symbol
183 returned by the function @code{terminal-live-p} (i.e., @code{x},
184 @code{t}, @code{w32}, @code{ns}, or @code{pc}).  @xref{Frames}.
186 @item
187 A list of terminal parameters.  @xref{Terminal Parameters}.
188 @end itemize
190   There is no primitive for creating terminal objects.  Emacs creates
191 them as needed, such as when you call @code{make-frame-on-display}
192 (described below).
194 @defun terminal-name &optional terminal
195 This function returns the file name of the device used by
196 @var{terminal}.  If @var{terminal} is omitted or @code{nil}, it
197 defaults to the selected frame's terminal.  @var{terminal} can also be
198 a frame, meaning that frame's terminal.
199 @end defun
201 @defun terminal-list
202 This function returns a list of all live terminal objects.
203 @end defun
205 @defun get-device-terminal device
206 This function returns a terminal whose device name is given by
207 @var{device}.  If @var{device} is a string, it can be either the file
208 name of a terminal device, or the name of an X display of the form
209 @samp{@var{host}:@var{server}.@var{screen}}.  If @var{device} is a
210 frame, this function returns that frame's terminal; @code{nil} means
211 the selected frame.  Finally, if @var{device} is a terminal object
212 that represents a live terminal, that terminal is returned.  The
213 function signals an error if its argument is none of the above.
214 @end defun
216 @defun delete-terminal &optional terminal force
217 This function deletes all frames on @var{terminal} and frees the
218 resources used by it.  It runs the abnormal hook
219 @code{delete-terminal-functions}, passing @var{terminal} as the
220 argument to each function.
222 If @var{terminal} is omitted or @code{nil}, it defaults to the
223 selected frame's terminal.  @var{terminal} can also be a frame,
224 meaning that frame's terminal.
226 Normally, this function signals an error if you attempt to delete the
227 sole active terminal, but if @var{force} is non-@code{nil}, you are
228 allowed to do so.  Emacs automatically calls this function when the
229 last frame on a terminal is deleted (@pxref{Deleting Frames}).
230 @end defun
232 @defvar delete-terminal-functions
233 An abnormal hook run by @code{delete-terminal}.  Each function
234 receives one argument, the @var{terminal} argument passed to
235 @code{delete-terminal}.  Due to technical details, the functions may
236 be called either just before the terminal is deleted, or just
237 afterwards.
238 @end defvar
240 @cindex terminal-local variables
241   A few Lisp variables are @dfn{terminal-local}; that is, they have a
242 separate binding for each terminal.  The binding in effect at any time
243 is the one for the terminal that the currently selected frame belongs
244 to.  These variables include @code{default-minibuffer-frame},
245 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
246 @code{system-key-alist}.  They are always terminal-local, and can
247 never be buffer-local (@pxref{Buffer-Local Variables}).
249   On GNU and Unix systems, each X display is a separate graphical
250 terminal.  When Emacs is started from within the X window system, it
251 uses the X display specified by the @env{DISPLAY} environment
252 variable, or by the @samp{--display} option (@pxref{Initial Options,,,
253 emacs, The GNU Emacs Manual}).  Emacs can connect to other X displays
254 via the command @code{make-frame-on-display}.  Each X display has its
255 own selected frame and its own minibuffer windows; however, only one
256 of those frames is ``@emph{the} selected frame'' at any given moment
257 (@pxref{Input Focus}).  Emacs can even connect to other text
258 terminals, by interacting with the @command{emacsclient} program.
259 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
261   A single X server can handle more than one display.  Each X display
262 has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
263 The first two parts, @var{host} and @var{server}, identify the X
264 server; the third part, @var{screen}, identifies a screen number on
265 that X server.  When you use two or more screens belonging to one
266 server, Emacs knows by the similarity in their names that they share a
267 single keyboard.
269   On some ``multi-monitor'' setups, a single X display outputs to more
270 than one physical monitor.  Currently, there is no way for Emacs to
271 distinguish between the different physical monitors.
273 @deffn Command make-frame-on-display display &optional parameters
274 This function creates and returns a new frame on @var{display}, taking
275 the other frame parameters from the alist @var{parameters}.
276 @var{display} should be the name of an X display (a string).
278 Before creating the frame, this function ensures that Emacs is ``set
279 up'' to display graphics.  For instance, if Emacs has not processed X
280 resources (e.g., if it was started on a text terminal), it does so at
281 this time.  In all other respects, this function behaves like
282 @code{make-frame} (@pxref{Creating Frames}).
283 @end deffn
285 @defun x-display-list
286 This function returns a list that indicates which X displays Emacs has
287 a connection to.  The elements of the list are strings, and each one
288 is a display name.
289 @end defun
291 @defun x-open-connection display &optional xrm-string must-succeed
292 This function opens a connection to the X display @var{display},
293 without creating a frame on that display.  Normally, Emacs Lisp
294 programs need not call this function, as @code{make-frame-on-display}
295 calls it automatically.  The only reason for calling it is to check
296 whether communication can be established with a given X display.
298 The optional argument @var{xrm-string}, if not @code{nil}, is a string
299 of resource names and values, in the same format used in the
300 @file{.Xresources} file.  @xref{X Resources,, X Resources, emacs, The
301 GNU Emacs Manual}.  These values apply to all Emacs frames created on
302 this display, overriding the resource values recorded in the X server.
303 Here's an example of what this string might look like:
305 @example
306 "*BorderWidth: 3\n*InternalBorder: 2\n"
307 @end example
309 If @var{must-succeed} is non-@code{nil}, failure to open the connection
310 terminates Emacs.  Otherwise, it is an ordinary Lisp error.
311 @end defun
313 @defun x-close-connection display
314 This function closes the connection to display @var{display}.  Before
315 you can do this, you must first delete all the frames that were open
316 on that display (@pxref{Deleting Frames}).
317 @end defun
319 @node Frame Parameters
320 @section Frame Parameters
321 @cindex frame parameters
323   A frame has many parameters that control its appearance and behavior.
324 Just what parameters a frame has depends on what display mechanism it
325 uses.
327   Frame parameters exist mostly for the sake of graphical displays.
328 Most frame parameters have no effect when applied to a frame on a text
329 terminal; only the @code{height}, @code{width}, @code{name},
330 @code{title}, @code{menu-bar-lines}, @code{buffer-list} and
331 @code{buffer-predicate} parameters do something special.  If the
332 terminal supports colors, the parameters @code{foreground-color},
333 @code{background-color}, @code{background-mode} and
334 @code{display-type} are also meaningful.  If the terminal supports
335 frame transparency, the parameter @code{alpha} is also meaningful.
337 @menu
338 * Parameter Access::       How to change a frame's parameters.
339 * Initial Parameters::     Specifying frame parameters when you make a frame.
340 * Window Frame Parameters:: List of frame parameters for window systems.
341 * Size and Position::      Changing the size and position of a frame.
342 * Geometry::               Parsing geometry specifications.
343 @end menu
345 @node Parameter Access
346 @subsection Access to Frame Parameters
348 These functions let you read and change the parameter values of a
349 frame.
351 @defun frame-parameter frame parameter
352 This function returns the value of the parameter @var{parameter} (a
353 symbol) of @var{frame}.  If @var{frame} is @code{nil}, it returns the
354 selected frame's parameter.  If @var{frame} has no setting for
355 @var{parameter}, this function returns @code{nil}.
356 @end defun
358 @defun frame-parameters &optional frame
359 The function @code{frame-parameters} returns an alist listing all the
360 parameters of @var{frame} and their values.  If @var{frame} is
361 @code{nil} or omitted, this returns the selected frame's parameters
362 @end defun
364 @defun modify-frame-parameters frame alist
365 This function alters the parameters of frame @var{frame} based on the
366 elements of @var{alist}.  Each element of @var{alist} has the form
367 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
368 parameter.  If you don't mention a parameter in @var{alist}, its value
369 doesn't change.  If @var{frame} is @code{nil}, it defaults to the selected
370 frame.
371 @end defun
373 @defun set-frame-parameter frame parm value
374 This function sets the frame parameter @var{parm} to the specified
375 @var{value}.  If @var{frame} is @code{nil}, it defaults to the
376 selected frame.
377 @end defun
379 @defun modify-all-frames-parameters alist
380 This function alters the frame parameters of all existing frames
381 according to @var{alist}, then modifies @code{default-frame-alist}
382 (and, if necessary, @code{initial-frame-alist}) to apply the same
383 parameter values to frames that will be created henceforth.
384 @end defun
386 @node Initial Parameters
387 @subsection Initial Frame Parameters
389 You can specify the parameters for the initial startup frame by
390 setting @code{initial-frame-alist} in your init file (@pxref{Init
391 File}).
393 @defopt initial-frame-alist
394 This variable's value is an alist of parameter values used when
395 creating the initial 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 @cindex minibuffer-only frame
424 If these parameters include @code{(minibuffer . nil)}, that indicates
425 that the initial frame should have no minibuffer.  In this case, Emacs
426 creates a separate @dfn{minibuffer-only frame} as well.
428 @defopt minibuffer-frame-alist
429 This variable's value is an alist of parameter values used when
430 creating an initial minibuffer-only frame (i.e., the minibuffer-only
431 frame that Emacs creates if @code{initial-frame-alist} specifies a
432 frame with no minibuffer).
433 @end defopt
435 @defopt default-frame-alist
436 This is an alist specifying default values of frame parameters for all
437 Emacs frames---the first frame, and subsequent frames.  When using the X
438 Window System, you can get the same results by means of X resources
439 in many cases.
441 Setting this variable does not affect existing frames.  Furthermore,
442 functions that display a buffer in a separate frame may override the
443 default parameters by supplying their own parameters.
444 @end defopt
446 If you invoke Emacs with command-line options that specify frame
447 appearance, those options take effect by adding elements to either
448 @code{initial-frame-alist} or @code{default-frame-alist}.  Options
449 which affect just the initial frame, such as @samp{-geometry} and
450 @samp{--maximized}, add to @code{initial-frame-alist}; the others add
451 to @code{default-frame-alist}.  @pxref{Emacs Invocation,, Command Line
452 Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
454 @node Window Frame Parameters
455 @subsection Window Frame Parameters
456 @cindex frame parameters for windowed displays
458   Just what parameters a frame has depends on what display mechanism
459 it uses.  This section describes the parameters that have special
460 meanings on some or all kinds of terminals.  Of these, @code{name},
461 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
462 @code{buffer-predicate} provide meaningful information in terminal
463 frames, and @code{tty-color-mode} is meaningful only for frames on
464 text terminals.
466 @menu
467 * Basic Parameters::            Parameters that are fundamental.
468 * Position Parameters::         The position of the frame on the screen.
469 * Size Parameters::             Frame's size.
470 * Layout Parameters::           Size of parts of the frame, and
471                                   enabling or disabling some parts.
472 * Buffer Parameters::           Which buffers have been or should be shown.
473 * Management Parameters::       Communicating with the window manager.
474 * Cursor Parameters::           Controlling the cursor appearance.
475 * Font and Color Parameters::   Fonts and colors for the frame text.
476 @end menu
478 @node Basic Parameters
479 @subsubsection Basic Parameters
481   These frame parameters give the most basic information about the
482 frame.  @code{title} and @code{name} are meaningful on all terminals.
484 @table @code
485 @vindex display, a frame parameter
486 @item display
487 The display on which to open this frame.  It should be a string of the
488 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
489 @env{DISPLAY} environment variable.
491 @vindex display-type, a frame parameter
492 @item display-type
493 This parameter describes the range of possible colors that can be used
494 in this frame.  Its value is @code{color}, @code{grayscale} or
495 @code{mono}.
497 @vindex title, a frame parameter
498 @item title
499 If a frame has a non-@code{nil} title, it appears in the window
500 system's title bar at the top of the frame, and also in the mode line
501 of windows in that frame if @code{mode-line-frame-identification} uses
502 @samp{%F} (@pxref{%-Constructs}).  This is normally the case when
503 Emacs is not using a window system, and can only display one frame at
504 a time.  @xref{Frame Titles}.
506 @vindex name, a frame parameter
507 @item name
508 The name of the frame.  The frame name serves as a default for the frame
509 title, if the @code{title} parameter is unspecified or @code{nil}.  If
510 you don't specify a name, Emacs sets the frame name automatically
511 (@pxref{Frame Titles}).
513 If you specify the frame name explicitly when you create the frame, the
514 name is also used (instead of the name of the Emacs executable) when
515 looking up X resources for the frame.
517 @item explicit-name
518 If the frame name was specified explicitly when the frame was created,
519 this parameter will be that name.  If the frame wasn't explicitly
520 named, this parameter will be @code{nil}.
521 @end table
523 @node Position Parameters
524 @subsubsection Position Parameters
525 @cindex window position on display
527   Position parameters' values are normally measured in pixels, but on
528 text terminals they count characters or lines instead.
530 @table @code
531 @vindex left, a frame parameter
532 @item left
533 The position, in pixels, of the left (or right) edge of the frame with
534 respect to the left (or right) edge of the screen.  The value may be:
536 @table @asis
537 @item an integer
538 A positive integer relates the left edge of the frame to the left edge
539 of the screen.  A negative integer relates the right frame edge to the
540 right screen edge.
542 @item @code{(+ @var{pos})}
543 This specifies the position of the left frame edge relative to the left
544 screen edge.  The integer @var{pos} may be positive or negative; a
545 negative value specifies a position outside the screen.
547 @item @code{(- @var{pos})}
548 This specifies the position of the right frame edge relative to the right
549 screen edge.  The integer @var{pos} may be positive or negative; a
550 negative value specifies a position outside the screen.
551 @end table
553 Some window managers ignore program-specified positions.  If you want to
554 be sure the position you specify is not ignored, specify a
555 non-@code{nil} value for the @code{user-position} parameter as well.
557 @vindex top, a frame parameter
558 @item top
559 The screen position of the top (or bottom) edge, in pixels, with respect
560 to the top (or bottom) edge of the screen.  It works just like
561 @code{left}, except vertically instead of horizontally.
563 @vindex icon-left, a frame parameter
564 @item icon-left
565 The screen position of the left edge of the frame's icon, in pixels,
566 counting from the left edge of the screen.  This takes effect when the
567 frame is iconified, if the window manager supports this feature.  If
568 you specify a value for this parameter, then you must also specify a
569 value for @code{icon-top} and vice versa.
571 @vindex icon-top, a frame parameter
572 @item icon-top
573 The screen position of the top edge of the frame's icon, in pixels,
574 counting from the top edge of the screen.  This takes effect when the
575 frame is iconified, if the window manager supports this feature.
577 @vindex user-position, a frame parameter
578 @item user-position
579 When you create a frame and specify its screen position with the
580 @code{left} and @code{top} parameters, use this parameter to say whether
581 the specified position was user-specified (explicitly requested in some
582 way by a human user) or merely program-specified (chosen by a program).
583 A non-@code{nil} value says the position was user-specified.
585 @cindex window positions and window managers
586 Window managers generally heed user-specified positions, and some heed
587 program-specified positions too.  But many ignore program-specified
588 positions, placing the window in a default fashion or letting the user
589 place it with the mouse.  Some window managers, including @code{twm},
590 let the user specify whether to obey program-specified positions or
591 ignore them.
593 When you call @code{make-frame}, you should specify a non-@code{nil}
594 value for this parameter if the values of the @code{left} and @code{top}
595 parameters represent the user's stated preference; otherwise, use
596 @code{nil}.
597 @end table
599 @node Size Parameters
600 @subsubsection Size Parameters
601 @cindex window size on display
603   Frame parameters specify frame sizes in character units.  On
604 graphical displays, the @code{default} face determines the actual
605 pixel sizes of these character units (@pxref{Face Attributes}).
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 can still be resized by dragging window manager decorations
636 with the mouse, while the latter really covers the whole screen and
637 does not allow resizing by mouse dragging.
638 @end table
640 @node Layout Parameters
641 @subsubsection Layout Parameters
642 @cindex layout parameters of frames
643 @cindex frame layout parameters
645   These frame parameters enable or disable various parts of the
646 frame, or control their sizes.
648 @table @code
649 @vindex border-width, a frame parameter
650 @item border-width
651 The width in pixels of the frame's border.
653 @vindex internal-border-width, a frame parameter
654 @item internal-border-width
655 The distance in pixels between text (or fringe) and the frame's border.
657 @vindex vertical-scroll-bars, a frame parameter
658 @item vertical-scroll-bars
659 Whether the frame has scroll bars for vertical scrolling, and which side
660 of the frame they should be on.  The possible values are @code{left},
661 @code{right}, and @code{nil} for no scroll bars.
663 @ignore
664 @vindex horizontal-scroll-bars, a frame parameter
665 @item horizontal-scroll-bars
666 Whether the frame has scroll bars for horizontal scrolling
667 (non-@code{nil} means yes).  Horizontal scroll bars are not currently
668 implemented.
669 @end ignore
671 @vindex scroll-bar-width, a frame parameter
672 @item scroll-bar-width
673 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
674 use the default width.
676 @vindex left-fringe, a frame parameter
677 @vindex right-fringe, a frame parameter
678 @item left-fringe
679 @itemx right-fringe
680 The default width of the left and right fringes of windows in this
681 frame (@pxref{Fringes}).  If either of these is zero, that effectively
682 removes the corresponding fringe.
684 When you use @code{frame-parameter} to query the value of either of
685 these two frame parameters, the return value is always an integer.
686 When using @code{set-frame-parameter}, passing a @code{nil} value
687 imposes an actual default value of 8 pixels.
689 The combined fringe widths must add up to an integral number of
690 columns, so the actual default fringe widths for the frame, as
691 reported by @code{frame-parameter}, may be larger than what you
692 specify.  Any extra width is distributed evenly between the left and
693 right fringe.  However, you can force one fringe or the other to a
694 precise width by specifying that width as a negative integer.  If both
695 widths are negative, only the left fringe gets the specified width.
697 @vindex menu-bar-lines frame parameter
698 @item menu-bar-lines
699 The number of lines to allocate at the top of the frame for a menu
700 bar.  The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
701 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
703 @vindex tool-bar-lines frame parameter
704 @item tool-bar-lines
705 The number of lines to use for the tool bar.  The default is 1 if Tool
706 Bar mode is enabled, and 0 otherwise.  @xref{Tool Bars,,,emacs, The
707 GNU Emacs Manual}.
709 @vindex tool-bar-position frame parameter
710 @item tool-bar-position
711 The position of the tool bar.  Currently only for the GTK tool bar.
712 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
713 The default is  @code{top}.
715 @vindex line-spacing, a frame parameter
716 @item line-spacing
717 Additional space to leave below each text line, in pixels (a positive
718 integer).  @xref{Line Height}, for more information.
719 @end table
721 @node Buffer Parameters
722 @subsubsection Buffer Parameters
724   These frame parameters, meaningful on all kinds of terminals, deal
725 with which buffers have been, or should, be displayed in the frame.
727 @table @code
728 @vindex minibuffer, a frame parameter
729 @item minibuffer
730 Whether this frame has its own minibuffer.  The value @code{t} means
731 yes, @code{nil} means no, @code{only} means this frame is just a
732 minibuffer.  If the value is a minibuffer window (in some other
733 frame), the frame uses that minibuffer.
735 This frame parameter takes effect when the frame is created, and can
736 not be changed afterwards.
738 @vindex buffer-predicate, a frame parameter
739 @item buffer-predicate
740 The buffer-predicate function for this frame.  The function
741 @code{other-buffer} uses this predicate (from the selected frame) to
742 decide which buffers it should consider, if the predicate is not
743 @code{nil}.  It calls the predicate with one argument, a buffer, once for
744 each buffer; if the predicate returns a non-@code{nil} value, it
745 considers that buffer.
747 @vindex buffer-list, a frame parameter
748 @item buffer-list
749 A list of buffers that have been selected in this frame, ordered
750 most-recently-selected first.
752 @vindex unsplittable, a frame parameter
753 @item unsplittable
754 If non-@code{nil}, this frame's window is never split automatically.
755 @end table
757 @node Management Parameters
758 @subsubsection Window Management Parameters
759 @cindex window manager interaction, and frame parameters
761   The following frame parameters control various aspects of the
762 frame's interaction with the window manager.  They have no effect on
763 text terminals.
765 @table @code
766 @vindex visibility, a frame parameter
767 @item visibility
768 The state of visibility of the frame.  There are three possibilities:
769 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
770 iconified.  @xref{Visibility of Frames}.
772 @vindex auto-raise, a frame parameter
773 @item auto-raise
774 If non-@code{nil}, Emacs automatically raises the frame when it is
775 selected.  Some window managers do not allow this.
777 @vindex auto-lower, a frame parameter
778 @item auto-lower
779 If non-@code{nil}, Emacs automatically lowers the frame when it is
780 deselected.  Some window managers do not allow this.
782 @vindex icon-type, a frame parameter
783 @item icon-type
784 The type of icon to use for this frame.  If the value is a string,
785 that specifies a file containing a bitmap to use; @code{nil} specifies
786 no icon (in which case the window manager decides what to show); any
787 other non-@code{nil} value specifies the default Emacs icon.
789 @vindex icon-name, a frame parameter
790 @item icon-name
791 The name to use in the icon for this frame, when and if the icon
792 appears.  If this is @code{nil}, the frame's title is used.
794 @vindex window-id, a frame parameter
795 @item window-id
796 The ID number which the graphical display uses for this frame.  Emacs
797 assigns this parameter when the frame is created; changing the
798 parameter has no effect on the actual ID number.
800 @vindex outer-window-id, a frame parameter
801 @item outer-window-id
802 The ID number of the outermost window-system window in which the frame
803 exists.  As with @code{window-id}, changing this parameter has no
804 actual effect.
806 @vindex wait-for-wm, a frame parameter
807 @item wait-for-wm
808 If non-@code{nil}, tell Xt to wait for the window manager to confirm
809 geometry changes.  Some window managers, including versions of Fvwm2
810 and KDE, fail to confirm, so Xt hangs.  Set this to @code{nil} to
811 prevent hanging with those window managers.
813 @vindex sticky, a frame parameter
814 @item sticky
815 If non-@code{nil}, the frame is visible on all virtual desktops on systems
816 with virtual desktops.
818 @ignore
819 @vindex parent-id, a frame parameter
820 @item parent-id
821 @c ??? Not yet working.
822 The X window number of the window that should be the parent of this one.
823 Specifying this lets you create an Emacs window inside some other
824 application's window.  (It is not certain this will be implemented; try
825 it and see if it works.)
826 @end ignore
827 @end table
829 @node Cursor Parameters
830 @subsubsection Cursor Parameters
831 @cindex cursor, and frame parameters
833   This frame parameter controls the way the cursor looks.
835 @table @code
836 @vindex cursor-type, a frame parameter
837 @item cursor-type
838 How to display the cursor.  Legitimate values are:
840 @table @code
841 @item box
842 Display a filled box.  (This is the default.)
843 @item hollow
844 Display a hollow box.
845 @item nil
846 Don't display a cursor.
847 @item bar
848 Display a vertical bar between characters.
849 @item (bar . @var{width})
850 Display a vertical bar @var{width} pixels wide between characters.
851 @item hbar
852 Display a horizontal bar.
853 @item (hbar . @var{height})
854 Display a horizontal bar @var{height} pixels high.
855 @end table
856 @end table
858 @vindex cursor-type
859 The @code{cursor-type} frame parameter may be overridden by the
860 variables @code{cursor-type} and
861 @code{cursor-in-non-selected-windows}:
863 @defvar cursor-type
864 This buffer-local variable controls how the cursor looks in a selected
865 window showing the buffer.  If its value is @code{t}, that means to
866 use the cursor specified by the @code{cursor-type} frame parameter.
867 Otherwise, the value should be one of the cursor types listed above,
868 and it overrides the @code{cursor-type} frame parameter.
869 @end defvar
871 @defopt cursor-in-non-selected-windows
872 This buffer-local variable controls how the cursor looks in a window
873 that is not selected.  It supports the same values as the
874 @code{cursor-type} frame parameter; also, @code{nil} means don't
875 display a cursor in nonselected windows, and @code{t} (the default)
876 means use a standard modification of the usual cursor type (solid box
877 becomes hollow box, and bar becomes a narrower bar).
878 @end defopt
880 @defopt blink-cursor-alist
881 This variable specifies how to blink the cursor.  Each element has the
882 form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
883 type equals @var{on-state} (comparing using @code{equal}), the
884 corresponding @var{off-state} specifies what the cursor looks like
885 when it blinks ``off''.  Both @var{on-state} and @var{off-state}
886 should be suitable values for the @code{cursor-type} frame parameter.
888 There are various defaults for how to blink each type of cursor, if
889 the type is not mentioned as an @var{on-state} here.  Changes in this
890 variable do not take effect immediately, only when you specify the
891 @code{cursor-type} frame parameter.
892 @end defopt
894 @node Font and Color Parameters
895 @subsubsection Font and Color Parameters
896 @cindex font and color, frame parameters
898   These frame parameters control the use of fonts and colors.
900 @table @code
901 @vindex font-backend, a frame parameter
902 @item font-backend
903 A list of symbols, specifying the @dfn{font backends} to use for
904 drawing fonts in the frame, in order of priority.  On X, there are
905 currently two available font backends: @code{x} (the X core font
906 driver) and @code{xft} (the Xft font driver).  On Windows, there are
907 currently two available font backends: @code{gdi} and
908 @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
909 Manual}).  On other systems, there is only one available font backend,
910 so it does not make sense to modify this frame parameter.
912 @vindex background-mode, a frame parameter
913 @item background-mode
914 This parameter is either @code{dark} or @code{light}, according
915 to whether the background color is a light one or a dark one.
917 @vindex tty-color-mode, a frame parameter
918 @item tty-color-mode
919 @cindex standard colors for character terminals
920 This parameter overrides the terminal's color support as given by the
921 system's terminal capabilities database in that this parameter's value
922 specifies the color mode to use on a text terminal.  The value can be
923 either a symbol or a number.  A number specifies the number of colors
924 to use (and, indirectly, what commands to issue to produce each
925 color).  For example, @code{(tty-color-mode . 8)} specifies use of the
926 ANSI escape sequences for 8 standard text colors.  A value of -1 turns
927 off color support.
929 If the parameter's value is a symbol, it specifies a number through
930 the value of @code{tty-color-mode-alist}, and the associated number is
931 used instead.
933 @vindex screen-gamma, a frame parameter
934 @item screen-gamma
935 @cindex gamma correction
936 If this is a number, Emacs performs ``gamma correction'' which adjusts
937 the brightness of all colors.  The value should be the screen gamma of
938 your display, a floating point number.
940 Usual PC monitors have a screen gamma of 2.2, so color values in
941 Emacs, and in X windows generally, are calibrated to display properly
942 on a monitor with that gamma value.  If you specify 2.2 for
943 @code{screen-gamma}, that means no correction is needed.  Other values
944 request correction, designed to make the corrected colors appear on
945 your screen the way they would have appeared without correction on an
946 ordinary monitor with a gamma value of 2.2.
948 If your monitor displays colors too light, you should specify a
949 @code{screen-gamma} value smaller than 2.2.  This requests correction
950 that makes colors darker.  A screen gamma value of 1.5 may give good
951 results for LCD color displays.
953 @vindex alpha, a frame parameter
954 @item alpha
955 @cindex opacity, frame
956 @cindex transparency, frame
957 @vindex frame-alpha-lower-limit
958 This parameter specifies the opacity of the frame, on graphical
959 displays that support variable opacity.  It should be an integer
960 between 0 and 100, where 0 means completely transparent and 100 means
961 completely opaque.  It can also have a @code{nil} value, which tells
962 Emacs not to set the frame opacity (leaving it to the window manager).
964 To prevent the frame from disappearing completely from view, the
965 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
966 If the value of the frame parameter is less than the value of this
967 variable, Emacs uses the latter.  By default,
968 @code{frame-alpha-lower-limit} is 20.
970 The @code{alpha} frame parameter can also be a cons cell
971 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
972 opacity of the frame when it is selected, and @samp{inactive} is the
973 opacity when it is not selected.
974 @end table
976 The following frame parameters are semi-obsolete in that they are
977 automatically equivalent to particular face attributes of particular
978 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
980 @table @code
981 @vindex font, a frame parameter
982 @item font
983 The name of the font for displaying text in the frame.  This is a
984 string, either a valid font name for your system or the name of an Emacs
985 fontset (@pxref{Fontsets}).  It is equivalent to the @code{font}
986 attribute of the @code{default} face.
988 @vindex foreground-color, a frame parameter
989 @item foreground-color
990 The color to use for the image of a character.  It is equivalent to
991 the @code{:foreground} attribute of the @code{default} face.
993 @vindex background-color, a frame parameter
994 @item background-color
995 The color to use for the background of characters.  It is equivalent to
996 the @code{:background} attribute of the @code{default} face.
998 @vindex mouse-color, a frame parameter
999 @item mouse-color
1000 The color for the mouse pointer.  It is equivalent to the @code{:background}
1001 attribute of the @code{mouse} face.
1003 @vindex cursor-color, a frame parameter
1004 @item cursor-color
1005 The color for the cursor that shows point.  It is equivalent to the
1006 @code{:background} attribute of the @code{cursor} face.
1008 @vindex border-color, a frame parameter
1009 @item border-color
1010 The color for the border of the frame.  It is equivalent to the
1011 @code{:background} attribute of the @code{border} face.
1013 @vindex scroll-bar-foreground, a frame parameter
1014 @item scroll-bar-foreground
1015 If non-@code{nil}, the color for the foreground of scroll bars.  It is
1016 equivalent to the @code{:foreground} attribute of the
1017 @code{scroll-bar} face.
1019 @vindex scroll-bar-background, a frame parameter
1020 @item scroll-bar-background
1021 If non-@code{nil}, the color for the background of scroll bars.  It is
1022 equivalent to the @code{:background} attribute of the
1023 @code{scroll-bar} face.
1024 @end table
1026 @node Size and Position
1027 @subsection Frame Size And Position
1028 @cindex size of frame
1029 @cindex screen size
1030 @cindex frame size
1031 @cindex resize frame
1033   You can read or change the size and position of a frame using the
1034 frame parameters @code{left}, @code{top}, @code{height}, and
1035 @code{width}.  Whatever geometry parameters you don't specify are chosen
1036 by the window manager in its usual fashion.
1038   Here are some special features for working with sizes and positions.
1039 (For the precise meaning of ``selected frame'' used by these functions,
1040 see @ref{Input Focus}.)
1042 @defun set-frame-position frame left top
1043 This function sets the position of the top left corner of @var{frame} to
1044 @var{left} and @var{top}.  These arguments are measured in pixels, and
1045 normally count from the top left corner of the screen.
1047 Negative parameter values position the bottom edge of the window up from
1048 the bottom edge of the screen, or the right window edge to the left of
1049 the right edge of the screen.  It would probably be better if the values
1050 were always counted from the left and top, so that negative arguments
1051 would position the frame partly off the top or left edge of the screen,
1052 but it seems inadvisable to change that now.
1053 @end defun
1055 @defun frame-height &optional frame
1056 @defunx frame-width &optional frame
1057 These functions return the height and width of @var{frame}, measured in
1058 lines and columns.  If you don't supply @var{frame}, they use the
1059 selected frame.
1060 @end defun
1062 @defun frame-pixel-height &optional frame
1063 @defunx frame-pixel-width &optional frame
1064 These functions return the height and width of the main display area
1065 of @var{frame}, measured in pixels.  If you don't supply @var{frame},
1066 they use the selected frame.  For a text terminal, the results are in
1067 characters rather than pixels.
1069 These values include the internal borders, and windows' scroll bars
1070 and fringes (which belong to individual windows, not to the frame
1071 itself).  The exact value of the heights depends on the window-system
1072 and toolkit in use.  With GTK+, the height does not include any tool
1073 bar or menu bar.  With the Motif or Lucid toolkits, it includes the
1074 tool bar but not the menu bar.  In a graphical version with no
1075 toolkit, it includes both the tool bar and menu bar.  For a text
1076 terminal, the result includes the menu bar.
1077 @end defun
1079 @defun frame-char-height &optional frame
1080 @defunx frame-char-width &optional frame
1081 These functions return the height and width of a character in
1082 @var{frame}, measured in pixels.  The values depend on the choice of
1083 font.  If you don't supply @var{frame}, these functions use the selected
1084 frame.
1085 @end defun
1087 @defun set-frame-size frame cols rows
1088 This function sets the size of @var{frame}, measured in characters;
1089 @var{cols} and @var{rows} specify the new width and height.
1091 To set the size based on values measured in pixels, use
1092 @code{frame-char-height} and @code{frame-char-width} to convert
1093 them to units of characters.
1094 @end defun
1096 @defun set-frame-height frame lines &optional pretend
1097 This function resizes @var{frame} to a height of @var{lines} lines.  The
1098 sizes of existing windows in @var{frame} are altered proportionally to
1099 fit.
1101 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
1102 lines of output in @var{frame}, but does not change its value for the
1103 actual height of the frame.  This is only useful on text terminals.
1104 Using a smaller height than the terminal actually implements may be
1105 useful to reproduce behavior observed on a smaller screen, or if the
1106 terminal malfunctions when using its whole screen.  Setting the frame
1107 height ``for real'' does not always work, because knowing the correct
1108 actual size may be necessary for correct cursor positioning on
1109 text terminals.
1110 @end defun
1112 @defun set-frame-width frame width &optional pretend
1113 This function sets the width of @var{frame}, measured in characters.
1114 The argument @var{pretend} has the same meaning as in
1115 @code{set-frame-height}.
1116 @end defun
1118 @c FIXME?  Belongs more in Emacs manual than here?
1119 @c But, e.g., fit-window-to-buffer is in this manual.
1120 @deffn Command fit-frame-to-buffer &optional frame max-height min-height
1121 This command adjusts the height of @var{frame} (the default is the
1122 selected frame) to fit its contents.  The optional arguments
1123 @var{max-height} and @var{min-height} specify the maximum and minimum
1124 new frame heights, respectively.
1126 @vindex fit-frame-to-buffer-bottom-margin
1127 The default minimum height corresponds to @code{window-min-height}.
1128 The default maximum height is the screen height below the current top
1129 position of the frame, minus any margin specified by the option
1130 @code{fit-frame-to-buffer-bottom-margin}.
1131 @end deffn
1133 @node Geometry
1134 @subsection Geometry
1136   Here's how to examine the data in an X-style window geometry
1137 specification:
1139 @defun x-parse-geometry geom
1140 @cindex geometry specification
1141 The function @code{x-parse-geometry} converts a standard X window
1142 geometry string to an alist that you can use as part of the argument to
1143 @code{make-frame}.
1145 The alist describes which parameters were specified in @var{geom}, and
1146 gives the values specified for them.  Each element looks like
1147 @code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
1148 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1150 For the size parameters, the value must be an integer.  The position
1151 parameter names @code{left} and @code{top} are not totally accurate,
1152 because some values indicate the position of the right or bottom edges
1153 instead.  The @var{value} possibilities for the position parameters are:
1154 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1155 as previously described (@pxref{Position Parameters}).
1157 Here is an example:
1159 @example
1160 (x-parse-geometry "35x70+0-0")
1161      @result{} ((height . 70) (width . 35)
1162          (top - 0) (left . 0))
1163 @end example
1164 @end defun
1166 @node Terminal Parameters
1167 @section Terminal Parameters
1168 @cindex terminal parameters
1170   Each terminal has a list of associated parameters.  These
1171 @dfn{terminal parameters} are mostly a convenient way of storage for
1172 terminal-local variables, but some terminal parameters have a special
1173 meaning.
1175   This section describes functions to read and change the parameter values
1176 of a terminal.  They all accept as their argument either a terminal or
1177 a frame; the latter means use that frame's terminal.  An argument of
1178 @code{nil} means the selected frame's terminal.
1180 @defun terminal-parameters &optional terminal
1181 This function returns an alist listing all the parameters of
1182 @var{terminal} and their values.
1183 @end defun
1185 @defun terminal-parameter terminal parameter
1186 This function returns the value of the parameter @var{parameter} (a
1187 symbol) of @var{terminal}.  If @var{terminal} has no setting for
1188 @var{parameter}, this function returns @code{nil}.
1189 @end defun
1191 @defun set-terminal-parameter terminal parameter value
1192 This function sets the parameter @var{parm} of @var{terminal} to the
1193 specified @var{value}, and returns the previous value of that
1194 parameter.
1195 @end defun
1197 Here's a list of a few terminal parameters that have a special
1198 meaning:
1200 @table @code
1201 @item background-mode
1202 The classification of the terminal's background color, either
1203 @code{light} or @code{dark}.
1204 @item normal-erase-is-backspace
1205 Value is either 1 or 0, depending on whether
1206 @code{normal-erase-is-backspace-mode} is turned on or off on this
1207 terminal.  @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1208 @item terminal-initted
1209 After the terminal is initialized, this is set to the
1210 terminal-specific initialization function.
1211 @end table
1213 @node Frame Titles
1214 @section Frame Titles
1215 @cindex frame title
1217   Every frame has a @code{name} parameter; this serves as the default
1218 for the frame title which window systems typically display at the top of
1219 the frame.  You can specify a name explicitly by setting the @code{name}
1220 frame property.
1222   Normally you don't specify the name explicitly, and Emacs computes the
1223 frame name automatically based on a template stored in the variable
1224 @code{frame-title-format}.  Emacs recomputes the name each time the
1225 frame is redisplayed.
1227 @defvar frame-title-format
1228 This variable specifies how to compute a name for a frame when you have
1229 not explicitly specified one.  The variable's value is actually a mode
1230 line construct, just like @code{mode-line-format}, except that the
1231 @samp{%c} and @samp{%l} constructs are ignored.  @xref{Mode Line
1232 Data}.
1233 @end defvar
1235 @defvar icon-title-format
1236 This variable specifies how to compute the name for an iconified frame,
1237 when you have not explicitly specified the frame title.  This title
1238 appears in the icon itself.
1239 @end defvar
1241 @defvar multiple-frames
1242 This variable is set automatically by Emacs.  Its value is @code{t} when
1243 there are two or more frames (not counting minibuffer-only frames or
1244 invisible frames).  The default value of @code{frame-title-format} uses
1245 @code{multiple-frames} so as to put the buffer name in the frame title
1246 only when there is more than one frame.
1248 The value of this variable is not guaranteed to be accurate except
1249 while processing @code{frame-title-format} or
1250 @code{icon-title-format}.
1251 @end defvar
1253 @node Deleting Frames
1254 @section Deleting Frames
1255 @cindex deleting frames
1257   A @dfn{live frame} is one that has not been deleted.  When a frame
1258 is deleted, it is removed from its terminal display, although it may
1259 continue to exist as a Lisp object until there are no more references
1260 to it.
1262 @deffn Command delete-frame &optional frame force
1263 @vindex delete-frame-functions
1264 This function deletes the frame @var{frame}.  Unless @var{frame} is a
1265 tooltip, it first runs the hook @code{delete-frame-functions} (each
1266 function gets one argument, @var{frame}).  By default, @var{frame} is
1267 the selected frame.
1269 A frame cannot be deleted if its minibuffer is used by other frames.
1270 Normally, you cannot delete a frame if all other frames are invisible,
1271 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1272 @end deffn
1274 @defun frame-live-p frame
1275 The function @code{frame-live-p} returns non-@code{nil} if the frame
1276 @var{frame} has not been deleted.  The possible non-@code{nil} return
1277 values are like those of @code{framep}.  @xref{Frames}.
1278 @end defun
1280   Some window managers provide a command to delete a window.  These work
1281 by sending a special message to the program that operates the window.
1282 When Emacs gets one of these commands, it generates a
1283 @code{delete-frame} event, whose normal definition is a command that
1284 calls the function @code{delete-frame}.  @xref{Misc Events}.
1286 @node Finding All Frames
1287 @section Finding All Frames
1288 @cindex frames, scanning all
1290 @defun frame-list
1291 This function returns a list of all the live frames, i.e., those that
1292 have not been deleted.  It is analogous to @code{buffer-list} for
1293 buffers, and includes frames on all terminals.  The list that you get
1294 is newly created, so modifying the list doesn't have any effect on the
1295 internals of Emacs.
1296 @end defun
1298 @defun visible-frame-list
1299 This function returns a list of just the currently visible frames.
1300 @xref{Visibility of Frames}.  Frames on text terminals always count as
1301 ``visible'', even though only the selected one is actually displayed.
1302 @end defun
1304 @defun next-frame &optional frame minibuf
1305 This function lets you cycle conveniently through all the frames on
1306 the current display from an arbitrary starting point.  It returns the
1307 ``next'' frame after @var{frame} in the cycle.  If @var{frame} is
1308 omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
1309 Focus}).
1311 The second argument, @var{minibuf}, says which frames to consider:
1313 @table @asis
1314 @item @code{nil}
1315 Exclude minibuffer-only frames.
1316 @item @code{visible}
1317 Consider all visible frames.
1318 @item 0
1319 Consider all visible or iconified frames.
1320 @item a window
1321 Consider only the frames using that particular window as their
1322 minibuffer.
1323 @item anything else
1324 Consider all frames.
1325 @end table
1326 @end defun
1328 @defun previous-frame &optional frame minibuf
1329 Like @code{next-frame}, but cycles through all frames in the opposite
1330 direction.
1331 @end defun
1333   See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1334 Window Ordering}.
1336 @node Minibuffers and Frames
1337 @section Minibuffers and Frames
1339 Normally, each frame has its own minibuffer window at the bottom, which
1340 is used whenever that frame is selected.  If the frame has a minibuffer,
1341 you can get it with @code{minibuffer-window} (@pxref{Definition of
1342 minibuffer-window}).
1344 However, you can also create a frame with no minibuffer.  Such a frame
1345 must use the minibuffer window of some other frame.  When you create the
1346 frame, you can explicitly specify the minibuffer window to use (in some
1347 other frame).  If you don't, then the minibuffer is found in the frame
1348 which is the value of the variable @code{default-minibuffer-frame}.  Its
1349 value should be a frame that does have a minibuffer.
1351 If you use a minibuffer-only frame, you might want that frame to raise
1352 when you enter the minibuffer.  If so, set the variable
1353 @code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.
1355 @defvar default-minibuffer-frame
1356 This variable specifies the frame to use for the minibuffer window, by
1357 default.  It does not affect existing frames.  It is always local to
1358 the current terminal and cannot be buffer-local.  @xref{Multiple
1359 Terminals}.
1360 @end defvar
1362 @node Input Focus
1363 @section Input Focus
1364 @cindex input focus
1365 @c @cindex selected frame    Duplicates selected-frame
1367 At any time, one frame in Emacs is the @dfn{selected frame}.  The selected
1368 window always resides on the selected frame.
1370 When Emacs displays its frames on several terminals (@pxref{Multiple
1371 Terminals}), each terminal has its own selected frame.  But only one
1372 of these is ``@emph{the} selected frame'': it's the frame that belongs
1373 to the terminal from which the most recent input came.  That is, when
1374 Emacs runs a command that came from a certain terminal, the selected
1375 frame is the one of that terminal.  Since Emacs runs only a single
1376 command at any given time, it needs to consider only one selected
1377 frame at a time; this frame is what we call @dfn{the selected frame}
1378 in this manual.  The display on which the selected frame is shown is
1379 the @dfn{selected frame's display}.
1381 @defun selected-frame
1382 This function returns the selected frame.
1383 @end defun
1385 Some window systems and window managers direct keyboard input to the
1386 window object that the mouse is in; others require explicit clicks or
1387 commands to @dfn{shift the focus} to various window objects.  Either
1388 way, Emacs automatically keeps track of which frame has the focus.  To
1389 explicitly switch to a different frame from a Lisp function, call
1390 @code{select-frame-set-input-focus}.
1392 Lisp programs can also switch frames ``temporarily'' by calling the
1393 function @code{select-frame}.  This does not alter the window system's
1394 concept of focus; rather, it escapes from the window manager's control
1395 until that control is somehow reasserted.
1397 When using a text terminal, only one frame can be displayed at a time
1398 on the terminal, so after a call to @code{select-frame}, the next
1399 redisplay actually displays the newly selected frame.  This frame
1400 remains selected until a subsequent call to @code{select-frame}.  Each
1401 frame on a text terminal has a number which appears in the mode line
1402 before the buffer name (@pxref{Mode Line Variables}).
1404 @defun select-frame-set-input-focus frame &optional norecord
1405 This function selects @var{frame}, raises it (should it happen to be
1406 obscured by other frames) and tries to give it the X server's focus.
1407 On a text terminal, the next redisplay displays the new frame on the
1408 entire terminal screen.  The optional argument @var{norecord} has the
1409 same meaning as for @code{select-frame} (see below).  The return value
1410 of this function is not significant.
1411 @end defun
1413 @deffn Command select-frame frame &optional norecord
1414 This function selects frame @var{frame}, temporarily disregarding the
1415 focus of the X server if any.  The selection of @var{frame} lasts until
1416 the next time the user does something to select a different frame, or
1417 until the next time this function is called.  (If you are using a
1418 window system, the previously selected frame may be restored as the
1419 selected frame after return to the command loop, because it still may
1420 have the window system's input focus.)
1422 The specified @var{frame} becomes the selected frame, and its terminal
1423 becomes the selected terminal.  This function then calls
1424 @code{select-window} as a subroutine, passing the window selected
1425 within @var{frame} as its first argument and @var{norecord} as its
1426 second argument (hence, if @var{norecord} is non-@code{nil}, this
1427 avoids changing the order of recently selected windows nor the buffer
1428 list).  @xref{Selecting Windows}.
1430 This function returns @var{frame}, or @code{nil} if @var{frame} has
1431 been deleted.
1433 In general, you should never use @code{select-frame} in a way that
1434 could switch to a different terminal without switching back when
1435 you're done.
1436 @end deffn
1438 Emacs cooperates with the window system by arranging to select frames as
1439 the server and window manager request.  It does so by generating a
1440 special kind of input event, called a @dfn{focus} event, when
1441 appropriate.  The command loop handles a focus event by calling
1442 @code{handle-switch-frame}.  @xref{Focus Events}.
1444 @deffn Command handle-switch-frame frame
1445 This function handles a focus event by selecting frame @var{frame}.
1447 Focus events normally do their job by invoking this command.
1448 Don't call it for any other reason.
1449 @end deffn
1451 @defun redirect-frame-focus frame &optional focus-frame
1452 This function redirects focus from @var{frame} to @var{focus-frame}.
1453 This means that @var{focus-frame} will receive subsequent keystrokes and
1454 events intended for @var{frame}.  After such an event, the value of
1455 @code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
1456 events specifying @var{frame} will instead select @var{focus-frame}.
1458 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1459 redirection for @var{frame}, which therefore once again receives its own
1460 events.
1462 One use of focus redirection is for frames that don't have minibuffers.
1463 These frames use minibuffers on other frames.  Activating a minibuffer
1464 on another frame redirects focus to that frame.  This puts the focus on
1465 the minibuffer's frame, where it belongs, even though the mouse remains
1466 in the frame that activated the minibuffer.
1468 Selecting a frame can also change focus redirections.  Selecting frame
1469 @code{bar}, when @code{foo} had been selected, changes any redirections
1470 pointing to @code{foo} so that they point to @code{bar} instead.  This
1471 allows focus redirection to work properly when the user switches from
1472 one frame to another using @code{select-window}.
1474 This means that a frame whose focus is redirected to itself is treated
1475 differently from a frame whose focus is not redirected.
1476 @code{select-frame} affects the former but not the latter.
1478 The redirection lasts until @code{redirect-frame-focus} is called to
1479 change it.
1480 @end defun
1482 @defopt focus-follows-mouse
1483 This option is how you inform Emacs whether the window manager transfers
1484 focus when the user moves the mouse.  Non-@code{nil} says that it does.
1485 When this is so, the command @code{other-frame} moves the mouse to a
1486 position consistent with the new selected frame.
1487 @end defopt
1489 @node Visibility of Frames
1490 @section Visibility of Frames
1491 @cindex visible frame
1492 @cindex invisible frame
1493 @cindex iconified frame
1494 @cindex minimized frame
1495 @cindex frame visibility
1497 A frame on a graphical display may be @dfn{visible}, @dfn{invisible},
1498 or @dfn{iconified}.  If it is visible, its contents are displayed in
1499 the usual manner.  If it is iconified, its contents are not displayed,
1500 but there is a little icon somewhere to bring the frame back into view
1501 (some window managers refer to this state as @dfn{minimized} rather
1502 than @dfn{iconified}, but from Emacs' point of view they are the same
1503 thing).  If a frame is invisible, it is not displayed at all.
1505   Visibility is meaningless on text terminals, since only the selected
1506 one is actually displayed in any case.
1508 @defun frame-visible-p frame
1509 This function returns the visibility status of frame @var{frame}.  The
1510 value is @code{t} if @var{frame} is visible, @code{nil} if it is
1511 invisible, and @code{icon} if it is iconified.
1513 On a text terminal, all frames are considered ``visible'' for the
1514 purposes of this function, even though only one frame is displayed.
1515 @xref{Raising and Lowering}.
1516 @end defun
1518 @deffn Command iconify-frame &optional frame
1519 This function iconifies frame @var{frame}.  If you omit @var{frame}, it
1520 iconifies the selected frame.
1521 @end deffn
1523 @deffn Command make-frame-visible &optional frame
1524 This function makes frame @var{frame} visible.  If you omit
1525 @var{frame}, it makes the selected frame visible.  This does not raise
1526 the frame, but you can do that with @code{raise-frame} if you wish
1527 (@pxref{Raising and Lowering}).
1528 @end deffn
1530 @deffn Command make-frame-invisible &optional frame force
1531 This function makes frame @var{frame} invisible.  If you omit
1532 @var{frame}, it makes the selected frame invisible.
1534 Unless @var{force} is non-@code{nil}, this function refuses to make
1535 @var{frame} invisible if all other frames are invisible..
1536 @end deffn
1538   The visibility status of a frame is also available as a frame
1539 parameter.  You can read or change it as such.  @xref{Management
1540 Parameters}.  The user can also iconify and deiconify frames with the
1541 window manager.  This happens below the level at which Emacs can exert
1542 any control, but Emacs does provide events that you can use to keep
1543 track of such changes.  @xref{Misc Events}.
1545 @node Raising and Lowering
1546 @section Raising and Lowering Frames
1548 @cindex raising a frame
1549 @cindex lowering a frame
1550   Most window systems use a desktop metaphor.  Part of this metaphor
1551 is the idea that system-level windows (e.g., Emacs frames) are
1552 stacked in a notional third dimension perpendicular to the screen
1553 surface.  Where two overlap, the one higher up covers the one
1554 underneath.  You can @dfn{raise} or @dfn{lower} a frame using the
1555 functions @code{raise-frame} and @code{lower-frame}.
1557 @deffn Command raise-frame &optional frame
1558 This function raises frame @var{frame} (default, the selected frame).
1559 If @var{frame} is invisible or iconified, this makes it visible.
1560 @end deffn
1562 @deffn Command lower-frame &optional frame
1563 This function lowers frame @var{frame} (default, the selected frame).
1564 @end deffn
1566 @defopt minibuffer-auto-raise
1567 If this is non-@code{nil}, activation of the minibuffer raises the frame
1568 that the minibuffer window is in.
1569 @end defopt
1571   On window systems, you can also enable auto-raising (on frame
1572 selection) or auto-lowering (on frame deselection) using frame
1573 parameters.  @xref{Management Parameters}.
1575 @cindex top frame
1576   The concept of raising and lowering frames also applies to text
1577 terminal frames.  On each text terminal, only the top frame is
1578 displayed at any one time.
1580 @defun tty-top-frame terminal
1581 This function returns the top frame on @var{terminal}.  @var{terminal}
1582 should be a terminal object, a frame (meaning that frame's terminal),
1583 or @code{nil} (meaning the selected frame's terminal).  If it does not
1584 refer to a text terminal, the return value is @code{nil}.
1585 @end defun
1587 @node Frame Configurations
1588 @section Frame Configurations
1589 @cindex frame configuration
1591   A @dfn{frame configuration} records the current arrangement of frames,
1592 all their properties, and the window configuration of each one.
1593 (@xref{Window Configurations}.)
1595 @defun current-frame-configuration
1596 This function returns a frame configuration list that describes
1597 the current arrangement of frames and their contents.
1598 @end defun
1600 @defun set-frame-configuration configuration &optional nodelete
1601 This function restores the state of frames described in
1602 @var{configuration}.  However, this function does not restore deleted
1603 frames.
1605 Ordinarily, this function deletes all existing frames not listed in
1606 @var{configuration}.  But if @var{nodelete} is non-@code{nil}, the
1607 unwanted frames are iconified instead.
1608 @end defun
1610 @node Mouse Tracking
1611 @section Mouse Tracking
1612 @cindex mouse tracking
1613 @c @cindex tracking the mouse   Duplicates track-mouse
1615   Sometimes it is useful to @dfn{track} the mouse, which means to display
1616 something to indicate where the mouse is and move the indicator as the
1617 mouse moves.  For efficient mouse tracking, you need a way to wait until
1618 the mouse actually moves.
1620   The convenient way to track the mouse is to ask for events to represent
1621 mouse motion.  Then you can wait for motion by waiting for an event.  In
1622 addition, you can easily handle any other sorts of events that may
1623 occur.  That is useful, because normally you don't want to track the
1624 mouse forever---only until some other event, such as the release of a
1625 button.
1627 @defspec track-mouse body@dots{}
1628 This special form executes @var{body}, with generation of mouse motion
1629 events enabled.  Typically, @var{body} would use @code{read-event} to
1630 read the motion events and modify the display accordingly.  @xref{Motion
1631 Events}, for the format of mouse motion events.
1633 The value of @code{track-mouse} is that of the last form in @var{body}.
1634 You should design @var{body} to return when it sees the up-event that
1635 indicates the release of the button, or whatever kind of event means
1636 it is time to stop tracking.
1637 @end defspec
1639 The usual purpose of tracking mouse motion is to indicate on the screen
1640 the consequences of pushing or releasing a button at the current
1641 position.
1643 In many cases, you can avoid the need to track the mouse by using
1644 the @code{mouse-face} text property (@pxref{Special Properties}).
1645 That works at a much lower level and runs more smoothly than
1646 Lisp-level mouse tracking.
1648 @ignore
1649 @c These are not implemented yet.
1651 These functions change the screen appearance instantaneously.  The
1652 effect is transient, only until the next ordinary Emacs redisplay.  That
1653 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1654 to change the text, and the body of @code{track-mouse} normally reads
1655 the events itself and does not do redisplay.
1657 @defun x-contour-region window beg end
1658 This function draws lines to make a box around the text from @var{beg}
1659 to @var{end}, in window @var{window}.
1660 @end defun
1662 @defun x-uncontour-region window beg end
1663 This function erases the lines that would make a box around the text
1664 from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
1665 a contour that you previously made by calling @code{x-contour-region}.
1666 @end defun
1668 @defun x-draw-rectangle frame left top right bottom
1669 This function draws a hollow rectangle on frame @var{frame} with the
1670 specified edge coordinates, all measured in pixels from the inside top
1671 left corner.  It uses the cursor color, the one used for indicating the
1672 location of point.
1673 @end defun
1675 @defun x-erase-rectangle frame left top right bottom
1676 This function erases a hollow rectangle on frame @var{frame} with the
1677 specified edge coordinates, all measured in pixels from the inside top
1678 left corner.  Erasure means redrawing the text and background that
1679 normally belong in the specified rectangle.
1680 @end defun
1681 @end ignore
1683 @node Mouse Position
1684 @section Mouse Position
1685 @cindex mouse position
1686 @cindex position of mouse
1688   The functions @code{mouse-position} and @code{set-mouse-position}
1689 give access to the current position of the mouse.
1691 @defun mouse-position
1692 This function returns a description of the position of the mouse.  The
1693 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1694 and @var{y} are integers giving the position in characters relative to
1695 the top left corner of the inside of @var{frame}.
1696 @end defun
1698 @defvar mouse-position-function
1699 If non-@code{nil}, the value of this variable is a function for
1700 @code{mouse-position} to call.  @code{mouse-position} calls this
1701 function just before returning, with its normal return value as the
1702 sole argument, and it returns whatever this function returns to it.
1704 This abnormal hook exists for the benefit of packages like
1705 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1706 @end defvar
1708 @defun set-mouse-position frame x y
1709 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1710 frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
1711 giving the position in characters relative to the top left corner of the
1712 inside of @var{frame}.  If @var{frame} is not visible, this function
1713 does nothing.  The return value is not significant.
1714 @end defun
1716 @defun mouse-pixel-position
1717 This function is like @code{mouse-position} except that it returns
1718 coordinates in units of pixels rather than units of characters.
1719 @end defun
1721 @defun set-mouse-pixel-position frame x y
1722 This function warps the mouse like @code{set-mouse-position} except that
1723 @var{x} and @var{y} are in units of pixels rather than units of
1724 characters.  These coordinates are not required to be within the frame.
1726 If @var{frame} is not visible, this function does nothing.  The return
1727 value is not significant.
1728 @end defun
1730 @defun frame-pointer-visible-p &optional frame
1731 This predicate function returns non-@code{nil} if the mouse pointer
1732 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
1733 @var{frame} omitted or @code{nil} means the selected frame.  This is
1734 useful when @code{make-pointer-invisible} is set to @code{t}: it
1735 allows to know if the pointer has been hidden.
1736 @xref{Mouse Avoidance,,,emacs, The Emacs Manual}.
1737 @end defun
1739 @need 3000
1741 @node Pop-Up Menus
1742 @section Pop-Up Menus
1744   When using a window system, a Lisp program can pop up a menu so that
1745 the user can choose an alternative with the mouse.
1747 @defun x-popup-menu position menu
1748 This function displays a pop-up menu and returns an indication of
1749 what selection the user makes.
1751 The argument @var{position} specifies where on the screen to put the
1752 top left corner of the menu.  It can be either a mouse button event
1753 (which says to put the menu where the user actuated the button) or a
1754 list of this form:
1756 @example
1757 ((@var{xoffset} @var{yoffset}) @var{window})
1758 @end example
1760 @noindent
1761 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1762 pixels, counting from the top left corner of @var{window}.  @var{window}
1763 may be a window or a frame.
1765 If @var{position} is @code{t}, it means to use the current mouse
1766 position.  If @var{position} is @code{nil}, it means to precompute the
1767 key binding equivalents for the keymaps specified in @var{menu},
1768 without actually displaying or popping up the menu.
1770 The argument @var{menu} says what to display in the menu.  It can be a
1771 keymap or a list of keymaps (@pxref{Menu Keymaps}).  In this case, the
1772 return value is the list of events corresponding to the user's choice.
1773 This list has more than one element if the choice occurred in a
1774 submenu.  (Note that @code{x-popup-menu} does not actually execute the
1775 command bound to that sequence of events.)  On toolkits that support
1776 menu titles, the title is taken from the prompt string of @var{menu}
1777 if @var{menu} is a keymap, or from the prompt string of the first
1778 keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
1779 Menus}).
1781 Alternatively, @var{menu} can have the following form:
1783 @example
1784 (@var{title} @var{pane1} @var{pane2}...)
1785 @end example
1787 @noindent
1788 where each pane is a list of form
1790 @example
1791 (@var{title} @var{item1} @var{item2}...)
1792 @end example
1794 Each @var{item} should be a cons cell, @code{(@var{line} . @var{value})},
1795 where @var{line} is a string and @var{value} is the value to return if
1796 that @var{line} is chosen.  Unlike in a menu keymap, a @code{nil}
1797 @var{value} does not make the menu item non-selectable.
1798 Alternatively, each @var{item} can be a string rather than a cons
1799 cell; this makes a non-selectable menu item.
1801 If the user gets rid of the menu without making a valid choice, for
1802 instance by clicking the mouse away from a valid choice or by typing
1803 keyboard input, then this normally results in a quit and
1804 @code{x-popup-menu} does not return.  But if @var{position} is a mouse
1805 button event (indicating that the user invoked the menu with the
1806 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1807 @end defun
1809   @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1810 if you could do the job with a prefix key defined with a menu keymap.
1811 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1812 a} can see the individual items in that menu and provide help for them.
1813 If instead you implement the menu by defining a command that calls
1814 @code{x-popup-menu}, the help facilities cannot know what happens inside
1815 that command, so they cannot give any help for the menu's items.
1817   The menu bar mechanism, which lets you switch between submenus by
1818 moving the mouse, cannot look within the definition of a command to see
1819 that it calls @code{x-popup-menu}.  Therefore, if you try to implement a
1820 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1821 an integrated fashion.  This is why all menu bar submenus are
1822 implemented with menu keymaps within the parent menu, and never with
1823 @code{x-popup-menu}.  @xref{Menu Bar}.
1825   If you want a menu bar submenu to have contents that vary, you should
1826 still use a menu keymap to implement it.  To make the contents vary, add
1827 a hook function to @code{menu-bar-update-hook} to update the contents of
1828 the menu keymap as necessary.
1830 @node Dialog Boxes
1831 @section Dialog Boxes
1832 @cindex dialog boxes
1834   A dialog box is a variant of a pop-up menu---it looks a little
1835 different, it always appears in the center of a frame, and it has just
1836 one level and one or more buttons.  The main use of dialog boxes is
1837 for asking questions that the user can answer with ``yes'', ``no'',
1838 and a few other alternatives.  With a single button, they can also
1839 force the user to acknowledge important information.  The functions
1840 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1841 keyboard, when called from commands invoked by mouse clicks.
1843 @defun x-popup-dialog position contents &optional header
1844 This function displays a pop-up dialog box and returns an indication of
1845 what selection the user makes.  The argument @var{contents} specifies
1846 the alternatives to offer; it has this format:
1848 @example
1849 (@var{title} (@var{string} . @var{value})@dots{})
1850 @end example
1852 @noindent
1853 which looks like the list that specifies a single pane for
1854 @code{x-popup-menu}.
1856 The return value is @var{value} from the chosen alternative.
1858 As for @code{x-popup-menu}, an element of the list may be just a
1859 string instead of a cons cell @code{(@var{string} . @var{value})}.
1860 That makes a box that cannot be selected.
1862 If @code{nil} appears in the list, it separates the left-hand items from
1863 the right-hand items; items that precede the @code{nil} appear on the
1864 left, and items that follow the @code{nil} appear on the right.  If you
1865 don't include a @code{nil} in the list, then approximately half the
1866 items appear on each side.
1868 Dialog boxes always appear in the center of a frame; the argument
1869 @var{position} specifies which frame.  The possible values are as in
1870 @code{x-popup-menu}, but the precise coordinates or the individual
1871 window don't matter; only the frame matters.
1873 If @var{header} is non-@code{nil}, the frame title for the box is
1874 @samp{Information}, otherwise it is @samp{Question}.  The former is used
1875 for @code{message-box} (@pxref{message-box}).
1877 In some configurations, Emacs cannot display a real dialog box; so
1878 instead it displays the same items in a pop-up menu in the center of the
1879 frame.
1881 If the user gets rid of the dialog box without making a valid choice,
1882 for instance using the window manager, then this produces a quit and
1883 @code{x-popup-dialog} does not return.
1884 @end defun
1886 @node Pointer Shape
1887 @section Pointer Shape
1888 @cindex pointer shape
1889 @cindex mouse pointer shape
1891   You can specify the mouse pointer style for particular text or
1892 images using the @code{pointer} text property, and for images with the
1893 @code{:pointer} and @code{:map} image properties.  The values you can
1894 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1895 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1896 @code{hourglass}.  @code{text} stands for the usual mouse pointer
1897 style used over text.
1899   Over void parts of the window (parts that do not correspond to any
1900 of the buffer contents), the mouse pointer usually uses the
1901 @code{arrow} style, but you can specify a different style (one of
1902 those above) by setting @code{void-text-area-pointer}.
1904 @defopt void-text-area-pointer
1905 This variable specifies the mouse pointer style for void text areas.
1906 These include the areas after the end of a line or below the last line
1907 in the buffer.  The default is to use the @code{arrow} (non-text)
1908 pointer style.
1909 @end defopt
1911   When using X, you can specify what the @code{text} pointer style
1912 really looks like by setting the variable @code{x-pointer-shape}.
1914 @defvar x-pointer-shape
1915 This variable specifies the pointer shape to use ordinarily in the
1916 Emacs frame, for the @code{text} pointer style.
1917 @end defvar
1919 @defvar x-sensitive-text-pointer-shape
1920 This variable specifies the pointer shape to use when the mouse
1921 is over mouse-sensitive text.
1922 @end defvar
1924   These variables affect newly created frames.  They do not normally
1925 affect existing frames; however, if you set the mouse color of a
1926 frame, that also installs the current value of those two variables.
1927 @xref{Font and Color Parameters}.
1929   The values you can use, to specify either of these pointer shapes, are
1930 defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
1931 @key{RET} x-pointer @key{RET}} to see a list of them.
1933 @node Window System Selections
1934 @section Window System Selections
1935 @cindex selection (for window systems)
1936 @cindex clipboard
1937 @cindex primary selection
1938 @cindex secondary selection
1940   In the X window system, data can be transferred between different
1941 applications by means of @dfn{selections}.  X defines an arbitrary
1942 number of @dfn{selection types}, each of which can store its own data;
1943 however, only three are commonly used: the @dfn{clipboard},
1944 @dfn{primary selection}, and @dfn{secondary selection}.  @xref{Cut and
1945 Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
1946 commands that make use of these selections.  This section documents
1947 the low-level functions for reading and setting X selections.
1949 @deffn Command x-set-selection type data
1950 This function sets an X selection.  It takes two arguments: a
1951 selection type @var{type}, and the value to assign to it, @var{data}.
1953 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
1954 @code{SECONDARY} or @code{CLIPBOARD}.  These are symbols with
1955 upper-case names, in accord with X Window System conventions.  If
1956 @var{type} is @code{nil}, that stands for @code{PRIMARY}.
1958 If @var{data} is @code{nil}, it means to clear out the selection.
1959 Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
1960 of two integers or list of two integers), an overlay, or a cons of two
1961 markers pointing to the same buffer.  An overlay or a pair of markers
1962 stands for text in the overlay or between the markers.  The argument
1963 @var{data} may also be a vector of valid non-vector selection values.
1965 This function returns @var{data}.
1966 @end deffn
1968 @defun x-get-selection &optional type data-type
1969 This function accesses selections set up by Emacs or by other X
1970 clients.  It takes two optional arguments, @var{type} and
1971 @var{data-type}.  The default for @var{type}, the selection type, is
1972 @code{PRIMARY}.
1974 The @var{data-type} argument specifies the form of data conversion to
1975 use, to convert the raw data obtained from another X client into Lisp
1976 data.  Meaningful values include @code{TEXT}, @code{STRING},
1977 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1978 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1979 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1980 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
1981 @code{INTEGER}.  (These are symbols with upper-case names in accord
1982 with X conventions.)  The default for @var{data-type} is
1983 @code{STRING}.
1984 @end defun
1986 @defopt selection-coding-system
1987 This variable specifies the coding system to use when reading and
1988 writing selections or the clipboard.  @xref{Coding
1989 Systems}.  The default is @code{compound-text-with-extensions}, which
1990 converts to the text representation that X11 normally uses.
1991 @end defopt
1993 @cindex clipboard support (for MS-Windows)
1994 When Emacs runs on MS-Windows, it does not implement X selections in
1995 general, but it does support the clipboard.  @code{x-get-selection}
1996 and @code{x-set-selection} on MS-Windows support the text data type
1997 only; if the clipboard holds other types of data, Emacs treats the
1998 clipboard as empty.
2000 @node Drag and Drop
2001 @section Drag and Drop
2003 @vindex x-dnd-test-function
2004 @vindex x-dnd-known-types
2005   When a user drags something from another application over Emacs, that other
2006 application expects Emacs to tell it if Emacs can handle the data that is
2007 dragged.  The variable @code{x-dnd-test-function} is used by Emacs to determine
2008 what to reply.  The default value is @code{x-dnd-default-test-function}
2009 which accepts drops if the type of the data to be dropped is present in
2010 @code{x-dnd-known-types}.  You can customize @code{x-dnd-test-function} and/or
2011 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
2012 on some other criteria.
2014 @vindex x-dnd-types-alist
2015   If you want to change the way Emacs handles drop of different types
2016 or add a new type, customize @code{x-dnd-types-alist}.  This requires
2017 detailed knowledge of what types other applications use for drag and
2018 drop.
2020 @vindex dnd-protocol-alist
2021   When an URL is dropped on Emacs it may be a file, but it may also be
2022 another URL type (ftp, http, etc.).  Emacs first checks
2023 @code{dnd-protocol-alist} to determine what to do with the URL@.  If
2024 there is no match there and if @code{browse-url-browser-function} is
2025 an alist, Emacs looks for a match there.  If no match is found the
2026 text for the URL is inserted.  If you want to alter Emacs behavior,
2027 you can customize these variables.
2029 @node Color Names
2030 @section Color Names
2032 @cindex color names
2033 @cindex specify color
2034 @cindex numerical RGB color specification
2035   A color name is text (usually in a string) that specifies a color.
2036 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2037 are allowed; use @kbd{M-x list-colors-display} to see a list of
2038 defined names.  You can also specify colors numerically in forms such
2039 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2040 @var{r} specifies the red level, @var{g} specifies the green level,
2041 and @var{b} specifies the blue level.  You can use either one, two,
2042 three, or four hex digits for @var{r}; then you must use the same
2043 number of hex digits for all @var{g} and @var{b} as well, making
2044 either 3, 6, 9 or 12 hex digits in all.  (See the documentation of the
2045 X Window System for more details about numerical RGB specification of
2046 colors.)
2048   These functions provide a way to determine which color names are
2049 valid, and what they look like.  In some cases, the value depends on the
2050 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2051 meaning of the term ``selected frame''.
2053   To read user input of color names with completion, use
2054 @code{read-color} (@pxref{High-Level Completion, read-color}).
2056 @defun color-defined-p color &optional frame
2057 This function reports whether a color name is meaningful.  It returns
2058 @code{t} if so; otherwise, @code{nil}.  The argument @var{frame} says
2059 which frame's display to ask about; if @var{frame} is omitted or
2060 @code{nil}, the selected frame is used.
2062 Note that this does not tell you whether the display you are using
2063 really supports that color.  When using X, you can ask for any defined
2064 color on any kind of display, and you will get some result---typically,
2065 the closest it can do.  To determine whether a frame can really display
2066 a certain color, use @code{color-supported-p} (see below).
2068 @findex x-color-defined-p
2069 This function used to be called @code{x-color-defined-p},
2070 and that name is still supported as an alias.
2071 @end defun
2073 @defun defined-colors &optional frame
2074 This function returns a list of the color names that are defined
2075 and supported on frame @var{frame} (default, the selected frame).
2076 If @var{frame} does not support colors, the value is @code{nil}.
2078 @findex x-defined-colors
2079 This function used to be called @code{x-defined-colors},
2080 and that name is still supported as an alias.
2081 @end defun
2083 @defun color-supported-p color &optional frame background-p
2084 This returns @code{t} if @var{frame} can really display the color
2085 @var{color} (or at least something close to it).  If @var{frame} is
2086 omitted or @code{nil}, the question applies to the selected frame.
2088 Some terminals support a different set of colors for foreground and
2089 background.  If @var{background-p} is non-@code{nil}, that means you are
2090 asking whether @var{color} can be used as a background; otherwise you
2091 are asking whether it can be used as a foreground.
2093 The argument @var{color} must be a valid color name.
2094 @end defun
2096 @defun color-gray-p color &optional frame
2097 This returns @code{t} if @var{color} is a shade of gray, as defined on
2098 @var{frame}'s display.  If @var{frame} is omitted or @code{nil}, the
2099 question applies to the selected frame.  If @var{color} is not a valid
2100 color name, this function returns @code{nil}.
2101 @end defun
2103 @defun color-values color &optional frame
2104 @cindex rgb value
2105 This function returns a value that describes what @var{color} should
2106 ideally look like on @var{frame}.  If @var{color} is defined, the
2107 value is a list of three integers, which give the amount of red, the
2108 amount of green, and the amount of blue.  Each integer ranges in
2109 principle from 0 to 65535, but some displays may not use the full
2110 range.  This three-element list is called the @dfn{rgb values} of the
2111 color.
2113 If @var{color} is not defined, the value is @code{nil}.
2115 @example
2116 (color-values "black")
2117      @result{} (0 0 0)
2118 (color-values "white")
2119      @result{} (65280 65280 65280)
2120 (color-values "red")
2121      @result{} (65280 0 0)
2122 (color-values "pink")
2123      @result{} (65280 49152 51968)
2124 (color-values "hungry")
2125      @result{} nil
2126 @end example
2128 The color values are returned for @var{frame}'s display.  If
2129 @var{frame} is omitted or @code{nil}, the information is returned for
2130 the selected frame's display.  If the frame cannot display colors, the
2131 value is @code{nil}.
2133 @findex x-color-values
2134 This function used to be called @code{x-color-values},
2135 and that name is still supported as an alias.
2136 @end defun
2138 @node Text Terminal Colors
2139 @section Text Terminal Colors
2140 @cindex colors on text terminals
2142   Text terminals usually support only a small number of colors, and
2143 the computer uses small integers to select colors on the terminal.
2144 This means that the computer cannot reliably tell what the selected
2145 color looks like; instead, you have to inform your application which
2146 small integers correspond to which colors.  However, Emacs does know
2147 the standard set of colors and will try to use them automatically.
2149   The functions described in this section control how terminal colors
2150 are used by Emacs.
2152   Several of these functions use or return @dfn{rgb values}, described
2153 in @ref{Color Names}.
2155   These functions accept a display (either a frame or the name of a
2156 terminal) as an optional argument.  We hope in the future to make
2157 Emacs support different colors on different text terminals; then this
2158 argument will specify which terminal to operate on (the default being
2159 the selected frame's terminal; @pxref{Input Focus}).  At present,
2160 though, the @var{frame} argument has no effect.
2162 @defun tty-color-define name number &optional rgb frame
2163 This function associates the color name @var{name} with
2164 color number @var{number} on the terminal.
2166 The optional argument @var{rgb}, if specified, is an rgb value, a list
2167 of three numbers that specify what the color actually looks like.
2168 If you do not specify @var{rgb}, then this color cannot be used by
2169 @code{tty-color-approximate} to approximate other colors, because
2170 Emacs will not know what it looks like.
2171 @end defun
2173 @defun tty-color-clear &optional frame
2174 This function clears the table of defined colors for a text terminal.
2175 @end defun
2177 @defun tty-color-alist &optional frame
2178 This function returns an alist recording the known colors supported by
2179 a text terminal.
2181 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2182 or @code{(@var{name} @var{number})}.  Here, @var{name} is the color
2183 name, @var{number} is the number used to specify it to the terminal.
2184 If present, @var{rgb} is a list of three color values (for red, green,
2185 and blue) that says what the color actually looks like.
2186 @end defun
2188 @defun tty-color-approximate rgb &optional frame
2189 This function finds the closest color, among the known colors
2190 supported for @var{display}, to that described by the rgb value
2191 @var{rgb} (a list of color values).  The return value is an element of
2192 @code{tty-color-alist}.
2193 @end defun
2195 @defun tty-color-translate color &optional frame
2196 This function finds the closest color to @var{color} among the known
2197 colors supported for @var{display} and returns its index (an integer).
2198 If the name @var{color} is not defined, the value is @code{nil}.
2199 @end defun
2201 @node Resources
2202 @section X Resources
2204 This section describes some of the functions and variables for
2205 querying and using X resources, or their equivalent on your operating
2206 system.  @xref{X Resources,, X Resources, emacs, The GNU Emacs
2207 Manual}, for more information about X resources.
2209 @defun x-get-resource attribute class &optional component subclass
2210 The function @code{x-get-resource} retrieves a resource value from the X
2211 Window defaults database.
2213 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2214 This function searches using a key of the form
2215 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2216 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2217 the class.
2219 The optional arguments @var{component} and @var{subclass} add to the key
2220 and the class, respectively.  You must specify both of them or neither.
2221 If you specify them, the key is
2222 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2223 @samp{Emacs.@var{class}.@var{subclass}}.
2224 @end defun
2226 @defvar x-resource-class
2227 This variable specifies the application name that @code{x-get-resource}
2228 should look up.  The default value is @code{"Emacs"}.  You can examine X
2229 resources for application names other than ``Emacs'' by binding this
2230 variable to some other string, around a call to @code{x-get-resource}.
2231 @end defvar
2233 @defvar x-resource-name
2234 This variable specifies the instance name that @code{x-get-resource}
2235 should look up.  The default value is the name Emacs was invoked with,
2236 or the value specified with the @samp{-name} or @samp{-rn} switches.
2237 @end defvar
2239 To illustrate some of the above, suppose that you have the line:
2241 @example
2242 xterm.vt100.background: yellow
2243 @end example
2245 @noindent
2246 in your X resources file (whose name is usually @file{~/.Xdefaults}
2247 or @file{~/.Xresources}).  Then:
2249 @example
2250 @group
2251 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2252   (x-get-resource "vt100.background" "VT100.Background"))
2253      @result{} "yellow"
2254 @end group
2255 @group
2256 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2257   (x-get-resource "background" "VT100" "vt100" "Background"))
2258      @result{} "yellow"
2259 @end group
2260 @end example
2262 @defvar inhibit-x-resources
2263 If this variable is non-@code{nil}, Emacs does not look up X
2264 resources, and X resources do not have any effect when creating new
2265 frames.
2266 @end defvar
2268 @node Display Feature Testing
2269 @section Display Feature Testing
2270 @cindex display feature testing
2272   The functions in this section describe the basic capabilities of a
2273 particular display.  Lisp programs can use them to adapt their behavior
2274 to what the display can do.  For example, a program that ordinarily uses
2275 a popup menu could use the minibuffer if popup menus are not supported.
2277   The optional argument @var{display} in these functions specifies which
2278 display to ask the question about.  It can be a display name, a frame
2279 (which designates the display that frame is on), or @code{nil} (which
2280 refers to the selected frame's display, @pxref{Input Focus}).
2282   @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2283 obtain information about displays.
2285 @defun display-popup-menus-p &optional display
2286 This function returns @code{t} if popup menus are supported on
2287 @var{display}, @code{nil} if not.  Support for popup menus requires that
2288 the mouse be available, since the user cannot choose menu items without
2289 a mouse.
2290 @end defun
2292 @defun display-graphic-p &optional display
2293 This function returns @code{t} if @var{display} is a graphic display
2294 capable of displaying several frames and several different fonts at
2295 once.  This is true for displays that use a window system such as X,
2296 and false for text terminals.
2297 @end defun
2299 @defun display-mouse-p &optional display
2300 @cindex mouse, availability
2301 This function returns @code{t} if @var{display} has a mouse available,
2302 @code{nil} if not.
2303 @end defun
2305 @defun display-color-p &optional display
2306 @findex x-display-color-p
2307 This function returns @code{t} if the screen is a color screen.
2308 It used to be called @code{x-display-color-p}, and that name
2309 is still supported as an alias.
2310 @end defun
2312 @defun display-grayscale-p &optional display
2313 This function returns @code{t} if the screen can display shades of gray.
2314 (All color displays can do this.)
2315 @end defun
2317 @defun display-supports-face-attributes-p attributes &optional display
2318 @anchor{Display Face Attribute Testing}
2319 This function returns non-@code{nil} if all the face attributes in
2320 @var{attributes} are supported (@pxref{Face Attributes}).
2322 The definition of `supported' is somewhat heuristic, but basically
2323 means that a face containing all the attributes in @var{attributes},
2324 when merged with the default face for display, can be represented in a
2325 way that's
2327 @enumerate
2328 @item
2329 different in appearance than the default face, and
2331 @item
2332 `close in spirit' to what the attributes specify, if not exact.
2333 @end enumerate
2335 Point (2) implies that a @code{:weight black} attribute will be
2336 satisfied by any display that can display bold, as will
2337 @code{:foreground "yellow"} as long as some yellowish color can be
2338 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2339 the tty display code's automatic substitution of a `dim' face for
2340 italic.
2341 @end defun
2343 @defun display-selections-p &optional display
2344 This function returns @code{t} if @var{display} supports selections.
2345 Windowed displays normally support selections, but they may also be
2346 supported in some other cases.
2347 @end defun
2349 @defun display-images-p &optional display
2350 This function returns @code{t} if @var{display} can display images.
2351 Windowed displays ought in principle to handle images, but some
2352 systems lack the support for that.  On a display that does not support
2353 images, Emacs cannot display a tool bar.
2354 @end defun
2356 @defun display-screens &optional display
2357 This function returns the number of screens associated with the display.
2358 @end defun
2360 @defun display-pixel-height &optional display
2361 This function returns the height of the screen in pixels.
2362 On a character terminal, it gives the height in characters.
2364 For graphical terminals, note that on ``multi-monitor'' setups this
2365 refers to the pixel width for all physical monitors associated with
2366 @var{display}.  @xref{Multiple Terminals}.
2367 @end defun
2369 @defun display-pixel-width &optional display
2370 This function returns the width of the screen in pixels.
2371 On a character terminal, it gives the width in characters.
2373 For graphical terminals, note that on ``multi-monitor'' setups this
2374 refers to the pixel width for all physical monitors associated with
2375 @var{display}.  @xref{Multiple Terminals}.
2376 @end defun
2378 @defun display-mm-height &optional display
2379 This function returns the height of the screen in millimeters,
2380 or @code{nil} if Emacs cannot get that information.
2381 @end defun
2383 @defun display-mm-width &optional display
2384 This function returns the width of the screen in millimeters,
2385 or @code{nil} if Emacs cannot get that information.
2386 @end defun
2388 @defopt display-mm-dimensions-alist
2389 This variable allows the user to specify the dimensions of graphical
2390 displays returned by @code{display-mm-height} and
2391 @code{display-mm-width} in case the system provides incorrect values.
2392 @end defopt
2394 @defun display-backing-store &optional display
2395 This function returns the backing store capability of the display.
2396 Backing store means recording the pixels of windows (and parts of
2397 windows) that are not exposed, so that when exposed they can be
2398 displayed very quickly.
2400 Values can be the symbols @code{always}, @code{when-mapped}, or
2401 @code{not-useful}.  The function can also return @code{nil}
2402 when the question is inapplicable to a certain kind of display.
2403 @end defun
2405 @defun display-save-under &optional display
2406 This function returns non-@code{nil} if the display supports the
2407 SaveUnder feature.  That feature is used by pop-up windows
2408 to save the pixels they obscure, so that they can pop down
2409 quickly.
2410 @end defun
2412 @defun display-planes &optional display
2413 This function returns the number of planes the display supports.
2414 This is typically the number of bits per pixel.
2415 For a tty display, it is log to base two of the number of colors supported.
2416 @end defun
2418 @defun display-visual-class &optional display
2419 This function returns the visual class for the screen.  The value is
2420 one of the symbols @code{static-gray} (a limited, unchangeable number
2421 of grays), @code{gray-scale} (a full range of grays),
2422 @code{static-color} (a limited, unchangeable number of colors),
2423 @code{pseudo-color} (a limited number of colors), @code{true-color} (a
2424 full range of colors), and @code{direct-color} (a full range of
2425 colors).
2426 @end defun
2428 @defun display-color-cells &optional display
2429 This function returns the number of color cells the screen supports.
2430 @end defun
2432   These functions obtain additional information specifically
2433 about X displays.
2435 @defun x-server-version &optional display
2436 This function returns the list of version numbers of the X server
2437 running the display.  The value is a list of three integers: the major
2438 and minor version numbers of the X protocol, and the
2439 distributor-specific release number of the X server software itself.
2440 @end defun
2442 @defun x-server-vendor &optional display
2443 This function returns the ``vendor'' that provided the X server
2444 software (as a string).  Really this means whoever distributes the X
2445 server.
2447 When the developers of X labeled software distributors as
2448 ``vendors'', they showed their false assumption that no system could
2449 ever be developed and distributed noncommercially.
2450 @end defun
2452 @ignore
2453 @defvar x-no-window-manager
2454 This variable's value is @code{t} if no X window manager is in use.
2455 @end defvar
2456 @end ignore
2458 @ignore
2459 @item
2460 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2461 width and height of an X Window frame, measured in pixels.
2462 @end ignore