*** empty log message ***
[emacs.git] / lispref / frames.texi
blob35dfb6dd312f5ed186d3434942f444ece3d3c6f1
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
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
8 @chapter Frames
9 @cindex frame
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.
21 @cindex window frame
22   When Emacs communicates directly with a supported window system, such
23 as X Windows, 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.
27 @defun framep object
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:
32 @table @code
33 @item x
34 The frame is displayed in an X window.
35 @item t
36 A terminal frame on a character display.
37 @item mac
38 The frame is displayed on a Macintosh.
39 @item w32
40 The frame is displayed on MS-Windows 9X/NT.
41 @item pc
42 The frame is displayed on an MS-DOS terminal.
43 @end table
44 @end defun
46 @menu
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.
71 @end menu
73   @xref{Display}, for information about the related topic of 
74 controlling Emacs redisplay.
76 @node Creating Frames
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
89 your system.
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.
94 @end defun
96 @defvar before-make-frame-hook
97 A normal hook run by @code{make-frame} before it actually creates the
98 frame.
99 @end defvar
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-hook} receives one argument, the
105 frame just created.
106 @end defvar
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.
123   A few Lisp variables are @dfn{terminal-local}; that is, they have a
124 separate binding for each terminal.  The binding in effect at any time
125 is the one for the terminal that the currently selected frame belongs
126 to.  These variables include @code{default-minibuffer-frame},
127 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
128 @code{system-key-alist}.  They are always terminal-local, and can never
129 be buffer-local (@pxref{Buffer-Local Variables}) or frame-local.
131   A single X server can handle more than one screen.  A display name
132 @samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
133 part specifies the screen number for a given server.  When you use two
134 screens belonging to one server, Emacs knows by the similarity in their
135 names that they share a single keyboard, and it treats them as a single
136 terminal.
138 @deffn Command make-frame-on-display display &optional parameters
139 This creates a new frame on display @var{display}, taking the other
140 frame parameters from @var{parameters}.  Aside from the @var{display}
141 argument, it is like @code{make-frame} (@pxref{Creating Frames}).
142 @end deffn
144 @defun x-display-list
145 This returns a list that indicates which X displays Emacs has a
146 connection to.  The elements of the list are strings, and each one is
147 a display name.
148 @end defun
150 @defun x-open-connection display &optional xrm-string must-succeed
151 This function opens a connection to the X display @var{display}.  It
152 does not create a frame on that display, but it permits you to check
153 that communication can be established with that display.
155 The optional argument @var{xrm-string}, if not @code{nil}, is a
156 string of resource names and values, in the same format used in the
157 @file{.Xresources} file.  The values you specify override the resource
158 values recorded in the X server itself; they apply to all Emacs frames
159 created on this display.  Here's an example of what this string might
160 look like:
162 @example
163 "*BorderWidth: 3\n*InternalBorder: 2\n"
164 @end example
166 @xref{Resources}.
168 If @var{must-succeed} is non-@code{nil}, failure to open the connection
169 terminates Emacs.  Otherwise, it is an ordinary Lisp error.
170 @end defun
172 @defun x-close-connection display
173 This function closes the connection to display @var{display}.  Before
174 you can do this, you must first delete all the frames that were open on
175 that display (@pxref{Deleting Frames}).
176 @end defun
178 @node Frame Parameters
179 @section Frame Parameters
181   A frame has many parameters that control its appearance and behavior.
182 Just what parameters a frame has depends on what display mechanism it
183 uses.
185   Frame parameters exist mostly for the sake of window systems.  A
186 terminal frame has a few parameters, mostly for compatibility's sake;
187 only the @code{height}, @code{width}, @code{name}, @code{title},
188 @code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
189 parameters do something special.  If the terminal supports colors, the
190 parameters @code{foreground-color}, @code{background-color},
191 @code{background-mode} and @code{display-type} are also meaningful.
193 @menu
194 * Parameter Access::       How to change a frame's parameters.
195 * Initial Parameters::     Specifying frame parameters when you make a frame.
196 * Window Frame Parameters:: List of frame parameters for window systems.
197 * Size and Position::      Changing the size and position of a frame.
198 @end menu
200 @node Parameter Access
201 @subsection Access to Frame Parameters
203 These functions let you read and change the parameter values of a
204 frame.
206 @defun frame-parameter frame parameter
207 @tindex frame-parameter
208 This function returns the value of the parameter named @var{parameter}
209 of @var{frame}.  If @var{frame} is @code{nil}, it returns the
210 selected  frame's parameter.
211 @end defun
213 @defun frame-parameters frame
214 The function @code{frame-parameters} returns an alist listing all the
215 parameters of @var{frame} and their values.
216 @end defun
218 @defun modify-frame-parameters frame alist
219 This function alters the parameters of frame @var{frame} based on the
220 elements of @var{alist}.  Each element of @var{alist} has the form
221 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
222 parameter.  If you don't mention a parameter in @var{alist}, its value
223 doesn't change.
224 @end defun
226 @node Initial Parameters
227 @subsection Initial Frame Parameters
229 You can specify the parameters for the initial startup frame
230 by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
232 @defvar initial-frame-alist
233 This variable's value is an alist of parameter values used when creating
234 the initial window frame.  You can set this variable to specify the
235 appearance of the initial frame without altering subsequent frames.
236 Each element has the form:
238 @example
239 (@var{parameter} . @var{value})
240 @end example
242 Emacs creates the initial frame before it reads your init
243 file.  After reading that file, Emacs checks @code{initial-frame-alist},
244 and applies the parameter settings in the altered value to the already
245 created initial frame.
247 If these settings affect the frame geometry and appearance, you'll see
248 the frame appear with the wrong ones and then change to the specified
249 ones.  If that bothers you, you can specify the same geometry and
250 appearance with X resources; those do take effect before the frame is
251 created.  @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
253 X resource settings typically apply to all frames.  If you want to
254 specify some X resources solely for the sake of the initial frame, and
255 you don't want them to apply to subsequent frames, here's how to achieve
256 this.  Specify parameters in @code{default-frame-alist} to override the
257 X resources for subsequent frames; then, to prevent these from affecting
258 the initial frame, specify the same parameters in
259 @code{initial-frame-alist} with values that match the X resources.
260 @end defvar
262 If these parameters specify a separate minibuffer-only frame with
263 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
264 one for you.
266 @defvar minibuffer-frame-alist
267 This variable's value is an alist of parameter values used when creating
268 an initial minibuffer-only frame---if such a frame is needed, according
269 to the parameters for the main initial frame.
270 @end defvar
272 @defvar default-frame-alist
273 This is an alist specifying default values of frame parameters for all
274 Emacs frames---the first frame, and subsequent frames.  When using the X
275 Window System, you can get the same results by means of X resources
276 in many cases.
277 @end defvar
279 See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
281 If you use options that specify window appearance when you invoke Emacs,
282 they take effect by adding elements to @code{default-frame-alist}.  One
283 exception is @samp{-geometry}, which adds the specified position to
284 @code{initial-frame-alist} instead.  @xref{Command Arguments,,, emacs,
285 The GNU Emacs Manual}.
287 @node Window Frame Parameters
288 @subsection Window Frame Parameters
290 Just what parameters a frame has depends on what display mechanism it
291 uses.  Here is a table of the parameters that have special meanings in a
292 window frame; of these, @code{name}, @code{title}, @code{height},
293 @code{width}, @code{buffer-list} and @code{buffer-predicate} provide
294 meaningful information in terminal frames.
296 @table @code
297 @item display
298 The display on which to open this frame.  It should be a string of the
299 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
300 @code{DISPLAY} environment variable.
302 @item title
303 If a frame has a non-@code{nil} title, it appears in the window system's
304 border for the frame, and also in the mode line of windows in that frame
305 if @code{mode-line-frame-identification} uses @samp{%F}
306 (@pxref{%-Constructs}).  This is normally the case when Emacs is not
307 using a window system, and can only display one frame at a time.
308 @xref{Frame Titles}.
310 @item name
311 The name of the frame.  The frame name serves as a default for the frame
312 title, if the @code{title} parameter is unspecified or @code{nil}.  If
313 you don't specify a name, Emacs sets the frame name automatically
314 (@pxref{Frame Titles}).
316 If you specify the frame name explicitly when you create the frame, the
317 name is also used (instead of the name of the Emacs executable) when
318 looking up X resources for the frame.
320 @item left
321 The screen position of the left edge, in pixels, with respect to the
322 left edge of the screen.  The value may be a positive number @var{pos},
323 or a list of the form @code{(+ @var{pos})} which permits specifying a
324 negative @var{pos} value.
326 A negative number @minus{}@var{pos}, or a list of the form @code{(-
327 @var{pos})}, actually specifies the position of the right edge of the
328 window with respect to the right edge of the screen.  A positive value
329 of @var{pos} counts toward the left.  @strong{Reminder:} if the
330 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
331 positive.
333 Some window managers ignore program-specified positions.  If you want to
334 be sure the position you specify is not ignored, specify a
335 non-@code{nil} value for the @code{user-position} parameter as well.
337 @item top
338 The screen position of the top edge, in pixels, with respect to the
339 top edge of the screen.  The value may be a positive number @var{pos},
340 or a list of the form @code{(+ @var{pos})} which permits specifying a
341 negative @var{pos} value.
343 A negative number @minus{}@var{pos}, or a list of the form @code{(-
344 @var{pos})}, actually specifies the position of the bottom edge of the
345 window with respect to the bottom edge of the screen.  A positive value
346 of @var{pos} counts toward the top.  @strong{Reminder:} if the
347 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
348 positive.
350 Some window managers ignore program-specified positions.  If you want to
351 be sure the position you specify is not ignored, specify a
352 non-@code{nil} value for the @code{user-position} parameter as well.
354 @item icon-left
355 The screen position of the left edge @emph{of the frame's icon}, in
356 pixels, counting from the left edge of the screen.  This takes effect if
357 and when the frame is iconified.
359 @item icon-top
360 The screen position of the top edge @emph{of the frame's icon}, in
361 pixels, counting from the top edge of the screen.  This takes effect if
362 and when the frame is iconified.
364 @item user-position
365 When you create a frame and specify its screen position with the
366 @code{left} and @code{top} parameters, use this parameter to say whether
367 the specified position was user-specified (explicitly requested in some
368 way by a human user) or merely program-specified (chosen by a program).
369 A non-@code{nil} value says the position was user-specified.
371 Window managers generally heed user-specified positions, and some heed
372 program-specified positions too.  But many ignore program-specified
373 positions, placing the window in a default fashion or letting the user
374 place it with the mouse.  Some window managers, including @code{twm},
375 let the user specify whether to obey program-specified positions or
376 ignore them.
378 When you call @code{make-frame}, you should specify a non-@code{nil}
379 value for this parameter if the values of the @code{left} and @code{top}
380 parameters represent the user's stated preference; otherwise, use
381 @code{nil}.
383 @item height
384 The height of the frame contents, in characters.  (To get the height in
385 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
387 @item width
388 The width of the frame contents, in characters.  (To get the height in
389 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
391 @item window-id
392 The number of the window-system window used by the frame
393 to contain the actual Emacs windows.
395 @item outer-window-id
396 The number of the outermost window-system window used for the whole frame.
398 @item minibuffer
399 Whether this frame has its own minibuffer.  The value @code{t} means
400 yes, @code{nil} means no, @code{only} means this frame is just a
401 minibuffer.  If the value is a minibuffer window (in some other frame),
402 the new frame uses that minibuffer.
404 @item buffer-predicate
405 The buffer-predicate function for this frame.  The function
406 @code{other-buffer} uses this predicate (from the selected frame) to
407 decide which buffers it should consider, if the predicate is not
408 @code{nil}.  It calls the predicate with one argument, a buffer, once for
409 each buffer; if the predicate returns a non-@code{nil} value, it
410 considers that buffer.
412 @item buffer-list
413 A list of buffers that have been selected in this frame,
414 ordered most-recently-selected first.
416 @item font
417 The name of the font for displaying text in the frame.  This is a
418 string, either a valid font name for your system or the name of an Emacs
419 fontset (@pxref{Fontsets}).  Changing this frame parameter on a frame
420 also changes the font-related attributes of the default face on that
421 frame.
423 @item auto-raise
424 Whether selecting the frame raises it (non-@code{nil} means yes).
426 @item auto-lower
427 Whether deselecting the frame lowers it (non-@code{nil} means yes).
429 @item vertical-scroll-bars
430 Whether the frame has scroll bars for vertical scrolling, and which side
431 of the frame they should be on.  The possible values are @code{left},
432 @code{right}, and @code{nil} for no scroll bars.
434 @item horizontal-scroll-bars
435 Whether the frame has scroll bars for horizontal scrolling
436 (non-@code{nil} means yes).  (Horizontal scroll bars are not currently
437 implemented.)
439 @item scroll-bar-width
440 The width of the vertical scroll bar, in pixels.
442 @item icon-type
443 The type of icon to use for this frame when it is iconified.  If the
444 value is a string, that specifies a file containing a bitmap to use.
445 Any other non-@code{nil} value specifies the default bitmap icon (a
446 picture of a gnu); @code{nil} specifies a text icon.
448 @item icon-name
449 The name to use in the icon for this frame, when and if the icon
450 appears.  If this is @code{nil}, the frame's title is used.
452 @item foreground-color
453 The color to use for the image of a character.  This is a string; the
454 window system defines the meaningful color names.  Changing this
455 parameter is equivalent to changing the foreground color of the face
456 @code{default} on the frame in question.
458 @item background-color
459 The color to use for the background of characters.  Changing this
460 parameter is equivalent to changing the foreground color of the face
461 @code{default} on the frame in question.
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.
467 @item mouse-color
468 The color for the mouse pointer.  Changing this parameter is equivalent
469 to changing the background color of face @code{mouse}.
471 @item cursor-color
472 The color for the cursor that shows point. Changing this parameter is
473 equivalent to changing the background color of face @code{cursor}.
475 @item border-color
476 The color for the border of the frame. Changing this parameter is
477 equivalent to changing the background color of face @code{border}.
479 @item scroll-bar-foreground
480 If non-@code{nil}, the color for the foreground of scroll bars.
481 Changing this parameter is equivalent to setting the foreground color of
482 face @code{scroll-bar}.
484 @item scroll-bar-background
485 If non-@code{nil}, the color for the background of scroll bars.
486 Changing this parameter is equivalent to setting the foreground color of
487 face @code{scroll-bar}.
489 @item display-type
490 This parameter describes the range of possible colors that can be used
491 in this frame.  Its value is @code{color}, @code{grayscale} or
492 @code{mono}.
494 @item cursor-type
495 The way to display the cursor.  The legitimate values are @code{bar},
496 @code{box}, and @code{(bar . @var{width})}.  The symbol @code{box}
497 specifies an ordinary black box overlaying the character after point;
498 that is the default.  The symbol @code{bar} specifies a vertical bar
499 between characters as the cursor.  @code{(bar . @var{width})} specifies
500 a bar @var{width} pixels wide.
502 @item border-width
503 The width in pixels of the window border.
505 @item internal-border-width
506 The distance in pixels between text and border.
508 @item unsplittable
509 If non-@code{nil}, this frame's window is never split automatically.
511 @item visibility
512 The state of visibility of the frame.  There are three possibilities:
513 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
514 iconified.  @xref{Visibility of Frames}.
516 @item menu-bar-lines
517 The number of lines to allocate at the top of the frame for a menu bar.
518 The default is 1.  @xref{Menu Bar}.  (In Emacs versions that use the X
519 toolkit, there is only one menu bar line; all that matters about the
520 number you specify is whether it is greater than zero.)
522 @item screen-gamma
523 If this is a number, Emacs performs ``gamma correction'' on colors.  The
524 value should be the screen gamma of your display, a floating point
525 number.  Usual PC monitors have a screen gamma of 2.2, so the default is
526 to display for that gamma value.  Specifying a smaller value results in
527 darker colors, which is desirable for a monitor that tends to display
528 colors too light.  A screen gamma value of 1.5 may give good results for
529 LCD color displays.
531 @item tool-bar-lines
532 The number of lines to use for the toolbar.  A value of @code{nil} means
533 don't display a tool bar.
535 @ignore
536 @item parent-id
537 @c ??? Not yet working.
538 The X window number of the window that should be the parent of this one.
539 Specifying this lets you create an Emacs window inside some other
540 application's window.  (It is not certain this will be implemented; try
541 it and see if it works.)
542 @end ignore
543 @end table
545 @node Size and Position
546 @subsection Frame Size And Position
547 @cindex size of frame
548 @cindex screen size
549 @cindex frame size
550 @cindex resize frame
552   You can read or change the size and position of a frame using the
553 frame parameters @code{left}, @code{top}, @code{height}, and
554 @code{width}.  Whatever geometry parameters you don't specify are chosen
555 by the window manager in its usual fashion.
557   Here are some special features for working with sizes and positions:
559 @defun set-frame-position frame left top
560 This function sets the position of the top left corner of @var{frame} to
561 @var{left} and @var{top}.  These arguments are measured in pixels, and
562 normally count from the top left corner of the screen.
564 Negative parameter values position the bottom edge of the window up from
565 the bottom edge of the screen, or the right window edge to the left of
566 the right edge of the screen.  It would probably be better if the values
567 were always counted from the left and top, so that negative arguments
568 would position the frame partly off the top or left edge of the screen,
569 but it seems inadvisable to change that now.
570 @end defun
572 @defun frame-height &optional frame
573 @defunx frame-width &optional frame
574 These functions return the height and width of @var{frame}, measured in
575 lines and columns.  If you don't supply @var{frame}, they use the
576 selected frame.
577 @end defun
579 @defun screen-height
580 @defunx screen-width
581 These functions are old aliases for @code{frame-height} and
582 @code{frame-width}.  When you are using a non-window terminal, the size
583 of the frame is normally the same as the size of the terminal screen.
584 @end defun
586 @defun frame-pixel-height &optional frame
587 @defunx frame-pixel-width &optional frame
588 These functions return the height and width of @var{frame}, measured in
589 pixels.  If you don't supply @var{frame}, they use the selected frame.
590 @end defun
592 @defun frame-char-height &optional frame
593 @defunx frame-char-width &optional frame
594 These functions return the height and width of a character in
595 @var{frame}, measured in pixels.  The values depend on the choice of
596 font.  If you don't supply @var{frame}, these functions use the selected
597 frame.
598 @end defun
600 @defun set-frame-size frame cols rows
601 This function sets the size of @var{frame}, measured in characters;
602 @var{cols} and @var{rows} specify the new width and height.
604 To set the size based on values measured in pixels, use
605 @code{frame-char-height} and @code{frame-char-width} to convert
606 them to units of characters.
607 @end defun
609 @defun set-frame-height frame lines &optional pretend
610 This function resizes @var{frame} to a height of @var{lines} lines.  The
611 sizes of existing windows in @var{frame} are altered proportionally to
612 fit.
614 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
615 lines of output in @var{frame}, but does not change its value for the
616 actual height of the frame.  This is only useful for a terminal frame.
617 Using a smaller height than the terminal actually implements may be
618 useful to reproduce behavior observed on a smaller screen, or if the
619 terminal malfunctions when using its whole screen.  Setting the frame
620 height ``for real'' does not always work, because knowing the correct
621 actual size may be necessary for correct cursor positioning on a
622 terminal frame.
623 @end defun
625 @defun set-frame-width frame width &optional pretend
626 This function sets the width of @var{frame}, measured in characters.
627 The argument @var{pretend} has the same meaning as in
628 @code{set-frame-height}.
629 @end defun
631 @findex set-screen-height
632 @findex set-screen-width
633   The older functions @code{set-screen-height} and
634 @code{set-screen-width} were used to specify the height and width of the
635 screen, in Emacs versions that did not support multiple frames.  They
636 are semi-obsolete, but still work; they apply to the selected frame.
638 @defun x-parse-geometry geom
639 @cindex geometry specification
640 The function @code{x-parse-geometry} converts a standard X window
641 geometry string to an alist that you can use as part of the argument to
642 @code{make-frame}.
644 The alist describes which parameters were specified in @var{geom}, and
645 gives the values specified for them.  Each element looks like
646 @code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
647 values are @code{left}, @code{top}, @code{width}, and @code{height}.
649 For the size parameters, the value must be an integer.  The position
650 parameter names @code{left} and @code{top} are not totally accurate,
651 because some values indicate the position of the right or bottom edges
652 instead.  These are the @var{value} possibilities for the position
653 parameters:
655 @table @asis
656 @item an integer
657 A positive integer relates the left edge or top edge of the window to
658 the left or top edge of the screen.  A negative integer relates the
659 right or bottom edge of the window to the right or bottom edge of the
660 screen.
662 @item @code{(+ @var{position})}
663 This specifies the position of the left or top edge of the window
664 relative to the left or top edge of the screen.  The integer
665 @var{position} may be positive or negative; a negative value specifies a
666 position outside the screen.
668 @item @code{(- @var{position})}
669 This specifies the position of the right or bottom edge of the window
670 relative to the right or bottom edge of the screen.  The integer
671 @var{position} may be positive or negative; a negative value specifies a
672 position outside the screen.
673 @end table
675 Here is an example:
677 @example
678 (x-parse-geometry "35x70+0-0")
679      @result{} ((height . 70) (width . 35)
680          (top - 0) (left . 0))
681 @end example
682 @end defun
684 @node Frame Titles
685 @section Frame Titles
687   Every frame has a @code{name} parameter; this serves as the default
688 for the frame title which window systems typically display at the top of
689 the frame.  You can specify a name explicitly by setting the @code{name}
690 frame property.
692   Normally you don't specify the name explicitly, and Emacs computes the
693 frame name automatically based on a template stored in the variable
694 @code{frame-title-format}.  Emacs recomputes the name each time the
695 frame is redisplayed.
697 @defvar frame-title-format
698 This variable specifies how to compute a name for a frame when you have
699 not explicitly specified one.  The variable's value is actually a mode
700 line construct, just like @code{mode-line-format}.  @xref{Mode Line
701 Data}.
702 @end defvar
704 @defvar icon-title-format
705 This variable specifies how to compute the name for an iconified frame,
706 when you have not explicitly specified the frame title.  This title
707 appears in the icon itself.
708 @end defvar
710 @defvar multiple-frames
711 This variable is set automatically by Emacs.  Its value is @code{t} when
712 there are two or more frames (not counting minibuffer-only frames or
713 invisible frames).  The default value of @code{frame-title-format} uses
714 @code{multiple-frames} so as to put the buffer name in the frame title
715 only when there is more than one frame.
716 @end defvar
718 @node Deleting Frames
719 @section Deleting Frames
720 @cindex deletion of frames
722 Frames remain potentially visible until you explicitly @dfn{delete}
723 them.  A deleted frame cannot appear on the screen, but continues to
724 exist as a Lisp object until there are no references to it.  There is no
725 way to cancel the deletion of a frame aside from restoring a saved frame
726 configuration (@pxref{Frame Configurations}); this is similar to the
727 way windows behave.
729 @deffn Command delete-frame &optional frame force
730 This function deletes the frame @var{frame}.  By default, @var{frame} is
731 the selected frame.  
733 A frame cannot be deleted if its minibuffer is used by other frames.
734 Normally, you cannot delete a frame if all other frames are invisible,
735 but if the @var{force} is non-@code{nil}, then you are allowed to do so.
736 @end deffn
738 @defun frame-live-p frame
739 The function @code{frame-live-p} returns non-@code{nil} if the frame
740 @var{frame} has not been deleted.
741 @end defun
743   Some window managers provide a command to delete a window.  These work
744 by sending a special message to the program that operates the window.
745 When Emacs gets one of these commands, it generates a
746 @code{delete-frame} event, whose normal definition is a command that
747 calls the function @code{delete-frame}.  @xref{Misc Events}.
749 @node Finding All Frames
750 @section Finding All Frames
752 @defun frame-list
753 The function @code{frame-list} returns a list of all the frames that
754 have not been deleted.  It is analogous to @code{buffer-list} for
755 buffers.  The list that you get is newly created, so modifying the list
756 doesn't have any effect on the internals of Emacs.
757 @end defun
759 @defun visible-frame-list
760 This function returns a list of just the currently visible frames.
761 @xref{Visibility of Frames}.  (Terminal frames always count as
762 ``visible'', even though only the selected one is actually displayed.)
763 @end defun
765 @defun next-frame &optional frame minibuf
766 The function @code{next-frame} lets you cycle conveniently through all
767 the frames from an arbitrary starting point.  It returns the ``next''
768 frame after @var{frame} in the cycle.  If @var{frame} is omitted or
769 @code{nil}, it defaults to the selected frame.
771 The second argument, @var{minibuf}, says which frames to consider:
773 @table @asis
774 @item @code{nil}
775 Exclude minibuffer-only frames.
776 @item @code{visible}
777 Consider all visible frames.
778 @item 0
779 Consider all visible or iconified frames.
780 @item a window
781 Consider only the frames using that particular window as their
782 minibuffer.
783 @item anything else
784 Consider all frames.
785 @end table
786 @end defun
788 @defun previous-frame &optional frame minibuf
789 Like @code{next-frame}, but cycles through all frames in the opposite
790 direction.
791 @end defun
793   See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
794 Window Ordering}.
796 @node Frames and Windows
797 @section Frames and Windows
799   Each window is part of one and only one frame; you can get the frame
800 with @code{window-frame}.
802 @defun window-frame window
803 This function returns the frame that @var{window} is on.
804 @end defun
806   All the non-minibuffer windows in a frame are arranged in a cyclic
807 order.  The order runs from the frame's top window, which is at the
808 upper left corner, down and to the right, until it reaches the window at
809 the lower right corner (always the minibuffer window, if the frame has
810 one), and then it moves back to the top.  @xref{Cyclic Window Ordering}.
812 @defun frame-first-window frame
813 This returns the topmost, leftmost window of frame @var{frame}.
814 @end defun
816 At any time, exactly one window on any frame is @dfn{selected within the
817 frame}.  The significance of this designation is that selecting the
818 frame also selects this window.  You can get the frame's current
819 selected window with @code{frame-selected-window}.
821 @defun frame-selected-window frame
822 This function returns the window on @var{frame} that is selected within
823 @var{frame}.
824 @end defun
826   Conversely, selecting a window for Emacs with @code{select-window} also
827 makes that window selected within its frame.  @xref{Selecting Windows}.
829   Another function that (usually) returns one of the windows in a given
830 frame is @code{minibuffer-window}.  @xref{Minibuffer Misc}.
832 @node Minibuffers and Frames
833 @section Minibuffers and Frames
835 Normally, each frame has its own minibuffer window at the bottom, which
836 is used whenever that frame is selected.  If the frame has a minibuffer,
837 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
839 However, you can also create a frame with no minibuffer.  Such a frame
840 must use the minibuffer window of some other frame.  When you create the
841 frame, you can specify explicitly the minibuffer window to use (in some
842 other frame).  If you don't, then the minibuffer is found in the frame
843 which is the value of the variable @code{default-minibuffer-frame}.  Its
844 value should be a frame that does have a minibuffer.
846 If you use a minibuffer-only frame, you might want that frame to raise
847 when you enter the minibuffer.  If so, set the variable
848 @code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.
850 @defvar default-minibuffer-frame
851 This variable specifies the frame to use for the minibuffer window, by
852 default.  It is always local to the current terminal and cannot be
853 buffer-local.  @xref{Multiple Displays}.
854 @end defvar
856 @node Input Focus
857 @section Input Focus
858 @cindex input focus
859 @cindex selected frame
861 At any time, one frame in Emacs is the @dfn{selected frame}.  The selected
862 window always resides on the selected frame.
864 @defun selected-frame
865 This function returns the selected frame.
866 @end defun
868 Some window systems and window managers direct keyboard input to the
869 window object that the mouse is in; others require explicit clicks or
870 commands to @dfn{shift the focus} to various window objects.  Either
871 way, Emacs automatically keeps track of which frame has the focus.
873 Lisp programs can also switch frames ``temporarily'' by calling the
874 function @code{select-frame}.  This does not alter the window system's
875 concept of focus; rather, it escapes from the window manager's control
876 until that control is somehow reasserted.
878 When using a text-only terminal, only the selected terminal frame is
879 actually displayed on the terminal.  @code{switch-frame} is the only way
880 to switch frames, and the change lasts until overridden by a subsequent
881 call to @code{switch-frame}.  Each terminal screen except for the
882 initial one has a number, and the number of the selected frame appears
883 in the mode line before the buffer name (@pxref{Mode Line Variables}).
885 @c ??? This is not yet implemented properly.
886 @defun select-frame frame
887 This function selects frame @var{frame}, temporarily disregarding the
888 focus of the X server if any.  The selection of @var{frame} lasts until
889 the next time the user does something to select a different frame, or
890 until the next time this function is called.
891 @end defun
893 Emacs cooperates with the window system by arranging to select frames as
894 the server and window manager request.  It does so by generating a
895 special kind of input event, called a @dfn{focus} event, when
896 appropriate.  The command loop handles a focus event by calling
897 @code{handle-switch-frame}.  @xref{Focus Events}.
899 @deffn Command handle-switch-frame frame
900 This function handles a focus event by selecting frame @var{frame}.
902 Focus events normally do their job by invoking this command.
903 Don't call it for any other reason.
904 @end deffn
906 @defun redirect-frame-focus frame focus-frame
907 This function redirects focus from @var{frame} to @var{focus-frame}.
908 This means that @var{focus-frame} will receive subsequent keystrokes and
909 events intended for @var{frame}.  After such an event, the value of
910 @code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
911 events specifying @var{frame} will instead select @var{focus-frame}.
913 If @var{focus-frame} is @code{nil}, that cancels any existing
914 redirection for @var{frame}, which therefore once again receives its own
915 events.
917 One use of focus redirection is for frames that don't have minibuffers.
918 These frames use minibuffers on other frames.  Activating a minibuffer
919 on another frame redirects focus to that frame.  This puts the focus on
920 the minibuffer's frame, where it belongs, even though the mouse remains
921 in the frame that activated the minibuffer.
923 Selecting a frame can also change focus redirections.  Selecting frame
924 @code{bar}, when @code{foo} had been selected, changes any redirections
925 pointing to @code{foo} so that they point to @code{bar} instead.  This
926 allows focus redirection to work properly when the user switches from
927 one frame to another using @code{select-window}.
929 This means that a frame whose focus is redirected to itself is treated
930 differently from a frame whose focus is not redirected.
931 @code{select-frame} affects the former but not the latter.
933 The redirection lasts until @code{redirect-frame-focus} is called to
934 change it.
935 @end defun
937 @defopt focus-follows-mouse
938 This option is how you inform Emacs whether the window manager transfers
939 focus when the user moves the mouse.  Non-@code{nil} says that it does.
940 When this is so, the command @code{other-frame} moves the mouse to a
941 position consistent with the new selected frame.
942 @end defopt
944 @node Visibility of Frames
945 @section Visibility of Frames
946 @cindex visible frame
947 @cindex invisible frame
948 @cindex iconified frame
949 @cindex frame visibility
951 A window frame may be @dfn{visible}, @dfn{invisible}, or
952 @dfn{iconified}.  If it is visible, you can see its contents.  If it is
953 iconified, the frame's contents do not appear on the screen, but an icon
954 does.  If the frame is invisible, it doesn't show on the screen, not
955 even as an icon.
957 Visibility is meaningless for terminal frames, since only the selected
958 one is actually displayed in any case.
960 @deffn Command make-frame-visible &optional frame
961 This function makes frame @var{frame} visible.  If you omit @var{frame},
962 it makes the selected frame visible.
963 @end deffn
965 @deffn Command make-frame-invisible &optional frame
966 This function makes frame @var{frame} invisible.  If you omit
967 @var{frame}, it makes the selected frame invisible.
968 @end deffn
970 @deffn Command iconify-frame &optional frame
971 This function iconifies frame @var{frame}.  If you omit @var{frame}, it
972 iconifies the selected frame.
973 @end deffn
975 @defun frame-visible-p frame
976 This returns the visibility status of frame @var{frame}.  The value is
977 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
978 @code{icon} if it is iconified.
979 @end defun
981   The visibility status of a frame is also available as a frame
982 parameter.  You can read or change it as such.  @xref{Window Frame
983 Parameters}.
985   The user can iconify and deiconify frames with the window manager.
986 This happens below the level at which Emacs can exert any control, but
987 Emacs does provide events that you can use to keep track of such
988 changes.  @xref{Misc Events}.
990 @node Raising and Lowering
991 @section Raising and Lowering Frames
993   Most window systems use a desktop metaphor.  Part of this metaphor is
994 the idea that windows are stacked in a notional third dimension
995 perpendicular to the screen surface, and thus ordered from ``highest''
996 to ``lowest''.  Where two windows overlap, the one higher up covers
997 the one underneath.  Even a window at the bottom of the stack can be
998 seen if no other window overlaps it.
1000 @cindex raising a frame
1001 @cindex lowering a frame
1002   A window's place in this ordering is not fixed; in fact, users tend
1003 to change the order frequently.  @dfn{Raising} a window means moving
1004 it ``up'', to the top of the stack.  @dfn{Lowering} a window means
1005 moving it to the bottom of the stack.  This motion is in the notional
1006 third dimension only, and does not change the position of the window
1007 on the screen.
1009   You can raise and lower Emacs frame Windows with these functions:
1011 @deffn Command raise-frame &optional frame
1012 This function raises frame @var{frame} (default, the selected frame).
1013 @end deffn
1015 @deffn Command lower-frame &optional frame
1016 This function lowers frame @var{frame} (default, the selected frame).
1017 @end deffn
1019 @defopt minibuffer-auto-raise
1020 If this is non-@code{nil}, activation of the minibuffer raises the frame
1021 that the minibuffer window is in.
1022 @end defopt
1024 You can also enable auto-raise (raising automatically when a frame is
1025 selected) or auto-lower (lowering automatically when it is deselected)
1026 for any frame using frame parameters.  @xref{Window Frame Parameters}.
1028 @node Frame Configurations
1029 @section Frame Configurations
1030 @cindex frame configuration
1032   A @dfn{frame configuration} records the current arrangement of frames,
1033 all their properties, and the window configuration of each one.
1034 (@xref{Window Configurations}.)
1036 @defun current-frame-configuration
1037 This function returns a frame configuration list that describes
1038 the current arrangement of frames and their contents.
1039 @end defun
1041 @defun set-frame-configuration configuration &optional nodelete
1042 This function restores the state of frames described in
1043 @var{configuration}.
1045 Ordinarily, this function deletes all existing frames not listed in
1046 @var{configuration}.  But if @var{nodelete} is non-@code{nil}, the
1047 unwanted frames are iconified instead.
1048 @end defun
1050 @node Mouse Tracking
1051 @section Mouse Tracking
1052 @cindex mouse tracking
1053 @cindex tracking the mouse
1055 Sometimes it is useful to @dfn{track} the mouse, which means to display
1056 something to indicate where the mouse is and move the indicator as the
1057 mouse moves.  For efficient mouse tracking, you need a way to wait until
1058 the mouse actually moves.
1060 The convenient way to track the mouse is to ask for events to represent
1061 mouse motion.  Then you can wait for motion by waiting for an event.  In
1062 addition, you can easily handle any other sorts of events that may
1063 occur.  That is useful, because normally you don't want to track the
1064 mouse forever---only until some other event, such as the release of a
1065 button.
1067 @defspec track-mouse body@dots{}
1068 This special form executes @var{body}, with generation of mouse motion
1069 events enabled.  Typically @var{body} would use @code{read-event} to
1070 read the motion events and modify the display accordingly.  @xref{Motion
1071 Events}, for the format of mouse motion events.
1073 The value of @code{track-mouse} is that of the last form in @var{body}.
1074 You should design @var{body} to return when it sees the up-event that
1075 indicates the release of the button, or whatever kind of event means
1076 it is time to stop tracking.
1077 @end defspec
1079 The usual purpose of tracking mouse motion is to indicate on the screen
1080 the consequences of pushing or releasing a button at the current
1081 position.
1083 In many cases, you can avoid the need to track the mouse by using
1084 the @code{mouse-face} text property (@pxref{Special Properties}).
1085 That works at a much lower level and runs more smoothly than
1086 Lisp-level mouse tracking.
1088 @ignore
1089 @c These are not implemented yet.
1091 These functions change the screen appearance instantaneously.  The
1092 effect is transient, only until the next ordinary Emacs redisplay.  That
1093 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1094 to change the text, and the body of @code{track-mouse} normally reads
1095 the events itself and does not do redisplay.
1097 @defun x-contour-region window beg end
1098 This function draws lines to make a box around the text from @var{beg}
1099 to @var{end}, in window @var{window}.
1100 @end defun
1102 @defun x-uncontour-region window beg end
1103 This function erases the lines that would make a box around the text
1104 from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
1105 a contour that you previously made by calling @code{x-contour-region}.
1106 @end defun
1108 @defun x-draw-rectangle frame left top right bottom
1109 This function draws a hollow rectangle on frame @var{frame} with the
1110 specified edge coordinates, all measured in pixels from the inside top
1111 left corner.  It uses the cursor color, the one used for indicating the
1112 location of point.
1113 @end defun
1115 @defun x-erase-rectangle frame left top right bottom
1116 This function erases a hollow rectangle on frame @var{frame} with the
1117 specified edge coordinates, all measured in pixels from the inside top
1118 left corner.  Erasure means redrawing the text and background that
1119 normally belong in the specified rectangle.
1120 @end defun
1121 @end ignore
1123 @node Mouse Position
1124 @section Mouse Position
1125 @cindex mouse position
1126 @cindex position of mouse
1128   The functions @code{mouse-position} and @code{set-mouse-position}
1129 give access to the current position of the mouse.
1131 @defun mouse-position
1132 This function returns a description of the position of the mouse.  The
1133 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1134 and @var{y} are integers giving the position in characters relative to
1135 the top left corner of the inside of @var{frame}.
1136 @end defun
1138 @defun set-mouse-position frame x y
1139 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1140 frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
1141 giving the position in characters relative to the top left corner of the
1142 inside of @var{frame}.  If @var{frame} is not visible, this function
1143 does nothing.  The return value is not significant.
1144 @end defun
1146 @defun mouse-pixel-position
1147 This function is like @code{mouse-position} except that it returns
1148 coordinates in units of pixels rather than units of characters.
1149 @end defun
1151 @defun set-mouse-pixel-position frame x y
1152 This function warps the mouse like @code{set-mouse-position} except that
1153 @var{x} and @var{y} are in units of pixels rather than units of
1154 characters.  These coordinates are not required to be within the frame.
1156 If @var{frame} is not visible, this function does nothing.  The return
1157 value is not significant.
1158 @end defun
1160 @need 3000
1162 @node Pop-Up Menus
1163 @section Pop-Up Menus
1165   When using a window system, a Lisp program can pop up a menu so that
1166 the user can choose an alternative with the mouse.
1168 @defun x-popup-menu position menu
1169 This function displays a pop-up menu and returns an indication of
1170 what selection the user makes.
1172 The argument @var{position} specifies where on the screen to put the
1173 menu.  It can be either a mouse button event (which says to put the menu
1174 where the user actuated the button) or a list of this form:
1176 @example
1177 ((@var{xoffset} @var{yoffset}) @var{window})
1178 @end example
1180 @noindent
1181 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1182 pixels, counting from the top left corner of @var{window}'s frame.
1184 If @var{position} is @code{t}, it means to use the current mouse
1185 position.  If @var{position} is @code{nil}, it means to precompute the
1186 key binding equivalents for the keymaps specified in @var{menu},
1187 without actually displaying or popping up the menu.
1189 The argument @var{menu} says what to display in the menu.  It can be a
1190 keymap or a list of keymaps (@pxref{Menu Keymaps}).  Alternatively, it
1191 can have the following form:
1193 @example
1194 (@var{title} @var{pane1} @var{pane2}...)
1195 @end example
1197 @noindent
1198 where each pane is a list of form
1200 @example
1201 (@var{title} (@var{line} . @var{item})...)
1202 @end example
1204 Each @var{line} should be a string, and each @var{item} should be the
1205 value to return if that @var{line} is chosen.
1206 @end defun
1208   @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1209 if you could do the job with a prefix key defined with a menu keymap.
1210 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1211 a} can see the individual items in that menu and provide help for them.
1212 If instead you implement the menu by defining a command that calls
1213 @code{x-popup-menu}, the help facilities cannot know what happens inside
1214 that command, so they cannot give any help for the menu's items.
1216   The menu bar mechanism, which lets you switch between submenus by
1217 moving the mouse, cannot look within the definition of a command to see
1218 that it calls @code{x-popup-menu}.  Therefore, if you try to implement a
1219 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1220 an integrated fashion.  This is why all menu bar submenus are
1221 implemented with menu keymaps within the parent menu, and never with
1222 @code{x-popup-menu}.  @xref{Menu Bar},
1224   If you want a menu bar submenu to have contents that vary, you should
1225 still use a menu keymap to implement it.  To make the contents vary, add
1226 a hook function to @code{menu-bar-update-hook} to update the contents of
1227 the menu keymap as necessary.
1229 @node Dialog Boxes
1230 @section Dialog Boxes
1231 @cindex dialog boxes
1233   A dialog box is a variant of a pop-up menu---it looks a little
1234 different, it always appears in the center of a frame, and it has just
1235 one level and one pane.  The main use of dialog boxes is for asking
1236 questions that the user can answer with ``yes'', ``no'', and a few other
1237 alternatives.  The functions @code{y-or-n-p} and @code{yes-or-no-p} use
1238 dialog boxes instead of the keyboard, when called from commands invoked
1239 by mouse clicks.
1241 @defun x-popup-dialog position contents
1242 This function displays a pop-up dialog box and returns an indication of
1243 what selection the user makes.  The argument @var{contents} specifies
1244 the alternatives to offer; it has this format:
1246 @example
1247 (@var{title} (@var{string} . @var{value})@dots{})
1248 @end example
1250 @noindent
1251 which looks like the list that specifies a single pane for
1252 @code{x-popup-menu}.
1254 The return value is @var{value} from the chosen alternative.
1256 An element of the list may be just a string instead of a cons cell
1257 @code{(@var{string} . @var{value})}.  That makes a box that cannot
1258 be selected.
1260 If @code{nil} appears in the list, it separates the left-hand items from
1261 the right-hand items; items that precede the @code{nil} appear on the
1262 left, and items that follow the @code{nil} appear on the right.  If you
1263 don't include a @code{nil} in the list, then approximately half the
1264 items appear on each side.
1266 Dialog boxes always appear in the center of a frame; the argument
1267 @var{position} specifies which frame.  The possible values are as in
1268 @code{x-popup-menu}, but the precise coordinates don't matter; only the
1269 frame matters.
1271 In some configurations, Emacs cannot display a real dialog box; so
1272 instead it displays the same items in a pop-up menu in the center of the
1273 frame.
1274 @end defun
1276 @node Pointer Shapes
1277 @section Pointer Shapes
1278 @cindex pointer shape
1279 @cindex mouse pointer shape
1281   These variables specify which shape to use for the mouse pointer in
1282 various situations, when using the X Window System:
1284 @table @code
1285 @item x-pointer-shape
1286 @vindex x-pointer-shape
1287 This variable specifies the pointer shape to use ordinarily in the Emacs
1288 frame.
1290 @item x-sensitive-text-pointer-shape
1291 @vindex x-sensitive-text-pointer-shape
1292 This variable specifies the pointer shape to use when the mouse
1293 is over mouse-sensitive text.
1294 @end table
1296   These variables affect newly created frames.  They do not normally
1297 affect existing frames; however, if you set the mouse color of a frame,
1298 that also updates its pointer shapes based on the current values of
1299 these variables.  @xref{Window Frame Parameters}.
1301   The values you can use, to specify either of these pointer shapes, are
1302 defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
1303 @key{RET} x-pointer @key{RET}} to see a list of them.
1305 @node Window System Selections
1306 @section Window System Selections
1307 @cindex selection (for X windows)
1309 The X server records a set of @dfn{selections} which permit transfer of
1310 data between application programs.  The various selections are
1311 distinguished by @dfn{selection types}, represented in Emacs by
1312 symbols.  X clients including Emacs can read or set the selection for
1313 any given type.
1315 @defun x-set-selection type data
1316 This function sets a ``selection'' in the X server.  It takes two
1317 arguments: a selection type @var{type}, and the value to assign to it,
1318 @var{data}.  If @var{data} is @code{nil}, it means to clear out the
1319 selection.  Otherwise, @var{data} may be a string, a symbol, an integer
1320 (or a cons of two integers or list of two integers), an overlay, or a
1321 cons of two markers pointing to the same buffer.  An overlay or a pair
1322 of markers stands for text in the overlay or between the markers.
1324 The argument @var{data} may also be a vector of valid non-vector
1325 selection values.
1327 Each possible @var{type} has its own selection value, which changes
1328 independently.  The usual values of @var{type} are @code{PRIMARY} and
1329 @code{SECONDARY}; these are symbols with upper-case names, in accord
1330 with X Window System conventions.  The default is @code{PRIMARY}.
1331 @end defun
1333 @defun x-get-selection &optional type data-type
1334 This function accesses selections set up by Emacs or by other X
1335 clients.  It takes two optional arguments, @var{type} and
1336 @var{data-type}.  The default for @var{type}, the selection type, is
1337 @code{PRIMARY}.
1339 The @var{data-type} argument specifies the form of data conversion to
1340 use, to convert the raw data obtained from another X client into Lisp
1341 data.  Meaningful values include @code{TEXT}, @code{STRING},
1342 @code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
1343 @code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
1344 @code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
1345 @code{NAME}, @code{ATOM}, and @code{INTEGER}.  (These are symbols with
1346 upper-case names in accord with X conventions.)  The default for
1347 @var{data-type} is @code{STRING}.
1348 @end defun
1350 @cindex cut buffer
1351 The X server also has a set of numbered @dfn{cut buffers} which can
1352 store text or other data being moved between applications.  Cut buffers
1353 are considered obsolete, but Emacs supports them for the sake of X
1354 clients that still use them.
1356 @defun x-get-cut-buffer n
1357 This function returns the contents of cut buffer number @var{n}.
1358 @end defun
1360 @defun x-set-cut-buffer string &optional push
1361 This function stores @var{string} into the first cut buffer (cut buffer
1362 0).  If @var{push} is @code{nil}, only the first cut buffer is changed.
1363 If @var{push} is non-@code{nil}, that says to move the values down
1364 through the series of cut buffers, much like the way successive kills in
1365 Emacs move down the kill ring.  In other words, the previous value of
1366 the first cut buffer moves into the second cut buffer, and the second to
1367 the third, and so on through all eight cut buffers.
1368 @end defun
1370 @defvar selection-coding-system
1371 This variable specifies the coding system to use when reading and
1372 writing selections, the clipboard, or a cut buffer.  @xref{Coding
1373 Systems}.  The default is @code{compound-text}, which converts to
1374 the text representation that X11 normally uses.
1375 @end defvar
1377 @cindex clipboard support (for MS-Windows)
1378 When Emacs runs on MS-Windows, it does not implement X selections in
1379 general, but it it does support the clipboard.  @code{x-get-selection}
1380 and @code{x-set-selection} on MS-Windows support the text data type
1381 only; if the clipboard holds other types of data, Emacs treats the
1382 clipboard as empty.
1384 @defopt x-select-enable-clipboard
1385 If this is non-@code{nil}, the Emacs yank functions consult the
1386 clipboard before the primary selection, and the kill functions store in
1387 the clipboard as well as the primary selection.  Otherwise they do not
1388 access the clipboard at all.  The default is @code{nil} on most systems,
1389 but @code{t} on MS-Windows.
1390 @end defopt
1392 @node Color Names
1393 @section Color Names
1395   These functions provide a way to determine which color names are
1396 valid, and what they look like.
1398 @defun color-defined-p color &optional frame
1399 @tindex color-defined-p
1400 This function reports whether a color name is meaningful.  It returns
1401 @code{t} if so; otherwise, @code{nil}.  The argument @var{frame} says
1402 which frame's display to ask about; if @var{frame} is omitted or
1403 @code{nil}, the selected frame is used.
1405 Note that this does not tell you whether the display you are using
1406 really supports that color.  When using X, you can ask for any defined
1407 color on any kind of display, and you will get some result---typically,
1408 the closest it can do.  To determine whether a frame can really display
1409 a certain color, use @code{color-supported-p} (see below).
1411 @findex x-color-defined-p
1412 This function used to be called @code{x-color-defined-p},
1413 and that name is still supported as an alias.
1414 @end defun
1416 @defun defined-colors &optional frame
1417 @tindex defined-colors
1418 This function returns a list of the color names that are defined
1419 and supported on frame @var{frame} (default, the selected frame).
1421 @findex x-defined-colors
1422 This function used to be called @code{x-defined-colors},
1423 and that name is still supported as an alias.
1424 @end defun
1426 @defun color-supported-p color &optional frame background-p
1427 @tindex color-supported-p
1428 This returns @code{t} if @var{frame} can really display the color
1429 @var{color} (or at least something close to it).  If @var{frame} is
1430 omitted or @code{nil}, the question applies to the selected frame.
1432 Some terminals support a different set of colors for foreground and
1433 background.  If @var{background-p} is non-@code{nil}, that means you are
1434 asking whether @var{color} can be used as a background; otherwise you
1435 are asking whether it can be used as a foreground.
1437 The argument @var{color} must be a valid color name.
1438 @end defun
1440 @defun color-gray-p color &optional frame
1441 @tindex color-gray-p
1442 This returns @code{t} if @var{color} is a shade of gray, as defined on
1443 @var{frame}'s display.  If @var{frame} is omitted or @code{nil}, the
1444 question applies to the selected frame.  The argument @var{color} must
1445 be a valid color name.
1446 @end defun
1448 @defun color-values color &optional frame
1449 @tindex color-values
1450 This function returns a value that describes what @var{color} should
1451 ideally look like.  If @var{color} is defined, the value is a list of
1452 three integers, which give the amount of red, the amount of green, and
1453 the amount of blue.  Each integer ranges in principle from 0 to 65535,
1454 but in practice no value seems to be above 65280.  This kind
1455 of three-element list is called an @dfn{rgb value}.
1457 If @var{color} is not defined, the value is @code{nil}.
1459 @example
1460 (color-values "black")
1461      @result{} (0 0 0)
1462 (color-values "white")
1463      @result{} (65280 65280 65280)
1464 (color-values "red")
1465      @result{} (65280 0 0)
1466 (color-values "pink")
1467      @result{} (65280 49152 51968)
1468 (color-values "hungry")
1469      @result{} nil
1470 @end example
1472 The color values are returned for @var{frame}'s display.  If @var{frame}
1473 is omitted or @code{nil}, the information is returned for the selected
1474 frame's display.
1476 @findex x-color-values
1477 This function used to be called @code{x-color-values},
1478 and that name is still supported as an alias.
1479 @end defun
1481 @node Text Terminal Colors
1482 @section Text Terminal Colors
1483 @cindex colors on text-only terminals
1485   Emacs can display color on text-only terminals, starting with version
1486 21.  These terminals support only a small number of colors, and the
1487 computer uses small integers to select colors on the terminal.  This
1488 means that the computer cannot reliably tell what the selected color
1489 looks like; instead, you have to inform your application which small
1490 integers correspond to which colors.  However, Emacs does know the
1491 standard set of colors and will try to use them automatically.
1493 @cindex rgb value
1494   Several of these functions use or return @dfn{rgb values}.  An rgb
1495 value is a list of three integers, which give the amount of red, the
1496 amount of green, and the amount of blue.  Each integer ranges in
1497 principle from 0 to 65535, but in practice the largest value used is
1498 65280.
1500   These functions accept a display (either a frame or the name of a
1501 terminal) as an optional argument.  We hope in the future to make Emacs
1502 support more than one text-only terminal at one time; then this argument
1503 will specify which terminal to operate on (the default being the
1504 selected frame's terminal).  At present, though, the @var{display}
1505 argument has no effect.
1507 @defun tty-color-define name number &optional rgb display
1508 @tindex tty-color-define
1509 This function associates the color name @var{name} with
1510 color number @var{number} on the terminal.
1512 The optional argument @var{rgb}, if specified, is an rgb value; it says
1513 what the color actually looks like.  If you do not specify @var{rgb},
1514 then this color cannot be used by @code{tty-color-approximate} to
1515 approximate other colors, because Emacs does not know what it looks
1516 like.
1517 @end defun
1519 @defun tty-color-clear &optional display
1520 @tindex tty-color-clear
1521 This function clears the table of defined colors for a text-only terminal.
1522 @end defun
1524 @defun tty-color-alist &optional display
1525 @tindex tty-color-alist
1526 This function returns an alist recording the known colors supported by a
1527 text-only terminal.
1529 Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
1530 or @code{(@var{name} @var{number})}.  Here, @var{name} is the color
1531 name, @var{number} is the number used to specify it to the terminal.
1532 If present, @var{rgb} is an rgb value that says what the color
1533 actually looks like.
1534 @end defun
1536 @defun tty-color-approximate rgb &optional display
1537 @tindex tty-color-approximate
1538 This function finds the closest color, among the known colors supported
1539 for @var{display}, to that described by the rgb value @var{rgb}.
1540 @end defun
1542 @defun tty-color-translate color &optional display
1543 @tindex tty-color-translate
1544 This function finds the closest color to @var{color} among the known
1545 colors supported for @var{display}.  If the name @var{color} is not
1546 defined, the value is @code{nil}.
1548 @var{color} can be an X-style @code{"#@var{xxxyyyzzz}"} specification
1549 instead of an actual name.  The format
1550 @code{"RGB:@var{xx}/@var{yy}/@var{zz}"} is also supported.
1551 @end defun
1553 @node Resources
1554 @section X Resources
1556 @defun x-get-resource attribute class &optional component subclass
1557 The function @code{x-get-resource} retrieves a resource value from the X
1558 Windows defaults database.
1560 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
1561 This function searches using a key of the form
1562 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
1563 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
1564 the class.
1566 The optional arguments @var{component} and @var{subclass} add to the key
1567 and the class, respectively.  You must specify both of them or neither.
1568 If you specify them, the key is
1569 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
1570 @samp{Emacs.@var{class}.@var{subclass}}.
1571 @end defun
1573 @defvar x-resource-class
1574 This variable specifies the application name that @code{x-get-resource}
1575 should look up.  The default value is @code{"Emacs"}.  You can examine X
1576 resources for application names other than ``Emacs'' by binding this
1577 variable to some other string, around a call to @code{x-get-resource}.
1578 @end defvar
1580   @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
1582 @node Display Feature Testing
1583 @section Display Feature Testing
1584 @cindex display feature testing
1586   The functions in this section describe the basic capabilities of a
1587 particular display.  Lisp programs can use them to adapt their behavior
1588 to what the display can do.  For example, a program that ordinarly uses
1589 a popup menu could use the minibuffer if popup menus are not supported.
1591   The optional argument @var{display} in these functions specifies which
1592 display to ask the question about.  It can be a display name, a frame
1593 (which designates the display that frame is on), or @code{nil} (which
1594 refers to the selected frame's display).
1596   @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
1597 obtain information about displays.
1599 @defun display-popup-menus-p &optional display
1600 @tindex display-popup-menus-p
1601 This function returns @code{t} if popup menus are supported on
1602 @var{display}, @code{nil} if not.  Support for popup menus requires that
1603 the mouse be available, since the user cannot choose menu items without
1604 a mouse.
1605 @end defun
1607 @defun display-graphic-p &optional display
1608 @tindex display-graphic-p
1609 @cindex frames, more than one on display
1610 @cindex fonts, more than one on display
1611 This function returns @code{t} if @var{display} is a graphic display
1612 capable of displaying several frames and several different fonts at
1613 once.  This is true for displays that use a window system such as X, and
1614 false for text-only terminals.
1615 @end defun
1617 @defun display-mouse-p &optional display
1618 @tindex display-mouse-p
1619 @cindex mouse, availability
1620 This function returns @code{t} if @var{display} has a mouse available,
1621 @code{nil} if not.
1622 @end defun
1624 @defun display-color-p &optional display
1625 @tindex display-color-p
1626 @findex x-display-color-p
1627 This function returns @code{t} if the screen is a color screen.
1628 It used to be called @code{x-display-color-p}, and that name
1629 is still supported as an alias.
1630 @end defun
1632 @defun display-grayscale-p &optional display
1633 @tindex display-grayscale-p
1634 This function returns @code{t} if the screen can display shades of gray.
1635 (All color displays can do this.)
1636 @end defun
1638 @defun display-selections-p &optional display
1639 @tindex display-selections-p
1640 This function returns @code{t} if @var{display} supports selections.
1641 Windowed displays normally support selections, but they may also be
1642 supported in some other cases.
1643 @end defun
1645 @defun display-screens &optional display
1646 @tindex display-screens
1647 This function returns the number of screens associated with the display.
1648 @end defun
1650 @defun display-pixel-height &optional display
1651 @tindex display-pixel-height
1652 This function returns the height of the screen in pixels.
1653 @end defun
1655 @defun display-mm-height &optional display
1656 @tindex display-mm-height
1657 This function returns the height of the screen in millimeters,
1658 or @code{nil} if Emacs cannot get that information.
1659 @end defun
1661 @defun display-pixel-width &optional display
1662 @tindex display-pixel-width
1663 This function returns the width of the screen in pixels.
1664 @end defun
1666 @defun display-mm-width &optional display
1667 @tindex display-mm-width
1668 This function returns the width of the screen in millimeters,
1669 or @code{nil} if Emacs cannot get that information.
1670 @end defun
1672 @defun display-backing-store &optional display
1673 @tindex display-backing-store
1674 This function returns the backing store capability of the display.
1675 Backing store means recording the pixels of windows (and parts of
1676 windows) that are not exposed, so that when exposed they can be
1677 displayed very quickly.
1679 Values can be the symbols @code{always}, @code{when-mapped}, or
1680 @code{not-useful}.  The function can also return @code{nil}
1681 when the question is inapplicable to a certain kind of display.
1682 @end defun
1684 @defun display-save-under &optional display
1685 @tindex display-save-under
1686 This function returns non-@code{nil} if the display supports the
1687 SaveUnder feature.  That feature is used by pop-up windows
1688 to save the pixels they obscure, so that they can pop down
1689 quickly.
1690 @end defun
1692 @defun display-planes &optional display
1693 @tindex display-planes
1694 This function returns the number of planes the display supports.
1695 This is typically the number of bits per pixel.
1696 @end defun
1698 @defun display-visual-class &optional display
1699 @tindex display-visual-class
1700 This function returns the visual class for the screen.  The value is one
1701 of the symbols @code{static-gray}, @code{gray-scale},
1702 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
1703 @code{direct-color}.
1704 @end defun
1706 @defun display-color-cells &optional display
1707 @tindex display-color-cells
1708 This function returns the number of color cells the screen supports.
1709 @end defun
1711   These functions obtain additional information specifically
1712 about X displays.
1714 @defun x-server-version &optional display
1715 This function returns the list of version numbers of the X server
1716 running the display.
1717 @end defun
1719 @defun x-server-vendor &optional display
1720 This function returns the vendor that provided the X server software.
1721 @end defun
1723 @ignore
1724 @defvar x-no-window-manager
1725 This variable's value is @code{t} if no X window manager is in use.
1726 @end defvar
1727 @end ignore
1729 @ignore
1730 @item
1731 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
1732 width and height of an X Window frame, measured in pixels.
1733 @end ignore