2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/frames
6 @node Frames, Positions, Windows, Top
10 A @dfn{frame} is a rectangle on the screen that contains one or more
11 Emacs windows. A frame initially contains a single main window (plus
12 perhaps a minibuffer window), which you can subdivide vertically or
13 horizontally into smaller windows.
15 @cindex terminal frame
16 When Emacs runs on a text-only terminal, it starts with one
17 @dfn{terminal frame}. If you create additional ones, Emacs displays
18 one and only one at any given time---on the terminal screen, of course.
21 When Emacs communicates directly with a supported window system, such
22 as X Windows, it does not have a terminal frame; instead, it starts with
23 a single @dfn{window frame}, but you can create more, and Emacs can
24 display several such frames at once as is usual for window systems.
27 This predicate returns @code{t} if @var{object} is a frame, and
32 * Creating Frames:: Creating additional frames.
33 * Multiple Displays:: Creating frames on other displays.
34 * Frame Parameters:: Controlling frame size, position, font, etc.
35 * Frame Titles:: Automatic updating of frame titles.
36 * Deleting Frames:: Frames last until explicitly deleted.
37 * Finding All Frames:: How to examine all existing frames.
38 * Frames and Windows:: A frame contains windows;
39 display of text always works through windows.
40 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
41 * Input Focus:: Specifying the selected frame.
42 * Visibility of Frames:: Frames may be visible or invisible, or icons.
43 * Raising and Lowering:: Raising a frame makes it hide other windows;
44 lowering it makes the others hide them.
45 * Frame Configurations:: Saving the state of all frames.
46 * Mouse Tracking:: Getting events that say when the mouse moves.
47 * Mouse Position:: Asking where the mouse is, or moving it.
48 * Pop-Up Menus:: Displaying a menu for the user to select from.
49 * Dialog Boxes:: Displaying a box to ask yes or no.
50 * Pointer Shapes:: Specifying the shape of the mouse pointer.
51 * Window System Selections:: Transferring text to and from other X clients.
52 * Font Names:: Looking up font names.
53 * Fontsets:: A fontset is a collection of fonts
54 for displaying various character sets.
55 * Color Names:: Getting the definitions of color names.
56 * Resources:: Getting resource values from the server.
57 * Server Data:: Getting info about the X server.
60 @xref{Display}, for information about the related topic of
61 controlling Emacs redisplay.
64 @section Creating Frames
66 To create a new frame, call the function @code{make-frame}.
68 @defun make-frame &optional alist
69 This function creates a new frame. If you are using a supported window
70 system, it makes a window frame; otherwise, it makes a terminal frame.
72 The argument is an alist specifying frame parameters. Any parameters
73 not mentioned in @var{alist} default according to the value of the
74 variable @code{default-frame-alist}; parameters not specified even there
75 default from the standard X resources or whatever is used instead on
78 The set of possible parameters depends in principle on what kind of
79 window system Emacs uses to display its frames. @xref{Window Frame
80 Parameters}, for documentation of individual parameters you can specify.
83 @defvar before-make-frame-hook
84 @tindex before-make-frame-hook
85 A normal hook run by @code{make-frame} before it actually creates the
89 @defvar after-make-frame-hook
90 @tindex after-make-frame-hook
91 An abnormal hook run by @code{make-frame} after it creates the frame.
92 Each function in @code{after-make-frame-hook} receives one argument, the
96 @node Multiple Displays
97 @section Multiple Displays
98 @cindex multiple X displays
99 @cindex displays, multiple
101 A single Emacs can talk to more than one X display.
102 Initially, Emacs uses just one display---the one chosen with the
103 @code{DISPLAY} environment variable or with the @samp{--display} option
104 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
105 another display, use the command @code{make-frame-on-display} or specify
106 the @code{display} frame parameter when you create the frame.
108 Emacs treats each X server as a separate terminal, giving each one its
109 own selected frame and its own minibuffer windows.
111 A few Lisp variables are @dfn{terminal-local}; that is, they have a
112 separate binding for each terminal. The binding in effect at any time
113 is the one for the terminal that the currently selected frame belongs
114 to. These variables include @code{default-minibuffer-frame},
115 @code{defining-kbd-macro}, @code{last-kbd-macro}, and
116 @code{system-key-alist}. They are always terminal-local, and can never
117 be buffer-local (@pxref{Buffer-Local Variables}) or frame-local.
119 A single X server can handle more than one screen. A display name
120 @samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
121 part specifies the screen number for a given server. When you use two
122 screens belonging to one server, Emacs knows by the similarity in their
123 names that they share a single keyboard, and it treats them as a single
126 @deffn Command make-frame-on-display display &optional parameters
127 This creates a new frame on display @var{display}, taking the other
128 frame parameters from @var{parameters}. Aside from the @var{display}
129 argument, it is like @code{make-frame} (@pxref{Creating Frames}).
132 @defun x-display-list
133 This returns a list that indicates which X displays Emacs has a
134 connection to. The elements of the list are strings, and each one is
138 @defun x-open-connection display &optional xrm-string
139 This function opens a connection to the X display @var{display}. It
140 does not create a frame on that display, but it permits you to check
141 that communication can be established with that display.
143 The optional argument @var{xrm-string}, if not @code{nil}, is a
144 string of resource names and values, in the same format used in the
145 @file{.Xresources} file. The values you specify override the resource
146 values recorded in the X server itself; they apply to all Emacs frames
147 created on this display. Here's an example of what this string might
151 "*BorderWidth: 3\n*InternalBorder: 2\n"
157 @defun x-close-connection display
158 This function closes the connection to display @var{display}. Before
159 you can do this, you must first delete all the frames that were open on
160 that display (@pxref{Deleting Frames}).
163 @node Frame Parameters
164 @section Frame Parameters
166 A frame has many parameters that control its appearance and behavior.
167 Just what parameters a frame has depends on what display mechanism it
170 Frame parameters exist for the sake of window systems. A terminal frame
171 has a few parameters, mostly for compatibility's sake; only the @code{height},
172 @code{width}, @code{name}, @code{title}, @code{buffer-list} and
173 @code{buffer-predicate} parameters do something special.
176 * Parameter Access:: How to change a frame's parameters.
177 * Initial Parameters:: Specifying frame parameters when you make a frame.
178 * Window Frame Parameters:: List of frame parameters for window systems.
179 * Size and Position:: Changing the size and position of a frame.
182 @node Parameter Access
183 @subsection Access to Frame Parameters
185 These functions let you read and change the parameter values of a
188 @defun frame-parameters frame
189 The function @code{frame-parameters} returns an alist listing all the
190 parameters of @var{frame} and their values.
193 @defun modify-frame-parameters frame alist
194 This function alters the parameters of frame @var{frame} based on the
195 elements of @var{alist}. Each element of @var{alist} has the form
196 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
197 parameter. If you don't mention a parameter in @var{alist}, its value
201 @node Initial Parameters
202 @subsection Initial Frame Parameters
204 You can specify the parameters for the initial startup frame
205 by setting @code{initial-frame-alist} in your @file{.emacs} file.
207 @defvar initial-frame-alist
208 This variable's value is an alist of parameter values used when creating
209 the initial window frame. You can set this variable to specify the
210 appearance of the initial frame without altering subsequent frames.
211 Each element has the form:
214 (@var{parameter} . @var{value})
217 Emacs creates the initial frame before it reads your @file{~/.emacs}
218 file. After reading that file, Emacs checks @code{initial-frame-alist},
219 and applies the parameter settings in the altered value to the already
220 created initial frame.
222 If these settings affect the frame geometry and appearance, you'll see
223 the frame appear with the wrong ones and then change to the specified
224 ones. If that bothers you, you can specify the same geometry and
225 appearance with X resources; those do take affect before the frame is
226 created. @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
228 X resource settings typically apply to all frames. If you want to
229 specify some X resources solely for the sake of the initial frame, and
230 you don't want them to apply to subsequent frames, here's how to achieve
231 this. Specify parameters in @code{default-frame-alist} to override the
232 X resources for subsequent frames; then, to prevent these from affecting
233 the initial frame, specify the same parameters in
234 @code{initial-frame-alist} with values that match the X resources.
237 If these parameters specify a separate minibuffer-only frame with
238 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
241 @defvar minibuffer-frame-alist
242 This variable's value is an alist of parameter values used when creating
243 an initial minibuffer-only frame---if such a frame is needed, according
244 to the parameters for the main initial frame.
247 @defvar default-frame-alist
248 This is an alist specifying default values of frame parameters for all
249 Emacs frames---the first frame, and subsequent frames. When using the X
250 Window System, you can get the same results by means of X resources
254 See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
256 If you use options that specify window appearance when you invoke Emacs,
257 they take effect by adding elements to @code{default-frame-alist}. One
258 exception is @samp{-geometry}, which adds the specified position to
259 @code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
260 The GNU Emacs Manual}.
262 @node Window Frame Parameters
263 @subsection Window Frame Parameters
265 Just what parameters a frame has depends on what display mechanism it
266 uses. Here is a table of the parameters that have special meanings in a
267 window frame; of these, @code{name}, @code{title}, @code{height},
268 @code{width}, @code{buffer-list} and @code{buffer-predicate} provide
269 meaningful information in terminal frames.
273 The display on which to open this frame. It should be a string of the
274 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
275 @code{DISPLAY} environment variable.
278 If a frame has a non-@code{nil} title, it appears in the window system's
279 border for the frame, and also in the mode line of windows in that frame
280 if @code{mode-line-frame-identification} uses @samp{%F}
281 (@pxref{%-Constructs}). This is normally the case when Emacs is not
282 using a window system, and can only display one frame at a time.
286 The name of the frame. The frame name serves as a default for the frame
287 title, if the @code{title} parameter is unspecified or @code{nil}. If
288 you don't specify a name, Emacs sets the frame name automatically
289 (@pxref{Frame Titles}).
291 If you specify the frame name explicitly when you create the frame, the
292 name is also used (instead of the name of the Emacs executable) when
293 looking up X resources for the frame.
296 The screen position of the left edge, in pixels, with respect to the
297 left edge of the screen. The value may be a positive number @var{pos},
298 or a list of the form @code{(+ @var{pos})} which permits specifying a
299 negative @var{pos} value.
301 A negative number @minus{}@var{pos}, or a list of the form @code{(-
302 @var{pos})}, actually specifies the position of the right edge of the
303 window with respect to the right edge of the screen. A positive value
304 of @var{pos} counts toward the left. @strong{Reminder:} if the
305 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
308 Some window managers ignore program-specified positions. If you want to
309 be sure the position you specify is not ignored, specify a
310 non-@code{nil} value for the @code{user-position} parameter as well.
313 The screen position of the top edge, in pixels, with respect to the
314 top edge of the screen. The value may be a positive number @var{pos},
315 or a list of the form @code{(+ @var{pos})} which permits specifying a
316 negative @var{pos} value.
318 A negative number @minus{}@var{pos}, or a list of the form @code{(-
319 @var{pos})}, actually specifies the position of the bottom edge of the
320 window with respect to the bottom edge of the screen. A positive value
321 of @var{pos} counts toward the top. @strong{Reminder:} if the
322 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
325 Some window managers ignore program-specified positions. If you want to
326 be sure the position you specify is not ignored, specify a
327 non-@code{nil} value for the @code{user-position} parameter as well.
330 The screen position of the left edge @emph{of the frame's icon}, in
331 pixels, counting from the left edge of the screen. This takes effect if
332 and when the frame is iconified.
335 The screen position of the top edge @emph{of the frame's icon}, in
336 pixels, counting from the top edge of the screen. This takes effect if
337 and when the frame is iconified.
340 When you create a frame and specify its screen position with the
341 @code{left} and @code{top} parameters, use this parameter to say whether
342 the specified position was user-specified (explicitly requested in some
343 way by a human user) or merely program-specified (chosen by a program).
344 A non-@code{nil} value says the position was user-specified.
346 Window managers generally heed user-specified positions, and some heed
347 program-specified positions too. But many ignore program-specified
348 positions, placing the window in a default fashion or letting the user
349 place it with the mouse. Some window managers, including @code{twm},
350 let the user specify whether to obey program-specified positions or
353 When you call @code{make-frame}, you should specify a non-@code{nil}
354 value for this parameter if the values of the @code{left} and @code{top}
355 parameters represent the user's stated preference; otherwise, use
359 The height of the frame contents, in characters. (To get the height in
360 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
363 The width of the frame contents, in characters. (To get the height in
364 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
367 The number of the window-system window used by the frame
368 to contain the actual Emacs windows.
370 @item outer-window-id
371 The number of the outermost window-system window used for the whole frame.
374 Whether this frame has its own minibuffer. The value @code{t} means
375 yes, @code{nil} means no, @code{only} means this frame is just a
376 minibuffer. If the value is a minibuffer window (in some other frame),
377 the new frame uses that minibuffer.
379 @item buffer-predicate
380 The buffer-predicate function for this frame. The function
381 @code{other-buffer} uses this predicate (from the selected frame) to
382 decide which buffers it should consider, if the predicate is not
383 @code{nil}. It calls the predicate with one argument, a buffer, once for
384 each buffer; if the predicate returns a non-@code{nil} value, it
385 considers that buffer.
388 A list of buffers that have been selected in this frame,
389 ordered most-recently-selected first.
392 The name of the font for displaying text in the frame. This is a
393 string, either a valid font name for your system or the name of an Emacs
394 fontset (@pxref{Fontsets}).
397 Whether selecting the frame raises it (non-@code{nil} means yes).
400 Whether deselecting the frame lowers it (non-@code{nil} means yes).
402 @item vertical-scroll-bars
403 Whether the frame has scroll bars for vertical scrolling, and which side
404 of the frame they should be on. The possible values are @code{left},
405 @code{right}, and @code{nil} for no scroll bars.
407 @item horizontal-scroll-bars
408 Whether the frame has scroll bars for horizontal scrolling
409 (non-@code{nil} means yes). (Horizontal scroll bars are not currently
412 @item scroll-bar-width
413 The width of the vertical scroll bar, in pixels.
416 The type of icon to use for this frame when it is iconified. If the
417 value is a string, that specifies a file containing a bitmap to use.
418 Any other non-@code{nil} value specifies the default bitmap icon (a
419 picture of a gnu); @code{nil} specifies a text icon.
422 The name to use in the icon for this frame, when and if the icon
423 appears. If this is @code{nil}, the frame's title is used.
425 @item foreground-color
426 The color to use for the image of a character. This is a string; the
427 window system defines the meaningful color names.
429 If you set the @code{foreground-color} frame parameter, you should
430 call @code{frame-update-face-colors} to update faces accordingly.
432 @item background-color
433 The color to use for the background of characters.
435 If you set the @code{background-color} frame parameter, you should
436 call @code{frame-update-face-colors} to update faces accordingly.
437 @xref{Face Functions}.
439 @item background-mode
440 This parameter is either @code{dark} or @code{light}, according
441 to whether the background color is a light one or a dark one.
444 The color for the mouse pointer.
447 The color for the cursor that shows point.
450 The color for the border of the frame.
453 This parameter describes the range of possible colors that can be used
454 in this frame. Its value is @code{color}, @code{grayscale} or
458 The way to display the cursor. The legitimate values are @code{bar},
459 @code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
460 specifies an ordinary black box overlaying the character after point;
461 that is the default. The symbol @code{bar} specifies a vertical bar
462 between characters as the cursor. @code{(bar . @var{width})} specifies
463 a bar @var{width} pixels wide.
466 The width in pixels of the window border.
468 @item internal-border-width
469 The distance in pixels between text and border.
472 If non-@code{nil}, this frame's window is never split automatically.
475 The state of visibility of the frame. There are three possibilities:
476 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
477 iconified. @xref{Visibility of Frames}.
480 The number of lines to allocate at the top of the frame for a menu bar.
481 The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
482 toolkit, there is only one menu bar line; all that matters about the
483 number you specify is whether it is greater than zero.)
487 @c ??? Not yet working.
488 The X window number of the window that should be the parent of this one.
489 Specifying this lets you create an Emacs window inside some other
490 application's window. (It is not certain this will be implemented; try
491 it and see if it works.)
495 @node Size and Position
496 @subsection Frame Size And Position
497 @cindex size of frame
502 You can read or change the size and position of a frame using the
503 frame parameters @code{left}, @code{top}, @code{height}, and
504 @code{width}. Whatever geometry parameters you don't specify are chosen
505 by the window manager in its usual fashion.
507 Here are some special features for working with sizes and positions:
509 @defun set-frame-position frame left top
510 This function sets the position of the top left corner of @var{frame} to
511 @var{left} and @var{top}. These arguments are measured in pixels, and
512 normally count from the top left corner of the screen.
514 Negative parameter values position the bottom edge of the window up from
515 the bottom edge of the screen, or the right window edge to the left of
516 the right edge of the screen. It would probably be better if the values
517 were always counted from the left and top, so that negative arguments
518 would position the frame partly off the top or left edge of the screen,
519 but it seems inadvisable to change that now.
522 @defun frame-height &optional frame
523 @defunx frame-width &optional frame
524 These functions return the height and width of @var{frame}, measured in
525 lines and columns. If you don't supply @var{frame}, they use the
531 These functions are old aliases for @code{frame-height} and
532 @code{frame-width}. When you are using a non-window terminal, the size
533 of the frame is normally the same as the size of the terminal screen.
536 @defun frame-pixel-height &optional frame
537 @defunx frame-pixel-width &optional frame
538 These functions return the height and width of @var{frame}, measured in
539 pixels. If you don't supply @var{frame}, they use the selected frame.
542 @defun frame-char-height &optional frame
543 @defunx frame-char-width &optional frame
544 These functions return the height and width of a character in
545 @var{frame}, measured in pixels. The values depend on the choice of
546 font. If you don't supply @var{frame}, these functions use the selected
550 @defun set-frame-size frame cols rows
551 This function sets the size of @var{frame}, measured in characters;
552 @var{cols} and @var{rows} specify the new width and height.
554 To set the size based on values measured in pixels, use
555 @code{frame-char-height} and @code{frame-char-width} to convert
556 them to units of characters.
559 @defun set-frame-height frame lines &optional pretend
560 This function resizes @var{frame} to a height of @var{lines} lines. The
561 sizes of existing windows in @var{frame} are altered proportionally to
564 If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
565 lines of output in @var{frame}, but does not change its value for the
566 actual height of the frame. This is only useful for a terminal frame.
567 Using a smaller height than the terminal actually implements may be
568 useful to reproduce behavior observed on a smaller screen, or if the
569 terminal malfunctions when using its whole screen. Setting the frame
570 height ``for real'' does not always work, because knowing the correct
571 actual size may be necessary for correct cursor positioning on a
575 @defun set-frame-width frame width &optional pretend
576 This function sets the width of @var{frame}, measured in characters.
577 The argument @var{pretend} has the same meaning as in
578 @code{set-frame-height}.
581 @findex set-screen-height
582 @findex set-screen-width
583 The older functions @code{set-screen-height} and
584 @code{set-screen-width} were used to specify the height and width of the
585 screen, in Emacs versions that did not support multiple frames. They
586 are semi-obsolete, but still work; they apply to the selected frame.
588 @defun x-parse-geometry geom
589 @cindex geometry specification
590 The function @code{x-parse-geometry} converts a standard X window
591 geometry string to an alist that you can use as part of the argument to
594 The alist describes which parameters were specified in @var{geom}, and
595 gives the values specified for them. Each element looks like
596 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
597 values are @code{left}, @code{top}, @code{width}, and @code{height}.
599 For the size parameters, the value must be an integer. The position
600 parameter names @code{left} and @code{top} are not totally accurate,
601 because some values indicate the position of the right or bottom edges
602 instead. These are the @var{value} possibilities for the position
607 A positive integer relates the left edge or top edge of the window to
608 the left or top edge of the screen. A negative integer relates the
609 right or bottom edge of the window to the right or bottom edge of the
612 @item @code{(+ @var{position})}
613 This specifies the position of the left or top edge of the window
614 relative to the left or top edge of the screen. The integer
615 @var{position} may be positive or negative; a negative value specifies a
616 position outside the screen.
618 @item @code{(- @var{position})}
619 This specifies the position of the right or bottom edge of the window
620 relative to the right or bottom edge of the screen. The integer
621 @var{position} may be positive or negative; a negative value specifies a
622 position outside the screen.
628 (x-parse-geometry "35x70+0-0")
629 @result{} ((height . 70) (width . 35)
630 (top - 0) (left . 0))
635 @section Frame Titles
637 Every frame has a @code{name} parameter; this serves as the default
638 for the frame title which window systems typically display at the top of
639 the frame. You can specify a name explicitly by setting the @code{name}
642 Normally you don't specify the name explicitly, and Emacs computes the
643 frame name automatically based on a template stored in the variable
644 @code{frame-title-format}. Emacs recomputes the name each time the
645 frame is redisplayed.
647 @defvar frame-title-format
648 This variable specifies how to compute a name for a frame when you have
649 not explicitly specified one. The variable's value is actually a mode
650 line construct, just like @code{mode-line-format}. @xref{Mode Line
654 @defvar icon-title-format
655 This variable specifies how to compute the name for an iconified frame,
656 when you have not explicitly specified the frame title. This title
657 appears in the icon itself.
660 @defvar multiple-frames
661 This variable is set automatically by Emacs. Its value is @code{t} when
662 there are two or more frames (not counting minibuffer-only frames or
663 invisible frames). The default value of @code{frame-title-format} uses
664 @code{multiple-frames} so as to put the buffer name in the frame title
665 only when there is more than one frame.
668 @node Deleting Frames
669 @section Deleting Frames
670 @cindex deletion of frames
672 Frames remain potentially visible until you explicitly @dfn{delete}
673 them. A deleted frame cannot appear on the screen, but continues to
674 exist as a Lisp object until there are no references to it. There is no
675 way to cancel the deletion of a frame aside from restoring a saved frame
676 configuration (@pxref{Frame Configurations}); this is similar to the
679 @deffn Command delete-frame &optional frame
680 This function deletes the frame @var{frame}. By default, @var{frame} is
684 @defun frame-live-p frame
685 The function @code{frame-live-p} returns non-@code{nil} if the frame
686 @var{frame} has not been deleted.
689 Some window managers provide a command to delete a window. These work
690 by sending a special message to the program that operates the window.
691 When Emacs gets one of these commands, it generates a
692 @code{delete-frame} event, whose normal definition is a command that
693 calls the function @code{delete-frame}. @xref{Misc Events}.
695 @node Finding All Frames
696 @section Finding All Frames
699 The function @code{frame-list} returns a list of all the frames that
700 have not been deleted. It is analogous to @code{buffer-list} for
701 buffers. The list that you get is newly created, so modifying the list
702 doesn't have any effect on the internals of Emacs.
705 @defun visible-frame-list
706 This function returns a list of just the currently visible frames.
707 @xref{Visibility of Frames}. (Terminal frames always count as
708 ``visible'', even though only the selected one is actually displayed.)
711 @defun next-frame &optional frame minibuf
712 The function @code{next-frame} lets you cycle conveniently through all
713 the frames from an arbitrary starting point. It returns the ``next''
714 frame after @var{frame} in the cycle. If @var{frame} is omitted or
715 @code{nil}, it defaults to the selected frame.
717 The second argument, @var{minibuf}, says which frames to consider:
721 Exclude minibuffer-only frames.
723 Consider all visible frames.
725 Consider all visible or iconified frames.
727 Consider only the frames using that particular window as their
734 @defun previous-frame &optional frame minibuf
735 Like @code{next-frame}, but cycles through all frames in the opposite
739 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
742 @node Frames and Windows
743 @section Frames and Windows
745 Each window is part of one and only one frame; you can get the frame
746 with @code{window-frame}.
748 @defun window-frame window
749 This function returns the frame that @var{window} is on.
752 All the non-minibuffer windows in a frame are arranged in a cyclic
753 order. The order runs from the frame's top window, which is at the
754 upper left corner, down and to the right, until it reaches the window at
755 the lower right corner (always the minibuffer window, if the frame has
756 one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
758 @defun frame-top-window frame
759 This returns the topmost, leftmost window of frame @var{frame}.
762 At any time, exactly one window on any frame is @dfn{selected within the
763 frame}. The significance of this designation is that selecting the
764 frame also selects this window. You can get the frame's current
765 selected window with @code{frame-selected-window}.
767 @defun frame-selected-window frame
768 This function returns the window on @var{frame} that is selected within
772 Conversely, selecting a window for Emacs with @code{select-window} also
773 makes that window selected within its frame. @xref{Selecting Windows}.
775 Another function that (usually) returns one of the windows in a given
776 frame is @code{minibuffer-window}. @xref{Minibuffer Misc}.
778 @node Minibuffers and Frames
779 @section Minibuffers and Frames
781 Normally, each frame has its own minibuffer window at the bottom, which
782 is used whenever that frame is selected. If the frame has a minibuffer,
783 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
785 However, you can also create a frame with no minibuffer. Such a frame
786 must use the minibuffer window of some other frame. When you create the
787 frame, you can specify explicitly the minibuffer window to use (in some
788 other frame). If you don't, then the minibuffer is found in the frame
789 which is the value of the variable @code{default-minibuffer-frame}. Its
790 value should be a frame that does have a minibuffer.
792 If you use a minibuffer-only frame, you might want that frame to raise
793 when you enter the minibuffer. If so, set the variable
794 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
796 @defvar default-minibuffer-frame
797 This variable specifies the frame to use for the minibuffer window, by
798 default. It is always local to the current terminal and cannot be
799 buffer-local. @xref{Multiple Displays}.
805 @cindex selected frame
807 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
808 window always resides on the selected frame.
810 @defun selected-frame
811 This function returns the selected frame.
814 Some window systems and window managers direct keyboard input to the
815 window object that the mouse is in; others require explicit clicks or
816 commands to @dfn{shift the focus} to various window objects. Either
817 way, Emacs automatically keeps track of which frame has the focus.
819 Lisp programs can also switch frames ``temporarily'' by calling the
820 function @code{select-frame}. This does not alter the window system's
821 concept of focus; rather, it escapes from the window manager's control
822 until that control is somehow reasserted.
824 When using a text-only terminal, only the selected terminal frame is
825 actually displayed on the terminal. @code{switch-frame} is the only way
826 to switch frames, and the change lasts until overridden by a subsequent
827 call to @code{switch-frame}. Each terminal screen except for the
828 initial one has a number, and the number of the selected frame appears
829 in the mode line before the buffer name (@pxref{Mode Line Variables}).
831 @c ??? This is not yet implemented properly.
832 @defun select-frame frame
833 This function selects frame @var{frame}, temporarily disregarding the
834 focus of the X server if any. The selection of @var{frame} lasts until
835 the next time the user does something to select a different frame, or
836 until the next time this function is called.
839 Emacs cooperates with the window system by arranging to select frames as
840 the server and window manager request. It does so by generating a
841 special kind of input event, called a @dfn{focus} event, when
842 appropriate. The command loop handles a focus event by calling
843 @code{handle-switch-frame}. @xref{Focus Events}.
845 @deffn Command handle-switch-frame frame
846 This function handles a focus event by selecting frame @var{frame}.
848 Focus events normally do their job by invoking this command.
849 Don't call it for any other reason.
852 @defun redirect-frame-focus frame focus-frame
853 This function redirects focus from @var{frame} to @var{focus-frame}.
854 This means that @var{focus-frame} will receive subsequent keystrokes and
855 events intended for @var{frame}. After such an event, the value of
856 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
857 events specifying @var{frame} will instead select @var{focus-frame}.
859 If @var{focus-frame} is @code{nil}, that cancels any existing
860 redirection for @var{frame}, which therefore once again receives its own
863 One use of focus redirection is for frames that don't have minibuffers.
864 These frames use minibuffers on other frames. Activating a minibuffer
865 on another frame redirects focus to that frame. This puts the focus on
866 the minibuffer's frame, where it belongs, even though the mouse remains
867 in the frame that activated the minibuffer.
869 Selecting a frame can also change focus redirections. Selecting frame
870 @code{bar}, when @code{foo} had been selected, changes any redirections
871 pointing to @code{foo} so that they point to @code{bar} instead. This
872 allows focus redirection to work properly when the user switches from
873 one frame to another using @code{select-window}.
875 This means that a frame whose focus is redirected to itself is treated
876 differently from a frame whose focus is not redirected.
877 @code{select-frame} affects the former but not the latter.
879 The redirection lasts until @code{redirect-frame-focus} is called to
883 @defopt focus-follows-mouse
884 @tindex focus-follows-mouse
885 This option is how you inform Emacs whether the window manager transfers
886 focus when the user moves the mouse. Non-@code{nil} says that it does.
887 When this is so, the command @code{other-frame} moves the mouse to a
888 position consistent with the new selected frame.
891 @node Visibility of Frames
892 @section Visibility of Frames
893 @cindex visible frame
894 @cindex invisible frame
895 @cindex iconified frame
896 @cindex frame visibility
898 A window frame may be @dfn{visible}, @dfn{invisible}, or
899 @dfn{iconified}. If it is visible, you can see its contents. If it is
900 iconified, the frame's contents do not appear on the screen, but an icon
901 does. If the frame is invisible, it doesn't show on the screen, not
904 Visibility is meaningless for terminal frames, since only the selected
905 one is actually displayed in any case.
907 @deffn Command make-frame-visible &optional frame
908 This function makes frame @var{frame} visible. If you omit @var{frame},
909 it makes the selected frame visible.
912 @deffn Command make-frame-invisible &optional frame
913 This function makes frame @var{frame} invisible. If you omit
914 @var{frame}, it makes the selected frame invisible.
917 @deffn Command iconify-frame &optional frame
918 This function iconifies frame @var{frame}. If you omit @var{frame}, it
919 iconifies the selected frame.
922 @defun frame-visible-p frame
923 This returns the visibility status of frame @var{frame}. The value is
924 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
925 @code{icon} if it is iconified.
928 The visibility status of a frame is also available as a frame
929 parameter. You can read or change it as such. @xref{Window Frame
932 The user can iconify and deiconify frames with the window manager.
933 This happens below the level at which Emacs can exert any control, but
934 Emacs does provide events that you can use to keep track of such
935 changes. @xref{Misc Events}.
937 @node Raising and Lowering
938 @section Raising and Lowering Frames
940 Most window systems use a desktop metaphor. Part of this metaphor is
941 the idea that windows are stacked in a notional third dimension
942 perpendicular to the screen surface, and thus ordered from ``highest''
943 to ``lowest''. Where two windows overlap, the one higher up covers
944 the one underneath. Even a window at the bottom of the stack can be
945 seen if no other window overlaps it.
947 @cindex raising a frame
948 @cindex lowering a frame
949 A window's place in this ordering is not fixed; in fact, users tend
950 to change the order frequently. @dfn{Raising} a window means moving
951 it ``up'', to the top of the stack. @dfn{Lowering} a window means
952 moving it to the bottom of the stack. This motion is in the notional
953 third dimension only, and does not change the position of the window
956 You can raise and lower Emacs frame Windows with these functions:
958 @deffn Command raise-frame &optional frame
959 This function raises frame @var{frame} (default, the selected frame).
962 @deffn Command lower-frame &optional frame
963 This function lowers frame @var{frame} (default, the selected frame).
966 @defopt minibuffer-auto-raise
967 If this is non-@code{nil}, activation of the minibuffer raises the frame
968 that the minibuffer window is in.
971 You can also enable auto-raise (raising automatically when a frame is
972 selected) or auto-lower (lowering automatically when it is deselected)
973 for any frame using frame parameters. @xref{Window Frame Parameters}.
975 @node Frame Configurations
976 @section Frame Configurations
977 @cindex frame configuration
979 A @dfn{frame configuration} records the current arrangement of frames,
980 all their properties, and the window configuration of each one.
981 (@xref{Window Configurations}.)
983 @defun current-frame-configuration
984 This function returns a frame configuration list that describes
985 the current arrangement of frames and their contents.
988 @defun set-frame-configuration configuration
989 This function restores the state of frames described in
994 @section Mouse Tracking
995 @cindex mouse tracking
996 @cindex tracking the mouse
998 Sometimes it is useful to @dfn{track} the mouse, which means to display
999 something to indicate where the mouse is and move the indicator as the
1000 mouse moves. For efficient mouse tracking, you need a way to wait until
1001 the mouse actually moves.
1003 The convenient way to track the mouse is to ask for events to represent
1004 mouse motion. Then you can wait for motion by waiting for an event. In
1005 addition, you can easily handle any other sorts of events that may
1006 occur. That is useful, because normally you don't want to track the
1007 mouse forever---only until some other event, such as the release of a
1010 @defspec track-mouse body@dots{}
1011 This special form executes @var{body}, with generation of mouse motion
1012 events enabled. Typically @var{body} would use @code{read-event} to
1013 read the motion events and modify the display accordingly. @xref{Motion
1014 Events}, for the format of mouse motion events.
1016 The value of @code{track-mouse} is that of the last form in @var{body}.
1017 You should design @var{body} to return when it sees the up-event that
1018 indicates the release of the button, or whatever kind of event means
1019 it is time to stop tracking.
1022 The usual purpose of tracking mouse motion is to indicate on the screen
1023 the consequences of pushing or releasing a button at the current
1026 In many cases, you can avoid the need to track the mouse by using
1027 the @code{mouse-face} text property (@pxref{Special Properties}).
1028 That works at a much lower level and runs more smoothly than
1029 Lisp-level mouse tracking.
1032 @c These are not implemented yet.
1034 These functions change the screen appearance instantaneously. The
1035 effect is transient, only until the next ordinary Emacs redisplay. That
1036 is OK for mouse tracking, since it doesn't make sense for mouse tracking
1037 to change the text, and the body of @code{track-mouse} normally reads
1038 the events itself and does not do redisplay.
1040 @defun x-contour-region window beg end
1041 This function draws lines to make a box around the text from @var{beg}
1042 to @var{end}, in window @var{window}.
1045 @defun x-uncontour-region window beg end
1046 This function erases the lines that would make a box around the text
1047 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1048 a contour that you previously made by calling @code{x-contour-region}.
1051 @defun x-draw-rectangle frame left top right bottom
1052 This function draws a hollow rectangle on frame @var{frame} with the
1053 specified edge coordinates, all measured in pixels from the inside top
1054 left corner. It uses the cursor color, the one used for indicating the
1058 @defun x-erase-rectangle frame left top right bottom
1059 This function erases a hollow rectangle on frame @var{frame} with the
1060 specified edge coordinates, all measured in pixels from the inside top
1061 left corner. Erasure means redrawing the text and background that
1062 normally belong in the specified rectangle.
1066 @node Mouse Position
1067 @section Mouse Position
1068 @cindex mouse position
1069 @cindex position of mouse
1071 The functions @code{mouse-position} and @code{set-mouse-position}
1072 give access to the current position of the mouse.
1074 @defun mouse-position
1075 This function returns a description of the position of the mouse. The
1076 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1077 and @var{y} are integers giving the position in characters relative to
1078 the top left corner of the inside of @var{frame}.
1081 @defun set-mouse-position frame x y
1082 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1083 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1084 giving the position in characters relative to the top left corner of the
1085 inside of @var{frame}. If @var{frame} is not visible, this function
1086 does nothing. The return value is not significant.
1089 @defun mouse-pixel-position
1090 This function is like @code{mouse-position} except that it returns
1091 coordinates in units of pixels rather than units of characters.
1094 @defun set-mouse-pixel-position frame x y
1095 This function warps the mouse like @code{set-mouse-position} except that
1096 @var{x} and @var{y} are in units of pixels rather than units of
1097 characters. These coordinates are not required to be within the frame.
1099 If @var{frame} is not visible, this function does nothing. The return
1100 value is not significant.
1106 @section Pop-Up Menus
1108 When using a window system, a Lisp program can pop up a menu so that
1109 the user can choose an alternative with the mouse.
1111 @defun x-popup-menu position menu
1112 This function displays a pop-up menu and returns an indication of
1113 what selection the user makes.
1115 The argument @var{position} specifies where on the screen to put the
1116 menu. It can be either a mouse button event (which says to put the menu
1117 where the user actuated the button) or a list of this form:
1120 ((@var{xoffset} @var{yoffset}) @var{window})
1124 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1125 pixels, counting from the top left corner of @var{window}'s frame.
1127 If @var{position} is @code{t}, it means to use the current mouse
1128 position. If @var{position} is @code{nil}, it means to precompute the
1129 key binding equivalents for the keymaps specified in @var{menu},
1130 without actually displaying or popping up the menu.
1132 The argument @var{menu} says what to display in the menu. It can be a
1133 keymap or a list of keymaps (@pxref{Menu Keymaps}). Alternatively, it
1134 can have the following form:
1137 (@var{title} @var{pane1} @var{pane2}...)
1141 where each pane is a list of form
1144 (@var{title} (@var{line} . @var{item})...)
1147 Each @var{line} should be a string, and each @var{item} should be the
1148 value to return if that @var{line} is chosen.
1151 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1152 if you could do the job with a prefix key defined with a menu keymap.
1153 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1154 a} can see the individual items in that menu and provide help for them.
1155 If instead you implement the menu by defining a command that calls
1156 @code{x-popup-menu}, the help facilities cannot know what happens inside
1157 that command, so they cannot give any help for the menu's items.
1159 The menu bar mechanism, which lets you switch between submenus by
1160 moving the mouse, cannot look within the definition of a command to see
1161 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1162 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1163 an integrated fashion. This is why all menu bar submenus are
1164 implemented with menu keymaps within the parent menu, and never with
1165 @code{x-popup-menu}. @xref{Menu Bar},
1167 If you want a menu bar submenu to have contents that vary, you should
1168 still use a menu keymap to implement it. To make the contents vary, add
1169 a hook function to @code{menu-bar-update-hook} to update the contents of
1170 the menu keymap as necessary.
1173 @section Dialog Boxes
1174 @cindex dialog boxes
1176 A dialog box is a variant of a pop-up menu---it looks a little
1177 different, it always appears in the center of a frame, and it has just
1178 one level and one pane. The main use of dialog boxes is for asking
1179 questions that the user can answer with ``yes'', ``no'', and a few other
1180 alternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} use
1181 dialog boxes instead of the keyboard, when called from commands invoked
1184 @defun x-popup-dialog position contents
1185 This function displays a pop-up dialog box and returns an indication of
1186 what selection the user makes. The argument @var{contents} specifies
1187 the alternatives to offer; it has this format:
1190 (@var{title} (@var{string} . @var{value})@dots{})
1194 which looks like the list that specifies a single pane for
1195 @code{x-popup-menu}.
1197 The return value is @var{value} from the chosen alternative.
1199 An element of the list may be just a string instead of a cons cell
1200 @code{(@var{string} . @var{value})}. That makes a box that cannot
1203 If @code{nil} appears in the list, it separates the left-hand items from
1204 the right-hand items; items that precede the @code{nil} appear on the
1205 left, and items that follow the @code{nil} appear on the right. If you
1206 don't include a @code{nil} in the list, then approximately half the
1207 items appear on each side.
1209 Dialog boxes always appear in the center of a frame; the argument
1210 @var{position} specifies which frame. The possible values are as in
1211 @code{x-popup-menu}, but the precise coordinates don't matter; only the
1214 In some configurations, Emacs cannot display a real dialog box; so
1215 instead it displays the same items in a pop-up menu in the center of the
1219 @node Pointer Shapes
1220 @section Pointer Shapes
1221 @cindex pointer shape
1222 @cindex mouse pointer shape
1224 These variables specify which shape to use for the mouse pointer in
1225 various situations, when using the X Window System:
1228 @item x-pointer-shape
1229 @vindex x-pointer-shape
1230 This variable specifies the pointer shape to use ordinarily in the Emacs
1233 @item x-sensitive-text-pointer-shape
1234 @vindex x-sensitive-text-pointer-shape
1235 This variable specifies the pointer shape to use when the mouse
1236 is over mouse-sensitive text.
1239 These variables affect newly created frames. They do not normally
1240 affect existing frames; however, if you set the mouse color of a frame,
1241 that also updates its pointer shapes based on the current values of
1242 these variables. @xref{Window Frame Parameters}.
1244 The values you can use, to specify either of these pointer shapes, are
1245 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1246 @key{RET} x-pointer @key{RET}} to see a list of them.
1248 @node Window System Selections
1249 @section Window System Selections
1250 @cindex selection (for X windows)
1252 The X server records a set of @dfn{selections} which permit transfer of
1253 data between application programs. The various selections are
1254 distinguished by @dfn{selection types}, represented in Emacs by
1255 symbols. X clients including Emacs can read or set the selection for
1258 @defun x-set-selection type data
1259 This function sets a ``selection'' in the X server. It takes two
1260 arguments: a selection type @var{type}, and the value to assign to it,
1261 @var{data}. If @var{data} is @code{nil}, it means to clear out the
1262 selection. Otherwise, @var{data} may be a string, a symbol, an integer
1263 (or a cons of two integers or list of two integers), an overlay, or a
1264 cons of two markers pointing to the same buffer. An overlay or a pair
1265 of markers stands for text in the overlay or between the markers.
1267 The argument @var{data} may also be a vector of valid non-vector
1270 Each possible @var{type} has its own selection value, which changes
1271 independently. The usual values of @var{type} are @code{PRIMARY} and
1272 @code{SECONDARY}; these are symbols with upper-case names, in accord
1273 with X Window System conventions. The default is @code{PRIMARY}.
1276 @defun x-get-selection &optional type data-type
1277 This function accesses selections set up by Emacs or by other X
1278 clients. It takes two optional arguments, @var{type} and
1279 @var{data-type}. The default for @var{type}, the selection type, is
1282 The @var{data-type} argument specifies the form of data conversion to
1283 use, to convert the raw data obtained from another X client into Lisp
1284 data. Meaningful values include @code{TEXT}, @code{STRING},
1285 @code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
1286 @code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
1287 @code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
1288 @code{NAME}, @code{ATOM}, and @code{INTEGER}. (These are symbols with
1289 upper-case names in accord with X conventions.) The default for
1290 @var{data-type} is @code{STRING}.
1294 The X server also has a set of numbered @dfn{cut buffers} which can
1295 store text or other data being moved between applications. Cut buffers
1296 are considered obsolete, but Emacs supports them for the sake of X
1297 clients that still use them.
1299 @defun x-get-cut-buffer n
1300 This function returns the contents of cut buffer number @var{n}.
1303 @defun x-set-cut-buffer string
1304 This function stores @var{string} into the first cut buffer (cut buffer
1305 0), moving the other values down through the series of cut buffers, much
1306 like the way successive kills in Emacs move down the kill ring.
1309 @defvar selection-coding-system
1310 @tindex selection-coding-system
1311 This variable specifies the coding system to use when reading and
1312 writing a selections, the clipboard, or a cut buffer. @xref{Coding
1313 Systems}. The default is @code{compound-text}.
1318 @section Looking up Font Names
1320 @defun x-list-font pattern &optional face frame maximum
1321 This function returns a list of available font names that match
1322 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
1323 specified, then the list is limited to fonts that are the same size as
1324 @var{face} currently is on @var{frame}.
1326 The argument @var{pattern} should be a string, perhaps with wildcard
1327 characters: the @samp{*} character matches any substring, and the
1328 @samp{?} character matches any single character. Pattern matching
1329 of font names ignores case.
1331 If you specify @var{face} and @var{frame}, @var{face} should be a face name
1332 (a symbol) and @var{frame} should be a frame.
1334 The optional argument @var{maximum} sets a limit on how many fonts to
1335 return. If this is non-@code{nil}, then the return value is truncated
1336 after the first @var{maximum} matching fonts. Specifying a small value
1337 for @var{maximum} can make this function much faster, in cases where
1338 many fonts match the pattern.
1344 A @dfn{fontset} is a list of fonts, each assigned to a range of
1345 character codes. An individual font cannot display the whole range of
1346 characters that Emacs supports, but a fontset can. Fontsets have names,
1347 just as fonts do, and you can use a fontset name in place of a font name
1348 when you specify the ``font'' for a frame or a face. Here is
1349 information about defining a fontset under Lisp program control.
1351 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
1352 This function defines a new fontset according to the specification
1353 string @var{fontset-spec}. The string should have this format:
1356 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
1360 Whitespace characters before and after the commas are ignored.
1362 The first part of the string, @var{fontpattern}, should have the form of
1363 a standard X font name, except that the last two fields should be
1364 @samp{fontset-@var{alias}}.
1366 The new fontset has two names, one long and one short. The long name is
1367 @var{fontpattern} in its entirety. The short name is
1368 @samp{fontset-@var{alias}}. You can refer to the fontset by either
1369 name. If a fontset with the same name already exists, an error is
1370 signaled, unless @var{noerror} is non-@code{nil}, in which case this
1371 function does nothing.
1373 If optional argument @var{style-variant-p} is non-@code{nil}, that says
1374 to create bold, italic and bold-italic variants of the fontset as well.
1375 These variant fontsets do not have a short name, only a long one, which
1376 is made by altering @var{fontpattern} to indicate the bold or italic
1379 The specification string also says which fonts to use in the fontset.
1380 See below for the details.
1383 The construct @samp{@var{charset}:@var{font}} specifies which font to
1384 use (in this fontset) for one particular character set. Here,
1385 @var{charset} is the name of a character set, and @var{font} is the font
1386 to use for that character set. You can use this construct any number of
1387 times in the specification string.
1389 For the remaining character sets, those that you don't specify
1390 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
1391 @samp{fontset-@var{alias}} with a value that names one character set.
1392 For the @sc{ASCII} character set, @samp{fontset-@var{alias}} is replaced
1393 with @samp{ISO8859-1}.
1395 In addition, when several consecutive fields are wildcards, Emacs
1396 collapses them into a single wildcard. This is to prevent use of
1397 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
1398 for editing, and scaling a smaller font is not useful because it is
1399 better to use the smaller font in its own size, which Emacs does.
1401 Thus if @var{fontpattern} is this,
1404 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
1408 the font specification for ASCII characters would be this:
1411 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
1415 and the font specification for Chinese GB2312 characters would be this:
1418 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
1421 You may not have any Chinese font matching the above font
1422 specification. Most X distributions include only Chinese fonts that
1423 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
1424 such a case, @samp{Fontset-@var{n}} can be specified as below:
1427 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
1428 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
1432 Then, the font specifications for all but Chinese GB2312 characters have
1433 @samp{fixed} in the @var{family} field, and the font specification for
1434 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
1438 @section Color Names
1440 @defun x-color-defined-p color &optional frame
1441 This function reports whether a color name is meaningful. It returns
1442 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
1443 which frame's display to ask about; if @var{frame} is omitted or
1444 @code{nil}, the selected frame is used.
1446 Note that this does not tell you whether the display you are using
1447 really supports that color. You can ask for any defined color on any
1448 kind of display, and you will get some result---that is how the X server
1449 works. Here's an approximate way to test whether your display supports
1450 the color @var{color}:
1453 (defun x-color-supported-p (color &optional frame)
1454 (and (x-color-defined-p color frame)
1455 (or (x-display-color-p frame)
1456 (member color '("black" "white"))
1457 (and (> (x-display-planes frame) 1)
1458 (equal color "gray")))))
1462 @defun x-color-values color &optional frame
1463 This function returns a value that describes what @var{color} should
1464 ideally look like. If @var{color} is defined, the value is a list of
1465 three integers, which give the amount of red, the amount of green, and
1466 the amount of blue. Each integer ranges in principle from 0 to 65535,
1467 but in practice no value seems to be above 65280. If @var{color} is not
1468 defined, the value is @code{nil}.
1471 (x-color-values "black")
1473 (x-color-values "white")
1474 @result{} (65280 65280 65280)
1475 (x-color-values "red")
1476 @result{} (65280 0 0)
1477 (x-color-values "pink")
1478 @result{} (65280 49152 51968)
1479 (x-color-values "hungry")
1483 The color values are returned for @var{frame}'s display. If @var{frame}
1484 is omitted or @code{nil}, the information is returned for the selected
1489 @section X Resources
1491 @defun x-get-resource attribute class &optional component subclass
1492 The function @code{x-get-resource} retrieves a resource value from the X
1493 Windows defaults database.
1495 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
1496 This function searches using a key of the form
1497 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
1498 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
1501 The optional arguments @var{component} and @var{subclass} add to the key
1502 and the class, respectively. You must specify both of them or neither.
1503 If you specify them, the key is
1504 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
1505 @samp{Emacs.@var{class}.@var{subclass}}.
1508 @defvar x-resource-class
1509 This variable specifies the application name that @code{x-get-resource}
1510 should look up. The default value is @code{"Emacs"}. You can examine X
1511 resources for application names other than ``Emacs'' by binding this
1512 variable to some other string, around a call to @code{x-get-resource}.
1515 @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
1518 @section Data about the X Server
1520 This section describes functions you can use to get information about
1521 the capabilities and origin of an X display that Emacs is using. Each
1522 of these functions lets you specify the display you are interested in:
1523 the @var{display} argument can be either a display name, or a frame
1524 (meaning use the display that frame is on). If you omit the
1525 @var{display} argument, or specify @code{nil}, that means to use the
1526 selected frame's display.
1528 @defun x-display-screens &optional display
1529 This function returns the number of screens associated with the display.
1532 @defun x-server-version &optional display
1533 This function returns the list of version numbers of the X server
1534 running the display.
1537 @defun x-server-vendor &optional display
1538 This function returns the vendor that provided the X server software.
1541 @defun x-display-pixel-height &optional display
1542 This function returns the height of the screen in pixels.
1545 @defun x-display-mm-height &optional display
1546 This function returns the height of the screen in millimeters.
1549 @defun x-display-pixel-width &optional display
1550 This function returns the width of the screen in pixels.
1553 @defun x-display-mm-width &optional display
1554 This function returns the width of the screen in millimeters.
1557 @defun x-display-backing-store &optional display
1558 This function returns the backing store capability of the screen.
1559 Values can be the symbols @code{always}, @code{when-mapped}, or
1563 @defun x-display-save-under &optional display
1564 This function returns non-@code{nil} if the display supports the
1568 @defun x-display-planes &optional display
1569 This function returns the number of planes the display supports.
1572 @defun x-display-visual-class &optional display
1573 This function returns the visual class for the screen. The value is one
1574 of the symbols @code{static-gray}, @code{gray-scale},
1575 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
1576 @code{direct-color}.
1579 @defun x-display-grayscale-p &optional display
1580 This function returns @code{t} if the screen can display shades of gray.
1583 @defun x-display-color-p &optional display
1584 This function returns @code{t} if the screen is a color screen.
1587 @defun x-display-color-cells &optional display
1588 This function returns the number of color cells the screen supports.
1592 @defvar x-no-window-manager
1593 This variable's value is @code{t} if no X window manager is in use.
1599 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
1600 width and height of an X Window frame, measured in pixels.