2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
5 @c See the file elisp.texi for copying conditions.
10 A @dfn{frame} is a screen object that contains one or more Emacs
11 windows (@pxref{Windows}). It is the kind of object called a
12 ``window'' in the terminology of graphical environments; but we can't
13 call it a ``window'' here, because Emacs uses that word in a different
14 way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that
15 represents a frame on the screen. @xref{Frame Type}.
17 A frame initially contains a single main window and/or a minibuffer
18 window; you can subdivide the main window vertically or horizontally
19 into smaller windows. @xref{Splitting Windows}.
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}.
27 @cindex graphical terminal
28 @cindex graphical display
29 There are two classes of terminals: @dfn{text terminals} and
30 @dfn{graphical terminals}. Text terminals are non-graphics-capable
31 displays, including @command{xterm} and other terminal emulators. On
32 a text terminal, each Emacs frame occupies the terminal's entire
33 screen; although you can create additional frames and switch between
34 them, the terminal only shows one frame at a time. Graphical
35 terminals, on the other hand, are managed by graphical display systems
36 such as the X Window System, which allow Emacs to show multiple frames
37 simultaneously on the same display.
39 On GNU and Unix systems, you can create additional frames on any
40 available terminal, within a single Emacs session, regardless of
41 whether Emacs was started on a text or graphical terminal. Emacs can
42 display on both graphical and text terminals simultaneously. This
43 comes in handy, for instance, when you connect to the same session
44 from several remote locations. @xref{Multiple Terminals}.
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:
53 The frame is displayed on a text terminal.
55 The frame is displayed on an X graphical terminal.
57 The frame is displayed on a MS-Windows graphical terminal.
59 The frame is displayed on a GNUstep or Macintosh Cocoa graphical
62 The frame is displayed on an MS-DOS terminal.
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
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.
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.
107 @node Creating Frames
108 @section Creating Frames
110 To create a new frame, call the function @code{make-frame}.
112 @deffn Command make-frame &optional alist
113 This function creates and returns a new frame, displaying the current
116 The @var{alist} argument is an alist that specifies frame parameters
117 for the new frame. @xref{Frame Parameters}. If you specify the
118 @code{terminal} parameter in @var{alist}, the new frame is created on
119 that terminal. Otherwise, if you specify the @code{window-system}
120 frame parameter in @var{alist}, that determines whether the frame
121 should be displayed on a text terminal or a graphical terminal.
122 @xref{Window Systems}. If neither is specified, the new frame is
123 created in the same terminal as the selected frame.
125 Any parameters not mentioned in @var{alist} default to the values in
126 the alist @code{default-frame-alist} (@pxref{Initial Parameters});
127 parameters not specified there default from the X resources or its
128 equivalent on your operating system (@pxref{X Resources,, X Resources,
129 emacs, The GNU Emacs Manual}). After the frame is created, Emacs
130 applies any parameters listed in @code{frame-inherited-parameters}
131 (see below) and not present in the argument, taking the values from
132 the frame that was selected when @code{make-frame} was called.
134 Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
135 window manager might position the frame differently than specified by
136 the positional parameters in @var{alist} (@pxref{Position
137 Parameters}). For example, some window managers have a policy of
138 displaying the frame on the monitor that contains the largest part of
139 the window (a.k.a.@: the @dfn{dominating} monitor).
141 This function itself does not make the new frame the selected frame.
142 @xref{Input Focus}. The previously selected frame remains selected.
143 On graphical terminals, however, the windowing system may select the
144 new frame for its own reasons.
147 @defvar before-make-frame-hook
148 A normal hook run by @code{make-frame} before it creates the frame.
151 @defvar after-make-frame-functions
152 An abnormal hook run by @code{make-frame} after it creates the frame.
153 Each function in @code{after-make-frame-functions} receives one argument, the
157 @defvar frame-inherited-parameters
158 This variable specifies the list of frame parameters that a newly
159 created frame inherits from the currently selected frame. For each
160 parameter (a symbol) that is an element in the list and is not present
161 in the argument to @code{make-frame}, the function sets the value of
162 that parameter in the created frame to its value in the selected
166 @node Multiple Terminals
167 @section Multiple Terminals
168 @cindex multiple terminals
170 @cindex multiple X displays
171 @cindex displays, multiple
173 Emacs represents each terminal as a @dfn{terminal object} data type
174 (@pxref{Terminal Type}). On GNU and Unix systems, Emacs can use
175 multiple terminals simultaneously in each session. On other systems,
176 it can only use a single terminal. Each terminal object has the
177 following attributes:
181 The name of the device used by the terminal (e.g., @samp{:0.0} or
185 The terminal and keyboard coding systems used on the terminal.
186 @xref{Terminal I/O Encoding}.
189 The kind of display associated with the terminal. This is the symbol
190 returned by the function @code{terminal-live-p} (i.e., @code{x},
191 @code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.
194 A list of terminal parameters. @xref{Terminal Parameters}.
197 There is no primitive for creating terminal objects. Emacs creates
198 them as needed, such as when you call @code{make-frame-on-display}
201 @defun terminal-name &optional terminal
202 This function returns the file name of the device used by
203 @var{terminal}. If @var{terminal} is omitted or @code{nil}, it
204 defaults to the selected frame's terminal. @var{terminal} can also be
205 a frame, meaning that frame's terminal.
209 This function returns a list of all live terminal objects.
212 @defun get-device-terminal device
213 This function returns a terminal whose device name is given by
214 @var{device}. If @var{device} is a string, it can be either the file
215 name of a terminal device, or the name of an X display of the form
216 @samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a
217 frame, this function returns that frame's terminal; @code{nil} means
218 the selected frame. Finally, if @var{device} is a terminal object
219 that represents a live terminal, that terminal is returned. The
220 function signals an error if its argument is none of the above.
223 @defun delete-terminal &optional terminal force
224 This function deletes all frames on @var{terminal} and frees the
225 resources used by it. It runs the abnormal hook
226 @code{delete-terminal-functions}, passing @var{terminal} as the
227 argument to each function.
229 If @var{terminal} is omitted or @code{nil}, it defaults to the
230 selected frame's terminal. @var{terminal} can also be a frame,
231 meaning that frame's terminal.
233 Normally, this function signals an error if you attempt to delete the
234 sole active terminal, but if @var{force} is non-@code{nil}, you are
235 allowed to do so. Emacs automatically calls this function when the
236 last frame on a terminal is deleted (@pxref{Deleting Frames}).
239 @defvar delete-terminal-functions
240 An abnormal hook run by @code{delete-terminal}. Each function
241 receives one argument, the @var{terminal} argument passed to
242 @code{delete-terminal}. Due to technical details, the functions may
243 be called either just before the terminal is deleted, or just
247 @cindex terminal-local variables
248 A few Lisp variables are @dfn{terminal-local}; that is, they have a
249 separate binding for each terminal. The binding in effect at any time
250 is the one for the terminal that the currently selected frame belongs
251 to. These variables include @code{default-minibuffer-frame},
252 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
253 @code{system-key-alist}. They are always terminal-local, and can
254 never be buffer-local (@pxref{Buffer-Local Variables}).
256 On GNU and Unix systems, each X display is a separate graphical
257 terminal. When Emacs is started from within the X window system, it
258 uses the X display specified by the @env{DISPLAY} environment
259 variable, or by the @samp{--display} option (@pxref{Initial Options,,,
260 emacs, The GNU Emacs Manual}). Emacs can connect to other X displays
261 via the command @code{make-frame-on-display}. Each X display has its
262 own selected frame and its own minibuffer windows; however, only one
263 of those frames is ``@emph{the} selected frame'' at any given moment
264 (@pxref{Input Focus}). Emacs can even connect to other text
265 terminals, by interacting with the @command{emacsclient} program.
266 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
268 @cindex X display names
269 @cindex display name on X
270 A single X server can handle more than one display. Each X display
271 has a three-part name,
272 @samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}. The
273 first part, @var{hostname}, specifies the name of the machine to which
274 the display is physically connected. The second part,
275 @var{displaynumber}, is a zero-based number that identifies one or
276 more monitors connected to that machine that share a common keyboard
277 and pointing device (mouse, tablet, etc.). The third part,
278 @var{screennumber}, identifies a zero-based screen number (a separate
279 monitor) that is part of a single monitor collection on that X server.
280 When you use two or more screens belonging to one server, Emacs knows
281 by the similarity in their names that they share a single keyboard.
283 Systems that don't use the X window system, such as MS-Windows,
284 don't support the notion of X displays, and have only one display on
285 each host. The display name on these systems doesn't follow the above
286 3-part format; for example, the display name on MS-Windows systems is
287 a constant string @samp{w32}, and exists for compatibility, so that
288 you could pass it to functions that expect a display name.
290 @deffn Command make-frame-on-display display &optional parameters
291 This function creates and returns a new frame on @var{display}, taking
292 the other frame parameters from the alist @var{parameters}.
293 @var{display} should be the name of an X display (a string).
295 Before creating the frame, this function ensures that Emacs is ``set
296 up'' to display graphics. For instance, if Emacs has not processed X
297 resources (e.g., if it was started on a text terminal), it does so at
298 this time. In all other respects, this function behaves like
299 @code{make-frame} (@pxref{Creating Frames}).
302 @defun x-display-list
303 This function returns a list that indicates which X displays Emacs has
304 a connection to. The elements of the list are strings, and each one
308 @defun x-open-connection display &optional xrm-string must-succeed
309 This function opens a connection to the X display @var{display},
310 without creating a frame on that display. Normally, Emacs Lisp
311 programs need not call this function, as @code{make-frame-on-display}
312 calls it automatically. The only reason for calling it is to check
313 whether communication can be established with a given X display.
315 The optional argument @var{xrm-string}, if not @code{nil}, is a string
316 of resource names and values, in the same format used in the
317 @file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The
318 GNU Emacs Manual}. These values apply to all Emacs frames created on
319 this display, overriding the resource values recorded in the X server.
320 Here's an example of what this string might look like:
323 "*BorderWidth: 3\n*InternalBorder: 2\n"
326 If @var{must-succeed} is non-@code{nil}, failure to open the connection
327 terminates Emacs. Otherwise, it is an ordinary Lisp error.
330 @defun x-close-connection display
331 This function closes the connection to display @var{display}. Before
332 you can do this, you must first delete all the frames that were open
333 on that display (@pxref{Deleting Frames}).
336 @cindex multi-monitor
337 On some ``multi-monitor'' setups, a single X display outputs to more
338 than one physical monitor. You can use the functions
339 @code{display-monitor-attributes-list} and @code{frame-monitor-attributes}
340 to obtain information about such setups.
342 @defun display-monitor-attributes-list &optional display
343 This function returns a list of physical monitor attributes on
344 @var{display}, which can be a display name (a string), a terminal, or
345 a frame; if omitted or @code{nil}, it defaults to the selected frame's
346 display. Each element of the list is an association list,
347 representing the attributes of a physical monitor. The first element
348 corresponds to the primary monitor. The attribute keys and values
353 Position of the top-left corner of the monitor's screen and its size,
354 in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}. Note
355 that, if the monitor is not the primary monitor, some of the
356 coordinates might be negative.
359 Position of the top-left corner and size of the work area (``usable''
360 space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}.
361 This may be different from @samp{geometry} in that space occupied by
362 various window manager features (docks, taskbars, etc.) may be
363 excluded from the work area. Whether or not such features actually
364 subtract from the work area depends on the platform and environment.
365 Again, if the monitor is not the primary monitor, some of the
366 coordinates might be negative.
369 Width and height in millimeters as @samp{(@var{width} @var{height})}
372 List of frames that this physical monitor dominates (see below).
375 Name of the physical monitor as @var{string}.
378 Source of the multi-monitor information as @var{string};
379 e.g., @samp{XRandr} or @samp{Xinerama}.
382 @var{x}, @var{y}, @var{width}, and @var{height} are integers.
383 @samp{name} and @samp{source} may be absent.
385 A frame is @dfn{dominated} by a physical monitor when either the
386 largest area of the frame resides in that monitor, or (if the frame
387 does not intersect any physical monitors) that monitor is the closest
388 to the frame. Every (non-tooltip) frame (whether visible or not) in a
389 graphical display is dominated by exactly one physical monitor at a
390 time, though the frame can span multiple (or no) physical monitors.
392 Here's an example of the data produced by this function on a 2-monitor
396 (display-monitor-attributes-list)
398 (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor}
399 (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height}
402 (frames #<frame emacs@@host *Messages* 0x11578c0>
403 #<frame emacs@@host *scratch* 0x114b838>))
404 ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor}
405 (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used}
413 @defun frame-monitor-attributes &optional frame
414 This function returns the attributes of the physical monitor
415 dominating (see above) @var{frame}, which defaults to the selected frame.
418 @node Frame Parameters
419 @section Frame Parameters
420 @cindex frame parameters
422 A frame has many parameters that control its appearance and behavior.
423 Just what parameters a frame has depends on what display mechanism it
426 Frame parameters exist mostly for the sake of graphical displays.
427 Most frame parameters have no effect when applied to a frame on a text
428 terminal; only the @code{height}, @code{width}, @code{name},
429 @code{title}, @code{menu-bar-lines}, @code{buffer-list} and
430 @code{buffer-predicate} parameters do something special. If the
431 terminal supports colors, the parameters @code{foreground-color},
432 @code{background-color}, @code{background-mode} and
433 @code{display-type} are also meaningful. If the terminal supports
434 frame transparency, the parameter @code{alpha} is also meaningful.
437 * Parameter Access:: How to change a frame's parameters.
438 * Initial Parameters:: Specifying frame parameters when you make a frame.
439 * Window Frame Parameters:: List of frame parameters for window systems.
440 * Size and Position:: Changing the size and position of a frame.
441 * Geometry:: Parsing geometry specifications.
444 @node Parameter Access
445 @subsection Access to Frame Parameters
447 These functions let you read and change the parameter values of a
450 @defun frame-parameter frame parameter
451 This function returns the value of the parameter @var{parameter} (a
452 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
453 selected frame's parameter. If @var{frame} has no setting for
454 @var{parameter}, this function returns @code{nil}.
457 @defun frame-parameters &optional frame
458 The function @code{frame-parameters} returns an alist listing all the
459 parameters of @var{frame} and their values. If @var{frame} is
460 @code{nil} or omitted, this returns the selected frame's parameters
463 @defun modify-frame-parameters frame alist
464 This function alters the parameters of frame @var{frame} based on the
465 elements of @var{alist}. Each element of @var{alist} has the form
466 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
467 parameter. If you don't mention a parameter in @var{alist}, its value
468 doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
472 @defun set-frame-parameter frame parm value
473 This function sets the frame parameter @var{parm} to the specified
474 @var{value}. If @var{frame} is @code{nil}, it defaults to the
478 @defun modify-all-frames-parameters alist
479 This function alters the frame parameters of all existing frames
480 according to @var{alist}, then modifies @code{default-frame-alist}
481 (and, if necessary, @code{initial-frame-alist}) to apply the same
482 parameter values to frames that will be created henceforth.
485 @node Initial Parameters
486 @subsection Initial Frame Parameters
488 You can specify the parameters for the initial startup frame by
489 setting @code{initial-frame-alist} in your init file (@pxref{Init
492 @defopt initial-frame-alist
493 This variable's value is an alist of parameter values used when
494 creating the initial frame. You can set this variable to specify the
495 appearance of the initial frame without altering subsequent frames.
496 Each element has the form:
499 (@var{parameter} . @var{value})
502 Emacs creates the initial frame before it reads your init
503 file. After reading that file, Emacs checks @code{initial-frame-alist},
504 and applies the parameter settings in the altered value to the already
505 created initial frame.
507 If these settings affect the frame geometry and appearance, you'll see
508 the frame appear with the wrong ones and then change to the specified
509 ones. If that bothers you, you can specify the same geometry and
510 appearance with X resources; those do take effect before the frame is
511 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
513 X resource settings typically apply to all frames. If you want to
514 specify some X resources solely for the sake of the initial frame, and
515 you don't want them to apply to subsequent frames, here's how to achieve
516 this. Specify parameters in @code{default-frame-alist} to override the
517 X resources for subsequent frames; then, to prevent these from affecting
518 the initial frame, specify the same parameters in
519 @code{initial-frame-alist} with values that match the X resources.
522 @cindex minibuffer-only frame
523 If these parameters include @code{(minibuffer . nil)}, that indicates
524 that the initial frame should have no minibuffer. In this case, Emacs
525 creates a separate @dfn{minibuffer-only frame} as well.
527 @defopt minibuffer-frame-alist
528 This variable's value is an alist of parameter values used when
529 creating an initial minibuffer-only frame (i.e., the minibuffer-only
530 frame that Emacs creates if @code{initial-frame-alist} specifies a
531 frame with no minibuffer).
534 @defopt default-frame-alist
535 This is an alist specifying default values of frame parameters for all
536 Emacs frames---the first frame, and subsequent frames. When using the X
537 Window System, you can get the same results by means of X resources
540 Setting this variable does not affect existing frames. Furthermore,
541 functions that display a buffer in a separate frame may override the
542 default parameters by supplying their own parameters.
545 If you invoke Emacs with command-line options that specify frame
546 appearance, those options take effect by adding elements to either
547 @code{initial-frame-alist} or @code{default-frame-alist}. Options
548 which affect just the initial frame, such as @samp{--geometry} and
549 @samp{--maximized}, add to @code{initial-frame-alist}; the others add
550 to @code{default-frame-alist}. @pxref{Emacs Invocation,, Command Line
551 Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
553 @node Window Frame Parameters
554 @subsection Window Frame Parameters
555 @cindex frame parameters for windowed displays
557 Just what parameters a frame has depends on what display mechanism
558 it uses. This section describes the parameters that have special
559 meanings on some or all kinds of terminals. Of these, @code{name},
560 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
561 @code{buffer-predicate} provide meaningful information in terminal
562 frames, and @code{tty-color-mode} is meaningful only for frames on
566 * Basic Parameters:: Parameters that are fundamental.
567 * Position Parameters:: The position of the frame on the screen.
568 * Size Parameters:: Frame's size.
569 * Layout Parameters:: Size of parts of the frame, and
570 enabling or disabling some parts.
571 * Buffer Parameters:: Which buffers have been or should be shown.
572 * Management Parameters:: Communicating with the window manager.
573 * Cursor Parameters:: Controlling the cursor appearance.
574 * Font and Color Parameters:: Fonts and colors for the frame text.
577 @node Basic Parameters
578 @subsubsection Basic Parameters
580 These frame parameters give the most basic information about the
581 frame. @code{title} and @code{name} are meaningful on all terminals.
584 @vindex display, a frame parameter
586 The display on which to open this frame. It should be a string of the
587 form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the
588 @env{DISPLAY} environment variable. @xref{Multiple Terminals}, for
589 more details about display names.
591 @vindex display-type, a frame parameter
593 This parameter describes the range of possible colors that can be used
594 in this frame. Its value is @code{color}, @code{grayscale} or
597 @vindex title, a frame parameter
599 If a frame has a non-@code{nil} title, it appears in the window
600 system's title bar at the top of the frame, and also in the mode line
601 of windows in that frame if @code{mode-line-frame-identification} uses
602 @samp{%F} (@pxref{%-Constructs}). This is normally the case when
603 Emacs is not using a window system, and can only display one frame at
604 a time. @xref{Frame Titles}.
606 @vindex name, a frame parameter
608 The name of the frame. The frame name serves as a default for the frame
609 title, if the @code{title} parameter is unspecified or @code{nil}. If
610 you don't specify a name, Emacs sets the frame name automatically
611 (@pxref{Frame Titles}).
613 If you specify the frame name explicitly when you create the frame, the
614 name is also used (instead of the name of the Emacs executable) when
615 looking up X resources for the frame.
618 If the frame name was specified explicitly when the frame was created,
619 this parameter will be that name. If the frame wasn't explicitly
620 named, this parameter will be @code{nil}.
623 @node Position Parameters
624 @subsubsection Position Parameters
625 @cindex window position on display
627 Position parameters' values are normally measured in pixels, but on
628 text terminals they count characters or lines instead.
631 @vindex left, a frame parameter
633 The position, in pixels, of the left (or right) edge of the frame with
634 respect to the left (or right) edge of the screen. The value may be:
638 A positive integer relates the left edge of the frame to the left edge
639 of the screen. A negative integer relates the right frame edge to the
642 @item @code{(+ @var{pos})}
643 This specifies the position of the left frame edge relative to the left
644 screen edge. The integer @var{pos} may be positive or negative; a
645 negative value specifies a position outside the screen or on a monitor
646 other than the primary one (for multi-monitor displays).
648 @item @code{(- @var{pos})}
649 This specifies the position of the right frame edge relative to the right
650 screen edge. The integer @var{pos} may be positive or negative; a
651 negative value specifies a position outside the screen or on a monitor
652 other than the primary one (for multi-monitor displays).
655 Some window managers ignore program-specified positions. If you want to
656 be sure the position you specify is not ignored, specify a
657 non-@code{nil} value for the @code{user-position} parameter as well.
659 @vindex top, a frame parameter
661 The screen position of the top (or bottom) edge, in pixels, with respect
662 to the top (or bottom) edge of the screen. It works just like
663 @code{left}, except vertically instead of horizontally.
665 @vindex icon-left, a frame parameter
667 The screen position of the left edge of the frame's icon, in pixels,
668 counting from the left edge of the screen. This takes effect when the
669 frame is iconified, if the window manager supports this feature. If
670 you specify a value for this parameter, then you must also specify a
671 value for @code{icon-top} and vice versa.
673 @vindex icon-top, a frame parameter
675 The screen position of the top edge of the frame's icon, in pixels,
676 counting from the top edge of the screen. This takes effect when the
677 frame is iconified, if the window manager supports this feature.
679 @vindex user-position, a frame parameter
681 When you create a frame and specify its screen position with the
682 @code{left} and @code{top} parameters, use this parameter to say whether
683 the specified position was user-specified (explicitly requested in some
684 way by a human user) or merely program-specified (chosen by a program).
685 A non-@code{nil} value says the position was user-specified.
687 @cindex window positions and window managers
688 Window managers generally heed user-specified positions, and some heed
689 program-specified positions too. But many ignore program-specified
690 positions, placing the window in a default fashion or letting the user
691 place it with the mouse. Some window managers, including @code{twm},
692 let the user specify whether to obey program-specified positions or
695 When you call @code{make-frame}, you should specify a non-@code{nil}
696 value for this parameter if the values of the @code{left} and @code{top}
697 parameters represent the user's stated preference; otherwise, use
701 @node Size Parameters
702 @subsubsection Size Parameters
703 @cindex window size on display
705 Frame parameters specify frame sizes in character units. On
706 graphical displays, the @code{default} face determines the actual
707 pixel sizes of these character units (@pxref{Face Attributes}).
710 @vindex height, a frame parameter
712 The height of the frame contents, in characters. (To get the height in
713 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
715 @vindex width, a frame parameter
717 The width of the frame contents, in characters. (To get the width in
718 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
720 @vindex user-size, a frame parameter
722 This does for the size parameters @code{height} and @code{width} what
723 the @code{user-position} parameter (@pxref{Position Parameters,
724 user-position}) does for the position parameters @code{top} and
727 @cindex full-screen frames
728 @vindex fullscreen, a frame parameter
730 Specify that width, height or both shall be maximized. The value
731 @code{fullwidth} specifies that width shall be as wide as possible.
732 The value @code{fullheight} specifies that height shall be as tall as
733 possible. The value @code{fullboth} specifies that both the width and
734 the height shall be set to the size of the screen. The value
735 @code{maximized} specifies that the frame shall be maximized. The
736 difference between @code{maximized} and @code{fullboth} is that the
737 former can still be resized by dragging window manager decorations
738 with the mouse, while the latter really covers the whole screen and
739 does not allow resizing by mouse dragging.
741 With some window managers you may have to customize the variable
742 @code{frame-resize-pixelwise} to a non-@code{nil} value in order to make
743 a frame appear ``maximized'' or ``fullscreen''.
747 @node Layout Parameters
748 @subsubsection Layout Parameters
749 @cindex layout parameters of frames
750 @cindex frame layout parameters
752 These frame parameters enable or disable various parts of the
753 frame, or control their sizes.
756 @vindex border-width, a frame parameter
758 The width in pixels of the frame's border.
760 @vindex internal-border-width, a frame parameter
761 @item internal-border-width
762 The distance in pixels between text (or fringe) and the frame's border.
764 @vindex vertical-scroll-bars, a frame parameter
765 @item vertical-scroll-bars
766 Whether the frame has scroll bars for vertical scrolling, and which side
767 of the frame they should be on. The possible values are @code{left},
768 @code{right}, and @code{nil} for no scroll bars.
770 @vindex horizontal-scroll-bars, a frame parameter
771 @item horizontal-scroll-bars
772 Whether the frame has scroll bars for horizontal scrolling (@code{t} and
773 @code{bottom} mean yes, @code{nil} means no).
775 @vindex scroll-bar-width, a frame parameter
776 @item scroll-bar-width
777 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
778 use the default width.
780 @vindex scroll-bar-height, a frame parameter
781 @item scroll-bar-height
782 The height of horizontal scroll bars, in pixels, or @code{nil} meaning
783 to use the default height.
785 @vindex left-fringe, a frame parameter
786 @vindex right-fringe, a frame parameter
789 The default width of the left and right fringes of windows in this
790 frame (@pxref{Fringes}). If either of these is zero, that effectively
791 removes the corresponding fringe.
793 When you use @code{frame-parameter} to query the value of either of
794 these two frame parameters, the return value is always an integer.
795 When using @code{set-frame-parameter}, passing a @code{nil} value
796 imposes an actual default value of 8 pixels.
798 @vindex right-divider-width, a frame parameter
799 @item right-divider-width
800 The width (thickness) reserved for the right divider (@pxref{Window
801 Dividers}) of any window on the frame, in pixels. A value of zero means
802 to not draw right dividers.
804 @vindex bottom-divider-width, a frame parameter
805 @item bottom-divider-width
806 The width (thickness) reserved for the bottom divider (@pxref{Window
807 Dividers}) of any window on the frame, in pixels. A value of zero means
808 to not draw bottom dividers.
810 @vindex menu-bar-lines frame parameter
812 The number of lines to allocate at the top of the frame for a menu
813 bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
814 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
816 @vindex tool-bar-lines frame parameter
818 The number of lines to use for the tool bar. The default is 1 if Tool
819 Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The
822 @vindex tool-bar-position frame parameter
823 @item tool-bar-position
824 The position of the tool bar. Currently only for the GTK tool bar.
825 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
826 The default is @code{top}.
828 @vindex line-spacing, a frame parameter
830 Additional space to leave below each text line, in pixels (a positive
831 integer). @xref{Line Height}, for more information.
834 @node Buffer Parameters
835 @subsubsection Buffer Parameters
837 These frame parameters, meaningful on all kinds of terminals, deal
838 with which buffers have been, or should, be displayed in the frame.
841 @vindex minibuffer, a frame parameter
843 Whether this frame has its own minibuffer. The value @code{t} means
844 yes, @code{nil} means no, @code{only} means this frame is just a
845 minibuffer. If the value is a minibuffer window (in some other
846 frame), the frame uses that minibuffer.
848 This frame parameter takes effect when the frame is created, and can
849 not be changed afterwards.
851 @vindex buffer-predicate, a frame parameter
852 @item buffer-predicate
853 The buffer-predicate function for this frame. The function
854 @code{other-buffer} uses this predicate (from the selected frame) to
855 decide which buffers it should consider, if the predicate is not
856 @code{nil}. It calls the predicate with one argument, a buffer, once for
857 each buffer; if the predicate returns a non-@code{nil} value, it
858 considers that buffer.
860 @vindex buffer-list, a frame parameter
862 A list of buffers that have been selected in this frame, ordered
863 most-recently-selected first.
865 @vindex unsplittable, a frame parameter
867 If non-@code{nil}, this frame's window is never split automatically.
870 @node Management Parameters
871 @subsubsection Window Management Parameters
872 @cindex window manager interaction, and frame parameters
874 The following frame parameters control various aspects of the
875 frame's interaction with the window manager. They have no effect on
879 @vindex visibility, a frame parameter
881 The state of visibility of the frame. There are three possibilities:
882 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
883 iconified. @xref{Visibility of Frames}.
885 @vindex auto-raise, a frame parameter
887 If non-@code{nil}, Emacs automatically raises the frame when it is
888 selected. Some window managers do not allow this.
890 @vindex auto-lower, a frame parameter
892 If non-@code{nil}, Emacs automatically lowers the frame when it is
893 deselected. Some window managers do not allow this.
895 @vindex icon-type, a frame parameter
897 The type of icon to use for this frame. If the value is a string,
898 that specifies a file containing a bitmap to use; @code{nil} specifies
899 no icon (in which case the window manager decides what to show); any
900 other non-@code{nil} value specifies the default Emacs icon.
902 @vindex icon-name, a frame parameter
904 The name to use in the icon for this frame, when and if the icon
905 appears. If this is @code{nil}, the frame's title is used.
907 @vindex window-id, a frame parameter
909 The ID number which the graphical display uses for this frame. Emacs
910 assigns this parameter when the frame is created; changing the
911 parameter has no effect on the actual ID number.
913 @vindex outer-window-id, a frame parameter
914 @item outer-window-id
915 The ID number of the outermost window-system window in which the frame
916 exists. As with @code{window-id}, changing this parameter has no
919 @vindex wait-for-wm, a frame parameter
921 If non-@code{nil}, tell Xt to wait for the window manager to confirm
922 geometry changes. Some window managers, including versions of Fvwm2
923 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
924 prevent hanging with those window managers.
926 @vindex sticky, a frame parameter
928 If non-@code{nil}, the frame is visible on all virtual desktops on systems
929 with virtual desktops.
932 @vindex parent-id, a frame parameter
934 @c ??? Not yet working.
935 The X window number of the window that should be the parent of this one.
936 Specifying this lets you create an Emacs window inside some other
937 application's window. (It is not certain this will be implemented; try
938 it and see if it works.)
942 @node Cursor Parameters
943 @subsubsection Cursor Parameters
944 @cindex cursor, and frame parameters
946 This frame parameter controls the way the cursor looks.
949 @vindex cursor-type, a frame parameter
951 How to display the cursor. Legitimate values are:
955 Display a filled box. (This is the default.)
957 Display a hollow box.
959 Don't display a cursor.
961 Display a vertical bar between characters.
962 @item (bar . @var{width})
963 Display a vertical bar @var{width} pixels wide between characters.
965 Display a horizontal bar.
966 @item (hbar . @var{height})
967 Display a horizontal bar @var{height} pixels high.
972 The @code{cursor-type} frame parameter may be overridden by the
973 variables @code{cursor-type} and
974 @code{cursor-in-non-selected-windows}:
977 This buffer-local variable controls how the cursor looks in a selected
978 window showing the buffer. If its value is @code{t}, that means to
979 use the cursor specified by the @code{cursor-type} frame parameter.
980 Otherwise, the value should be one of the cursor types listed above,
981 and it overrides the @code{cursor-type} frame parameter.
984 @defopt cursor-in-non-selected-windows
985 This buffer-local variable controls how the cursor looks in a window
986 that is not selected. It supports the same values as the
987 @code{cursor-type} frame parameter; also, @code{nil} means don't
988 display a cursor in nonselected windows, and @code{t} (the default)
989 means use a standard modification of the usual cursor type (solid box
990 becomes hollow box, and bar becomes a narrower bar).
993 @defopt blink-cursor-alist
994 This variable specifies how to blink the cursor. Each element has the
995 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
996 type equals @var{on-state} (comparing using @code{equal}), the
997 corresponding @var{off-state} specifies what the cursor looks like
998 when it blinks ``off''. Both @var{on-state} and @var{off-state}
999 should be suitable values for the @code{cursor-type} frame parameter.
1001 There are various defaults for how to blink each type of cursor, if
1002 the type is not mentioned as an @var{on-state} here. Changes in this
1003 variable do not take effect immediately, only when you specify the
1004 @code{cursor-type} frame parameter.
1007 @node Font and Color Parameters
1008 @subsubsection Font and Color Parameters
1009 @cindex font and color, frame parameters
1011 These frame parameters control the use of fonts and colors.
1014 @vindex font-backend, a frame parameter
1016 A list of symbols, specifying the @dfn{font backends} to use for
1017 drawing fonts in the frame, in order of priority. On X, there are
1018 currently two available font backends: @code{x} (the X core font
1019 driver) and @code{xft} (the Xft font driver). On MS-Windows, there are
1020 currently two available font backends: @code{gdi} and
1021 @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
1022 Manual}). On other systems, there is only one available font backend,
1023 so it does not make sense to modify this frame parameter.
1025 @vindex background-mode, a frame parameter
1026 @item background-mode
1027 This parameter is either @code{dark} or @code{light}, according
1028 to whether the background color is a light one or a dark one.
1030 @vindex tty-color-mode, a frame parameter
1031 @item tty-color-mode
1032 @cindex standard colors for character terminals
1033 This parameter overrides the terminal's color support as given by the
1034 system's terminal capabilities database in that this parameter's value
1035 specifies the color mode to use on a text terminal. The value can be
1036 either a symbol or a number. A number specifies the number of colors
1037 to use (and, indirectly, what commands to issue to produce each
1038 color). For example, @code{(tty-color-mode . 8)} specifies use of the
1039 ANSI escape sequences for 8 standard text colors. A value of -1 turns
1042 If the parameter's value is a symbol, it specifies a number through
1043 the value of @code{tty-color-mode-alist}, and the associated number is
1046 @vindex screen-gamma, a frame parameter
1048 @cindex gamma correction
1049 If this is a number, Emacs performs ``gamma correction'' which adjusts
1050 the brightness of all colors. The value should be the screen gamma of
1053 Usual PC monitors have a screen gamma of 2.2, so color values in
1054 Emacs, and in X windows generally, are calibrated to display properly
1055 on a monitor with that gamma value. If you specify 2.2 for
1056 @code{screen-gamma}, that means no correction is needed. Other values
1057 request correction, designed to make the corrected colors appear on
1058 your screen the way they would have appeared without correction on an
1059 ordinary monitor with a gamma value of 2.2.
1061 If your monitor displays colors too light, you should specify a
1062 @code{screen-gamma} value smaller than 2.2. This requests correction
1063 that makes colors darker. A screen gamma value of 1.5 may give good
1064 results for LCD color displays.
1066 @vindex alpha, a frame parameter
1068 @cindex opacity, frame
1069 @cindex transparency, frame
1070 @vindex frame-alpha-lower-limit
1071 This parameter specifies the opacity of the frame, on graphical
1072 displays that support variable opacity. It should be an integer
1073 between 0 and 100, where 0 means completely transparent and 100 means
1074 completely opaque. It can also have a @code{nil} value, which tells
1075 Emacs not to set the frame opacity (leaving it to the window manager).
1077 To prevent the frame from disappearing completely from view, the
1078 variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
1079 If the value of the frame parameter is less than the value of this
1080 variable, Emacs uses the latter. By default,
1081 @code{frame-alpha-lower-limit} is 20.
1083 The @code{alpha} frame parameter can also be a cons cell
1084 @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
1085 opacity of the frame when it is selected, and @samp{inactive} is the
1086 opacity when it is not selected.
1089 The following frame parameters are semi-obsolete in that they are
1090 automatically equivalent to particular face attributes of particular
1091 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
1094 @vindex font, a frame parameter
1096 The name of the font for displaying text in the frame. This is a
1097 string, either a valid font name for your system or the name of an Emacs
1098 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
1099 attribute of the @code{default} face.
1101 @vindex foreground-color, a frame parameter
1102 @item foreground-color
1103 The color to use for the image of a character. It is equivalent to
1104 the @code{:foreground} attribute of the @code{default} face.
1106 @vindex background-color, a frame parameter
1107 @item background-color
1108 The color to use for the background of characters. It is equivalent to
1109 the @code{:background} attribute of the @code{default} face.
1111 @vindex mouse-color, a frame parameter
1113 The color for the mouse pointer. It is equivalent to the @code{:background}
1114 attribute of the @code{mouse} face.
1116 @vindex cursor-color, a frame parameter
1118 The color for the cursor that shows point. It is equivalent to the
1119 @code{:background} attribute of the @code{cursor} face.
1121 @vindex border-color, a frame parameter
1123 The color for the border of the frame. It is equivalent to the
1124 @code{:background} attribute of the @code{border} face.
1126 @vindex scroll-bar-foreground, a frame parameter
1127 @item scroll-bar-foreground
1128 If non-@code{nil}, the color for the foreground of scroll bars. It is
1129 equivalent to the @code{:foreground} attribute of the
1130 @code{scroll-bar} face.
1132 @vindex scroll-bar-background, a frame parameter
1133 @item scroll-bar-background
1134 If non-@code{nil}, the color for the background of scroll bars. It is
1135 equivalent to the @code{:background} attribute of the
1136 @code{scroll-bar} face.
1139 @node Size and Position
1140 @subsection Frame Size And Position
1141 @cindex size of frame
1144 @cindex resize frame
1146 You can read or change the size and position of a frame using the
1147 frame parameters @code{left}, @code{top}, @code{height}, and
1148 @code{width}. Whatever geometry parameters you don't specify are chosen
1149 by the window manager in its usual fashion.
1151 Here are some special features for working with sizes and positions.
1152 (For the precise meaning of ``selected frame'' used by these functions,
1153 see @ref{Input Focus}.)
1155 @defun set-frame-position frame left top
1156 This function sets the position of the top left corner of @var{frame} to
1157 @var{left} and @var{top}. These arguments are measured in pixels, and
1158 normally count from the top left corner of the screen.
1160 Negative parameter values position the bottom edge of the window up from
1161 the bottom edge of the screen, or the right window edge to the left of
1162 the right edge of the screen. It would probably be better if the values
1163 were always counted from the left and top, so that negative arguments
1164 would position the frame partly off the top or left edge of the screen,
1165 but it seems inadvisable to change that now.
1168 @defun frame-height &optional frame
1169 @defunx frame-width &optional frame
1170 These functions return the height and width of @var{frame}, measured in
1171 lines and columns. If you don't supply @var{frame}, they use the
1175 @defun frame-pixel-height &optional frame
1176 @defunx frame-pixel-width &optional frame
1177 These functions return the height and width of the main display area
1178 of @var{frame}, measured in pixels. If you don't supply @var{frame},
1179 they use the selected frame. For a text terminal, the results are in
1180 characters rather than pixels.
1182 These values include the internal borders, and windows' scroll bars
1183 and fringes (which belong to individual windows, not to the frame
1184 itself). The exact value of the heights depends on the window-system
1185 and toolkit in use. With GTK+, the height does not include any tool
1186 bar or menu bar. With the Motif or Lucid toolkits, it includes the
1187 tool bar but not the menu bar. In a graphical version with no
1188 toolkit, it includes both the tool bar and menu bar. For a text
1189 terminal, the result includes the menu bar.
1192 @defun frame-char-height &optional frame
1193 @defunx frame-char-width &optional frame
1194 These functions return the height and width of a character in
1195 @var{frame}, measured in pixels. The values depend on the choice of
1196 font. If you don't supply @var{frame}, these functions use the selected
1200 @defopt frame-resize-pixelwise
1201 If this option is @code{nil}, a frame's size is usually rounded to a
1202 multiple of the current values of that frame's @code{frame-char-height}
1203 and @code{frame-char-width}. If this is non-@code{nil}, no rounding
1204 occurs, hence frame sizes can increase/decrease by one pixel.
1206 Setting this causes the next resize operation to pass the corresponding
1207 size hints to the window manager. This means that this variable should
1208 be set only in a user's initial file; applications should never bind it
1211 The precise meaning of a value of @code{nil} for this option depends
1212 on the toolkit used. Dragging the frame border with the mouse is usually
1213 done character-wise. Calling @code{set-frame-size} (see below)
1214 with arguments that do not specify the frame size as an integer multiple
1215 of its character size, however, may: be ignored, cause a
1216 rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows).
1218 With some window managers you may have to set this to non-@code{nil} in
1219 order to make a frame appear truly ``maximized'' or ``fullscreen''.
1222 @defun set-frame-size frame width height pixelwise
1223 This function sets the size of @var{frame}, measured in characters;
1224 @var{width} and @var{height} specify the new width in columns and the
1225 new height in lines.
1227 The optional argument @var{pixelwise} non-@code{nil} means to measure
1228 the new width and height in units of pixels instead. Note that if
1229 @code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
1230 fully honor the request if it does not increase/decrease the frame size
1231 to a multiple of its character size.
1234 @defun set-frame-height frame height &optional pretend pixelwise
1235 This function resizes @var{frame} to a height of @var{height} lines. The
1236 sizes of existing windows in @var{frame} are altered proportionally to
1239 If @var{pretend} is non-@code{nil}, then Emacs displays @var{height}
1240 lines of output in @var{frame}, but does not change its value for the
1241 actual height of the frame. This is only useful on text terminals.
1242 Using a smaller height than the terminal actually implements may be
1243 useful to reproduce behavior observed on a smaller screen, or if the
1244 terminal malfunctions when using its whole screen. Setting the frame
1245 height ``for real'' does not always work, because knowing the correct
1246 actual size may be necessary for correct cursor positioning on
1249 The optional fourth argument @var{pixelwise} non-@code{nil} means that
1250 @var{frame} should be @var{height} pixels high. Note that if
1251 @code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
1252 fully honor the request if it does not increase/decrease the frame
1253 height to a multiple of its character height.
1256 @defun set-frame-width frame width &optional pretend pixelwise
1257 This function sets the width of @var{frame}, measured in characters.
1258 The argument @var{pretend} has the same meaning as in
1259 @code{set-frame-height}.
1261 The optional fourth argument @var{pixelwise} non-@code{nil} means that
1262 @var{frame} should be @var{width} pixels wide. Note that if
1263 @code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
1264 fully honor the request if it does not increase/decrease the frame width
1265 to a multiple of its character width.
1268 @c FIXME? Belongs more in Emacs manual than here?
1269 @c But, e.g., fit-window-to-buffer is in this manual.
1270 If you have a frame that displays only one window, you can fit that
1271 frame to its buffer using the command @code{fit-frame-to-buffer}.
1273 @deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
1274 This command adjusts the size of @var{frame} to display the contents of
1275 its buffer exactly. @var{frame} can be any live frame and defaults to
1276 the selected one. Fitting is done only if @var{frame}'s root window is
1277 live. The arguments @var{max-height}, @var{min-height}, @var{max-width}
1278 and @var{min-width} specify bounds on the new total size of
1279 @var{frame}'s root window. @var{min-height} and @var{min-width} default
1280 to the values of @code{window-min-height} and @code{window-min-width}
1283 If the optional argument @var{only} is @code{vertically}, this function
1284 may resize the frame vertically only. If @var{only} is
1285 @code{horizontally}, it may resize the frame horizontally only.
1288 The behavior of @code{fit-frame-to-buffer} can be controlled with the
1289 help of the two options listed next.
1291 @defopt fit-frame-to-buffer-margins
1292 This option can be used to specify margins around frames to be fit by
1293 @code{fit-frame-to-buffer}. Such margins can be useful to avoid, for
1294 example, that such frames overlap the taskbar.
1296 It specifies the numbers of pixels to be left free on the left, above,
1297 the right, and below a frame that shall be fit. The default specifies
1298 @code{nil} for each which means to use no margins. The value specified
1299 here can be overridden for a specific frame by that frame's
1300 @code{fit-frame-to-buffer-margins} parameter, if present.
1303 @defopt fit-frame-to-buffer-sizes
1304 This option specifies size boundaries for @code{fit-frame-to-buffer}.
1305 It specifies the total maximum and minimum lines and maximum and minimum
1306 columns of the root window of any frame that shall be fit to its buffer.
1307 If any of these values is non-@code{nil}, it overrides the corresponding
1308 argument of @code{fit-frame-to-buffer}.
1313 @subsection Geometry
1315 Here's how to examine the data in an X-style window geometry
1318 @defun x-parse-geometry geom
1319 @cindex geometry specification
1320 The function @code{x-parse-geometry} converts a standard X window
1321 geometry string to an alist that you can use as part of the argument to
1324 The alist describes which parameters were specified in @var{geom}, and
1325 gives the values specified for them. Each element looks like
1326 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
1327 values are @code{left}, @code{top}, @code{width}, and @code{height}.
1329 For the size parameters, the value must be an integer. The position
1330 parameter names @code{left} and @code{top} are not totally accurate,
1331 because some values indicate the position of the right or bottom edges
1332 instead. The @var{value} possibilities for the position parameters are:
1333 an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1334 as previously described (@pxref{Position Parameters}).
1339 (x-parse-geometry "35x70+0-0")
1340 @result{} ((height . 70) (width . 35)
1341 (top - 0) (left . 0))
1345 @node Terminal Parameters
1346 @section Terminal Parameters
1347 @cindex terminal parameters
1349 Each terminal has a list of associated parameters. These
1350 @dfn{terminal parameters} are mostly a convenient way of storage for
1351 terminal-local variables, but some terminal parameters have a special
1354 This section describes functions to read and change the parameter values
1355 of a terminal. They all accept as their argument either a terminal or
1356 a frame; the latter means use that frame's terminal. An argument of
1357 @code{nil} means the selected frame's terminal.
1359 @defun terminal-parameters &optional terminal
1360 This function returns an alist listing all the parameters of
1361 @var{terminal} and their values.
1364 @defun terminal-parameter terminal parameter
1365 This function returns the value of the parameter @var{parameter} (a
1366 symbol) of @var{terminal}. If @var{terminal} has no setting for
1367 @var{parameter}, this function returns @code{nil}.
1370 @defun set-terminal-parameter terminal parameter value
1371 This function sets the parameter @var{parm} of @var{terminal} to the
1372 specified @var{value}, and returns the previous value of that
1376 Here's a list of a few terminal parameters that have a special
1380 @item background-mode
1381 The classification of the terminal's background color, either
1382 @code{light} or @code{dark}.
1383 @item normal-erase-is-backspace
1384 Value is either 1 or 0, depending on whether
1385 @code{normal-erase-is-backspace-mode} is turned on or off on this
1386 terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1387 @item terminal-initted
1388 After the terminal is initialized, this is set to the
1389 terminal-specific initialization function.
1390 @item tty-mode-set-strings
1391 When present, a list of strings containing escape sequences that Emacs
1392 will output while configuring a tty for rendering. Emacs emits these
1393 strings only when configuring a terminal: if you want to enable a mode
1394 on a terminal that is already active (for example, while in
1395 @code{tty-setup-hook}), explicitly output the necessary escape
1396 sequence using @code{send-string-to-terminal} in addition to adding
1397 the sequence to @code{tty-mode-set-strings}.
1398 @item tty-mode-reset-strings
1399 When present, a list of strings that undo the effects of the strings
1400 in @code{tty-mode-set-strings}. Emacs emits these strings when
1401 exiting, deleting a terminal, or suspending itself.
1405 @section Frame Titles
1408 Every frame has a @code{name} parameter; this serves as the default
1409 for the frame title which window systems typically display at the top of
1410 the frame. You can specify a name explicitly by setting the @code{name}
1413 Normally you don't specify the name explicitly, and Emacs computes the
1414 frame name automatically based on a template stored in the variable
1415 @code{frame-title-format}. Emacs recomputes the name each time the
1416 frame is redisplayed.
1418 @defvar frame-title-format
1419 This variable specifies how to compute a name for a frame when you have
1420 not explicitly specified one. The variable's value is actually a mode
1421 line construct, just like @code{mode-line-format}, except that the
1422 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
1426 @defvar icon-title-format
1427 This variable specifies how to compute the name for an iconified frame,
1428 when you have not explicitly specified the frame title. This title
1429 appears in the icon itself.
1432 @defvar multiple-frames
1433 This variable is set automatically by Emacs. Its value is @code{t} when
1434 there are two or more frames (not counting minibuffer-only frames or
1435 invisible frames). The default value of @code{frame-title-format} uses
1436 @code{multiple-frames} so as to put the buffer name in the frame title
1437 only when there is more than one frame.
1439 The value of this variable is not guaranteed to be accurate except
1440 while processing @code{frame-title-format} or
1441 @code{icon-title-format}.
1444 @node Deleting Frames
1445 @section Deleting Frames
1446 @cindex deleting frames
1448 A @dfn{live frame} is one that has not been deleted. When a frame
1449 is deleted, it is removed from its terminal display, although it may
1450 continue to exist as a Lisp object until there are no more references
1453 @deffn Command delete-frame &optional frame force
1454 @vindex delete-frame-functions
1455 This function deletes the frame @var{frame}. Unless @var{frame} is a
1456 tooltip, it first runs the hook @code{delete-frame-functions} (each
1457 function gets one argument, @var{frame}). By default, @var{frame} is
1460 A frame cannot be deleted if its minibuffer is used by other frames.
1461 Normally, you cannot delete a frame if all other frames are invisible,
1462 but if @var{force} is non-@code{nil}, then you are allowed to do so.
1465 @defun frame-live-p frame
1466 The function @code{frame-live-p} returns non-@code{nil} if the frame
1467 @var{frame} has not been deleted. The possible non-@code{nil} return
1468 values are like those of @code{framep}. @xref{Frames}.
1471 Some window managers provide a command to delete a window. These work
1472 by sending a special message to the program that operates the window.
1473 When Emacs gets one of these commands, it generates a
1474 @code{delete-frame} event, whose normal definition is a command that
1475 calls the function @code{delete-frame}. @xref{Misc Events}.
1477 @node Finding All Frames
1478 @section Finding All Frames
1479 @cindex frames, scanning all
1482 This function returns a list of all the live frames, i.e., those that
1483 have not been deleted. It is analogous to @code{buffer-list} for
1484 buffers, and includes frames on all terminals. The list that you get
1485 is newly created, so modifying the list doesn't have any effect on the
1489 @defun visible-frame-list
1490 This function returns a list of just the currently visible frames.
1491 @xref{Visibility of Frames}. Frames on text terminals always count as
1492 ``visible'', even though only the selected one is actually displayed.
1495 @defun next-frame &optional frame minibuf
1496 This function lets you cycle conveniently through all the frames on
1497 the current display from an arbitrary starting point. It returns the
1498 ``next'' frame after @var{frame} in the cycle. If @var{frame} is
1499 omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
1502 The second argument, @var{minibuf}, says which frames to consider:
1506 Exclude minibuffer-only frames.
1507 @item @code{visible}
1508 Consider all visible frames.
1510 Consider all visible or iconified frames.
1512 Consider only the frames using that particular window as their
1515 Consider all frames.
1519 @defun previous-frame &optional frame minibuf
1520 Like @code{next-frame}, but cycles through all frames in the opposite
1524 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1527 @node Minibuffers and Frames
1528 @section Minibuffers and Frames
1530 Normally, each frame has its own minibuffer window at the bottom, which
1531 is used whenever that frame is selected. If the frame has a minibuffer,
1532 you can get it with @code{minibuffer-window} (@pxref{Definition of
1533 minibuffer-window}).
1535 However, you can also create a frame with no minibuffer. Such a frame
1536 must use the minibuffer window of some other frame. When you create the
1537 frame, you can explicitly specify the minibuffer window to use (in some
1538 other frame). If you don't, then the minibuffer is found in the frame
1539 which is the value of the variable @code{default-minibuffer-frame}. Its
1540 value should be a frame that does have a minibuffer.
1542 If you use a minibuffer-only frame, you might want that frame to raise
1543 when you enter the minibuffer. If so, set the variable
1544 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
1546 @defvar default-minibuffer-frame
1547 This variable specifies the frame to use for the minibuffer window, by
1548 default. It does not affect existing frames. It is always local to
1549 the current terminal and cannot be buffer-local. @xref{Multiple
1554 @section Input Focus
1556 @c @cindex selected frame Duplicates selected-frame, same for selected-window.
1558 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
1559 window always resides on the selected frame.
1561 When Emacs displays its frames on several terminals (@pxref{Multiple
1562 Terminals}), each terminal has its own selected frame. But only one
1563 of these is ``@emph{the} selected frame'': it's the frame that belongs
1564 to the terminal from which the most recent input came. That is, when
1565 Emacs runs a command that came from a certain terminal, the selected
1566 frame is the one of that terminal. Since Emacs runs only a single
1567 command at any given time, it needs to consider only one selected
1568 frame at a time; this frame is what we call @dfn{the selected frame}
1569 in this manual. The display on which the selected frame is shown is
1570 the @dfn{selected frame's display}.
1572 @defun selected-frame
1573 This function returns the selected frame.
1576 Some window systems and window managers direct keyboard input to the
1577 window object that the mouse is in; others require explicit clicks or
1578 commands to @dfn{shift the focus} to various window objects. Either
1579 way, Emacs automatically keeps track of which frame has the focus. To
1580 explicitly switch to a different frame from a Lisp function, call
1581 @code{select-frame-set-input-focus}.
1583 Lisp programs can also switch frames ``temporarily'' by calling the
1584 function @code{select-frame}. This does not alter the window system's
1585 concept of focus; rather, it escapes from the window manager's control
1586 until that control is somehow reasserted.
1588 When using a text terminal, only one frame can be displayed at a time
1589 on the terminal, so after a call to @code{select-frame}, the next
1590 redisplay actually displays the newly selected frame. This frame
1591 remains selected until a subsequent call to @code{select-frame}. Each
1592 frame on a text terminal has a number which appears in the mode line
1593 before the buffer name (@pxref{Mode Line Variables}).
1595 @defun select-frame-set-input-focus frame &optional norecord
1596 This function selects @var{frame}, raises it (should it happen to be
1597 obscured by other frames) and tries to give it the X server's focus.
1598 On a text terminal, the next redisplay displays the new frame on the
1599 entire terminal screen. The optional argument @var{norecord} has the
1600 same meaning as for @code{select-frame} (see below). The return value
1601 of this function is not significant.
1604 @deffn Command select-frame frame &optional norecord
1605 This function selects frame @var{frame}, temporarily disregarding the
1606 focus of the X server if any. The selection of @var{frame} lasts until
1607 the next time the user does something to select a different frame, or
1608 until the next time this function is called. (If you are using a
1609 window system, the previously selected frame may be restored as the
1610 selected frame after return to the command loop, because it still may
1611 have the window system's input focus.)
1613 The specified @var{frame} becomes the selected frame, and its terminal
1614 becomes the selected terminal. This function then calls
1615 @code{select-window} as a subroutine, passing the window selected
1616 within @var{frame} as its first argument and @var{norecord} as its
1617 second argument (hence, if @var{norecord} is non-@code{nil}, this
1618 avoids changing the order of recently selected windows nor the buffer
1619 list). @xref{Selecting Windows}.
1621 This function returns @var{frame}, or @code{nil} if @var{frame} has
1624 In general, you should never use @code{select-frame} in a way that
1625 could switch to a different terminal without switching back when
1629 Emacs cooperates with the window system by arranging to select frames as
1630 the server and window manager request. It does so by generating a
1631 special kind of input event, called a @dfn{focus} event, when
1632 appropriate. The command loop handles a focus event by calling
1633 @code{handle-switch-frame}. @xref{Focus Events}.
1635 @deffn Command handle-switch-frame frame
1636 This function handles a focus event by selecting frame @var{frame}.
1638 Focus events normally do their job by invoking this command.
1639 Don't call it for any other reason.
1642 @defun redirect-frame-focus frame &optional focus-frame
1643 This function redirects focus from @var{frame} to @var{focus-frame}.
1644 This means that @var{focus-frame} will receive subsequent keystrokes and
1645 events intended for @var{frame}. After such an event, the value of
1646 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1647 events specifying @var{frame} will instead select @var{focus-frame}.
1649 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1650 redirection for @var{frame}, which therefore once again receives its own
1653 One use of focus redirection is for frames that don't have minibuffers.
1654 These frames use minibuffers on other frames. Activating a minibuffer
1655 on another frame redirects focus to that frame. This puts the focus on
1656 the minibuffer's frame, where it belongs, even though the mouse remains
1657 in the frame that activated the minibuffer.
1659 Selecting a frame can also change focus redirections. Selecting frame
1660 @code{bar}, when @code{foo} had been selected, changes any redirections
1661 pointing to @code{foo} so that they point to @code{bar} instead. This
1662 allows focus redirection to work properly when the user switches from
1663 one frame to another using @code{select-window}.
1665 This means that a frame whose focus is redirected to itself is treated
1666 differently from a frame whose focus is not redirected.
1667 @code{select-frame} affects the former but not the latter.
1669 The redirection lasts until @code{redirect-frame-focus} is called to
1673 @defvar focus-in-hook
1674 This is a normal hook run when an Emacs frame gains input focus.
1677 @defvar focus-out-hook
1678 This is a normal hook run when an Emacs frame loses input focus.
1681 @defopt focus-follows-mouse
1682 This option is how you inform Emacs whether the window manager transfers
1683 focus when the user moves the mouse. Non-@code{nil} says that it does.
1684 When this is so, the command @code{other-frame} moves the mouse to a
1685 position consistent with the new selected frame.
1688 @node Visibility of Frames
1689 @section Visibility of Frames
1690 @cindex visible frame
1691 @cindex invisible frame
1692 @cindex iconified frame
1693 @cindex minimized frame
1694 @cindex frame visibility
1696 A frame on a graphical display may be @dfn{visible}, @dfn{invisible},
1697 or @dfn{iconified}. If it is visible, its contents are displayed in
1698 the usual manner. If it is iconified, its contents are not displayed,
1699 but there is a little icon somewhere to bring the frame back into view
1700 (some window managers refer to this state as @dfn{minimized} rather
1701 than @dfn{iconified}, but from Emacs' point of view they are the same
1702 thing). If a frame is invisible, it is not displayed at all.
1704 Visibility is meaningless on text terminals, since only the selected
1705 one is actually displayed in any case.
1707 @defun frame-visible-p frame
1708 This function returns the visibility status of frame @var{frame}. The
1709 value is @code{t} if @var{frame} is visible, @code{nil} if it is
1710 invisible, and @code{icon} if it is iconified.
1712 On a text terminal, all frames are considered ``visible'' for the
1713 purposes of this function, even though only one frame is displayed.
1714 @xref{Raising and Lowering}.
1717 @deffn Command iconify-frame &optional frame
1718 This function iconifies frame @var{frame}. If you omit @var{frame}, it
1719 iconifies the selected frame.
1722 @deffn Command make-frame-visible &optional frame
1723 This function makes frame @var{frame} visible. If you omit
1724 @var{frame}, it makes the selected frame visible. This does not raise
1725 the frame, but you can do that with @code{raise-frame} if you wish
1726 (@pxref{Raising and Lowering}).
1729 @deffn Command make-frame-invisible &optional frame force
1730 This function makes frame @var{frame} invisible. If you omit
1731 @var{frame}, it makes the selected frame invisible.
1733 Unless @var{force} is non-@code{nil}, this function refuses to make
1734 @var{frame} invisible if all other frames are invisible..
1737 The visibility status of a frame is also available as a frame
1738 parameter. You can read or change it as such. @xref{Management
1739 Parameters}. The user can also iconify and deiconify frames with the
1740 window manager. This happens below the level at which Emacs can exert
1741 any control, but Emacs does provide events that you can use to keep
1742 track of such changes. @xref{Misc Events}.
1744 @node Raising and Lowering
1745 @section Raising and Lowering Frames
1747 @cindex raising a frame
1748 @cindex lowering a frame
1749 Most window systems use a desktop metaphor. Part of this metaphor
1750 is the idea that system-level windows (e.g., Emacs frames) are
1751 stacked in a notional third dimension perpendicular to the screen
1752 surface. Where two overlap, the one higher up covers the one
1753 underneath. You can @dfn{raise} or @dfn{lower} a frame using the
1754 functions @code{raise-frame} and @code{lower-frame}.
1756 @deffn Command raise-frame &optional frame
1757 This function raises frame @var{frame} (default, the selected frame).
1758 If @var{frame} is invisible or iconified, this makes it visible.
1761 @deffn Command lower-frame &optional frame
1762 This function lowers frame @var{frame} (default, the selected frame).
1765 @defopt minibuffer-auto-raise
1766 If this is non-@code{nil}, activation of the minibuffer raises the frame
1767 that the minibuffer window is in.
1770 On window systems, you can also enable auto-raising (on frame
1771 selection) or auto-lowering (on frame deselection) using frame
1772 parameters. @xref{Management Parameters}.
1775 The concept of raising and lowering frames also applies to text
1776 terminal frames. On each text terminal, only the top frame is
1777 displayed at any one time.
1779 @defun tty-top-frame terminal
1780 This function returns the top frame on @var{terminal}. @var{terminal}
1781 should be a terminal object, a frame (meaning that frame's terminal),
1782 or @code{nil} (meaning the selected frame's terminal). If it does not
1783 refer to a text terminal, the return value is @code{nil}.
1786 @node Frame Configurations
1787 @section Frame Configurations
1788 @cindex frame configuration
1790 A @dfn{frame configuration} records the current arrangement of frames,
1791 all their properties, and the window configuration of each one.
1792 (@xref{Window Configurations}.)
1794 @defun current-frame-configuration
1795 This function returns a frame configuration list that describes
1796 the current arrangement of frames and their contents.
1799 @defun set-frame-configuration configuration &optional nodelete
1800 This function restores the state of frames described in
1801 @var{configuration}. However, this function does not restore deleted
1804 Ordinarily, this function deletes all existing frames not listed in
1805 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1806 unwanted frames are iconified instead.
1809 @node Mouse Tracking
1810 @section Mouse Tracking
1811 @cindex mouse tracking
1812 @c @cindex tracking the mouse Duplicates track-mouse
1814 Sometimes it is useful to @dfn{track} the mouse, which means to display
1815 something to indicate where the mouse is and move the indicator as the
1816 mouse moves. For efficient mouse tracking, you need a way to wait until
1817 the mouse actually moves.
1819 The convenient way to track the mouse is to ask for events to represent
1820 mouse motion. Then you can wait for motion by waiting for an event. In
1821 addition, you can easily handle any other sorts of events that may
1822 occur. That is useful, because normally you don't want to track the
1823 mouse forever---only until some other event, such as the release of a
1826 @defspec track-mouse body@dots{}
1827 This special form executes @var{body}, with generation of mouse motion
1828 events enabled. Typically, @var{body} would use @code{read-event} to
1829 read the motion events and modify the display accordingly. @xref{Motion
1830 Events}, for the format of mouse motion events.
1832 The value of @code{track-mouse} is that of the last form in @var{body}.
1833 You should design @var{body} to return when it sees the up-event that
1834 indicates the release of the button, or whatever kind of event means
1835 it is time to stop tracking.
1838 The usual purpose of tracking mouse motion is to indicate on the screen
1839 the consequences of pushing or releasing a button at the current
1842 In many cases, you can avoid the need to track the mouse by using
1843 the @code{mouse-face} text property (@pxref{Special Properties}).
1844 That works at a much lower level and runs more smoothly than
1845 Lisp-level mouse tracking.
1848 @c These are not implemented yet.
1850 These functions change the screen appearance instantaneously. The
1851 effect is transient, only until the next ordinary Emacs redisplay. That
1852 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1853 to change the text, and the body of @code{track-mouse} normally reads
1854 the events itself and does not do redisplay.
1856 @defun x-contour-region window beg end
1857 This function draws lines to make a box around the text from @var{beg}
1858 to @var{end}, in window @var{window}.
1861 @defun x-uncontour-region window beg end
1862 This function erases the lines that would make a box around the text
1863 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1864 a contour that you previously made by calling @code{x-contour-region}.
1867 @defun x-draw-rectangle frame left top right bottom
1868 This function draws a hollow rectangle on frame @var{frame} with the
1869 specified edge coordinates, all measured in pixels from the inside top
1870 left corner. It uses the cursor color, the one used for indicating the
1874 @defun x-erase-rectangle frame left top right bottom
1875 This function erases a hollow rectangle on frame @var{frame} with the
1876 specified edge coordinates, all measured in pixels from the inside top
1877 left corner. Erasure means redrawing the text and background that
1878 normally belong in the specified rectangle.
1882 @node Mouse Position
1883 @section Mouse Position
1884 @cindex mouse position
1885 @cindex position of mouse
1887 The functions @code{mouse-position} and @code{set-mouse-position}
1888 give access to the current position of the mouse.
1890 @defun mouse-position
1891 This function returns a description of the position of the mouse. The
1892 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1893 and @var{y} are integers giving the position in characters relative to
1894 the top left corner of the inside of @var{frame}.
1897 @defvar mouse-position-function
1898 If non-@code{nil}, the value of this variable is a function for
1899 @code{mouse-position} to call. @code{mouse-position} calls this
1900 function just before returning, with its normal return value as the
1901 sole argument, and it returns whatever this function returns to it.
1903 This abnormal hook exists for the benefit of packages like
1904 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1907 @defun set-mouse-position frame x y
1908 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1909 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1910 giving the position in characters relative to the top left corner of the
1911 inside of @var{frame}. If @var{frame} is not visible, this function
1912 does nothing. The return value is not significant.
1915 @defun mouse-pixel-position
1916 This function is like @code{mouse-position} except that it returns
1917 coordinates in units of pixels rather than units of characters.
1920 @defun set-mouse-pixel-position frame x y
1921 This function warps the mouse like @code{set-mouse-position} except that
1922 @var{x} and @var{y} are in units of pixels rather than units of
1923 characters. These coordinates are not required to be within the frame.
1925 If @var{frame} is not visible, this function does nothing. The return
1926 value is not significant.
1929 @defun frame-pointer-visible-p &optional frame
1930 This predicate function returns non-@code{nil} if the mouse pointer
1931 displayed on @var{frame} is visible; otherwise it returns @code{nil}.
1932 @var{frame} omitted or @code{nil} means the selected frame. This is
1933 useful when @code{make-pointer-invisible} is set to @code{t}: it
1934 allows to know if the pointer has been hidden.
1935 @xref{Mouse Avoidance,,,emacs, The Emacs Manual}.
1941 @section Pop-Up Menus
1943 A Lisp program can pop up a menu so that the user can choose an
1944 alternative with the mouse. On a text terminal, if the mouse is not
1945 available, the user can choose an alternative using the keyboard
1946 motion keys---@kbd{C-n}, @kbd{C-p}, or up- and down-arrow keys.
1948 @defun x-popup-menu position menu
1949 This function displays a pop-up menu and returns an indication of
1950 what selection the user makes.
1952 The argument @var{position} specifies where on the screen to put the
1953 top left corner of the menu. It can be either a mouse button event
1954 (which says to put the menu where the user actuated the button) or a
1958 ((@var{xoffset} @var{yoffset}) @var{window})
1962 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1963 pixels, counting from the top left corner of @var{window}. @var{window}
1964 may be a window or a frame.
1966 If @var{position} is @code{t}, it means to use the current mouse
1967 position (or the top-left corner of the frame if the mouse is not
1968 available on a text terminal). If @var{position} is @code{nil}, it
1969 means to precompute the key binding equivalents for the keymaps
1970 specified in @var{menu}, without actually displaying or popping up the
1973 The argument @var{menu} says what to display in the menu. It can be a
1974 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
1975 return value is the list of events corresponding to the user's choice.
1976 This list has more than one element if the choice occurred in a
1977 submenu. (Note that @code{x-popup-menu} does not actually execute the
1978 command bound to that sequence of events.) On text terminals and
1979 toolkits that support menu titles, the title is taken from the prompt
1980 string of @var{menu} if @var{menu} is a keymap, or from the prompt
1981 string of the first keymap in @var{menu} if it is a list of keymaps
1982 (@pxref{Defining Menus}).
1984 Alternatively, @var{menu} can have the following form:
1987 (@var{title} @var{pane1} @var{pane2}...)
1991 where each pane is a list of form
1994 (@var{title} @var{item1} @var{item2}...)
1997 Each @var{item} should be a cons cell, @code{(@var{line} . @var{value})},
1998 where @var{line} is a string and @var{value} is the value to return if
1999 that @var{line} is chosen. Unlike in a menu keymap, a @code{nil}
2000 @var{value} does not make the menu item non-selectable.
2001 Alternatively, each @var{item} can be a string rather than a cons
2002 cell; this makes a non-selectable menu item.
2004 If the user gets rid of the menu without making a valid choice, for
2005 instance by clicking the mouse away from a valid choice or by typing
2006 @kbd{C-g}, then this normally results in a quit and
2007 @code{x-popup-menu} does not return. But if @var{position} is a mouse
2008 button event (indicating that the user invoked the menu with the
2009 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
2012 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
2013 if you could do the job with a prefix key defined with a menu keymap.
2014 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
2015 a} can see the individual items in that menu and provide help for them.
2016 If instead you implement the menu by defining a command that calls
2017 @code{x-popup-menu}, the help facilities cannot know what happens inside
2018 that command, so they cannot give any help for the menu's items.
2020 The menu bar mechanism, which lets you switch between submenus by
2021 moving the mouse, cannot look within the definition of a command to see
2022 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
2023 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
2024 an integrated fashion. This is why all menu bar submenus are
2025 implemented with menu keymaps within the parent menu, and never with
2026 @code{x-popup-menu}. @xref{Menu Bar}.
2028 If you want a menu bar submenu to have contents that vary, you should
2029 still use a menu keymap to implement it. To make the contents vary, add
2030 a hook function to @code{menu-bar-update-hook} to update the contents of
2031 the menu keymap as necessary.
2034 @section Dialog Boxes
2035 @cindex dialog boxes
2037 A dialog box is a variant of a pop-up menu---it looks a little
2038 different, it always appears in the center of a frame, and it has just
2039 one level and one or more buttons. The main use of dialog boxes is
2040 for asking questions that the user can answer with ``yes'', ``no'',
2041 and a few other alternatives. With a single button, they can also
2042 force the user to acknowledge important information. The functions
2043 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
2044 keyboard, when called from commands invoked by mouse clicks.
2046 @defun x-popup-dialog position contents &optional header
2047 This function displays a pop-up dialog box and returns an indication of
2048 what selection the user makes. The argument @var{contents} specifies
2049 the alternatives to offer; it has this format:
2052 (@var{title} (@var{string} . @var{value})@dots{})
2056 which looks like the list that specifies a single pane for
2057 @code{x-popup-menu}.
2059 The return value is @var{value} from the chosen alternative.
2061 As for @code{x-popup-menu}, an element of the list may be just a
2062 string instead of a cons cell @code{(@var{string} . @var{value})}.
2063 That makes a box that cannot be selected.
2065 If @code{nil} appears in the list, it separates the left-hand items from
2066 the right-hand items; items that precede the @code{nil} appear on the
2067 left, and items that follow the @code{nil} appear on the right. If you
2068 don't include a @code{nil} in the list, then approximately half the
2069 items appear on each side.
2071 Dialog boxes always appear in the center of a frame; the argument
2072 @var{position} specifies which frame. The possible values are as in
2073 @code{x-popup-menu}, but the precise coordinates or the individual
2074 window don't matter; only the frame matters.
2076 If @var{header} is non-@code{nil}, the frame title for the box is
2077 @samp{Information}, otherwise it is @samp{Question}. The former is used
2078 for @code{message-box} (@pxref{message-box}). (On text terminals, the
2079 box title is not displayed.)
2081 In some configurations, Emacs cannot display a real dialog box; so
2082 instead it displays the same items in a pop-up menu in the center of the
2085 If the user gets rid of the dialog box without making a valid choice,
2086 for instance using the window manager, then this produces a quit and
2087 @code{x-popup-dialog} does not return.
2091 @section Pointer Shape
2092 @cindex pointer shape
2093 @cindex mouse pointer shape
2095 You can specify the mouse pointer style for particular text or
2096 images using the @code{pointer} text property, and for images with the
2097 @code{:pointer} and @code{:map} image properties. The values you can
2098 use in these properties are @code{text} (or @code{nil}), @code{arrow},
2099 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
2100 @code{hourglass}. @code{text} stands for the usual mouse pointer
2101 style used over text.
2103 Over void parts of the window (parts that do not correspond to any
2104 of the buffer contents), the mouse pointer usually uses the
2105 @code{arrow} style, but you can specify a different style (one of
2106 those above) by setting @code{void-text-area-pointer}.
2108 @defopt void-text-area-pointer
2109 This variable specifies the mouse pointer style for void text areas.
2110 These include the areas after the end of a line or below the last line
2111 in the buffer. The default is to use the @code{arrow} (non-text)
2115 When using X, you can specify what the @code{text} pointer style
2116 really looks like by setting the variable @code{x-pointer-shape}.
2118 @defvar x-pointer-shape
2119 This variable specifies the pointer shape to use ordinarily in the
2120 Emacs frame, for the @code{text} pointer style.
2123 @defvar x-sensitive-text-pointer-shape
2124 This variable specifies the pointer shape to use when the mouse
2125 is over mouse-sensitive text.
2128 These variables affect newly created frames. They do not normally
2129 affect existing frames; however, if you set the mouse color of a
2130 frame, that also installs the current value of those two variables.
2131 @xref{Font and Color Parameters}.
2133 The values you can use, to specify either of these pointer shapes, are
2134 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
2135 @key{RET} x-pointer @key{RET}} to see a list of them.
2137 @node Window System Selections
2138 @section Window System Selections
2139 @cindex selection (for window systems)
2141 @cindex primary selection
2142 @cindex secondary selection
2144 In the X window system, data can be transferred between different
2145 applications by means of @dfn{selections}. X defines an arbitrary
2146 number of @dfn{selection types}, each of which can store its own data;
2147 however, only three are commonly used: the @dfn{clipboard},
2148 @dfn{primary selection}, and @dfn{secondary selection}. @xref{Cut and
2149 Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
2150 commands that make use of these selections. This section documents
2151 the low-level functions for reading and setting X selections.
2153 @deffn Command x-set-selection type data
2154 This function sets an X selection. It takes two arguments: a
2155 selection type @var{type}, and the value to assign to it, @var{data}.
2157 @var{type} should be a symbol; it is usually one of @code{PRIMARY},
2158 @code{SECONDARY} or @code{CLIPBOARD}. These are symbols with
2159 upper-case names, in accord with X Window System conventions. If
2160 @var{type} is @code{nil}, that stands for @code{PRIMARY}.
2162 If @var{data} is @code{nil}, it means to clear out the selection.
2163 Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
2164 of two integers or list of two integers), an overlay, or a cons of two
2165 markers pointing to the same buffer. An overlay or a pair of markers
2166 stands for text in the overlay or between the markers. The argument
2167 @var{data} may also be a vector of valid non-vector selection values.
2169 This function returns @var{data}.
2172 @defun x-get-selection &optional type data-type
2173 This function accesses selections set up by Emacs or by other X
2174 clients. It takes two optional arguments, @var{type} and
2175 @var{data-type}. The default for @var{type}, the selection type, is
2178 The @var{data-type} argument specifies the form of data conversion to
2179 use, to convert the raw data obtained from another X client into Lisp
2180 data. Meaningful values include @code{TEXT}, @code{STRING},
2181 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
2182 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
2183 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
2184 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
2185 @code{INTEGER}. (These are symbols with upper-case names in accord
2186 with X conventions.) The default for @var{data-type} is
2190 @defopt selection-coding-system
2191 This variable specifies the coding system to use when reading and
2192 writing selections or the clipboard. @xref{Coding
2193 Systems}. The default is @code{compound-text-with-extensions}, which
2194 converts to the text representation that X11 normally uses.
2197 @cindex clipboard support (for MS-Windows)
2198 When Emacs runs on MS-Windows, it does not implement X selections in
2199 general, but it does support the clipboard. @code{x-get-selection}
2200 and @code{x-set-selection} on MS-Windows support the text data type
2201 only; if the clipboard holds other types of data, Emacs treats the
2205 @section Drag and Drop
2207 @vindex x-dnd-test-function
2208 @vindex x-dnd-known-types
2209 When a user drags something from another application over Emacs, that other
2210 application expects Emacs to tell it if Emacs can handle the data that is
2211 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
2212 what to reply. The default value is @code{x-dnd-default-test-function}
2213 which accepts drops if the type of the data to be dropped is present in
2214 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
2215 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
2216 on some other criteria.
2218 @vindex x-dnd-types-alist
2219 If you want to change the way Emacs handles drop of different types
2220 or add a new type, customize @code{x-dnd-types-alist}. This requires
2221 detailed knowledge of what types other applications use for drag and
2224 @vindex dnd-protocol-alist
2225 When an URL is dropped on Emacs it may be a file, but it may also be
2226 another URL type (ftp, http, etc.). Emacs first checks
2227 @code{dnd-protocol-alist} to determine what to do with the URL@. If
2228 there is no match there and if @code{browse-url-browser-function} is
2229 an alist, Emacs looks for a match there. If no match is found the
2230 text for the URL is inserted. If you want to alter Emacs behavior,
2231 you can customize these variables.
2234 @section Color Names
2237 @cindex specify color
2238 @cindex numerical RGB color specification
2239 A color name is text (usually in a string) that specifies a color.
2240 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2241 are allowed; use @kbd{M-x list-colors-display} to see a list of
2242 defined names. You can also specify colors numerically in forms such
2243 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2244 @var{r} specifies the red level, @var{g} specifies the green level,
2245 and @var{b} specifies the blue level. You can use either one, two,
2246 three, or four hex digits for @var{r}; then you must use the same
2247 number of hex digits for all @var{g} and @var{b} as well, making
2248 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
2249 X Window System for more details about numerical RGB specification of
2252 These functions provide a way to determine which color names are
2253 valid, and what they look like. In some cases, the value depends on the
2254 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2255 meaning of the term ``selected frame''.
2257 To read user input of color names with completion, use
2258 @code{read-color} (@pxref{High-Level Completion, read-color}).
2260 @defun color-defined-p color &optional frame
2261 This function reports whether a color name is meaningful. It returns
2262 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
2263 which frame's display to ask about; if @var{frame} is omitted or
2264 @code{nil}, the selected frame is used.
2266 Note that this does not tell you whether the display you are using
2267 really supports that color. When using X, you can ask for any defined
2268 color on any kind of display, and you will get some result---typically,
2269 the closest it can do. To determine whether a frame can really display
2270 a certain color, use @code{color-supported-p} (see below).
2272 @findex x-color-defined-p
2273 This function used to be called @code{x-color-defined-p},
2274 and that name is still supported as an alias.
2277 @defun defined-colors &optional frame
2278 This function returns a list of the color names that are defined
2279 and supported on frame @var{frame} (default, the selected frame).
2280 If @var{frame} does not support colors, the value is @code{nil}.
2282 @findex x-defined-colors
2283 This function used to be called @code{x-defined-colors},
2284 and that name is still supported as an alias.
2287 @defun color-supported-p color &optional frame background-p
2288 This returns @code{t} if @var{frame} can really display the color
2289 @var{color} (or at least something close to it). If @var{frame} is
2290 omitted or @code{nil}, the question applies to the selected frame.
2292 Some terminals support a different set of colors for foreground and
2293 background. If @var{background-p} is non-@code{nil}, that means you are
2294 asking whether @var{color} can be used as a background; otherwise you
2295 are asking whether it can be used as a foreground.
2297 The argument @var{color} must be a valid color name.
2300 @defun color-gray-p color &optional frame
2301 This returns @code{t} if @var{color} is a shade of gray, as defined on
2302 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
2303 question applies to the selected frame. If @var{color} is not a valid
2304 color name, this function returns @code{nil}.
2307 @defun color-values color &optional frame
2309 This function returns a value that describes what @var{color} should
2310 ideally look like on @var{frame}. If @var{color} is defined, the
2311 value is a list of three integers, which give the amount of red, the
2312 amount of green, and the amount of blue. Each integer ranges in
2313 principle from 0 to 65535, but some displays may not use the full
2314 range. This three-element list is called the @dfn{rgb values} of the
2317 If @var{color} is not defined, the value is @code{nil}.
2320 (color-values "black")
2322 (color-values "white")
2323 @result{} (65280 65280 65280)
2324 (color-values "red")
2325 @result{} (65280 0 0)
2326 (color-values "pink")
2327 @result{} (65280 49152 51968)
2328 (color-values "hungry")
2332 The color values are returned for @var{frame}'s display. If
2333 @var{frame} is omitted or @code{nil}, the information is returned for
2334 the selected frame's display. If the frame cannot display colors, the
2335 value is @code{nil}.
2337 @findex x-color-values
2338 This function used to be called @code{x-color-values},
2339 and that name is still supported as an alias.
2342 @node Text Terminal Colors
2343 @section Text Terminal Colors
2344 @cindex colors on text terminals
2346 Text terminals usually support only a small number of colors, and
2347 the computer uses small integers to select colors on the terminal.
2348 This means that the computer cannot reliably tell what the selected
2349 color looks like; instead, you have to inform your application which
2350 small integers correspond to which colors. However, Emacs does know
2351 the standard set of colors and will try to use them automatically.
2353 The functions described in this section control how terminal colors
2356 Several of these functions use or return @dfn{rgb values}, described
2357 in @ref{Color Names}.
2359 These functions accept a display (either a frame or the name of a
2360 terminal) as an optional argument. We hope in the future to make
2361 Emacs support different colors on different text terminals; then this
2362 argument will specify which terminal to operate on (the default being
2363 the selected frame's terminal; @pxref{Input Focus}). At present,
2364 though, the @var{frame} argument has no effect.
2366 @defun tty-color-define name number &optional rgb frame
2367 This function associates the color name @var{name} with
2368 color number @var{number} on the terminal.
2370 The optional argument @var{rgb}, if specified, is an rgb value, a list
2371 of three numbers that specify what the color actually looks like.
2372 If you do not specify @var{rgb}, then this color cannot be used by
2373 @code{tty-color-approximate} to approximate other colors, because
2374 Emacs will not know what it looks like.
2377 @defun tty-color-clear &optional frame
2378 This function clears the table of defined colors for a text terminal.
2381 @defun tty-color-alist &optional frame
2382 This function returns an alist recording the known colors supported by
2385 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2386 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
2387 name, @var{number} is the number used to specify it to the terminal.
2388 If present, @var{rgb} is a list of three color values (for red, green,
2389 and blue) that says what the color actually looks like.
2392 @defun tty-color-approximate rgb &optional frame
2393 This function finds the closest color, among the known colors
2394 supported for @var{display}, to that described by the rgb value
2395 @var{rgb} (a list of color values). The return value is an element of
2396 @code{tty-color-alist}.
2399 @defun tty-color-translate color &optional frame
2400 This function finds the closest color to @var{color} among the known
2401 colors supported for @var{display} and returns its index (an integer).
2402 If the name @var{color} is not defined, the value is @code{nil}.
2406 @section X Resources
2408 This section describes some of the functions and variables for
2409 querying and using X resources, or their equivalent on your operating
2410 system. @xref{X Resources,, X Resources, emacs, The GNU Emacs
2411 Manual}, for more information about X resources.
2413 @defun x-get-resource attribute class &optional component subclass
2414 The function @code{x-get-resource} retrieves a resource value from the X
2415 Window defaults database.
2417 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2418 This function searches using a key of the form
2419 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2420 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2423 The optional arguments @var{component} and @var{subclass} add to the key
2424 and the class, respectively. You must specify both of them or neither.
2425 If you specify them, the key is
2426 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2427 @samp{Emacs.@var{class}.@var{subclass}}.
2430 @defvar x-resource-class
2431 This variable specifies the application name that @code{x-get-resource}
2432 should look up. The default value is @code{"Emacs"}. You can examine X
2433 resources for application names other than ``Emacs'' by binding this
2434 variable to some other string, around a call to @code{x-get-resource}.
2437 @defvar x-resource-name
2438 This variable specifies the instance name that @code{x-get-resource}
2439 should look up. The default value is the name Emacs was invoked with,
2440 or the value specified with the @samp{-name} or @samp{-rn} switches.
2443 To illustrate some of the above, suppose that you have the line:
2446 xterm.vt100.background: yellow
2450 in your X resources file (whose name is usually @file{~/.Xdefaults}
2451 or @file{~/.Xresources}). Then:
2455 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2456 (x-get-resource "vt100.background" "VT100.Background"))
2460 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2461 (x-get-resource "background" "VT100" "vt100" "Background"))
2466 @defvar inhibit-x-resources
2467 If this variable is non-@code{nil}, Emacs does not look up X
2468 resources, and X resources do not have any effect when creating new
2472 @node Display Feature Testing
2473 @section Display Feature Testing
2474 @cindex display feature testing
2476 The functions in this section describe the basic capabilities of a
2477 particular display. Lisp programs can use them to adapt their behavior
2478 to what the display can do. For example, a program that ordinarily uses
2479 a popup menu could use the minibuffer if popup menus are not supported.
2481 The optional argument @var{display} in these functions specifies which
2482 display to ask the question about. It can be a display name, a frame
2483 (which designates the display that frame is on), or @code{nil} (which
2484 refers to the selected frame's display, @pxref{Input Focus}).
2486 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2487 obtain information about displays.
2489 @defun display-popup-menus-p &optional display
2490 This function returns @code{t} if popup menus are supported on
2491 @var{display}, @code{nil} if not. Support for popup menus requires
2492 that the mouse be available, since the menu is popped up by clicking
2493 the mouse on some portion of the Emacs display.
2496 @defun display-graphic-p &optional display
2497 This function returns @code{t} if @var{display} is a graphic display
2498 capable of displaying several frames and several different fonts at
2499 once. This is true for displays that use a window system such as X,
2500 and false for text terminals.
2503 @defun display-mouse-p &optional display
2504 @cindex mouse, availability
2505 This function returns @code{t} if @var{display} has a mouse available,
2509 @defun display-color-p &optional display
2510 @findex x-display-color-p
2511 This function returns @code{t} if the screen is a color screen.
2512 It used to be called @code{x-display-color-p}, and that name
2513 is still supported as an alias.
2516 @defun display-grayscale-p &optional display
2517 This function returns @code{t} if the screen can display shades of gray.
2518 (All color displays can do this.)
2521 @defun display-supports-face-attributes-p attributes &optional display
2522 @anchor{Display Face Attribute Testing}
2523 This function returns non-@code{nil} if all the face attributes in
2524 @var{attributes} are supported (@pxref{Face Attributes}).
2526 The definition of `supported' is somewhat heuristic, but basically
2527 means that a face containing all the attributes in @var{attributes},
2528 when merged with the default face for display, can be represented in a
2533 different in appearance than the default face, and
2536 `close in spirit' to what the attributes specify, if not exact.
2539 Point (2) implies that a @code{:weight black} attribute will be
2540 satisfied by any display that can display bold, as will
2541 @code{:foreground "yellow"} as long as some yellowish color can be
2542 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2543 the tty display code's automatic substitution of a `dim' face for
2547 @defun display-selections-p &optional display
2548 This function returns @code{t} if @var{display} supports selections.
2549 Windowed displays normally support selections, but they may also be
2550 supported in some other cases.
2553 @defun display-images-p &optional display
2554 This function returns @code{t} if @var{display} can display images.
2555 Windowed displays ought in principle to handle images, but some
2556 systems lack the support for that. On a display that does not support
2557 images, Emacs cannot display a tool bar.
2560 @defun display-screens &optional display
2561 This function returns the number of screens associated with the display.
2564 @defun display-pixel-height &optional display
2565 This function returns the height of the screen in pixels.
2566 On a character terminal, it gives the height in characters.
2568 For graphical terminals, note that on ``multi-monitor'' setups this
2569 refers to the pixel height for all physical monitors associated with
2570 @var{display}. @xref{Multiple Terminals}.
2573 @defun display-pixel-width &optional display
2574 This function returns the width of the screen in pixels.
2575 On a character terminal, it gives the width in characters.
2577 For graphical terminals, note that on ``multi-monitor'' setups this
2578 refers to the pixel width for all physical monitors associated with
2579 @var{display}. @xref{Multiple Terminals}.
2582 @defun display-mm-height &optional display
2583 This function returns the height of the screen in millimeters,
2584 or @code{nil} if Emacs cannot get that information.
2586 For graphical terminals, note that on ``multi-monitor'' setups this
2587 refers to the height for all physical monitors associated with
2588 @var{display}. @xref{Multiple Terminals}.
2591 @defun display-mm-width &optional display
2592 This function returns the width of the screen in millimeters,
2593 or @code{nil} if Emacs cannot get that information.
2595 For graphical terminals, note that on ``multi-monitor'' setups this
2596 refers to the width for all physical monitors associated with
2597 @var{display}. @xref{Multiple Terminals}.
2600 @defopt display-mm-dimensions-alist
2601 This variable allows the user to specify the dimensions of graphical
2602 displays returned by @code{display-mm-height} and
2603 @code{display-mm-width} in case the system provides incorrect values.
2606 @cindex backing store
2607 @defun display-backing-store &optional display
2608 This function returns the backing store capability of the display.
2609 Backing store means recording the pixels of windows (and parts of
2610 windows) that are not exposed, so that when exposed they can be
2611 displayed very quickly.
2613 Values can be the symbols @code{always}, @code{when-mapped}, or
2614 @code{not-useful}. The function can also return @code{nil}
2615 when the question is inapplicable to a certain kind of display.
2618 @cindex SaveUnder feature
2619 @defun display-save-under &optional display
2620 This function returns non-@code{nil} if the display supports the
2621 SaveUnder feature. That feature is used by pop-up windows
2622 to save the pixels they obscure, so that they can pop down
2626 @defun display-planes &optional display
2627 This function returns the number of planes the display supports.
2628 This is typically the number of bits per pixel.
2629 For a tty display, it is log to base two of the number of colors supported.
2632 @defun display-visual-class &optional display
2633 This function returns the visual class for the screen. The value is
2634 one of the symbols @code{static-gray} (a limited, unchangeable number
2635 of grays), @code{gray-scale} (a full range of grays),
2636 @code{static-color} (a limited, unchangeable number of colors),
2637 @code{pseudo-color} (a limited number of colors), @code{true-color} (a
2638 full range of colors), and @code{direct-color} (a full range of
2642 @defun display-color-cells &optional display
2643 This function returns the number of color cells the screen supports.
2646 These functions obtain additional information specifically
2649 @defun x-server-version &optional display
2650 This function returns the list of version numbers of the X server
2651 running the display. The value is a list of three integers: the major
2652 and minor version numbers of the X protocol, and the
2653 distributor-specific release number of the X server software itself.
2656 @defun x-server-vendor &optional display
2657 This function returns the ``vendor'' that provided the X server
2658 software (as a string). Really this means whoever distributes the X
2661 When the developers of X labeled software distributors as
2662 ``vendors'', they showed their false assumption that no system could
2663 ever be developed and distributed noncommercially.
2667 @defvar x-no-window-manager
2668 This variable's value is @code{t} if no X window manager is in use.
2674 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2675 width and height of an X Window frame, measured in pixels.