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