2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/frames
7 @node Frames, Positions, Windows, Top
11 In Emacs editing, A @dfn{frame} is a screen object that contains one
12 or more Emacs windows. It's the kind of object that is called a
13 ``window'' in the terminology of graphical environments; but we can't
14 call it a ``window'' here, because Emacs uses that word in a different
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. In Emacs Lisp, a @dfn{frame object} is a Lisp
20 object that represents a frame on the screen.
22 @cindex terminal frame
23 When Emacs runs on a text-only terminal, it starts with one
24 @dfn{terminal frame}. If you create additional ones, Emacs displays
25 one and only one at any given time---on the terminal screen, of course.
28 When Emacs communicates directly with a supported window system, such
29 as X, it does not have a terminal frame; instead, it starts with
30 a single @dfn{window frame}, but you can create more, and Emacs can
31 display several such frames at once as is usual for window systems.
34 This predicate returns a non-@code{nil} value if @var{object} is a
35 frame, and @code{nil} otherwise. For a frame, the value indicates which
36 kind of display the frame uses:
40 The frame is displayed in an X window.
42 A terminal frame on a character display.
44 The frame is displayed on a Macintosh.
46 The frame is displayed on MS-Windows 9X/NT.
48 The frame is displayed on an MS-DOS terminal.
53 * Creating Frames:: Creating additional frames.
54 * Multiple Displays:: Creating frames on other displays.
55 * Frame Parameters:: Controlling frame size, position, font, etc.
56 * Frame Titles:: Automatic updating of frame titles.
57 * Deleting Frames:: Frames last until explicitly deleted.
58 * Finding All Frames:: How to examine all existing frames.
59 * Frames and Windows:: A frame contains windows;
60 display of text always works through windows.
61 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
62 * Input Focus:: Specifying the selected frame.
63 * Visibility of Frames:: Frames may be visible or invisible, or icons.
64 * Raising and Lowering:: Raising a frame makes it hide other windows;
65 lowering it makes the others hide it.
66 * Frame Configurations:: Saving the state of all frames.
67 * Mouse Tracking:: Getting events that say when the mouse moves.
68 * Mouse Position:: Asking where the mouse is, or moving it.
69 * Pop-Up Menus:: Displaying a menu for the user to select from.
70 * Dialog Boxes:: Displaying a box to ask yes or no.
71 * Pointer Shape:: Specifying the shape of the mouse pointer.
72 * Window System Selections:: Transferring text to and from other X clients.
73 * Drag and Drop:: Internals of Drag-and-Drop implementation.
74 * Color Names:: Getting the definitions of color names.
75 * Text Terminal Colors:: Defining colors for text-only terminals.
76 * Resources:: Getting resource values from the server.
77 * Display Feature Testing:: Determining the features of a terminal.
80 @xref{Display}, for information about the related topic of
81 controlling Emacs redisplay.
84 @section Creating Frames
86 To create a new frame, call the function @code{make-frame}.
88 @defun make-frame &optional alist
89 This function creates and returns a new frame, displaying the current
90 buffer. If you are using a supported window system, it makes a window
91 frame; otherwise, it makes a terminal frame.
93 The argument is an alist specifying frame parameters. Any parameters
94 not mentioned in @var{alist} default according to the value of the
95 variable @code{default-frame-alist}; parameters not specified even there
96 default from the standard X resources or whatever is used instead on
99 The set of possible parameters depends in principle on what kind of
100 window system Emacs uses to display its frames. @xref{Window Frame
101 Parameters}, for documentation of individual parameters you can specify.
103 This function itself does not make the new frame the selected frame.
104 @xref{Input Focus}. The previously selected frame remains selected.
105 However, the window system may select the new frame for its own reasons,
106 for instance if the frame appears under the mouse pointer and your
107 setup is for focus to follow the pointer.
110 @defvar before-make-frame-hook
111 A normal hook run by @code{make-frame} before it actually creates the
115 @defvar after-make-frame-functions
116 An abnormal hook run by @code{make-frame} after it creates the frame.
117 Each function in @code{after-make-frame-functions} receives one argument, the
121 @node Multiple Displays
122 @section Multiple Displays
123 @cindex multiple X displays
124 @cindex displays, multiple
126 A single Emacs can talk to more than one X display.
127 Initially, Emacs uses just one display---the one chosen with the
128 @code{DISPLAY} environment variable or with the @samp{--display} option
129 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
130 another display, use the command @code{make-frame-on-display} or specify
131 the @code{display} frame parameter when you create the frame.
133 Emacs treats each X server as a separate terminal, giving each one its
134 own selected frame and its own minibuffer windows. However, only one of
135 those frames is ``@emph{the} selected frame'' at any given moment, see
138 A few Lisp variables are @dfn{terminal-local}; that is, they have a
139 separate binding for each terminal. The binding in effect at any time
140 is the one for the terminal that the currently selected frame belongs
141 to. These variables include @code{default-minibuffer-frame},
142 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
143 @code{system-key-alist}. They are always terminal-local, and can never
144 be buffer-local (@pxref{Buffer-Local Variables}).
146 A single X server can handle more than one screen. A display name
147 @samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
148 part specifies the screen number for a given server. When you use two
149 screens belonging to one server, Emacs knows by the similarity in their
150 names that they share a single keyboard, and it treats them as a single
153 Note that some graphical terminals can output to more than a one
154 monitor (or other output device) at the same time. On these
155 ``multi-monitor'' setups, a single @var{display} value controls the
156 output to all the physical monitors. In this situation, there is
157 currently no platform-independent way for Emacs to distinguish between
158 the different physical monitors.
160 @deffn Command make-frame-on-display display &optional parameters
161 This creates and returns a new frame on display @var{display}, taking
162 the other frame parameters from @var{parameters}. Aside from the
163 @var{display} argument, it is like @code{make-frame} (@pxref{Creating
167 @defun x-display-list
168 This returns a list that indicates which X displays Emacs has a
169 connection to. The elements of the list are strings, and each one is
173 @defun x-open-connection display &optional xrm-string must-succeed
174 This function opens a connection to the X display @var{display}. It
175 does not create a frame on that display, but it permits you to check
176 that communication can be established with that display.
178 The optional argument @var{xrm-string}, if not @code{nil}, is a
179 string of resource names and values, in the same format used in the
180 @file{.Xresources} file. The values you specify override the resource
181 values recorded in the X server itself; they apply to all Emacs frames
182 created on this display. Here's an example of what this string might
186 "*BorderWidth: 3\n*InternalBorder: 2\n"
189 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
191 If @var{must-succeed} is non-@code{nil}, failure to open the connection
192 terminates Emacs. Otherwise, it is an ordinary Lisp error.
195 @defun x-close-connection display
196 This function closes the connection to display @var{display}. Before
197 you can do this, you must first delete all the frames that were open on
198 that display (@pxref{Deleting Frames}).
201 @node Frame Parameters
202 @section Frame Parameters
203 @cindex frame parameters
205 A frame has many parameters that control its appearance and behavior.
206 Just what parameters a frame has depends on what display mechanism it
209 Frame parameters exist mostly for the sake of window systems. A
210 terminal frame has a few parameters, mostly for compatibility's sake;
211 only the @code{height}, @code{width}, @code{name}, @code{title},
212 @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
213 parameters do something special. If the terminal supports colors, the
214 parameters @code{foreground-color}, @code{background-color},
215 @code{background-mode} and @code{display-type} are also meaningful.
218 * Parameter Access:: How to change a frame's parameters.
219 * Initial Parameters:: Specifying frame parameters when you make a frame.
220 * Window Frame Parameters:: List of frame parameters for window systems.
221 * Size and Position:: Changing the size and position of a frame.
222 * Geometry:: Parsing geometry specifications.
225 @node Parameter Access
226 @subsection Access to Frame Parameters
228 These functions let you read and change the parameter values of a
231 @defun frame-parameter frame parameter
232 This function returns the value of the parameter @var{parameter} (a
233 symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
234 selected frame's parameter. If @var{frame} has no setting for
235 @var{parameter}, this function returns @code{nil}.
238 @defun frame-parameters &optional frame
239 The function @code{frame-parameters} returns an alist listing all the
240 parameters of @var{frame} and their values. If @var{frame} is
241 @code{nil} or omitted, this returns the selected frame's parameters
244 @defun modify-frame-parameters frame alist
245 This function alters the parameters of frame @var{frame} based on the
246 elements of @var{alist}. Each element of @var{alist} has the form
247 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
248 parameter. If you don't mention a parameter in @var{alist}, its value
249 doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
253 @defun modify-all-frames-parameters alist
254 This function alters the frame parameters of all existing frames
255 according to @var{alist}, then modifies @code{default-frame-alist}
256 (and, if necessary, @code{initial-frame-alist}) to apply the same
257 parameter values to frames that will be created henceforth.
260 @node Initial Parameters
261 @subsection Initial Frame Parameters
263 You can specify the parameters for the initial startup frame
264 by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
266 @defvar initial-frame-alist
267 This variable's value is an alist of parameter values used when creating
268 the initial window frame. You can set this variable to specify the
269 appearance of the initial frame without altering subsequent frames.
270 Each element has the form:
273 (@var{parameter} . @var{value})
276 Emacs creates the initial frame before it reads your init
277 file. After reading that file, Emacs checks @code{initial-frame-alist},
278 and applies the parameter settings in the altered value to the already
279 created initial frame.
281 If these settings affect the frame geometry and appearance, you'll see
282 the frame appear with the wrong ones and then change to the specified
283 ones. If that bothers you, you can specify the same geometry and
284 appearance with X resources; those do take effect before the frame is
285 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
287 X resource settings typically apply to all frames. If you want to
288 specify some X resources solely for the sake of the initial frame, and
289 you don't want them to apply to subsequent frames, here's how to achieve
290 this. Specify parameters in @code{default-frame-alist} to override the
291 X resources for subsequent frames; then, to prevent these from affecting
292 the initial frame, specify the same parameters in
293 @code{initial-frame-alist} with values that match the X resources.
296 If these parameters specify a separate minibuffer-only frame with
297 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
300 @defvar minibuffer-frame-alist
301 This variable's value is an alist of parameter values used when creating
302 an initial minibuffer-only frame---if such a frame is needed, according
303 to the parameters for the main initial frame.
306 @defvar default-frame-alist
307 This is an alist specifying default values of frame parameters for all
308 Emacs frames---the first frame, and subsequent frames. When using the X
309 Window System, you can get the same results by means of X resources
312 Setting this variable does not affect existing frames.
315 See also @code{special-display-frame-alist}. @xref{Definition of
316 special-display-frame-alist}.
318 If you use options that specify window appearance when you invoke Emacs,
319 they take effect by adding elements to @code{default-frame-alist}. One
320 exception is @samp{-geometry}, which adds the specified position to
321 @code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command
322 Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
324 @node Window Frame Parameters
325 @subsection Window Frame Parameters
327 Just what parameters a frame has depends on what display mechanism
328 it uses. This section describes the parameters that have special
329 meanings on some or all kinds of terminals. Of these, @code{name},
330 @code{title}, @code{height}, @code{width}, @code{buffer-list} and
331 @code{buffer-predicate} provide meaningful information in terminal
332 frames, and @code{tty-color-mode} is meaningful @emph{only} in
336 * Basic Parameters:: Parameters that are fundamental.
337 * Position Parameters:: The position of the frame on the screen.
338 * Size Parameters:: Frame's size.
339 * Layout Parameters:: Size of parts of the frame, and
340 enabling or disabling some parts.
341 * Buffer Parameters:: Which buffers have been or should be shown.
342 * Management Parameters:: Communicating with the window manager.
343 * Cursor Parameters:: Controlling the cursor appearance.
344 * Color Parameters:: Colors of various parts of the frame.
347 @node Basic Parameters
348 @subsubsection Basic Parameters
350 These frame parameters give the most basic information about the
351 frame. @code{title} and @code{name} are meaningful on all terminals.
355 The display on which to open this frame. It should be a string of the
356 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
357 @code{DISPLAY} environment variable.
360 This parameter describes the range of possible colors that can be used
361 in this frame. Its value is @code{color}, @code{grayscale} or
365 If a frame has a non-@code{nil} title, it appears in the window
366 system's title bar at the top of the frame, and also in the mode line
367 of windows in that frame if @code{mode-line-frame-identification} uses
368 @samp{%F} (@pxref{%-Constructs}). This is normally the case when
369 Emacs is not using a window system, and can only display one frame at
370 a time. @xref{Frame Titles}.
373 The name of the frame. The frame name serves as a default for the frame
374 title, if the @code{title} parameter is unspecified or @code{nil}. If
375 you don't specify a name, Emacs sets the frame name automatically
376 (@pxref{Frame Titles}).
378 If you specify the frame name explicitly when you create the frame, the
379 name is also used (instead of the name of the Emacs executable) when
380 looking up X resources for the frame.
382 @item display-environment-variable
383 The value of the @code{DISPLAY} environment variable for the frame. It
384 is passed to child processes.
386 @item term-environment-variable
387 The value of the @code{TERM} environment variable for the frame. It
388 is passed to child processes.
391 @node Position Parameters
392 @subsubsection Position Parameters
394 Position parameters' values are normally measured in pixels, but on
395 text-only terminals they count characters or lines instead.
399 The screen position of the left edge, in pixels, with respect to the
400 left edge of the screen. The value may be a positive number @var{pos},
401 or a list of the form @code{(+ @var{pos})} which permits specifying a
402 negative @var{pos} value.
404 A negative number @minus{}@var{pos}, or a list of the form @code{(-
405 @var{pos})}, actually specifies the position of the right edge of the
406 window with respect to the right edge of the screen. A positive value
407 of @var{pos} counts toward the left. @strong{Reminder:} if the
408 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
411 Some window managers ignore program-specified positions. If you want to
412 be sure the position you specify is not ignored, specify a
413 non-@code{nil} value for the @code{user-position} parameter as well.
416 The screen position of the top edge, in pixels, with respect to the
417 top edge of the screen. It works just like @code{left}, except vertically
418 instead of horizontally.
421 The screen position of the left edge @emph{of the frame's icon}, in
422 pixels, counting from the left edge of the screen. This takes effect if
423 and when the frame is iconified.
425 If you specify a value for this parameter, then you must also specify
426 a value for @code{icon-top} and vice versa. The window manager may
427 ignore these two parameters.
430 The screen position of the top edge @emph{of the frame's icon}, in
431 pixels, counting from the top edge of the screen. This takes effect if
432 and when the frame is iconified.
435 When you create a frame and specify its screen position with the
436 @code{left} and @code{top} parameters, use this parameter to say whether
437 the specified position was user-specified (explicitly requested in some
438 way by a human user) or merely program-specified (chosen by a program).
439 A non-@code{nil} value says the position was user-specified.
441 Window managers generally heed user-specified positions, and some heed
442 program-specified positions too. But many ignore program-specified
443 positions, placing the window in a default fashion or letting the user
444 place it with the mouse. Some window managers, including @code{twm},
445 let the user specify whether to obey program-specified positions or
448 When you call @code{make-frame}, you should specify a non-@code{nil}
449 value for this parameter if the values of the @code{left} and @code{top}
450 parameters represent the user's stated preference; otherwise, use
454 @node Size Parameters
455 @subsubsection Size Parameters
457 Size parameters' values are normally measured in pixels, but on
458 text-only terminals they count characters or lines instead.
462 The height of the frame contents, in characters. (To get the height in
463 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
466 The width of the frame contents, in characters. (To get the width in
467 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
470 This does for the size parameters @code{height} and @code{width} what
471 the @code{user-position} parameter (see above) does for the position
472 parameters @code{top} and @code{left}.
475 Specify that width, height or both shall be set to the size of the screen.
476 The value @code{fullwidth} specifies that width shall be the size of the
477 screen. The value @code{fullheight} specifies that height shall be the
478 size of the screen. The value @code{fullboth} specifies that both the
479 width and the height shall be set to the size of the screen.
482 @node Layout Parameters
483 @subsubsection Layout Parameters
485 These frame parameters enable or disable various parts of the
486 frame, or control their sizes.
490 The width in pixels of the frame's border.
492 @item internal-border-width
493 The distance in pixels between text (or fringe) and the frame's border.
495 @item vertical-scroll-bars
496 Whether the frame has scroll bars for vertical scrolling, and which side
497 of the frame they should be on. The possible values are @code{left},
498 @code{right}, and @code{nil} for no scroll bars.
501 @item horizontal-scroll-bars
502 Whether the frame has scroll bars for horizontal scrolling
503 (non-@code{nil} means yes). Horizontal scroll bars are not currently
507 @item scroll-bar-width
508 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
509 use the default width.
513 The default width of the left and right fringes of windows in this
514 frame (@pxref{Fringes}). If either of these is zero, that effectively
515 removes the corresponding fringe. A value of @code{nil} stands for
516 the standard fringe width, which is the width needed to display the
519 The combined fringe widths must add up to an integral number of
520 columns, so the actual default fringe widths for the frame may be
521 larger than the specified values. The extra width needed to reach an
522 acceptable total is distributed evenly between the left and right
523 fringe. However, you can force one fringe or the other to a precise
524 width by specifying that width as a negative integer. If both widths are
525 negative, only the left fringe gets the specified width.
528 The number of lines to allocate at the top of the frame for a menu
529 bar. The default is 1. A value of @code{nil} means don't display a
530 menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one
531 menu bar line; they treat larger values as 1.)
534 The number of lines to use for the tool bar. A value of @code{nil}
535 means don't display a tool bar. (GTK allows at most one tool bar line;
536 it treats larger values as 1.)
539 Additional space to leave below each text line, in pixels (a positive
540 integer). @xref{Line Height}, for more information.
543 @node Buffer Parameters
544 @subsubsection Buffer Parameters
546 These frame parameters, meaningful on all kinds of terminals, deal
547 with which buffers have been, or should, be displayed in the frame.
551 Whether this frame has its own minibuffer. The value @code{t} means
552 yes, @code{nil} means no, @code{only} means this frame is just a
553 minibuffer. If the value is a minibuffer window (in some other frame),
554 the new frame uses that minibuffer.
556 @item buffer-predicate
557 The buffer-predicate function for this frame. The function
558 @code{other-buffer} uses this predicate (from the selected frame) to
559 decide which buffers it should consider, if the predicate is not
560 @code{nil}. It calls the predicate with one argument, a buffer, once for
561 each buffer; if the predicate returns a non-@code{nil} value, it
562 considers that buffer.
565 A list of buffers that have been selected in this frame,
566 ordered most-recently-selected first.
569 If non-@code{nil}, this frame's window is never split automatically.
572 @node Management Parameters
573 @subsubsection Window Management Parameters
574 @cindex window manager, and frame parameters
576 These frame parameters, meaningful only on window system displays,
577 interact with the window manager.
581 The state of visibility of the frame. There are three possibilities:
582 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
583 iconified. @xref{Visibility of Frames}.
586 Whether selecting the frame raises it (non-@code{nil} means yes).
589 Whether deselecting the frame lowers it (non-@code{nil} means yes).
592 The type of icon to use for this frame when it is iconified. If the
593 value is a string, that specifies a file containing a bitmap to use.
594 Any other non-@code{nil} value specifies the default bitmap icon (a
595 picture of a gnu); @code{nil} specifies a text icon.
598 The name to use in the icon for this frame, when and if the icon
599 appears. If this is @code{nil}, the frame's title is used.
602 The number of the window-system window used by the frame
603 to contain the actual Emacs windows.
605 @item outer-window-id
606 The number of the outermost window-system window used for the whole frame.
609 If non-@code{nil}, tell Xt to wait for the window manager to confirm
610 geometry changes. Some window managers, including versions of Fvwm2
611 and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
612 prevent hanging with those window managers.
616 @c ??? Not yet working.
617 The X window number of the window that should be the parent of this one.
618 Specifying this lets you create an Emacs window inside some other
619 application's window. (It is not certain this will be implemented; try
620 it and see if it works.)
624 @node Cursor Parameters
625 @subsubsection Cursor Parameters
627 This frame parameter controls the way the cursor looks.
631 How to display the cursor. Legitimate values are:
635 Display a filled box. (This is the default.)
637 Display a hollow box.
639 Don't display a cursor.
641 Display a vertical bar between characters.
642 @item (bar . @var{width})
643 Display a vertical bar @var{width} pixels wide between characters.
645 Display a horizontal bar.
646 @item (hbar . @var{height})
647 Display a horizontal bar @var{height} pixels high.
652 The buffer-local variable @code{cursor-type} overrides the value of
653 the @code{cursor-type} frame parameter, but if it is @code{t}, that
654 means to use the cursor specified for the frame.
656 @defvar blink-cursor-alist
657 This variable specifies how to blink the cursor. Each element has the
658 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
659 type equals @var{on-state} (comparing using @code{equal}), the
660 corresponding @var{off-state} specifies what the cursor looks like
661 when it blinks ``off.'' Both @var{on-state} and @var{off-state}
662 should be suitable values for the @code{cursor-type} frame parameter.
664 There are various defaults for how to blink each type of cursor, if
665 the type is not mentioned as an @var{on-state} here. Changes in this
666 variable do not take effect immediately, only when you specify the
667 @code{cursor-type} frame parameter.
670 @defvar cursor-in-non-selected-windows
671 This variable controls how the cursor looks in a window that is not
672 selected. It supports the same values as the @code{cursor-type} frame
673 parameter; also, @code{nil} means don't display a cursor in
674 nonselected windows, and @code{t} (the default) means use a standard
675 modificatoin of the usual cursor type (solid box becomes hollow box,
676 and bar becomes a narrower bar).
679 @node Color Parameters
680 @subsubsection Color Parameters
682 These frame parameters control the use of colors.
685 @item background-mode
686 This parameter is either @code{dark} or @code{light}, according
687 to whether the background color is a light one or a dark one.
690 @cindex standard colors for character terminals
691 This parameter overrides the terminal's color support as given by the
692 system's terminal capabilities database in that this parameter's value
693 specifies the color mode to use in terminal frames. The value can be
694 either a symbol or a number. A number specifies the number of colors
695 to use (and, indirectly, what commands to issue to produce each
696 color). For example, @code{(tty-color-mode . 8)} specifies use of the
697 ANSI escape sequences for 8 standard text colors. A value of -1 turns
700 If the parameter's value is a symbol, it specifies a number through
701 the value of @code{tty-color-mode-alist}, and the associated number is
705 @cindex gamma correction
706 If this is a number, Emacs performs ``gamma correction'' which adjusts
707 the brightness of all colors. The value should be the screen gamma of
708 your display, a floating point number.
710 Usual PC monitors have a screen gamma of 2.2, so color values in
711 Emacs, and in X windows generally, are calibrated to display properly
712 on a monitor with that gamma value. If you specify 2.2 for
713 @code{screen-gamma}, that means no correction is needed. Other values
714 request correction, designed to make the corrected colors appear on
715 your screen the way they would have appeared without correction on an
716 ordinary monitor with a gamma value of 2.2.
718 If your monitor displays colors too light, you should specify a
719 @code{screen-gamma} value smaller than 2.2. This requests correction
720 that makes colors darker. A screen gamma value of 1.5 may give good
721 results for LCD color displays.
724 These frame parameters are semi-obsolete in that they are automatically
725 equivalent to particular face attributes of particular faces.
726 @xref{Standard Faces,,, emacs, The Emacs Manual}.
730 The name of the font for displaying text in the frame. This is a
731 string, either a valid font name for your system or the name of an Emacs
732 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
733 attribute of the @code{default} face.
735 @item foreground-color
736 The color to use for the image of a character. It is equivalent to
737 the @code{:foreground} attribute of the @code{default} face.
739 @item background-color
740 The color to use for the background of characters. It is equivalent to
741 the @code{:background} attribute of the @code{default} face.
744 The color for the mouse pointer. It is equivalent to the @code{:background}
745 attribute of the @code{mouse} face.
748 The color for the cursor that shows point. It is equivalent to the
749 @code{:background} attribute of the @code{cursor} face.
752 The color for the border of the frame. It is equivalent to the
753 @code{:background} attribute of the @code{border} face.
755 @item scroll-bar-foreground
756 If non-@code{nil}, the color for the foreground of scroll bars. It is
757 equivalent to the @code{:foreground} attribute of the
758 @code{scroll-bar} face.
760 @item scroll-bar-background
761 If non-@code{nil}, the color for the background of scroll bars. It is
762 equivalent to the @code{:background} attribute of the
763 @code{scroll-bar} face.
766 @node Size and Position
767 @subsection Frame Size And Position
768 @cindex size of frame
773 You can read or change the size and position of a frame using the
774 frame parameters @code{left}, @code{top}, @code{height}, and
775 @code{width}. Whatever geometry parameters you don't specify are chosen
776 by the window manager in its usual fashion.
778 Here are some special features for working with sizes and positions.
779 (For the precise meaning of ``selected frame'' used by these functions,
780 see @ref{Input Focus}.)
782 @defun set-frame-position frame left top
783 This function sets the position of the top left corner of @var{frame} to
784 @var{left} and @var{top}. These arguments are measured in pixels, and
785 normally count from the top left corner of the screen.
787 Negative parameter values position the bottom edge of the window up from
788 the bottom edge of the screen, or the right window edge to the left of
789 the right edge of the screen. It would probably be better if the values
790 were always counted from the left and top, so that negative arguments
791 would position the frame partly off the top or left edge of the screen,
792 but it seems inadvisable to change that now.
795 @defun frame-height &optional frame
796 @defunx frame-width &optional frame
797 These functions return the height and width of @var{frame}, measured in
798 lines and columns. If you don't supply @var{frame}, they use the
804 These functions are old aliases for @code{frame-height} and
805 @code{frame-width}. When you are using a non-window terminal, the size
806 of the frame is normally the same as the size of the terminal screen.
809 @defun frame-pixel-height &optional frame
810 @defunx frame-pixel-width &optional frame
811 These functions return the height and width of the main display area
812 of @var{frame}, measured in pixels. If you don't supply @var{frame},
813 they use the selected frame.
815 These values include the internal borders, and windows' scroll bars
816 and fringes (which belong to individual windows, not to the frame
817 itself), but do not include menu bars or tool bars (except when using
818 X without an X toolkit).
821 @defun frame-char-height &optional frame
822 @defunx frame-char-width &optional frame
823 These functions return the height and width of a character in
824 @var{frame}, measured in pixels. The values depend on the choice of
825 font. If you don't supply @var{frame}, these functions use the selected
829 @defun set-frame-size frame cols rows
830 This function sets the size of @var{frame}, measured in characters;
831 @var{cols} and @var{rows} specify the new width and height.
833 To set the size based on values measured in pixels, use
834 @code{frame-char-height} and @code{frame-char-width} to convert
835 them to units of characters.
838 @defun set-frame-height frame lines &optional pretend
839 This function resizes @var{frame} to a height of @var{lines} lines. The
840 sizes of existing windows in @var{frame} are altered proportionally to
843 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
844 lines of output in @var{frame}, but does not change its value for the
845 actual height of the frame. This is only useful for a terminal frame.
846 Using a smaller height than the terminal actually implements may be
847 useful to reproduce behavior observed on a smaller screen, or if the
848 terminal malfunctions when using its whole screen. Setting the frame
849 height ``for real'' does not always work, because knowing the correct
850 actual size may be necessary for correct cursor positioning on a
854 @defun set-frame-width frame width &optional pretend
855 This function sets the width of @var{frame}, measured in characters.
856 The argument @var{pretend} has the same meaning as in
857 @code{set-frame-height}.
860 @findex set-screen-height
861 @findex set-screen-width
862 The older functions @code{set-screen-height} and
863 @code{set-screen-width} were used to specify the height and width of the
864 screen, in Emacs versions that did not support multiple frames. They
865 are semi-obsolete, but still work; they apply to the selected frame.
870 Here's how to examine the data in an X-style window geometry
873 @defun x-parse-geometry geom
874 @cindex geometry specification
875 The function @code{x-parse-geometry} converts a standard X window
876 geometry string to an alist that you can use as part of the argument to
879 The alist describes which parameters were specified in @var{geom}, and
880 gives the values specified for them. Each element looks like
881 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
882 values are @code{left}, @code{top}, @code{width}, and @code{height}.
884 For the size parameters, the value must be an integer. The position
885 parameter names @code{left} and @code{top} are not totally accurate,
886 because some values indicate the position of the right or bottom edges
887 instead. These are the @var{value} possibilities for the position
892 A positive integer relates the left edge or top edge of the window to
893 the left or top edge of the screen. A negative integer relates the
894 right or bottom edge of the window to the right or bottom edge of the
897 @item @code{(+ @var{position})}
898 This specifies the position of the left or top edge of the window
899 relative to the left or top edge of the screen. The integer
900 @var{position} may be positive or negative; a negative value specifies a
901 position outside the screen.
903 @item @code{(- @var{position})}
904 This specifies the position of the right or bottom edge of the window
905 relative to the right or bottom edge of the screen. The integer
906 @var{position} may be positive or negative; a negative value specifies a
907 position outside the screen.
913 (x-parse-geometry "35x70+0-0")
914 @result{} ((height . 70) (width . 35)
915 (top - 0) (left . 0))
920 @section Frame Titles
923 Every frame has a @code{name} parameter; this serves as the default
924 for the frame title which window systems typically display at the top of
925 the frame. You can specify a name explicitly by setting the @code{name}
928 Normally you don't specify the name explicitly, and Emacs computes the
929 frame name automatically based on a template stored in the variable
930 @code{frame-title-format}. Emacs recomputes the name each time the
931 frame is redisplayed.
933 @defvar frame-title-format
934 This variable specifies how to compute a name for a frame when you have
935 not explicitly specified one. The variable's value is actually a mode
936 line construct, just like @code{mode-line-format}, except that the
937 @samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
941 @defvar icon-title-format
942 This variable specifies how to compute the name for an iconified frame,
943 when you have not explicitly specified the frame title. This title
944 appears in the icon itself.
947 @defvar multiple-frames
948 This variable is set automatically by Emacs. Its value is @code{t} when
949 there are two or more frames (not counting minibuffer-only frames or
950 invisible frames). The default value of @code{frame-title-format} uses
951 @code{multiple-frames} so as to put the buffer name in the frame title
952 only when there is more than one frame.
954 The value of this variable is not guaranteed to be accurate except
955 while processing @code{frame-title-format} or
956 @code{icon-title-format}.
959 @node Deleting Frames
960 @section Deleting Frames
961 @cindex deleting frames
963 Frames remain potentially visible until you explicitly @dfn{delete}
964 them. A deleted frame cannot appear on the screen, but continues to
965 exist as a Lisp object until there are no references to it.
967 @deffn Command delete-frame &optional frame force
968 @vindex delete-frame-functions
969 This function deletes the frame @var{frame}. Unless @var{frame} is a
970 tooltip, it first runs the hook @code{delete-frame-functions} (each
971 function gets one argument, @var{frame}). By default, @var{frame} is
974 A frame cannot be deleted if its minibuffer is used by other frames.
975 Normally, you cannot delete a frame if all other frames are invisible,
976 but if the @var{force} is non-@code{nil}, then you are allowed to do so.
979 @defun frame-live-p frame
980 The function @code{frame-live-p} returns non-@code{nil} if the frame
981 @var{frame} has not been deleted. The possible non-@code{nil} return
982 values are like those of @code{framep}. @xref{Frames}.
985 Some window managers provide a command to delete a window. These work
986 by sending a special message to the program that operates the window.
987 When Emacs gets one of these commands, it generates a
988 @code{delete-frame} event, whose normal definition is a command that
989 calls the function @code{delete-frame}. @xref{Misc Events}.
991 @node Finding All Frames
992 @section Finding All Frames
993 @cindex frames, scanning all
996 The function @code{frame-list} returns a list of all the frames that
997 have not been deleted. It is analogous to @code{buffer-list} for
998 buffers, and includes frames on all terminals. The list that you get is
999 newly created, so modifying the list doesn't have any effect on the
1003 @defun visible-frame-list
1004 This function returns a list of just the currently visible frames.
1005 @xref{Visibility of Frames}. (Terminal frames always count as
1006 ``visible,'' even though only the selected one is actually displayed.)
1009 @defun next-frame &optional frame minibuf
1010 The function @code{next-frame} lets you cycle conveniently through all
1011 the frames on the current display from an arbitrary starting point. It
1012 returns the ``next'' frame after @var{frame} in the cycle. If
1013 @var{frame} is omitted or @code{nil}, it defaults to the selected frame
1014 (@pxref{Input Focus}).
1016 The second argument, @var{minibuf}, says which frames to consider:
1020 Exclude minibuffer-only frames.
1021 @item @code{visible}
1022 Consider all visible frames.
1024 Consider all visible or iconified frames.
1026 Consider only the frames using that particular window as their
1029 Consider all frames.
1033 @defun previous-frame &optional frame minibuf
1034 Like @code{next-frame}, but cycles through all frames in the opposite
1038 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1041 @node Frames and Windows
1042 @section Frames and Windows
1044 Each window is part of one and only one frame; you can get the frame
1045 with @code{window-frame}.
1047 @defun window-frame window
1048 This function returns the frame that @var{window} is on.
1051 All the non-minibuffer windows in a frame are arranged in a cyclic
1052 order. The order runs from the frame's top window, which is at the
1053 upper left corner, down and to the right, until it reaches the window at
1054 the lower right corner (always the minibuffer window, if the frame has
1055 one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
1057 @defun frame-first-window &optional frame
1058 This returns the topmost, leftmost window of frame @var{frame}.
1059 If omitted or @code{nil}, @var{frame} defaults to the selected frame.
1062 At any time, exactly one window on any frame is @dfn{selected within the
1063 frame}. The significance of this designation is that selecting the
1064 frame also selects this window. You can get the frame's current
1065 selected window with @code{frame-selected-window}.
1067 @defun frame-selected-window &optional frame
1068 This function returns the window on @var{frame} that is selected
1069 within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to
1073 @defun set-frame-selected-window frame window
1074 This sets the selected window of frame @var{frame} to @var{window}.
1075 If @var{frame} is @code{nil}, it operates on the selected frame. If
1076 @var{frame} is the selected frame, this makes @var{window} the
1077 selected window. This function returns @var{window}.
1080 Conversely, selecting a window for Emacs with @code{select-window} also
1081 makes that window selected within its frame. @xref{Selecting Windows}.
1083 Another function that (usually) returns one of the windows in a given
1084 frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
1086 @node Minibuffers and Frames
1087 @section Minibuffers and Frames
1089 Normally, each frame has its own minibuffer window at the bottom, which
1090 is used whenever that frame is selected. If the frame has a minibuffer,
1091 you can get it with @code{minibuffer-window} (@pxref{Definition of
1092 minibuffer-window}).
1094 However, you can also create a frame with no minibuffer. Such a frame
1095 must use the minibuffer window of some other frame. When you create the
1096 frame, you can specify explicitly the minibuffer window to use (in some
1097 other frame). If you don't, then the minibuffer is found in the frame
1098 which is the value of the variable @code{default-minibuffer-frame}. Its
1099 value should be a frame that does have a minibuffer.
1101 If you use a minibuffer-only frame, you might want that frame to raise
1102 when you enter the minibuffer. If so, set the variable
1103 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
1105 @defvar default-minibuffer-frame
1106 This variable specifies the frame to use for the minibuffer window, by
1107 default. It does not affect existing frames. It is always local to
1108 the current terminal and cannot be buffer-local. @xref{Multiple
1113 @section Input Focus
1115 @c @cindex selected frame Duplicates selected-frame
1117 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
1118 window always resides on the selected frame.
1120 When Emacs displays its frames on several terminals (@pxref{Multiple
1121 Displays}), each terminal has its own selected frame. But only one of
1122 these is ``@emph{the} selected frame'': it's the frame that belongs to
1123 the terminal from which the most recent input came. That is, when Emacs
1124 runs a command that came from a certain terminal, the selected frame is
1125 the one of that terminal. Since Emacs runs only a single command at any
1126 given time, it needs to consider only one selected frame at a time; this
1127 frame is what we call @dfn{the selected frame} in this manual. The
1128 display on which the selected frame is displayed is the @dfn{selected
1131 @defun selected-frame
1132 This function returns the selected frame.
1135 Some window systems and window managers direct keyboard input to the
1136 window object that the mouse is in; others require explicit clicks or
1137 commands to @dfn{shift the focus} to various window objects. Either
1138 way, Emacs automatically keeps track of which frame has the focus. To
1139 switch to a different frame from a Lisp function, call
1140 @code{select-frame-set-input-focus}.
1142 Lisp programs can also switch frames ``temporarily'' by calling the
1143 function @code{select-frame}. This does not alter the window system's
1144 concept of focus; rather, it escapes from the window manager's control
1145 until that control is somehow reasserted.
1147 When using a text-only terminal, only one frame can be displayed at a
1148 time on the terminal, so after a call to @code{select-frame}, the next
1149 redisplay actually displays the newly selected frame. This frame
1150 remains selected until a subsequent call to @code{select-frame} or
1151 @code{select-frame-set-input-focus}. Each terminal frame has a number
1152 which appears in the mode line before the buffer name (@pxref{Mode
1155 @defun select-frame-set-input-focus frame
1156 This function makes @var{frame} the selected frame, raises it (should
1157 it happen to be obscured by other frames) and tries to give it the X
1158 server's focus. On a text-only terminal, the next redisplay displays
1159 the new frame on the entire terminal screen. The return value of this
1160 function is not significant.
1163 @c ??? This is not yet implemented properly.
1164 @defun select-frame frame
1165 This function selects frame @var{frame}, temporarily disregarding the
1166 focus of the X server if any. The selection of @var{frame} lasts until
1167 the next time the user does something to select a different frame, or
1168 until the next time this function is called. (If you are using a
1169 window system, the previously selected frame may be restored as the
1170 selected frame after return to the command loop, because it still may
1171 have the window system's input focus.) The specified @var{frame}
1172 becomes the selected frame, as explained above, and the terminal that
1173 @var{frame} is on becomes the selected terminal. This function
1174 returns @var{frame}, or @code{nil} if @var{frame} has been deleted.
1176 In general, you should never use @code{select-frame} in a way that could
1177 switch to a different terminal without switching back when you're done.
1180 Emacs cooperates with the window system by arranging to select frames as
1181 the server and window manager request. It does so by generating a
1182 special kind of input event, called a @dfn{focus} event, when
1183 appropriate. The command loop handles a focus event by calling
1184 @code{handle-switch-frame}. @xref{Focus Events}.
1186 @deffn Command handle-switch-frame frame
1187 This function handles a focus event by selecting frame @var{frame}.
1189 Focus events normally do their job by invoking this command.
1190 Don't call it for any other reason.
1193 @defun redirect-frame-focus frame &optional focus-frame
1194 This function redirects focus from @var{frame} to @var{focus-frame}.
1195 This means that @var{focus-frame} will receive subsequent keystrokes and
1196 events intended for @var{frame}. After such an event, the value of
1197 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1198 events specifying @var{frame} will instead select @var{focus-frame}.
1200 If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1201 redirection for @var{frame}, which therefore once again receives its own
1204 One use of focus redirection is for frames that don't have minibuffers.
1205 These frames use minibuffers on other frames. Activating a minibuffer
1206 on another frame redirects focus to that frame. This puts the focus on
1207 the minibuffer's frame, where it belongs, even though the mouse remains
1208 in the frame that activated the minibuffer.
1210 Selecting a frame can also change focus redirections. Selecting frame
1211 @code{bar}, when @code{foo} had been selected, changes any redirections
1212 pointing to @code{foo} so that they point to @code{bar} instead. This
1213 allows focus redirection to work properly when the user switches from
1214 one frame to another using @code{select-window}.
1216 This means that a frame whose focus is redirected to itself is treated
1217 differently from a frame whose focus is not redirected.
1218 @code{select-frame} affects the former but not the latter.
1220 The redirection lasts until @code{redirect-frame-focus} is called to
1224 @defopt focus-follows-mouse
1225 This option is how you inform Emacs whether the window manager transfers
1226 focus when the user moves the mouse. Non-@code{nil} says that it does.
1227 When this is so, the command @code{other-frame} moves the mouse to a
1228 position consistent with the new selected frame. (This option has no
1229 effect on MS-Windows, where the mouse pointer is always automatically
1230 moved by the OS to the selected frame.)
1233 @node Visibility of Frames
1234 @section Visibility of Frames
1235 @cindex visible frame
1236 @cindex invisible frame
1237 @cindex iconified frame
1238 @cindex frame visibility
1240 A window frame may be @dfn{visible}, @dfn{invisible}, or
1241 @dfn{iconified}. If it is visible, you can see its contents, unless
1242 other windows cover it. If it is iconified, the frame's contents do
1243 not appear on the screen, but an icon does. If the frame is
1244 invisible, it doesn't show on the screen, not even as an icon.
1246 Visibility is meaningless for terminal frames, since only the selected
1247 one is actually displayed in any case.
1249 @deffn Command make-frame-visible &optional frame
1250 This function makes frame @var{frame} visible. If you omit
1251 @var{frame}, it makes the selected frame visible. This does not raise
1252 the frame, but you can do that with @code{raise-frame} if you wish
1253 (@pxref{Raising and Lowering}).
1256 @deffn Command make-frame-invisible &optional frame force
1257 This function makes frame @var{frame} invisible. If you omit
1258 @var{frame}, it makes the selected frame invisible.
1260 Unless @var{force} is non-@code{nil}, this function refuses to make
1261 @var{frame} invisible if all other frames are invisible..
1264 @deffn Command iconify-frame &optional frame
1265 This function iconifies frame @var{frame}. If you omit @var{frame}, it
1266 iconifies the selected frame.
1269 @defun frame-visible-p frame
1270 This returns the visibility status of frame @var{frame}. The value is
1271 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
1272 @code{icon} if it is iconified.
1274 On a text-only terminal, all frames are considered visible, whether
1275 they are currently being displayed or not, and this function returns
1276 @code{t} for all frames.
1279 The visibility status of a frame is also available as a frame
1280 parameter. You can read or change it as such. @xref{Management
1283 The user can iconify and deiconify frames with the window manager.
1284 This happens below the level at which Emacs can exert any control, but
1285 Emacs does provide events that you can use to keep track of such
1286 changes. @xref{Misc Events}.
1288 @node Raising and Lowering
1289 @section Raising and Lowering Frames
1291 Most window systems use a desktop metaphor. Part of this metaphor is
1292 the idea that windows are stacked in a notional third dimension
1293 perpendicular to the screen surface, and thus ordered from ``highest''
1294 to ``lowest.'' Where two windows overlap, the one higher up covers
1295 the one underneath. Even a window at the bottom of the stack can be
1296 seen if no other window overlaps it.
1298 @c @cindex raising a frame redundant with raise-frame
1299 @cindex lowering a frame
1300 A window's place in this ordering is not fixed; in fact, users tend
1301 to change the order frequently. @dfn{Raising} a window means moving
1302 it ``up,'' to the top of the stack. @dfn{Lowering} a window means
1303 moving it to the bottom of the stack. This motion is in the notional
1304 third dimension only, and does not change the position of the window
1307 You can raise and lower Emacs frame Windows with these functions:
1309 @deffn Command raise-frame &optional frame
1310 This function raises frame @var{frame} (default, the selected frame).
1311 If @var{frame} is invisible or iconified, this makes it visible.
1314 @deffn Command lower-frame &optional frame
1315 This function lowers frame @var{frame} (default, the selected frame).
1318 @defopt minibuffer-auto-raise
1319 If this is non-@code{nil}, activation of the minibuffer raises the frame
1320 that the minibuffer window is in.
1323 You can also enable auto-raise (raising automatically when a frame is
1324 selected) or auto-lower (lowering automatically when it is deselected)
1325 for any frame using frame parameters. @xref{Management Parameters}.
1327 @node Frame Configurations
1328 @section Frame Configurations
1329 @cindex frame configuration
1331 A @dfn{frame configuration} records the current arrangement of frames,
1332 all their properties, and the window configuration of each one.
1333 (@xref{Window Configurations}.)
1335 @defun current-frame-configuration
1336 This function returns a frame configuration list that describes
1337 the current arrangement of frames and their contents.
1340 @defun set-frame-configuration configuration &optional nodelete
1341 This function restores the state of frames described in
1342 @var{configuration}. However, this function does not restore deleted
1345 Ordinarily, this function deletes all existing frames not listed in
1346 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1347 unwanted frames are iconified instead.
1350 @node Mouse Tracking
1351 @section Mouse Tracking
1352 @cindex mouse tracking
1353 @c @cindex tracking the mouse Duplicates track-mouse
1355 Sometimes it is useful to @dfn{track} the mouse, which means to display
1356 something to indicate where the mouse is and move the indicator as the
1357 mouse moves. For efficient mouse tracking, you need a way to wait until
1358 the mouse actually moves.
1360 The convenient way to track the mouse is to ask for events to represent
1361 mouse motion. Then you can wait for motion by waiting for an event. In
1362 addition, you can easily handle any other sorts of events that may
1363 occur. That is useful, because normally you don't want to track the
1364 mouse forever---only until some other event, such as the release of a
1367 @defspec track-mouse body@dots{}
1368 This special form executes @var{body}, with generation of mouse motion
1369 events enabled. Typically @var{body} would use @code{read-event} to
1370 read the motion events and modify the display accordingly. @xref{Motion
1371 Events}, for the format of mouse motion events.
1373 The value of @code{track-mouse} is that of the last form in @var{body}.
1374 You should design @var{body} to return when it sees the up-event that
1375 indicates the release of the button, or whatever kind of event means
1376 it is time to stop tracking.
1379 The usual purpose of tracking mouse motion is to indicate on the screen
1380 the consequences of pushing or releasing a button at the current
1383 In many cases, you can avoid the need to track the mouse by using
1384 the @code{mouse-face} text property (@pxref{Special Properties}).
1385 That works at a much lower level and runs more smoothly than
1386 Lisp-level mouse tracking.
1389 @c These are not implemented yet.
1391 These functions change the screen appearance instantaneously. The
1392 effect is transient, only until the next ordinary Emacs redisplay. That
1393 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1394 to change the text, and the body of @code{track-mouse} normally reads
1395 the events itself and does not do redisplay.
1397 @defun x-contour-region window beg end
1398 This function draws lines to make a box around the text from @var{beg}
1399 to @var{end}, in window @var{window}.
1402 @defun x-uncontour-region window beg end
1403 This function erases the lines that would make a box around the text
1404 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1405 a contour that you previously made by calling @code{x-contour-region}.
1408 @defun x-draw-rectangle frame left top right bottom
1409 This function draws a hollow rectangle on frame @var{frame} with the
1410 specified edge coordinates, all measured in pixels from the inside top
1411 left corner. It uses the cursor color, the one used for indicating the
1415 @defun x-erase-rectangle frame left top right bottom
1416 This function erases a hollow rectangle on frame @var{frame} with the
1417 specified edge coordinates, all measured in pixels from the inside top
1418 left corner. Erasure means redrawing the text and background that
1419 normally belong in the specified rectangle.
1423 @node Mouse Position
1424 @section Mouse Position
1425 @cindex mouse position
1426 @cindex position of mouse
1428 The functions @code{mouse-position} and @code{set-mouse-position}
1429 give access to the current position of the mouse.
1431 @defun mouse-position
1432 This function returns a description of the position of the mouse. The
1433 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1434 and @var{y} are integers giving the position in characters relative to
1435 the top left corner of the inside of @var{frame}.
1438 @defvar mouse-position-function
1439 If non-@code{nil}, the value of this variable is a function for
1440 @code{mouse-position} to call. @code{mouse-position} calls this
1441 function just before returning, with its normal return value as the
1442 sole argument, and it returns whatever this function returns to it.
1444 This abnormal hook exists for the benefit of packages like
1445 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1448 @defun set-mouse-position frame x y
1449 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1450 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1451 giving the position in characters relative to the top left corner of the
1452 inside of @var{frame}. If @var{frame} is not visible, this function
1453 does nothing. The return value is not significant.
1456 @defun mouse-pixel-position
1457 This function is like @code{mouse-position} except that it returns
1458 coordinates in units of pixels rather than units of characters.
1461 @defun set-mouse-pixel-position frame x y
1462 This function warps the mouse like @code{set-mouse-position} except that
1463 @var{x} and @var{y} are in units of pixels rather than units of
1464 characters. These coordinates are not required to be within the frame.
1466 If @var{frame} is not visible, this function does nothing. The return
1467 value is not significant.
1473 @section Pop-Up Menus
1475 When using a window system, a Lisp program can pop up a menu so that
1476 the user can choose an alternative with the mouse.
1478 @defun x-popup-menu position menu
1479 This function displays a pop-up menu and returns an indication of
1480 what selection the user makes.
1482 The argument @var{position} specifies where on the screen to put the
1483 top left corner of the menu. It can be either a mouse button event
1484 (which says to put the menu where the user actuated the button) or a
1488 ((@var{xoffset} @var{yoffset}) @var{window})
1492 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1493 pixels, counting from the top left corner of @var{window}. @var{window}
1494 may be a window or a frame.
1496 If @var{position} is @code{t}, it means to use the current mouse
1497 position. If @var{position} is @code{nil}, it means to precompute the
1498 key binding equivalents for the keymaps specified in @var{menu},
1499 without actually displaying or popping up the menu.
1501 The argument @var{menu} says what to display in the menu. It can be a
1502 keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
1503 return value is the list of events corresponding to the user's choice.
1504 (This list has more than one element if the choice occurred in a
1505 submenu.) Note that @code{x-popup-menu} does not actually execute the
1506 command bound to that sequence of events.
1508 Alternatively, @var{menu} can have the following form:
1511 (@var{title} @var{pane1} @var{pane2}...)
1515 where each pane is a list of form
1518 (@var{title} @var{item1} @var{item2}...)
1521 Each item should normally be a cons cell @code{(@var{line} . @var{value})},
1522 where @var{line} is a string, and @var{value} is the value to return if
1523 that @var{line} is chosen. An item can also be a string; this makes a
1524 non-selectable line in the menu.
1526 If the user gets rid of the menu without making a valid choice, for
1527 instance by clicking the mouse away from a valid choice or by typing
1528 keyboard input, then this normally results in a quit and
1529 @code{x-popup-menu} does not return. But if @var{position} is a mouse
1530 button event (indicating that the user invoked the menu with the
1531 mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1534 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1535 if you could do the job with a prefix key defined with a menu keymap.
1536 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1537 a} can see the individual items in that menu and provide help for them.
1538 If instead you implement the menu by defining a command that calls
1539 @code{x-popup-menu}, the help facilities cannot know what happens inside
1540 that command, so they cannot give any help for the menu's items.
1542 The menu bar mechanism, which lets you switch between submenus by
1543 moving the mouse, cannot look within the definition of a command to see
1544 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1545 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1546 an integrated fashion. This is why all menu bar submenus are
1547 implemented with menu keymaps within the parent menu, and never with
1548 @code{x-popup-menu}. @xref{Menu Bar}.
1550 If you want a menu bar submenu to have contents that vary, you should
1551 still use a menu keymap to implement it. To make the contents vary, add
1552 a hook function to @code{menu-bar-update-hook} to update the contents of
1553 the menu keymap as necessary.
1556 @section Dialog Boxes
1557 @cindex dialog boxes
1559 A dialog box is a variant of a pop-up menu---it looks a little
1560 different, it always appears in the center of a frame, and it has just
1561 one level and one or more buttons. The main use of dialog boxes is
1562 for asking questions that the user can answer with ``yes,'' ``no,''
1563 and a few other alternatives. With a single button, they can also
1564 force the user to acknowledge important information. The functions
1565 @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1566 keyboard, when called from commands invoked by mouse clicks.
1568 @defun x-popup-dialog position contents &optional header
1569 This function displays a pop-up dialog box and returns an indication of
1570 what selection the user makes. The argument @var{contents} specifies
1571 the alternatives to offer; it has this format:
1574 (@var{title} (@var{string} . @var{value})@dots{})
1578 which looks like the list that specifies a single pane for
1579 @code{x-popup-menu}.
1581 The return value is @var{value} from the chosen alternative.
1583 As for @code{x-popup-menu}, an element of the list may be just a
1584 string instead of a cons cell @code{(@var{string} . @var{value})}.
1585 That makes a box that cannot be selected.
1587 If @code{nil} appears in the list, it separates the left-hand items from
1588 the right-hand items; items that precede the @code{nil} appear on the
1589 left, and items that follow the @code{nil} appear on the right. If you
1590 don't include a @code{nil} in the list, then approximately half the
1591 items appear on each side.
1593 Dialog boxes always appear in the center of a frame; the argument
1594 @var{position} specifies which frame. The possible values are as in
1595 @code{x-popup-menu}, but the precise coordinates or the individual
1596 window don't matter; only the frame matters.
1598 If @var{header} is non-@code{nil}, the frame title for the box is
1599 @samp{Information}, otherwise it is @samp{Question}. The former is used
1600 for @code{message-box} (@pxref{message-box}).
1602 In some configurations, Emacs cannot display a real dialog box; so
1603 instead it displays the same items in a pop-up menu in the center of the
1606 If the user gets rid of the dialog box without making a valid choice,
1607 for instance using the window manager, then this produces a quit and
1608 @code{x-popup-dialog} does not return.
1612 @section Pointer Shape
1613 @cindex pointer shape
1614 @cindex mouse pointer shape
1616 You can specify the mouse pointer style for particular text or
1617 images using the @code{pointer} text property, and for images with the
1618 @code{:pointer} and @code{:map} image properties. The values you can
1619 use in these properties are @code{text} (or @code{nil}), @code{arrow},
1620 @code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1621 @code{hourglass}. @code{text} stands for the usual mouse pointer
1622 style used over text.
1624 Over void parts of the window (parts that do not correspond to any
1625 of the buffer contents), the mouse pointer usually uses the
1626 @code{arrow} style, but you can specify a different style (one of
1627 those above) by setting @code{void-text-area-pointer}.
1629 @defvar void-text-area-pointer
1630 This variable specifies the mouse pointer style for void text areas.
1631 These include the areas after the end of a line or below the last line
1632 in the buffer. The default is to use the @code{arrow} (non-text)
1636 You can specify what the @code{text} pointer style really looks like
1637 by setting the variable @code{x-pointer-shape}.
1639 @defvar x-pointer-shape
1640 This variable specifies the pointer shape to use ordinarily in the
1641 Emacs frame, for the @code{text} pointer style.
1644 @defvar x-sensitive-text-pointer-shape
1645 This variable specifies the pointer shape to use when the mouse
1646 is over mouse-sensitive text.
1649 These variables affect newly created frames. They do not normally
1650 affect existing frames; however, if you set the mouse color of a
1651 frame, that also installs the current value of those two variables.
1652 @xref{Color Parameters}.
1654 The values you can use, to specify either of these pointer shapes, are
1655 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1656 @key{RET} x-pointer @key{RET}} to see a list of them.
1658 @node Window System Selections
1659 @section Window System Selections
1660 @cindex selection (for window systems)
1662 The X server records a set of @dfn{selections} which permit transfer of
1663 data between application programs. The various selections are
1664 distinguished by @dfn{selection types}, represented in Emacs by
1665 symbols. X clients including Emacs can read or set the selection for
1668 @deffn Command x-set-selection type data
1669 This function sets a ``selection'' in the X server. It takes two
1670 arguments: a selection type @var{type}, and the value to assign to it,
1671 @var{data}. If @var{data} is @code{nil}, it means to clear out the
1672 selection. Otherwise, @var{data} may be a string, a symbol, an integer
1673 (or a cons of two integers or list of two integers), an overlay, or a
1674 cons of two markers pointing to the same buffer. An overlay or a pair
1675 of markers stands for text in the overlay or between the markers.
1677 The argument @var{data} may also be a vector of valid non-vector
1680 Each possible @var{type} has its own selection value, which changes
1681 independently. The usual values of @var{type} are @code{PRIMARY},
1682 @code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
1683 names, in accord with X Window System conventions. If @var{type} is
1684 @code{nil}, that stands for @code{PRIMARY}.
1686 This function returns @var{data}.
1689 @defun x-get-selection &optional type data-type
1690 This function accesses selections set up by Emacs or by other X
1691 clients. It takes two optional arguments, @var{type} and
1692 @var{data-type}. The default for @var{type}, the selection type, is
1695 The @var{data-type} argument specifies the form of data conversion to
1696 use, to convert the raw data obtained from another X client into Lisp
1697 data. Meaningful values include @code{TEXT}, @code{STRING},
1698 @code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1699 @code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1700 @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1701 @code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
1702 @code{INTEGER}. (These are symbols with upper-case names in accord
1703 with X conventions.) The default for @var{data-type} is
1708 The X server also has a set of eight numbered @dfn{cut buffers} which can
1709 store text or other data being moved between applications. Cut buffers
1710 are considered obsolete, but Emacs supports them for the sake of X
1711 clients that still use them. Cut buffers are numbered from 0 to 7.
1713 @defun x-get-cut-buffer &optional n
1714 This function returns the contents of cut buffer number @var{n}.
1715 If omitted @var{n} defaults to 0.
1718 @defun x-set-cut-buffer string &optional push
1719 @anchor{Definition of x-set-cut-buffer}
1720 This function stores @var{string} into the first cut buffer (cut buffer
1721 0). If @var{push} is @code{nil}, only the first cut buffer is changed.
1722 If @var{push} is non-@code{nil}, that says to move the values down
1723 through the series of cut buffers, much like the way successive kills in
1724 Emacs move down the kill ring. In other words, the previous value of
1725 the first cut buffer moves into the second cut buffer, and the second to
1726 the third, and so on through all eight cut buffers.
1729 @defvar selection-coding-system
1730 This variable specifies the coding system to use when reading and
1731 writing selections or the clipboard. @xref{Coding
1732 Systems}. The default is @code{compound-text-with-extensions}, which
1733 converts to the text representation that X11 normally uses.
1736 @cindex clipboard support (for MS-Windows)
1737 When Emacs runs on MS-Windows, it does not implement X selections in
1738 general, but it does support the clipboard. @code{x-get-selection}
1739 and @code{x-set-selection} on MS-Windows support the text data type
1740 only; if the clipboard holds other types of data, Emacs treats the
1743 @cindex scrap support (for Mac OS)
1744 On Mac OS, selection-like data transfer between applications is
1745 performed through a mechanism called @dfn{scraps}. The clipboard is a
1746 particular scrap named @code{com.apple.scrap.clipboard}. Types of scrap
1747 data are called @dfn{scrap flavor types}, which are identified by
1748 four-char codes such as @code{TEXT}. Emacs associates a selection with
1749 a scrap, and a selection type with a scrap flavor type via
1750 @code{mac-scrap-name} and @code{mac-ostype} properties, respectively.
1753 (get 'CLIPBOARD 'mac-scrap-name)
1754 @result{} "com.apple.scrap.clipboard"
1755 (get 'com.apple.traditional-mac-plain-text 'mac-ostype)
1759 Conventionally, selection types for scrap flavor types on Mac OS have
1760 the form of @acronym{UTI, Uniform Type Identifier} such as
1761 @code{com.apple.traditional-mac-plain-text},
1762 @code{public.utf16-plain-text}, and @code{public.file-url}.
1764 @defopt x-select-enable-clipboard
1765 If this is non-@code{nil}, the Emacs yank functions consult the
1766 clipboard before the primary selection, and the kill functions store in
1767 the clipboard as well as the primary selection. Otherwise they do not
1768 access the clipboard at all. The default is @code{nil} on most systems,
1769 but @code{t} on MS-Windows and Mac.
1773 @section Drag and Drop
1775 @vindex x-dnd-test-function
1776 @vindex x-dnd-known-types
1777 When a user drags something from another application over Emacs, that other
1778 application expects Emacs to tell it if Emacs can handle the data that is
1779 dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
1780 what to reply. The default value is @code{x-dnd-default-test-function}
1781 which accepts drops if the type of the data to be dropped is present in
1782 @code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
1783 @code{x-dnd-known-types} if you want Emacs to accept or reject drops based
1784 on some other criteria.
1786 @vindex x-dnd-types-alist
1787 If you want to change the way Emacs handles drop of different types
1788 or add a new type, customize @code{x-dnd-types-alist}. This requires
1789 detailed knowledge of what types other applications use for drag and
1792 @vindex dnd-protocol-alist
1793 When an URL is dropped on Emacs it may be a file, but it may also be
1794 another URL type (ftp, http, etc.). Emacs first checks
1795 @code{dnd-protocol-alist} to determine what to do with the URL. If
1796 there is no match there and if @code{browse-url-browser-function} is
1797 an alist, Emacs looks for a match there. If no match is found the
1798 text for the URL is inserted. If you want to alter Emacs behavior,
1799 you can customize these variables.
1802 @section Color Names
1805 @cindex specify color
1806 @cindex numerical RGB color specification
1807 A color name is text (usually in a string) that specifies a color.
1808 Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
1809 are allowed; use @kbd{M-x list-colors-display} to see a list of
1810 defined names. You can also specify colors numerically in forms such
1811 as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
1812 @var{r} specifies the red level, @var{g} specifies the green level,
1813 and @var{b} specifies the blue level. You can use either one, two,
1814 three, or four hex digits for @var{r}; then you must use the same
1815 number of hex digits for all @var{g} and @var{b} as well, making
1816 either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
1817 X Window System for more details about numerical RGB specification of
1820 These functions provide a way to determine which color names are
1821 valid, and what they look like. In some cases, the value depends on the
1822 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
1823 meaning of the term ``selected frame.''
1825 @defun color-defined-p color &optional frame
1826 This function reports whether a color name is meaningful. It returns
1827 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
1828 which frame's display to ask about; if @var{frame} is omitted or
1829 @code{nil}, the selected frame is used.
1831 Note that this does not tell you whether the display you are using
1832 really supports that color. When using X, you can ask for any defined
1833 color on any kind of display, and you will get some result---typically,
1834 the closest it can do. To determine whether a frame can really display
1835 a certain color, use @code{color-supported-p} (see below).
1837 @findex x-color-defined-p
1838 This function used to be called @code{x-color-defined-p},
1839 and that name is still supported as an alias.
1842 @defun defined-colors &optional frame
1843 This function returns a list of the color names that are defined
1844 and supported on frame @var{frame} (default, the selected frame).
1845 If @var{frame} does not support colors, the value is @code{nil}.
1847 @findex x-defined-colors
1848 This function used to be called @code{x-defined-colors},
1849 and that name is still supported as an alias.
1852 @defun color-supported-p color &optional frame background-p
1853 This returns @code{t} if @var{frame} can really display the color
1854 @var{color} (or at least something close to it). If @var{frame} is
1855 omitted or @code{nil}, the question applies to the selected frame.
1857 Some terminals support a different set of colors for foreground and
1858 background. If @var{background-p} is non-@code{nil}, that means you are
1859 asking whether @var{color} can be used as a background; otherwise you
1860 are asking whether it can be used as a foreground.
1862 The argument @var{color} must be a valid color name.
1865 @defun color-gray-p color &optional frame
1866 This returns @code{t} if @var{color} is a shade of gray, as defined on
1867 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
1868 question applies to the selected frame. If @var{color} is not a valid
1869 color name, this function returns @code{nil}.
1872 @defun color-values color &optional frame
1874 This function returns a value that describes what @var{color} should
1875 ideally look like on @var{frame}. If @var{color} is defined, the
1876 value is a list of three integers, which give the amount of red, the
1877 amount of green, and the amount of blue. Each integer ranges in
1878 principle from 0 to 65535, but some displays may not use the full
1879 range. This three-element list is called the @dfn{rgb values} of the
1882 If @var{color} is not defined, the value is @code{nil}.
1885 (color-values "black")
1887 (color-values "white")
1888 @result{} (65280 65280 65280)
1889 (color-values "red")
1890 @result{} (65280 0 0)
1891 (color-values "pink")
1892 @result{} (65280 49152 51968)
1893 (color-values "hungry")
1897 The color values are returned for @var{frame}'s display. If
1898 @var{frame} is omitted or @code{nil}, the information is returned for
1899 the selected frame's display. If the frame cannot display colors, the
1900 value is @code{nil}.
1902 @findex x-color-values
1903 This function used to be called @code{x-color-values},
1904 and that name is still supported as an alias.
1907 @node Text Terminal Colors
1908 @section Text Terminal Colors
1909 @cindex colors on text-only terminals
1911 Text-only terminals usually support only a small number of colors,
1912 and the computer uses small integers to select colors on the terminal.
1913 This means that the computer cannot reliably tell what the selected
1914 color looks like; instead, you have to inform your application which
1915 small integers correspond to which colors. However, Emacs does know
1916 the standard set of colors and will try to use them automatically.
1918 The functions described in this section control how terminal colors
1921 Several of these functions use or return @dfn{rgb values}, described
1922 in @ref{Color Names}.
1924 These functions accept a display (either a frame or the name of a
1925 terminal) as an optional argument. We hope in the future to make Emacs
1926 support more than one text-only terminal at one time; then this argument
1927 will specify which terminal to operate on (the default being the
1928 selected frame's terminal; @pxref{Input Focus}). At present, though,
1929 the @var{frame} argument has no effect.
1931 @defun tty-color-define name number &optional rgb frame
1932 This function associates the color name @var{name} with
1933 color number @var{number} on the terminal.
1935 The optional argument @var{rgb}, if specified, is an rgb value, a list
1936 of three numbers that specify what the color actually looks like.
1937 If you do not specify @var{rgb}, then this color cannot be used by
1938 @code{tty-color-approximate} to approximate other colors, because
1939 Emacs will not know what it looks like.
1942 @defun tty-color-clear &optional frame
1943 This function clears the table of defined colors for a text-only terminal.
1946 @defun tty-color-alist &optional frame
1947 This function returns an alist recording the known colors supported by a
1950 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
1951 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
1952 name, @var{number} is the number used to specify it to the terminal.
1953 If present, @var{rgb} is a list of three color values (for red, green,
1954 and blue) that says what the color actually looks like.
1957 @defun tty-color-approximate rgb &optional frame
1958 This function finds the closest color, among the known colors
1959 supported for @var{display}, to that described by the rgb value
1960 @var{rgb} (a list of color values). The return value is an element of
1961 @code{tty-color-alist}.
1964 @defun tty-color-translate color &optional frame
1965 This function finds the closest color to @var{color} among the known
1966 colors supported for @var{display} and returns its index (an integer).
1967 If the name @var{color} is not defined, the value is @code{nil}.
1971 @section X Resources
1973 @defun x-get-resource attribute class &optional component subclass
1974 The function @code{x-get-resource} retrieves a resource value from the X
1975 Window defaults database.
1977 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
1978 This function searches using a key of the form
1979 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
1980 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
1983 The optional arguments @var{component} and @var{subclass} add to the key
1984 and the class, respectively. You must specify both of them or neither.
1985 If you specify them, the key is
1986 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
1987 @samp{Emacs.@var{class}.@var{subclass}}.
1990 @defvar x-resource-class
1991 This variable specifies the application name that @code{x-get-resource}
1992 should look up. The default value is @code{"Emacs"}. You can examine X
1993 resources for application names other than ``Emacs'' by binding this
1994 variable to some other string, around a call to @code{x-get-resource}.
1997 @defvar x-resource-name
1998 This variable specifies the instance name that @code{x-get-resource}
1999 should look up. The default value is the name Emacs was invoked with,
2000 or the value specified with the @samp{-name} or @samp{-rn} switches.
2003 To illustrate some of the above, suppose that you have the line:
2006 xterm.vt100.background: yellow
2010 in your X resources file (whose name is usually @file{~/.Xdefaults}
2011 or @file{~/.Xresources}). Then:
2015 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2016 (x-get-resource "vt100.background" "VT100.Background"))
2020 (let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2021 (x-get-resource "background" "VT100" "vt100" "Background"))
2026 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
2028 @node Display Feature Testing
2029 @section Display Feature Testing
2030 @cindex display feature testing
2032 The functions in this section describe the basic capabilities of a
2033 particular display. Lisp programs can use them to adapt their behavior
2034 to what the display can do. For example, a program that ordinarily uses
2035 a popup menu could use the minibuffer if popup menus are not supported.
2037 The optional argument @var{display} in these functions specifies which
2038 display to ask the question about. It can be a display name, a frame
2039 (which designates the display that frame is on), or @code{nil} (which
2040 refers to the selected frame's display, @pxref{Input Focus}).
2042 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2043 obtain information about displays.
2045 @defun display-popup-menus-p &optional display
2046 This function returns @code{t} if popup menus are supported on
2047 @var{display}, @code{nil} if not. Support for popup menus requires that
2048 the mouse be available, since the user cannot choose menu items without
2052 @defun display-graphic-p &optional display
2053 This function returns @code{t} if @var{display} is a graphic display
2054 capable of displaying several frames and several different fonts at
2055 once. This is true for displays that use a window system such as X, and
2056 false for text-only terminals.
2059 @defun display-mouse-p &optional display
2060 @cindex mouse, availability
2061 This function returns @code{t} if @var{display} has a mouse available,
2065 @defun display-color-p &optional display
2066 @findex x-display-color-p
2067 This function returns @code{t} if the screen is a color screen.
2068 It used to be called @code{x-display-color-p}, and that name
2069 is still supported as an alias.
2072 @defun display-grayscale-p &optional display
2073 This function returns @code{t} if the screen can display shades of gray.
2074 (All color displays can do this.)
2077 @defun display-supports-face-attributes-p attributes &optional display
2078 @anchor{Display Face Attribute Testing}
2079 This function returns non-@code{nil} if all the face attributes in
2080 @var{attributes} are supported (@pxref{Face Attributes}).
2082 The definition of `supported' is somewhat heuristic, but basically
2083 means that a face containing all the attributes in @var{attributes},
2084 when merged with the default face for display, can be represented in a
2089 different in appearance than the default face, and
2092 `close in spirit' to what the attributes specify, if not exact.
2095 Point (2) implies that a @code{:weight black} attribute will be
2096 satisfied by any display that can display bold, as will
2097 @code{:foreground "yellow"} as long as some yellowish color can be
2098 displayed, but @code{:slant italic} will @emph{not} be satisfied by
2099 the tty display code's automatic substitution of a `dim' face for
2103 @defun display-selections-p &optional display
2104 This function returns @code{t} if @var{display} supports selections.
2105 Windowed displays normally support selections, but they may also be
2106 supported in some other cases.
2109 @defun display-images-p &optional display
2110 This function returns @code{t} if @var{display} can display images.
2111 Windowed displays ought in principle to handle images, but some
2112 systems lack the support for that. On a display that does not support
2113 images, Emacs cannot display a tool bar.
2116 @defun display-screens &optional display
2117 This function returns the number of screens associated with the display.
2120 @defun display-pixel-height &optional display
2121 This function returns the height of the screen in pixels.
2122 On a character terminal, it gives the height in characters.
2124 For graphical terminals, note that on ``multi-monitor'' setups this
2125 refers to the pixel width for all physical monitors associated with
2126 @var{display}. @xref{Multiple Displays}.
2129 @defun display-pixel-width &optional display
2130 This function returns the width of the screen in pixels.
2131 On a character terminal, it gives the width in characters.
2133 For graphical terminals, note that on ``multi-monitor'' setups this
2134 refers to the pixel width for all physical monitors associated with
2135 @var{display}. @xref{Multiple Displays}.
2138 @defun display-mm-height &optional display
2139 This function returns the height of the screen in millimeters,
2140 or @code{nil} if Emacs cannot get that information.
2143 @defun display-mm-width &optional display
2144 This function returns the width of the screen in millimeters,
2145 or @code{nil} if Emacs cannot get that information.
2148 @defvar display-mm-dimensions-alist
2149 This variable allows the user to specify the dimensions of graphical
2150 displays returned by @code{display-mm-height} and
2151 @code{display-mm-width} in case the system provides incorrect values.
2154 @defun display-backing-store &optional display
2155 This function returns the backing store capability of the display.
2156 Backing store means recording the pixels of windows (and parts of
2157 windows) that are not exposed, so that when exposed they can be
2158 displayed very quickly.
2160 Values can be the symbols @code{always}, @code{when-mapped}, or
2161 @code{not-useful}. The function can also return @code{nil}
2162 when the question is inapplicable to a certain kind of display.
2165 @defun display-save-under &optional display
2166 This function returns non-@code{nil} if the display supports the
2167 SaveUnder feature. That feature is used by pop-up windows
2168 to save the pixels they obscure, so that they can pop down
2172 @defun display-planes &optional display
2173 This function returns the number of planes the display supports.
2174 This is typically the number of bits per pixel.
2175 For a tty display, it is log to base two of the number of colors supported.
2178 @defun display-visual-class &optional display
2179 This function returns the visual class for the screen. The value is one
2180 of the symbols @code{static-gray}, @code{gray-scale},
2181 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
2182 @code{direct-color}.
2185 @defun display-color-cells &optional display
2186 This function returns the number of color cells the screen supports.
2189 These functions obtain additional information specifically
2192 @defun x-server-version &optional display
2193 This function returns the list of version numbers of the X server
2194 running the display. The value is a list of three integers: the major
2195 and minor version numbers of the X protocol, and the
2196 distributor-specific release number of the X server software itself.
2199 @defun x-server-vendor &optional display
2200 This function returns the ``vendor'' that provided the X server
2201 software (as a string). Really this means whoever distributes the X
2204 When the developers of X labelled software distributors as
2205 ``vendors,'' they showed their false assumption that no system could
2206 ever be developed and distributed noncommercially.
2210 @defvar x-no-window-manager
2211 This variable's value is @code{t} if no X window manager is in use.
2217 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2218 width and height of an X Window frame, measured in pixels.
2222 arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba