2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/frames
7 @node Frames, Positions, Windows, Top
11 A @dfn{frame} is a rectangle on the screen that contains one or more
12 Emacs windows. A frame initially contains a single main window (plus
13 perhaps a minibuffer window), which you can subdivide vertically or
14 horizontally into smaller windows.
16 @cindex terminal frame
17 When Emacs runs on a text-only terminal, it starts with one
18 @dfn{terminal frame}. If you create additional ones, Emacs displays
19 one and only one at any given time---on the terminal screen, of course.
22 When Emacs communicates directly with a supported window system, such
23 as X, it does not have a terminal frame; instead, it starts with
24 a single @dfn{window frame}, but you can create more, and Emacs can
25 display several such frames at once as is usual for window systems.
28 This predicate returns a non-@code{nil} value if @var{object} is a
29 frame, and @code{nil} otherwise. For a frame, the value indicates which
30 kind of display the frame uses:
34 The frame is displayed in an X window.
36 A terminal frame on a character display.
38 The frame is displayed on a Macintosh.
40 The frame is displayed on MS-Windows 9X/NT.
42 The frame is displayed on an MS-DOS terminal.
47 * Creating Frames:: Creating additional frames.
48 * Multiple Displays:: Creating frames on other displays.
49 * Frame Parameters:: Controlling frame size, position, font, etc.
50 * Frame Titles:: Automatic updating of frame titles.
51 * Deleting Frames:: Frames last until explicitly deleted.
52 * Finding All Frames:: How to examine all existing frames.
53 * Frames and Windows:: A frame contains windows;
54 display of text always works through windows.
55 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
56 * Input Focus:: Specifying the selected frame.
57 * Visibility of Frames:: Frames may be visible or invisible, or icons.
58 * Raising and Lowering:: Raising a frame makes it hide other windows;
59 lowering it makes the others hide them.
60 * Frame Configurations:: Saving the state of all frames.
61 * Mouse Tracking:: Getting events that say when the mouse moves.
62 * Mouse Position:: Asking where the mouse is, or moving it.
63 * Pop-Up Menus:: Displaying a menu for the user to select from.
64 * Dialog Boxes:: Displaying a box to ask yes or no.
65 * Pointer Shapes:: Specifying the shape of the mouse pointer.
66 * Window System Selections:: Transferring text to and from other X clients.
67 * Color Names:: Getting the definitions of color names.
68 * Text Terminal Colors:: Defining colors for text-only terminals.
69 * Resources:: Getting resource values from the server.
70 * Display Feature Testing:: Determining the features of a terminal.
73 @xref{Display}, for information about the related topic of
74 controlling Emacs redisplay.
77 @section Creating Frames
79 To create a new frame, call the function @code{make-frame}.
81 @defun make-frame &optional alist
82 This function creates a new frame. If you are using a supported window
83 system, it makes a window frame; otherwise, it makes a terminal frame.
85 The argument is an alist specifying frame parameters. Any parameters
86 not mentioned in @var{alist} default according to the value of the
87 variable @code{default-frame-alist}; parameters not specified even there
88 default from the standard X resources or whatever is used instead on
91 The set of possible parameters depends in principle on what kind of
92 window system Emacs uses to display its frames. @xref{Window Frame
93 Parameters}, for documentation of individual parameters you can specify.
96 @defvar before-make-frame-hook
97 A normal hook run by @code{make-frame} before it actually creates the
101 @defvar after-make-frame-functions
102 @tindex after-make-frame-functions
103 An abnormal hook run by @code{make-frame} after it creates the frame.
104 Each function in @code{after-make-frame-functions} receives one argument, the
108 @node Multiple Displays
109 @section Multiple Displays
110 @cindex multiple X displays
111 @cindex displays, multiple
113 A single Emacs can talk to more than one X display.
114 Initially, Emacs uses just one display---the one chosen with the
115 @code{DISPLAY} environment variable or with the @samp{--display} option
116 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
117 another display, use the command @code{make-frame-on-display} or specify
118 the @code{display} frame parameter when you create the frame.
120 Emacs treats each X server as a separate terminal, giving each one its
121 own selected frame and its own minibuffer windows. However, only one of
122 those frames is ``@emph{the} selected frame'' at any given moment, see
125 A few Lisp variables are @dfn{terminal-local}; that is, they have a
126 separate binding for each terminal. The binding in effect at any time
127 is the one for the terminal that the currently selected frame belongs
128 to. These variables include @code{default-minibuffer-frame},
129 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
130 @code{system-key-alist}. They are always terminal-local, and can never
131 be buffer-local (@pxref{Buffer-Local Variables}) or frame-local.
133 A single X server can handle more than one screen. A display name
134 @samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
135 part specifies the screen number for a given server. When you use two
136 screens belonging to one server, Emacs knows by the similarity in their
137 names that they share a single keyboard, and it treats them as a single
140 @deffn Command make-frame-on-display display &optional parameters
141 This creates a new frame on display @var{display}, taking the other
142 frame parameters from @var{parameters}. Aside from the @var{display}
143 argument, it is like @code{make-frame} (@pxref{Creating Frames}).
146 @defun x-display-list
147 This returns a list that indicates which X displays Emacs has a
148 connection to. The elements of the list are strings, and each one is
152 @defun x-open-connection display &optional xrm-string must-succeed
153 This function opens a connection to the X display @var{display}. It
154 does not create a frame on that display, but it permits you to check
155 that communication can be established with that display.
157 The optional argument @var{xrm-string}, if not @code{nil}, is a
158 string of resource names and values, in the same format used in the
159 @file{.Xresources} file. The values you specify override the resource
160 values recorded in the X server itself; they apply to all Emacs frames
161 created on this display. Here's an example of what this string might
165 "*BorderWidth: 3\n*InternalBorder: 2\n"
170 If @var{must-succeed} is non-@code{nil}, failure to open the connection
171 terminates Emacs. Otherwise, it is an ordinary Lisp error.
174 @defun x-close-connection display
175 This function closes the connection to display @var{display}. Before
176 you can do this, you must first delete all the frames that were open on
177 that display (@pxref{Deleting Frames}).
180 @node Frame Parameters
181 @section Frame Parameters
183 A frame has many parameters that control its appearance and behavior.
184 Just what parameters a frame has depends on what display mechanism it
187 Frame parameters exist mostly for the sake of window systems. A
188 terminal frame has a few parameters, mostly for compatibility's sake;
189 only the @code{height}, @code{width}, @code{name}, @code{title},
190 @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
191 parameters do something special. If the terminal supports colors, the
192 parameters @code{foreground-color}, @code{background-color},
193 @code{background-mode} and @code{display-type} are also meaningful.
196 * Parameter Access:: How to change a frame's parameters.
197 * Initial Parameters:: Specifying frame parameters when you make a frame.
198 * Window Frame Parameters:: List of frame parameters for window systems.
199 * Size and Position:: Changing the size and position of a frame.
202 @node Parameter Access
203 @subsection Access to Frame Parameters
205 These functions let you read and change the parameter values of a
208 @defun frame-parameter frame parameter
209 @tindex frame-parameter
210 This function returns the value of the parameter named @var{parameter}
211 of @var{frame}. If @var{frame} is @code{nil}, it returns the
212 selected frame's parameter.
215 @defun frame-parameters frame
216 The function @code{frame-parameters} returns an alist listing all the
217 parameters of @var{frame} and their values.
220 @defun modify-frame-parameters frame alist
221 This function alters the parameters of frame @var{frame} based on the
222 elements of @var{alist}. Each element of @var{alist} has the form
223 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
224 parameter. If you don't mention a parameter in @var{alist}, its value
228 @defun modify-all-frames-parameters alist
229 This function alters the frame parameters of all existing frames
230 according to @var{alist}, then modifies @code{default-frame-alist}
231 to apply the same parameter values to frames that will be created
235 @node Initial Parameters
236 @subsection Initial Frame Parameters
238 You can specify the parameters for the initial startup frame
239 by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
241 @defvar initial-frame-alist
242 This variable's value is an alist of parameter values used when creating
243 the initial window frame. You can set this variable to specify the
244 appearance of the initial frame without altering subsequent frames.
245 Each element has the form:
248 (@var{parameter} . @var{value})
251 Emacs creates the initial frame before it reads your init
252 file. After reading that file, Emacs checks @code{initial-frame-alist},
253 and applies the parameter settings in the altered value to the already
254 created initial frame.
256 If these settings affect the frame geometry and appearance, you'll see
257 the frame appear with the wrong ones and then change to the specified
258 ones. If that bothers you, you can specify the same geometry and
259 appearance with X resources; those do take effect before the frame is
260 created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
262 X resource settings typically apply to all frames. If you want to
263 specify some X resources solely for the sake of the initial frame, and
264 you don't want them to apply to subsequent frames, here's how to achieve
265 this. Specify parameters in @code{default-frame-alist} to override the
266 X resources for subsequent frames; then, to prevent these from affecting
267 the initial frame, specify the same parameters in
268 @code{initial-frame-alist} with values that match the X resources.
271 If these parameters specify a separate minibuffer-only frame with
272 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
275 @defvar minibuffer-frame-alist
276 This variable's value is an alist of parameter values used when creating
277 an initial minibuffer-only frame---if such a frame is needed, according
278 to the parameters for the main initial frame.
281 @defvar default-frame-alist
282 This is an alist specifying default values of frame parameters for all
283 Emacs frames---the first frame, and subsequent frames. When using the X
284 Window System, you can get the same results by means of X resources
288 See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
290 If you use options that specify window appearance when you invoke Emacs,
291 they take effect by adding elements to @code{default-frame-alist}. One
292 exception is @samp{-geometry}, which adds the specified position to
293 @code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
294 The GNU Emacs Manual}.
296 @node Window Frame Parameters
297 @subsection Window Frame Parameters
299 Just what parameters a frame has depends on what display mechanism it
300 uses. Here is a table of the parameters that have special meanings in a
301 window frame; of these, @code{name}, @code{title}, @code{height},
302 @code{width}, @code{buffer-list} and @code{buffer-predicate} provide
303 meaningful information in terminal frames, and @code{tty-color-mode}
304 is meaningful @emph{only} in terminal frames.
308 The display on which to open this frame. It should be a string of the
309 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
310 @code{DISPLAY} environment variable.
313 If a frame has a non-@code{nil} title, it appears in the window system's
314 border for the frame, and also in the mode line of windows in that frame
315 if @code{mode-line-frame-identification} uses @samp{%F}
316 (@pxref{%-Constructs}). This is normally the case when Emacs is not
317 using a window system, and can only display one frame at a time.
321 The name of the frame. The frame name serves as a default for the frame
322 title, if the @code{title} parameter is unspecified or @code{nil}. If
323 you don't specify a name, Emacs sets the frame name automatically
324 (@pxref{Frame Titles}).
326 If you specify the frame name explicitly when you create the frame, the
327 name is also used (instead of the name of the Emacs executable) when
328 looking up X resources for the frame.
331 The screen position of the left edge, in pixels, with respect to the
332 left edge of the screen. The value may be a positive number @var{pos},
333 or a list of the form @code{(+ @var{pos})} which permits specifying a
334 negative @var{pos} value.
336 A negative number @minus{}@var{pos}, or a list of the form @code{(-
337 @var{pos})}, actually specifies the position of the right edge of the
338 window with respect to the right edge of the screen. A positive value
339 of @var{pos} counts toward the left. @strong{Reminder:} if the
340 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
343 Some window managers ignore program-specified positions. If you want to
344 be sure the position you specify is not ignored, specify a
345 non-@code{nil} value for the @code{user-position} parameter as well.
348 The screen position of the top edge, in pixels, with respect to the
349 top edge of the screen. The value may be a positive number @var{pos},
350 or a list of the form @code{(+ @var{pos})} which permits specifying a
351 negative @var{pos} value.
353 A negative number @minus{}@var{pos}, or a list of the form @code{(-
354 @var{pos})}, actually specifies the position of the bottom edge of the
355 window with respect to the bottom edge of the screen. A positive value
356 of @var{pos} counts toward the top. @strong{Reminder:} if the
357 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
360 Some window managers ignore program-specified positions. If you want to
361 be sure the position you specify is not ignored, specify a
362 non-@code{nil} value for the @code{user-position} parameter as well.
365 The screen position of the left edge @emph{of the frame's icon}, in
366 pixels, counting from the left edge of the screen. This takes effect if
367 and when the frame is iconified.
370 The screen position of the top edge @emph{of the frame's icon}, in
371 pixels, counting from the top edge of the screen. This takes effect if
372 and when the frame is iconified.
375 When you create a frame and specify its screen position with the
376 @code{left} and @code{top} parameters, use this parameter to say whether
377 the specified position was user-specified (explicitly requested in some
378 way by a human user) or merely program-specified (chosen by a program).
379 A non-@code{nil} value says the position was user-specified.
381 Window managers generally heed user-specified positions, and some heed
382 program-specified positions too. But many ignore program-specified
383 positions, placing the window in a default fashion or letting the user
384 place it with the mouse. Some window managers, including @code{twm},
385 let the user specify whether to obey program-specified positions or
388 When you call @code{make-frame}, you should specify a non-@code{nil}
389 value for this parameter if the values of the @code{left} and @code{top}
390 parameters represent the user's stated preference; otherwise, use
394 The height of the frame contents, in characters. (To get the height in
395 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
398 The width of the frame contents, in characters. (To get the height in
399 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
402 Specify that width, height or both shall be set to the size of the screen.
403 The value @code{fullwidth} specifies that width shall be the size of the
404 screen. The value @code{fullheight} specifies that height shall be the
405 size of the screen. The value @code{fullboth} specifies that both the
406 width and the height shall be set to the size of the screen.
409 The number of the window-system window used by the frame
410 to contain the actual Emacs windows.
412 @item outer-window-id
413 The number of the outermost window-system window used for the whole frame.
416 Whether this frame has its own minibuffer. The value @code{t} means
417 yes, @code{nil} means no, @code{only} means this frame is just a
418 minibuffer. If the value is a minibuffer window (in some other frame),
419 the new frame uses that minibuffer.
421 @item buffer-predicate
422 The buffer-predicate function for this frame. The function
423 @code{other-buffer} uses this predicate (from the selected frame) to
424 decide which buffers it should consider, if the predicate is not
425 @code{nil}. It calls the predicate with one argument, a buffer, once for
426 each buffer; if the predicate returns a non-@code{nil} value, it
427 considers that buffer.
430 A list of buffers that have been selected in this frame,
431 ordered most-recently-selected first.
434 Whether selecting the frame raises it (non-@code{nil} means yes).
437 Whether deselecting the frame lowers it (non-@code{nil} means yes).
439 @item vertical-scroll-bars
440 Whether the frame has scroll bars for vertical scrolling, and which side
441 of the frame they should be on. The possible values are @code{left},
442 @code{right}, and @code{nil} for no scroll bars.
444 @item horizontal-scroll-bars
445 Whether the frame has scroll bars for horizontal scrolling
446 (non-@code{nil} means yes). (Horizontal scroll bars are not currently
449 @item scroll-bar-width
450 The width of the vertical scroll bar, in pixels,
451 or @code{nil} meaning to use the default width.
454 The type of icon to use for this frame when it is iconified. If the
455 value is a string, that specifies a file containing a bitmap to use.
456 Any other non-@code{nil} value specifies the default bitmap icon (a
457 picture of a gnu); @code{nil} specifies a text icon.
460 The name to use in the icon for this frame, when and if the icon
461 appears. If this is @code{nil}, the frame's title is used.
463 @item background-mode
464 This parameter is either @code{dark} or @code{light}, according
465 to whether the background color is a light one or a dark one.
468 @cindex standard colors for character terminals
469 This parameter overrides the terminal's color support as given by the
470 system's terminal capabilities database in that this parameter's value
471 specifies the color mode to use in terminal frames. The value can be
472 either a symbol or a number. A number specifies the number of colors
473 to use (and, indirectly, what commands to issue to produce each
474 color). For example, @code{(tty-color-mode . 8)} forces Emacs to use
475 the ANSI escape sequences for 8 standard text colors; and a value of
476 -1 means Emacs should turn off color support. If the parameter's
477 value is a symbol, that symbol is looked up in the alist
478 @code{tty-color-mode-alist}, and if found, the associated number is
479 used as the color support mode.
482 This parameter describes the range of possible colors that can be used
483 in this frame. Its value is @code{color}, @code{grayscale} or
487 How to display the cursor. Legitimate values are:
491 Display a filled box. (This is the default.)
493 Display a hollow box.
495 Don't display a cursor.
497 Display a vertical bar between characters.
498 @item (bar . @var{width})
499 Display a vertical bar @var{width} pixels wide between characters.
501 Display a horizontal bar.
502 @item (bar . @var{width})
503 Display a horizontal bar @var{width} pixels high.
507 The buffer-local variable @code{cursor-type} overrides the value of
508 the @code{cursor-type} frame parameter, and can in addition have
509 values @code{t} (use the cursor specified for the frame) and
510 @code{nil} (don't display a cursor).
513 The width in pixels of the window border.
515 @item internal-border-width
516 The distance in pixels between text and border.
520 The default width of the left and right fringes of windows in this
521 frame (@pxref{Fringes}). If either of these is zero, that effectively
522 removes the corresponding fringe. A value of @code{nil} stands for
523 the standard fringe width, which is the width needed to display the
526 The combined fringe widths must add up to an integral number of
527 columns, so the actual default fringe widths for the frame may be
528 larger than the specified values. The extra width needed to reach an
529 acceptable total is distributed evenly between the left and right
530 fringe. However, you can force one frame or the other to a precise
531 width by specifying that width a negative integer. If both widths are
532 negative, only the left fringe gets the specified width.
535 If non-@code{nil}, this frame's window is never split automatically.
538 The state of visibility of the frame. There are three possibilities:
539 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
540 iconified. @xref{Visibility of Frames}.
543 The number of lines to allocate at the top of the frame for a menu bar.
544 The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
545 toolkit, there is only one menu bar line; all that matters about the
546 number you specify is whether it is greater than zero.)
549 @cindex gamma correction
550 If this is a number, Emacs performs ``gamma correction'' which adjusts
551 the brightness of all colors. The value should be the screen gamma of
552 your display, a floating point number.
554 Usual PC monitors have a screen gamma of 2.2, so color values in
555 Emacs, and in X windows generally, are calibrated to display properly
556 on a monitor with that gamma value. If you specify 2.2 for
557 @code{screen-gamma}, that means no correction is needed. Other values
558 request correction, designed to make the corrected colors appear on
559 your screen they way they would have appeared without correction on an
560 ordinary monitor with a gamma value of 2.2.
562 If your monitor displays colors too light, you should specify a
563 @code{screen-gamma} value smaller than 2.2. This requests correction
564 that makes colors darker. A screen gamma value of 1.5 may give good
565 results for LCD color displays.
568 The number of lines to use for the toolbar. A value of @code{nil} means
569 don't display a tool bar.
572 Additional space put below text lines in pixels (a positive integer).
576 @c ??? Not yet working.
577 The X window number of the window that should be the parent of this one.
578 Specifying this lets you create an Emacs window inside some other
579 application's window. (It is not certain this will be implemented; try
580 it and see if it works.)
584 @defvar blink-cursor-alist
585 This variable specifies how to blink the cursor. Each element has the
586 form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
587 type equals @var{on-state} (comparing using @code{equal}), Emacs uses
588 @var{off-state} to specify what the cursor looks like when it blinks
589 ``off''. Both @var{on-state} and @var{off-state} should be suitable
590 values for the @code{cursor-type} frame parameter.
592 There are various defaults for how to blink each type of cursor,
593 if the type is not mentioned as an @var{on-state} here. Changes
594 in this variable do not take effect immediately, because the variable
595 is examined only when you specify a cursor type for a frame.
598 These frame parameters are semi-obsolete in that they are automatically
599 equivalent to particular face attributes of particular faces.
603 The name of the font for displaying text in the frame. This is a
604 string, either a valid font name for your system or the name of an Emacs
605 fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
606 attribute of the @code{default} face.
608 @item foreground-color
609 The color to use for the image of a character. It is equivalent to
610 the @code{:foreground} attribute of the @code{default} face.
612 @item background-color
613 The color to use for the background of characters. It is equivalent to
614 the @code{:background} attribute of the @code{default} face.
617 The color for the mouse pointer. It is equivalent to the @code{:background}
618 attribute of the @code{mouse} face.
621 The color for the cursor that shows point. It is equivalent to the
622 @code{:background} attribute of the @code{cursor} face.
625 The color for the border of the frame. It is equivalent to the
626 @code{:background} attribute of the @code{border} face.
628 @item scroll-bar-foreground
629 If non-@code{nil}, the color for the foreground of scroll bars. It is
630 equivalent to the @code{:foreground} attribute of the
631 @code{scroll-bar} face.
633 @item scroll-bar-background
634 If non-@code{nil}, the color for the background of scroll bars. It is
635 equivalent to the @code{:background} attribute of the
636 @code{scroll-bar} face.
639 @node Size and Position
640 @subsection Frame Size And Position
641 @cindex size of frame
646 You can read or change the size and position of a frame using the
647 frame parameters @code{left}, @code{top}, @code{height}, and
648 @code{width}. Whatever geometry parameters you don't specify are chosen
649 by the window manager in its usual fashion.
651 Here are some special features for working with sizes and positions.
652 (For the precise meaning of ``selected frame'' used by these functions,
653 see @ref{Input Focus}.)
655 @defun set-frame-position frame left top
656 This function sets the position of the top left corner of @var{frame} to
657 @var{left} and @var{top}. These arguments are measured in pixels, and
658 normally count from the top left corner of the screen.
660 Negative parameter values position the bottom edge of the window up from
661 the bottom edge of the screen, or the right window edge to the left of
662 the right edge of the screen. It would probably be better if the values
663 were always counted from the left and top, so that negative arguments
664 would position the frame partly off the top or left edge of the screen,
665 but it seems inadvisable to change that now.
668 @defun frame-height &optional frame
669 @defunx frame-width &optional frame
670 These functions return the height and width of @var{frame}, measured in
671 lines and columns. If you don't supply @var{frame}, they use the
677 These functions are old aliases for @code{frame-height} and
678 @code{frame-width}. When you are using a non-window terminal, the size
679 of the frame is normally the same as the size of the terminal screen.
682 @defun frame-pixel-height &optional frame
683 @defunx frame-pixel-width &optional frame
684 These functions return the height and width of @var{frame}, measured in
685 pixels. If you don't supply @var{frame}, they use the selected frame.
688 @defun frame-char-height &optional frame
689 @defunx frame-char-width &optional frame
690 These functions return the height and width of a character in
691 @var{frame}, measured in pixels. The values depend on the choice of
692 font. If you don't supply @var{frame}, these functions use the selected
696 @defun set-frame-size frame cols rows
697 This function sets the size of @var{frame}, measured in characters;
698 @var{cols} and @var{rows} specify the new width and height.
700 To set the size based on values measured in pixels, use
701 @code{frame-char-height} and @code{frame-char-width} to convert
702 them to units of characters.
705 @defun set-frame-height frame lines &optional pretend
706 This function resizes @var{frame} to a height of @var{lines} lines. The
707 sizes of existing windows in @var{frame} are altered proportionally to
710 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
711 lines of output in @var{frame}, but does not change its value for the
712 actual height of the frame. This is only useful for a terminal frame.
713 Using a smaller height than the terminal actually implements may be
714 useful to reproduce behavior observed on a smaller screen, or if the
715 terminal malfunctions when using its whole screen. Setting the frame
716 height ``for real'' does not always work, because knowing the correct
717 actual size may be necessary for correct cursor positioning on a
721 @defun set-frame-width frame width &optional pretend
722 This function sets the width of @var{frame}, measured in characters.
723 The argument @var{pretend} has the same meaning as in
724 @code{set-frame-height}.
727 @findex set-screen-height
728 @findex set-screen-width
729 The older functions @code{set-screen-height} and
730 @code{set-screen-width} were used to specify the height and width of the
731 screen, in Emacs versions that did not support multiple frames. They
732 are semi-obsolete, but still work; they apply to the selected frame.
734 @defun x-parse-geometry geom
735 @cindex geometry specification
736 The function @code{x-parse-geometry} converts a standard X window
737 geometry string to an alist that you can use as part of the argument to
740 The alist describes which parameters were specified in @var{geom}, and
741 gives the values specified for them. Each element looks like
742 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
743 values are @code{left}, @code{top}, @code{width}, and @code{height}.
745 For the size parameters, the value must be an integer. The position
746 parameter names @code{left} and @code{top} are not totally accurate,
747 because some values indicate the position of the right or bottom edges
748 instead. These are the @var{value} possibilities for the position
753 A positive integer relates the left edge or top edge of the window to
754 the left or top edge of the screen. A negative integer relates the
755 right or bottom edge of the window to the right or bottom edge of the
758 @item @code{(+ @var{position})}
759 This specifies the position of the left or top edge of the window
760 relative to the left or top edge of the screen. The integer
761 @var{position} may be positive or negative; a negative value specifies a
762 position outside the screen.
764 @item @code{(- @var{position})}
765 This specifies the position of the right or bottom edge of the window
766 relative to the right or bottom edge of the screen. The integer
767 @var{position} may be positive or negative; a negative value specifies a
768 position outside the screen.
774 (x-parse-geometry "35x70+0-0")
775 @result{} ((height . 70) (width . 35)
776 (top - 0) (left . 0))
781 @section Frame Titles
783 Every frame has a @code{name} parameter; this serves as the default
784 for the frame title which window systems typically display at the top of
785 the frame. You can specify a name explicitly by setting the @code{name}
788 Normally you don't specify the name explicitly, and Emacs computes the
789 frame name automatically based on a template stored in the variable
790 @code{frame-title-format}. Emacs recomputes the name each time the
791 frame is redisplayed.
793 @defvar frame-title-format
794 This variable specifies how to compute a name for a frame when you have
795 not explicitly specified one. The variable's value is actually a mode
796 line construct, just like @code{mode-line-format}. @xref{Mode Line
800 @defvar icon-title-format
801 This variable specifies how to compute the name for an iconified frame,
802 when you have not explicitly specified the frame title. This title
803 appears in the icon itself.
806 @defvar multiple-frames
807 This variable is set automatically by Emacs. Its value is @code{t} when
808 there are two or more frames (not counting minibuffer-only frames or
809 invisible frames). The default value of @code{frame-title-format} uses
810 @code{multiple-frames} so as to put the buffer name in the frame title
811 only when there is more than one frame.
814 @node Deleting Frames
815 @section Deleting Frames
816 @cindex deletion of frames
818 Frames remain potentially visible until you explicitly @dfn{delete}
819 them. A deleted frame cannot appear on the screen, but continues to
820 exist as a Lisp object until there are no references to it. There is no
821 way to cancel the deletion of a frame aside from restoring a saved frame
822 configuration (@pxref{Frame Configurations}); this is similar to the
825 @deffn Command delete-frame &optional frame force
826 @vindex delete-frame-functions
827 This function deletes the frame @var{frame} after running the hook
828 @code{delete-frame-functions} (each function gets one argument,
829 @var{frame}). By default, @var{frame} is the selected frame.
831 A frame cannot be deleted if its minibuffer is used by other frames.
832 Normally, you cannot delete a frame if all other frames are invisible,
833 but if the @var{force} is non-@code{nil}, then you are allowed to do so.
836 @defun frame-live-p frame
837 The function @code{frame-live-p} returns non-@code{nil} if the frame
838 @var{frame} has not been deleted.
841 Some window managers provide a command to delete a window. These work
842 by sending a special message to the program that operates the window.
843 When Emacs gets one of these commands, it generates a
844 @code{delete-frame} event, whose normal definition is a command that
845 calls the function @code{delete-frame}. @xref{Misc Events}.
847 @node Finding All Frames
848 @section Finding All Frames
851 The function @code{frame-list} returns a list of all the frames that
852 have not been deleted. It is analogous to @code{buffer-list} for
853 buffers, and includes frames on all terminals. The list that you get is
854 newly created, so modifying the list doesn't have any effect on the
858 @defun visible-frame-list
859 This function returns a list of just the currently visible frames.
860 @xref{Visibility of Frames}. (Terminal frames always count as
861 ``visible'', even though only the selected one is actually displayed.)
864 @defun next-frame &optional frame minibuf
865 The function @code{next-frame} lets you cycle conveniently through all
866 the frames on the current display from an arbitrary starting point. It
867 returns the ``next'' frame after @var{frame} in the cycle. If
868 @var{frame} is omitted or @code{nil}, it defaults to the selected frame
869 (@pxref{Input Focus}).
871 The second argument, @var{minibuf}, says which frames to consider:
875 Exclude minibuffer-only frames.
877 Consider all visible frames.
879 Consider all visible or iconified frames.
881 Consider only the frames using that particular window as their
888 @defun previous-frame &optional frame minibuf
889 Like @code{next-frame}, but cycles through all frames in the opposite
893 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
896 @node Frames and Windows
897 @section Frames and Windows
899 Each window is part of one and only one frame; you can get the frame
900 with @code{window-frame}.
902 @defun window-frame window
903 This function returns the frame that @var{window} is on.
906 All the non-minibuffer windows in a frame are arranged in a cyclic
907 order. The order runs from the frame's top window, which is at the
908 upper left corner, down and to the right, until it reaches the window at
909 the lower right corner (always the minibuffer window, if the frame has
910 one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
912 @defun frame-first-window frame
913 This returns the topmost, leftmost window of frame @var{frame}.
916 At any time, exactly one window on any frame is @dfn{selected within the
917 frame}. The significance of this designation is that selecting the
918 frame also selects this window. You can get the frame's current
919 selected window with @code{frame-selected-window}.
921 @defun frame-selected-window frame
922 This function returns the window on @var{frame} that is selected within
926 Conversely, selecting a window for Emacs with @code{select-window} also
927 makes that window selected within its frame. @xref{Selecting Windows}.
929 Another function that (usually) returns one of the windows in a given
930 frame is @code{minibuffer-window}. @xref{Minibuffer Misc}.
932 @node Minibuffers and Frames
933 @section Minibuffers and Frames
935 Normally, each frame has its own minibuffer window at the bottom, which
936 is used whenever that frame is selected. If the frame has a minibuffer,
937 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
939 However, you can also create a frame with no minibuffer. Such a frame
940 must use the minibuffer window of some other frame. When you create the
941 frame, you can specify explicitly the minibuffer window to use (in some
942 other frame). If you don't, then the minibuffer is found in the frame
943 which is the value of the variable @code{default-minibuffer-frame}. Its
944 value should be a frame that does have a minibuffer.
946 If you use a minibuffer-only frame, you might want that frame to raise
947 when you enter the minibuffer. If so, set the variable
948 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
950 @defvar default-minibuffer-frame
951 This variable specifies the frame to use for the minibuffer window, by
952 default. It is always local to the current terminal and cannot be
953 buffer-local. @xref{Multiple Displays}.
959 @cindex selected frame
961 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
962 window always resides on the selected frame.
964 When Emacs displays its frames on several terminals (@pxref{Multiple
965 Displays}), each terminal has its own selected frame. But only one of
966 these is ``@emph{the} selected frame'': it's the frame that belongs to
967 the terminal from which the most recent input came. That is, when Emacs
968 runs a command that came from a certain terminal, the selected frame is
969 the one of that terminal. Since Emacs runs only a single command at any
970 given time, it needs to consider only one selected frame at a time; this
971 frame is what we call @dfn{the selected frame} in this manual. The
972 display on which the selected frame is displayed is the @dfn{selected
975 @defun selected-frame
976 This function returns the selected frame.
979 Some window systems and window managers direct keyboard input to the
980 window object that the mouse is in; others require explicit clicks or
981 commands to @dfn{shift the focus} to various window objects. Either
982 way, Emacs automatically keeps track of which frame has the focus.
984 Lisp programs can also switch frames ``temporarily'' by calling the
985 function @code{select-frame}. This does not alter the window system's
986 concept of focus; rather, it escapes from the window manager's control
987 until that control is somehow reasserted.
989 When using a text-only terminal, only the selected terminal frame is
990 actually displayed on the terminal. @code{switch-frame} is the only way
991 to switch frames, and the change lasts until overridden by a subsequent
992 call to @code{switch-frame}. Each terminal screen except for the
993 initial one has a number, and the number of the selected frame appears
994 in the mode line before the buffer name (@pxref{Mode Line Variables}).
996 @c ??? This is not yet implemented properly.
997 @defun select-frame frame
998 This function selects frame @var{frame}, temporarily disregarding the
999 focus of the X server if any. The selection of @var{frame} lasts until
1000 the next time the user does something to select a different frame, or
1001 until the next time this function is called. The specified @var{frame}
1002 becomes the selected frame, as explained above, and the terminal that
1003 @var{frame} is on becomes the selected terminal.
1005 In general, you should never use @code{select-frame} in a way that could
1006 switch to a different terminal without switching back when you're done.
1009 Emacs cooperates with the window system by arranging to select frames as
1010 the server and window manager request. It does so by generating a
1011 special kind of input event, called a @dfn{focus} event, when
1012 appropriate. The command loop handles a focus event by calling
1013 @code{handle-switch-frame}. @xref{Focus Events}.
1015 @deffn Command handle-switch-frame frame
1016 This function handles a focus event by selecting frame @var{frame}.
1018 Focus events normally do their job by invoking this command.
1019 Don't call it for any other reason.
1022 @defun redirect-frame-focus frame focus-frame
1023 This function redirects focus from @var{frame} to @var{focus-frame}.
1024 This means that @var{focus-frame} will receive subsequent keystrokes and
1025 events intended for @var{frame}. After such an event, the value of
1026 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1027 events specifying @var{frame} will instead select @var{focus-frame}.
1029 If @var{focus-frame} is @code{nil}, that cancels any existing
1030 redirection for @var{frame}, which therefore once again receives its own
1033 One use of focus redirection is for frames that don't have minibuffers.
1034 These frames use minibuffers on other frames. Activating a minibuffer
1035 on another frame redirects focus to that frame. This puts the focus on
1036 the minibuffer's frame, where it belongs, even though the mouse remains
1037 in the frame that activated the minibuffer.
1039 Selecting a frame can also change focus redirections. Selecting frame
1040 @code{bar}, when @code{foo} had been selected, changes any redirections
1041 pointing to @code{foo} so that they point to @code{bar} instead. This
1042 allows focus redirection to work properly when the user switches from
1043 one frame to another using @code{select-window}.
1045 This means that a frame whose focus is redirected to itself is treated
1046 differently from a frame whose focus is not redirected.
1047 @code{select-frame} affects the former but not the latter.
1049 The redirection lasts until @code{redirect-frame-focus} is called to
1053 @defopt focus-follows-mouse
1054 This option is how you inform Emacs whether the window manager transfers
1055 focus when the user moves the mouse. Non-@code{nil} says that it does.
1056 When this is so, the command @code{other-frame} moves the mouse to a
1057 position consistent with the new selected frame.
1060 @node Visibility of Frames
1061 @section Visibility of Frames
1062 @cindex visible frame
1063 @cindex invisible frame
1064 @cindex iconified frame
1065 @cindex frame visibility
1067 A window frame may be @dfn{visible}, @dfn{invisible}, or
1068 @dfn{iconified}. If it is visible, you can see its contents. If it is
1069 iconified, the frame's contents do not appear on the screen, but an icon
1070 does. If the frame is invisible, it doesn't show on the screen, not
1073 Visibility is meaningless for terminal frames, since only the selected
1074 one is actually displayed in any case.
1076 @deffn Command make-frame-visible &optional frame
1077 This function makes frame @var{frame} visible. If you omit @var{frame},
1078 it makes the selected frame visible.
1081 @deffn Command make-frame-invisible &optional frame
1082 This function makes frame @var{frame} invisible. If you omit
1083 @var{frame}, it makes the selected frame invisible.
1086 @deffn Command iconify-frame &optional frame
1087 This function iconifies frame @var{frame}. If you omit @var{frame}, it
1088 iconifies the selected frame.
1091 @defun frame-visible-p frame
1092 This returns the visibility status of frame @var{frame}. The value is
1093 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
1094 @code{icon} if it is iconified.
1097 The visibility status of a frame is also available as a frame
1098 parameter. You can read or change it as such. @xref{Window Frame
1101 The user can iconify and deiconify frames with the window manager.
1102 This happens below the level at which Emacs can exert any control, but
1103 Emacs does provide events that you can use to keep track of such
1104 changes. @xref{Misc Events}.
1106 @node Raising and Lowering
1107 @section Raising and Lowering Frames
1109 Most window systems use a desktop metaphor. Part of this metaphor is
1110 the idea that windows are stacked in a notional third dimension
1111 perpendicular to the screen surface, and thus ordered from ``highest''
1112 to ``lowest''. Where two windows overlap, the one higher up covers
1113 the one underneath. Even a window at the bottom of the stack can be
1114 seen if no other window overlaps it.
1116 @cindex raising a frame
1117 @cindex lowering a frame
1118 A window's place in this ordering is not fixed; in fact, users tend
1119 to change the order frequently. @dfn{Raising} a window means moving
1120 it ``up'', to the top of the stack. @dfn{Lowering} a window means
1121 moving it to the bottom of the stack. This motion is in the notional
1122 third dimension only, and does not change the position of the window
1125 You can raise and lower Emacs frame Windows with these functions:
1127 @deffn Command raise-frame &optional frame
1128 This function raises frame @var{frame} (default, the selected frame).
1131 @deffn Command lower-frame &optional frame
1132 This function lowers frame @var{frame} (default, the selected frame).
1135 @defopt minibuffer-auto-raise
1136 If this is non-@code{nil}, activation of the minibuffer raises the frame
1137 that the minibuffer window is in.
1140 You can also enable auto-raise (raising automatically when a frame is
1141 selected) or auto-lower (lowering automatically when it is deselected)
1142 for any frame using frame parameters. @xref{Window Frame Parameters}.
1144 @node Frame Configurations
1145 @section Frame Configurations
1146 @cindex frame configuration
1148 A @dfn{frame configuration} records the current arrangement of frames,
1149 all their properties, and the window configuration of each one.
1150 (@xref{Window Configurations}.)
1152 @defun current-frame-configuration
1153 This function returns a frame configuration list that describes
1154 the current arrangement of frames and their contents.
1157 @defun set-frame-configuration configuration &optional nodelete
1158 This function restores the state of frames described in
1159 @var{configuration}.
1161 Ordinarily, this function deletes all existing frames not listed in
1162 @var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1163 unwanted frames are iconified instead.
1166 @node Mouse Tracking
1167 @section Mouse Tracking
1168 @cindex mouse tracking
1169 @cindex tracking the mouse
1171 Sometimes it is useful to @dfn{track} the mouse, which means to display
1172 something to indicate where the mouse is and move the indicator as the
1173 mouse moves. For efficient mouse tracking, you need a way to wait until
1174 the mouse actually moves.
1176 The convenient way to track the mouse is to ask for events to represent
1177 mouse motion. Then you can wait for motion by waiting for an event. In
1178 addition, you can easily handle any other sorts of events that may
1179 occur. That is useful, because normally you don't want to track the
1180 mouse forever---only until some other event, such as the release of a
1183 @defspec track-mouse body@dots{}
1184 This special form executes @var{body}, with generation of mouse motion
1185 events enabled. Typically @var{body} would use @code{read-event} to
1186 read the motion events and modify the display accordingly. @xref{Motion
1187 Events}, for the format of mouse motion events.
1189 The value of @code{track-mouse} is that of the last form in @var{body}.
1190 You should design @var{body} to return when it sees the up-event that
1191 indicates the release of the button, or whatever kind of event means
1192 it is time to stop tracking.
1195 The usual purpose of tracking mouse motion is to indicate on the screen
1196 the consequences of pushing or releasing a button at the current
1199 In many cases, you can avoid the need to track the mouse by using
1200 the @code{mouse-face} text property (@pxref{Special Properties}).
1201 That works at a much lower level and runs more smoothly than
1202 Lisp-level mouse tracking.
1205 @c These are not implemented yet.
1207 These functions change the screen appearance instantaneously. The
1208 effect is transient, only until the next ordinary Emacs redisplay. That
1209 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1210 to change the text, and the body of @code{track-mouse} normally reads
1211 the events itself and does not do redisplay.
1213 @defun x-contour-region window beg end
1214 This function draws lines to make a box around the text from @var{beg}
1215 to @var{end}, in window @var{window}.
1218 @defun x-uncontour-region window beg end
1219 This function erases the lines that would make a box around the text
1220 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1221 a contour that you previously made by calling @code{x-contour-region}.
1224 @defun x-draw-rectangle frame left top right bottom
1225 This function draws a hollow rectangle on frame @var{frame} with the
1226 specified edge coordinates, all measured in pixels from the inside top
1227 left corner. It uses the cursor color, the one used for indicating the
1231 @defun x-erase-rectangle frame left top right bottom
1232 This function erases a hollow rectangle on frame @var{frame} with the
1233 specified edge coordinates, all measured in pixels from the inside top
1234 left corner. Erasure means redrawing the text and background that
1235 normally belong in the specified rectangle.
1239 @node Mouse Position
1240 @section Mouse Position
1241 @cindex mouse position
1242 @cindex position of mouse
1244 The functions @code{mouse-position} and @code{set-mouse-position}
1245 give access to the current position of the mouse.
1247 @defun mouse-position
1248 This function returns a description of the position of the mouse. The
1249 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1250 and @var{y} are integers giving the position in characters relative to
1251 the top left corner of the inside of @var{frame}.
1254 @defvar mouse-position-function
1255 If non-@code{nil}, the value of this variable is a function for
1256 @code{mouse-position} to call. @code{mouse-position} calls this
1257 function just before returning, with its normal return value as the
1258 sole argument, and it returns whatever this function returns to it.
1260 This abnormal hook exists for the benefit of packages like
1261 @file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1264 @defun set-mouse-position frame x y
1265 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1266 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1267 giving the position in characters relative to the top left corner of the
1268 inside of @var{frame}. If @var{frame} is not visible, this function
1269 does nothing. The return value is not significant.
1272 @defun mouse-pixel-position
1273 This function is like @code{mouse-position} except that it returns
1274 coordinates in units of pixels rather than units of characters.
1277 @defun set-mouse-pixel-position frame x y
1278 This function warps the mouse like @code{set-mouse-position} except that
1279 @var{x} and @var{y} are in units of pixels rather than units of
1280 characters. These coordinates are not required to be within the frame.
1282 If @var{frame} is not visible, this function does nothing. The return
1283 value is not significant.
1289 @section Pop-Up Menus
1291 When using a window system, a Lisp program can pop up a menu so that
1292 the user can choose an alternative with the mouse.
1294 @defun x-popup-menu position menu
1295 This function displays a pop-up menu and returns an indication of
1296 what selection the user makes.
1298 The argument @var{position} specifies where on the screen to put the
1299 menu. It can be either a mouse button event (which says to put the menu
1300 where the user actuated the button) or a list of this form:
1303 ((@var{xoffset} @var{yoffset}) @var{window})
1307 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1308 pixels, counting from the top left corner of @var{window}'s frame.
1310 If @var{position} is @code{t}, it means to use the current mouse
1311 position. If @var{position} is @code{nil}, it means to precompute the
1312 key binding equivalents for the keymaps specified in @var{menu},
1313 without actually displaying or popping up the menu.
1315 The argument @var{menu} says what to display in the menu. It can be a
1316 keymap or a list of keymaps (@pxref{Menu Keymaps}). Alternatively, it
1317 can have the following form:
1320 (@var{title} @var{pane1} @var{pane2}...)
1324 where each pane is a list of form
1327 (@var{title} (@var{line} . @var{item})...)
1330 Each @var{line} should be a string, and each @var{item} should be the
1331 value to return if that @var{line} is chosen.
1334 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1335 if you could do the job with a prefix key defined with a menu keymap.
1336 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1337 a} can see the individual items in that menu and provide help for them.
1338 If instead you implement the menu by defining a command that calls
1339 @code{x-popup-menu}, the help facilities cannot know what happens inside
1340 that command, so they cannot give any help for the menu's items.
1342 The menu bar mechanism, which lets you switch between submenus by
1343 moving the mouse, cannot look within the definition of a command to see
1344 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1345 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1346 an integrated fashion. This is why all menu bar submenus are
1347 implemented with menu keymaps within the parent menu, and never with
1348 @code{x-popup-menu}. @xref{Menu Bar},
1350 If you want a menu bar submenu to have contents that vary, you should
1351 still use a menu keymap to implement it. To make the contents vary, add
1352 a hook function to @code{menu-bar-update-hook} to update the contents of
1353 the menu keymap as necessary.
1356 @section Dialog Boxes
1357 @cindex dialog boxes
1359 A dialog box is a variant of a pop-up menu---it looks a little
1360 different, it always appears in the center of a frame, and it has just
1361 one level and one pane. The main use of dialog boxes is for asking
1362 questions that the user can answer with ``yes'', ``no'', and a few other
1363 alternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} use
1364 dialog boxes instead of the keyboard, when called from commands invoked
1367 @defun x-popup-dialog position contents
1368 This function displays a pop-up dialog box and returns an indication of
1369 what selection the user makes. The argument @var{contents} specifies
1370 the alternatives to offer; it has this format:
1373 (@var{title} (@var{string} . @var{value})@dots{})
1377 which looks like the list that specifies a single pane for
1378 @code{x-popup-menu}.
1380 The return value is @var{value} from the chosen alternative.
1382 An element of the list may be just a string instead of a cons cell
1383 @code{(@var{string} . @var{value})}. That makes a box that cannot
1386 If @code{nil} appears in the list, it separates the left-hand items from
1387 the right-hand items; items that precede the @code{nil} appear on the
1388 left, and items that follow the @code{nil} appear on the right. If you
1389 don't include a @code{nil} in the list, then approximately half the
1390 items appear on each side.
1392 Dialog boxes always appear in the center of a frame; the argument
1393 @var{position} specifies which frame. The possible values are as in
1394 @code{x-popup-menu}, but the precise coordinates don't matter; only the
1397 In some configurations, Emacs cannot display a real dialog box; so
1398 instead it displays the same items in a pop-up menu in the center of the
1402 @node Pointer Shapes
1403 @section Pointer Shapes
1404 @cindex pointer shape
1405 @cindex mouse pointer shape
1407 These variables specify which shape to use for the mouse pointer in
1408 various situations, when using the X Window System:
1411 @item x-pointer-shape
1412 @vindex x-pointer-shape
1413 This variable specifies the pointer shape to use ordinarily in the Emacs
1416 @item x-sensitive-text-pointer-shape
1417 @vindex x-sensitive-text-pointer-shape
1418 This variable specifies the pointer shape to use when the mouse
1419 is over mouse-sensitive text.
1422 These variables affect newly created frames. They do not normally
1423 affect existing frames; however, if you set the mouse color of a frame,
1424 that also updates its pointer shapes based on the current values of
1425 these variables. @xref{Window Frame Parameters}.
1427 The values you can use, to specify either of these pointer shapes, are
1428 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1429 @key{RET} x-pointer @key{RET}} to see a list of them.
1431 @node Window System Selections
1432 @section Window System Selections
1433 @cindex selection (for window systems)
1435 The X server records a set of @dfn{selections} which permit transfer of
1436 data between application programs. The various selections are
1437 distinguished by @dfn{selection types}, represented in Emacs by
1438 symbols. X clients including Emacs can read or set the selection for
1441 @defun x-set-selection type data
1442 This function sets a ``selection'' in the X server. It takes two
1443 arguments: a selection type @var{type}, and the value to assign to it,
1444 @var{data}. If @var{data} is @code{nil}, it means to clear out the
1445 selection. Otherwise, @var{data} may be a string, a symbol, an integer
1446 (or a cons of two integers or list of two integers), an overlay, or a
1447 cons of two markers pointing to the same buffer. An overlay or a pair
1448 of markers stands for text in the overlay or between the markers.
1450 The argument @var{data} may also be a vector of valid non-vector
1453 Each possible @var{type} has its own selection value, which changes
1454 independently. The usual values of @var{type} are @code{PRIMARY} and
1455 @code{SECONDARY}; these are symbols with upper-case names, in accord
1456 with X Window System conventions. The default is @code{PRIMARY}.
1459 @defun x-get-selection &optional type data-type
1460 This function accesses selections set up by Emacs or by other X
1461 clients. It takes two optional arguments, @var{type} and
1462 @var{data-type}. The default for @var{type}, the selection type, is
1465 The @var{data-type} argument specifies the form of data conversion to
1466 use, to convert the raw data obtained from another X client into Lisp
1467 data. Meaningful values include @code{TEXT}, @code{STRING},
1468 @code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
1469 @code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
1470 @code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
1471 @code{NAME}, @code{ATOM}, and @code{INTEGER}. (These are symbols with
1472 upper-case names in accord with X conventions.) The default for
1473 @var{data-type} is @code{STRING}.
1477 The X server also has a set of numbered @dfn{cut buffers} which can
1478 store text or other data being moved between applications. Cut buffers
1479 are considered obsolete, but Emacs supports them for the sake of X
1480 clients that still use them.
1482 @defun x-get-cut-buffer n
1483 This function returns the contents of cut buffer number @var{n}.
1486 @defun x-set-cut-buffer string &optional push
1487 This function stores @var{string} into the first cut buffer (cut buffer
1488 0). If @var{push} is @code{nil}, only the first cut buffer is changed.
1489 If @var{push} is non-@code{nil}, that says to move the values down
1490 through the series of cut buffers, much like the way successive kills in
1491 Emacs move down the kill ring. In other words, the previous value of
1492 the first cut buffer moves into the second cut buffer, and the second to
1493 the third, and so on through all eight cut buffers.
1496 @defvar selection-coding-system
1497 This variable specifies the coding system to use when reading and
1498 writing selections, the clipboard, or a cut buffer. @xref{Coding
1499 Systems}. The default is @code{compound-text-with-extensions}, which
1500 converts to the text representation that X11 normally uses.
1503 @cindex clipboard support (for MS-Windows)
1504 When Emacs runs on MS-Windows, it does not implement X selections in
1505 general, but it does support the clipboard. @code{x-get-selection}
1506 and @code{x-set-selection} on MS-Windows support the text data type
1507 only; if the clipboard holds other types of data, Emacs treats the
1510 @defopt x-select-enable-clipboard
1511 If this is non-@code{nil}, the Emacs yank functions consult the
1512 clipboard before the primary selection, and the kill functions store in
1513 the clipboard as well as the primary selection. Otherwise they do not
1514 access the clipboard at all. The default is @code{nil} on most systems,
1515 but @code{t} on MS-Windows.
1519 @section Color Names
1521 These functions provide a way to determine which color names are
1522 valid, and what they look like. In some cases, the value depends on the
1523 @dfn{selected frame}, as described below; see @ref{Input Focus}, for the
1524 meaning of the term ``selected frame''.
1526 @defun color-defined-p color &optional frame
1527 @tindex color-defined-p
1528 This function reports whether a color name is meaningful. It returns
1529 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
1530 which frame's display to ask about; if @var{frame} is omitted or
1531 @code{nil}, the selected frame is used.
1533 Note that this does not tell you whether the display you are using
1534 really supports that color. When using X, you can ask for any defined
1535 color on any kind of display, and you will get some result---typically,
1536 the closest it can do. To determine whether a frame can really display
1537 a certain color, use @code{color-supported-p} (see below).
1539 @findex x-color-defined-p
1540 This function used to be called @code{x-color-defined-p},
1541 and that name is still supported as an alias.
1544 @defun defined-colors &optional frame
1545 @tindex defined-colors
1546 This function returns a list of the color names that are defined
1547 and supported on frame @var{frame} (default, the selected frame).
1549 @findex x-defined-colors
1550 This function used to be called @code{x-defined-colors},
1551 and that name is still supported as an alias.
1554 @defun color-supported-p color &optional frame background-p
1555 @tindex color-supported-p
1556 This returns @code{t} if @var{frame} can really display the color
1557 @var{color} (or at least something close to it). If @var{frame} is
1558 omitted or @code{nil}, the question applies to the selected frame.
1560 Some terminals support a different set of colors for foreground and
1561 background. If @var{background-p} is non-@code{nil}, that means you are
1562 asking whether @var{color} can be used as a background; otherwise you
1563 are asking whether it can be used as a foreground.
1565 The argument @var{color} must be a valid color name.
1568 @defun color-gray-p color &optional frame
1569 @tindex color-gray-p
1570 This returns @code{t} if @var{color} is a shade of gray, as defined on
1571 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
1572 question applies to the selected frame. The argument @var{color} must
1573 be a valid color name.
1576 @defun color-values color &optional frame
1577 @tindex color-values
1578 This function returns a value that describes what @var{color} should
1579 ideally look like. If @var{color} is defined, the value is a list of
1580 three integers, which give the amount of red, the amount of green, and
1581 the amount of blue. Each integer ranges in principle from 0 to 65535,
1582 but in practice no value seems to be above 65280. This kind
1583 of three-element list is called an @dfn{rgb value}.
1585 If @var{color} is not defined, the value is @code{nil}.
1588 (color-values "black")
1590 (color-values "white")
1591 @result{} (65280 65280 65280)
1592 (color-values "red")
1593 @result{} (65280 0 0)
1594 (color-values "pink")
1595 @result{} (65280 49152 51968)
1596 (color-values "hungry")
1600 The color values are returned for @var{frame}'s display. If @var{frame}
1601 is omitted or @code{nil}, the information is returned for the selected
1604 @findex x-color-values
1605 This function used to be called @code{x-color-values},
1606 and that name is still supported as an alias.
1609 @node Text Terminal Colors
1610 @section Text Terminal Colors
1611 @cindex colors on text-only terminals
1613 Emacs can display color on text-only terminals, starting with version
1614 21. These terminals usually support only a small number of colors, and
1615 the computer uses small integers to select colors on the terminal. This
1616 means that the computer cannot reliably tell what the selected color
1617 looks like; instead, you have to inform your application which small
1618 integers correspond to which colors. However, Emacs does know the
1619 standard set of colors and will try to use them automatically.
1621 The functions described in this section control how terminal colors
1625 Several of these functions use or return @dfn{rgb values}. An rgb
1626 value is a list of three integers, which give the amount of red, the
1627 amount of green, and the amount of blue. Each integer ranges in
1628 principle from 0 to 65535, but in practice the largest value used is
1631 These functions accept a display (either a frame or the name of a
1632 terminal) as an optional argument. We hope in the future to make Emacs
1633 support more than one text-only terminal at one time; then this argument
1634 will specify which terminal to operate on (the default being the
1635 selected frame's terminal; @pxref{Input Focus}). At present, though,
1636 the @var{display} argument has no effect.
1638 @defun tty-color-define name number &optional rgb display
1639 @tindex tty-color-define
1640 This function associates the color name @var{name} with
1641 color number @var{number} on the terminal.
1643 The optional argument @var{rgb}, if specified, is an rgb value; it says
1644 what the color actually looks like. If you do not specify @var{rgb},
1645 then this color cannot be used by @code{tty-color-approximate} to
1646 approximate other colors, because Emacs does not know what it looks
1650 @defun tty-color-clear &optional display
1651 @tindex tty-color-clear
1652 This function clears the table of defined colors for a text-only terminal.
1655 @defun tty-color-alist &optional display
1656 @tindex tty-color-alist
1657 This function returns an alist recording the known colors supported by a
1660 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
1661 or @code{(@var{name} @var{number})}. Here, @var{name} is the color
1662 name, @var{number} is the number used to specify it to the terminal.
1663 If present, @var{rgb} is an rgb value that says what the color
1664 actually looks like.
1667 @defun tty-color-approximate rgb &optional display
1668 @tindex tty-color-approximate
1669 This function finds the closest color, among the known colors supported
1670 for @var{display}, to that described by the rgb value @var{rgb}.
1673 @defun tty-color-translate color &optional display
1674 @tindex tty-color-translate
1675 This function finds the closest color to @var{color} among the known
1676 colors supported for @var{display}. If the name @var{color} is not
1677 defined, the value is @code{nil}.
1679 @var{color} can be an X-style @code{"#@var{xxxyyyzzz}"} specification
1680 instead of an actual name. The format
1681 @code{"RGB:@var{xx}/@var{yy}/@var{zz}"} is also supported.
1685 @section X Resources
1687 @defun x-get-resource attribute class &optional component subclass
1688 The function @code{x-get-resource} retrieves a resource value from the X
1689 Windows defaults database.
1691 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
1692 This function searches using a key of the form
1693 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
1694 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
1697 The optional arguments @var{component} and @var{subclass} add to the key
1698 and the class, respectively. You must specify both of them or neither.
1699 If you specify them, the key is
1700 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
1701 @samp{Emacs.@var{class}.@var{subclass}}.
1704 @defvar x-resource-class
1705 This variable specifies the application name that @code{x-get-resource}
1706 should look up. The default value is @code{"Emacs"}. You can examine X
1707 resources for application names other than ``Emacs'' by binding this
1708 variable to some other string, around a call to @code{x-get-resource}.
1711 @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
1713 @node Display Feature Testing
1714 @section Display Feature Testing
1715 @cindex display feature testing
1717 The functions in this section describe the basic capabilities of a
1718 particular display. Lisp programs can use them to adapt their behavior
1719 to what the display can do. For example, a program that ordinarily uses
1720 a popup menu could use the minibuffer if popup menus are not supported.
1722 The optional argument @var{display} in these functions specifies which
1723 display to ask the question about. It can be a display name, a frame
1724 (which designates the display that frame is on), or @code{nil} (which
1725 refers to the selected frame's display, @pxref{Input Focus}).
1727 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
1728 obtain information about displays.
1730 @defun display-popup-menus-p &optional display
1731 @tindex display-popup-menus-p
1732 This function returns @code{t} if popup menus are supported on
1733 @var{display}, @code{nil} if not. Support for popup menus requires that
1734 the mouse be available, since the user cannot choose menu items without
1738 @defun display-graphic-p &optional display
1739 @tindex display-graphic-p
1740 @cindex frames, more than one on display
1741 @cindex fonts, more than one on display
1742 This function returns @code{t} if @var{display} is a graphic display
1743 capable of displaying several frames and several different fonts at
1744 once. This is true for displays that use a window system such as X, and
1745 false for text-only terminals.
1748 @defun display-mouse-p &optional display
1749 @tindex display-mouse-p
1750 @cindex mouse, availability
1751 This function returns @code{t} if @var{display} has a mouse available,
1755 @defun display-color-p &optional display
1756 @tindex display-color-p
1757 @findex x-display-color-p
1758 This function returns @code{t} if the screen is a color screen.
1759 It used to be called @code{x-display-color-p}, and that name
1760 is still supported as an alias.
1763 @defun display-grayscale-p &optional display
1764 @tindex display-grayscale-p
1765 This function returns @code{t} if the screen can display shades of gray.
1766 (All color displays can do this.)
1769 @anchor{Display Face Attribute Testing}
1770 @defun display-supports-face-attributes-p attributes &optional display
1771 @tindex display-supports-face-attributes-p
1772 This function returns non-@code{nil} if all the face attributes in
1773 @var{attributes} are supported (@pxref{Face Attributes}).
1775 The definition of `supported' is somewhat heuristic, but basically
1776 means that a face containing all the attributes in @var{attributes},
1777 when merged with the default face for display, can be represented in a
1782 different in appearance than the default face, and
1785 `close in spirit' to what the attributes specify, if not exact.
1788 Point (2) implies that a @code{:weight black} attribute will be
1789 satisfied by any display that can display bold, as will
1790 @code{:foreground "yellow"} as long as some yellowish color can be
1791 displayed, but @code{:slant italic} will @emph{not} be satisfied by
1792 the tty display code's automatic substitution of a `dim' face for
1796 @defun display-selections-p &optional display
1797 @tindex display-selections-p
1798 This function returns @code{t} if @var{display} supports selections.
1799 Windowed displays normally support selections, but they may also be
1800 supported in some other cases.
1803 @defun display-images-p &optional display
1804 This function returns @code{t} if @var{display} can display images.
1805 Windowed displays ought in principle to handle images, but some
1806 systems lack the support for that. On a display that does not support
1807 images, Emacs cannot display a tool bar.
1810 @defun display-screens &optional display
1811 @tindex display-screens
1812 This function returns the number of screens associated with the display.
1815 @defun display-pixel-height &optional display
1816 @tindex display-pixel-height
1817 This function returns the height of the screen in pixels.
1820 @defun display-mm-height &optional display
1821 @tindex display-mm-height
1822 This function returns the height of the screen in millimeters,
1823 or @code{nil} if Emacs cannot get that information.
1826 @defun display-pixel-width &optional display
1827 @tindex display-pixel-width
1828 This function returns the width of the screen in pixels.
1831 @defun display-mm-width &optional display
1832 @tindex display-mm-width
1833 This function returns the width of the screen in millimeters,
1834 or @code{nil} if Emacs cannot get that information.
1837 @defun display-backing-store &optional display
1838 @tindex display-backing-store
1839 This function returns the backing store capability of the display.
1840 Backing store means recording the pixels of windows (and parts of
1841 windows) that are not exposed, so that when exposed they can be
1842 displayed very quickly.
1844 Values can be the symbols @code{always}, @code{when-mapped}, or
1845 @code{not-useful}. The function can also return @code{nil}
1846 when the question is inapplicable to a certain kind of display.
1849 @defun display-save-under &optional display
1850 @tindex display-save-under
1851 This function returns non-@code{nil} if the display supports the
1852 SaveUnder feature. That feature is used by pop-up windows
1853 to save the pixels they obscure, so that they can pop down
1857 @defun display-planes &optional display
1858 @tindex display-planes
1859 This function returns the number of planes the display supports.
1860 This is typically the number of bits per pixel.
1861 For a tty display, it is log to base two of the number of colours supported.
1864 @defun display-visual-class &optional display
1865 @tindex display-visual-class
1866 This function returns the visual class for the screen. The value is one
1867 of the symbols @code{static-gray}, @code{gray-scale},
1868 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
1869 @code{direct-color}.
1872 @defun display-color-cells &optional display
1873 @tindex display-color-cells
1874 This function returns the number of color cells the screen supports.
1877 These functions obtain additional information specifically
1880 @defun x-server-version &optional display
1881 This function returns the list of version numbers of the X server
1882 running the display.
1885 @defun x-server-vendor &optional display
1886 This function returns the vendor that provided the X server software.
1890 @defvar x-no-window-manager
1891 This variable's value is @code{t} if no X window manager is in use.
1897 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
1898 width and height of an X Window frame, measured in pixels.
1902 arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba