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 * Color Names:: Getting the definitions of color names.
54 * Resources:: Getting resource values from the server.
55 * Server Data:: Getting info about the X server.
58 @xref{Display}, for related information.
61 @section Creating Frames
63 To create a new frame, call the function @code{make-frame}.
65 @defun make-frame &optional alist
66 This function creates a new frame. If you are using a supported window
67 system, it makes a window frame; otherwise, it makes a terminal frame.
69 The argument is an alist specifying frame parameters. Any parameters
70 not mentioned in @var{alist} default according to the value of the
71 variable @code{default-frame-alist}; parameters not specified even there
72 default from the standard X resources or whatever is used instead on
75 The set of possible parameters depends in principle on what kind of
76 window system Emacs uses to display its frames. @xref{Window Frame
77 Parameters}, for documentation of individual parameters you can specify.
80 @defvar before-make-frame-hook
81 @tindex before-make-frame-hook
82 A normal hook run by @code{make-frame} before it actually creates the
86 @defvar after-make-frame-hook
87 @tindex after-make-frame-hook
88 An abnormal hook run by @code{make-frame} after it creates the frame.
89 Each function in @code{after-make-frame-hook} receives one argument, the
93 @node Multiple Displays
94 @section Multiple Displays
95 @cindex multiple displays
96 @cindex multiple X terminals
97 @cindex displays, multiple
99 A single Emacs can talk to more than one X Window display.
100 Initially, Emacs uses just one display---the one chosen with the
101 @code{DISPLAY} environment variable or with the @samp{--display} option
102 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
103 another display, use the command @code{make-frame-on-display} or specify
104 the @code{display} frame parameter when you create the frame.
106 Emacs treats each X server as a separate terminal, giving each one its
107 own selected frame and its own minibuffer windows. A few Lisp variables
108 have values local to the current terminal (that is, the terminal
109 corresponding to the currently selected frame): these are
110 @code{default-minibuffer-frame}, @code{defining-kbd-macro},
111 @code{last-kbd-macro}, and @code{system-key-alist}. These variables are
112 always terminal-local and can never be buffer-local or frame-local
113 (@pxref{Buffer-Local Variables}).
115 A single X server can handle more than one screen. A display name
116 @samp{@var{host}.@var{server}.@var{screen}} has three parts; the last
117 part specifies the screen number for a given server. When you use two
118 screens belonging to one server, Emacs knows by the similarity in their
119 names that they share a single keyboard, and it treats them as a single
122 @deffn Command make-frame-on-display display &optional parameters
123 This creates a new frame on display @var{display}, taking the other
124 frame parameters from @var{parameters}. Aside from the @var{display}
125 argument, it is like @code{make-frame} (@pxref{Creating Frames}).
128 @defun x-display-list
129 This returns a list that indicates which X displays Emacs has a
130 connection to. The elements of the list are strings, and each one is
134 @defun x-open-connection display &optional xrm-string
135 This function opens a connection to the X display @var{display}. It
136 does not create a frame on that display, but it permits you to check
137 that communication can be established with that display.
139 The optional argument @var{xrm-string}, if not @code{nil}, is a
140 string of resource names and values, in the same format used in the
141 @file{.Xresources} file. The values you specify override the resource
142 values recorded in the X server itself; they apply to all Emacs frames
143 created on this display. Here's an example of what this string might
147 "*BorderWidth: 3\n*InternalBorder: 2\n"
153 @defun x-close-connection display
154 This function closes the connection to display @var{display}. Before
155 you can do this, you must first delete all the frames that were open on
156 that display (@pxref{Deleting Frames}).
159 @node Frame Parameters
160 @section Frame Parameters
162 A frame has many parameters that control its appearance and behavior.
163 Just what parameters a frame has depends on what display mechanism it
166 Frame parameters exist for the sake of window systems. A terminal frame
167 has a few parameters, mostly for compatibility's sake; only the height,
168 width, @code{name}, @code{title}, @code{buffer-list} and
169 @code{buffer-predicate} parameters do something special.
172 * Parameter Access:: How to change a frame's parameters.
173 * Initial Parameters:: Specifying frame parameters when you make a frame.
174 * Window Frame Parameters:: List of frame parameters for window systems.
175 * Size and Position:: Changing the size and position of a frame.
178 @node Parameter Access
179 @subsection Access to Frame Parameters
181 These functions let you read and change the parameter values of a
184 @defun frame-parameters frame
185 The function @code{frame-parameters} returns an alist listing all the
186 parameters of @var{frame} and their values.
189 @defun modify-frame-parameters frame alist
190 This function alters the parameters of frame @var{frame} based on the
191 elements of @var{alist}. Each element of @var{alist} has the form
192 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
193 parameter. If you don't mention a parameter in @var{alist}, its value
197 @node Initial Parameters
198 @subsection Initial Frame Parameters
200 You can specify the parameters for the initial startup frame
201 by setting @code{initial-frame-alist} in your @file{.emacs} file.
203 @defvar initial-frame-alist
204 This variable's value is an alist of parameter values used when creating
205 the initial window frame. You can set this variable to specify the
206 appearance of the initial frame without altering subsequent frames.
207 Each element has the form:
210 (@var{parameter} . @var{value})
213 Emacs creates the initial frame before it reads your @file{~/.emacs}
214 file. After reading that file, Emacs checks @code{initial-frame-alist},
215 and applies the parameter settings in the altered value to the already
216 created initial frame.
218 If these settings affect the frame geometry and appearance, you'll see
219 the frame appear with the wrong ones and then change to the specified
220 ones. If that bothers you, you can specify the same geometry and
221 appearance with X resources; those do take affect before the frame is
222 created. @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
224 X resource settings typically apply to all frames. If you want to
225 specify some X resources solely for the sake of the initial frame, and
226 you don't want them to apply to subsequent frames, here's how to achieve
227 this. Specify parameters in @code{default-frame-alist} to override the
228 X resources for subsequent frames; then, to prevent these from affecting
229 the initial frame, specify the same parameters in
230 @code{initial-frame-alist} with values that match the X resources.
233 If these parameters specify a separate minibuffer-only frame with
234 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
237 @defvar minibuffer-frame-alist
238 This variable's value is an alist of parameter values used when creating
239 an initial minibuffer-only frame---if such a frame is needed, according
240 to the parameters for the main initial frame.
243 @defvar default-frame-alist
244 This is an alist specifying default values of frame parameters for all
245 Emacs frames---the first frame, and subsequent frames. When using the X
246 Window System, you can get the same results by means of X resources
250 See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
252 If you use options that specify window appearance when you invoke Emacs,
253 they take effect by adding elements to @code{default-frame-alist}. One
254 exception is @samp{-geometry}, which adds the specified position to
255 @code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
256 The GNU Emacs Manual}.
258 @node Window Frame Parameters
259 @subsection Window Frame Parameters
261 Just what parameters a frame has depends on what display mechanism it
262 uses. Here is a table of the parameters that have special meanings in a
263 window frame; of these, @code{name}, @code{title}, @code{height},
264 @code{width}, @code{buffer-list} and @code{buffer-predicate} provide
265 meaningful information in terminal frames.
269 The display on which to open this frame. It should be a string of the
270 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
271 @code{DISPLAY} environment variable.
274 If a frame has a non-@code{nil} title, it appears in the window system's
275 border for the frame, and also in the mode line of windows in that frame
276 if @code{mode-line-frame-identification} uses @samp{%F}
277 (@pxref{%-Constructs}). This is normally the case when Emacs is not
278 using a window system, and can only display one frame at a time.
282 The name of the frame. The frame name serves as a default for the frame
283 title, if the @code{title} parameter is unspecified or @code{nil}. If
284 you don't specify a name, Emacs sets the frame name automatically
285 (@pxref{Frame Titles}).
287 If you specify the frame name explicitly when you create the frame, the
288 name is also used (instead of the name of the Emacs executable) when
289 looking up X resources for the frame.
292 The screen position of the left edge, in pixels, with respect to the
293 left edge of the screen. The value may be a positive number @var{pos},
294 or a list of the form @code{(+ @var{pos})} which permits specifying a
295 negative @var{pos} value.
297 A negative number @minus{}@var{pos}, or a list of the form @code{(-
298 @var{pos})}, actually specifies the position of the right edge of the
299 window with respect to the right edge of the screen. A positive value
300 of @var{pos} counts toward the left. @strong{Reminder:} if the
301 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
304 Some window managers ignore program-specified positions. If you want to
305 be sure the position you specify is not ignored, specify a
306 non-@code{nil} value for the @code{user-position} parameter as well.
309 The screen position of the top edge, in pixels, with respect to the
310 top edge of the screen. The value may be a positive number @var{pos},
311 or a list of the form @code{(+ @var{pos})} which permits specifying a
312 negative @var{pos} value.
314 A negative number @minus{}@var{pos}, or a list of the form @code{(-
315 @var{pos})}, actually specifies the position of the bottom edge of the
316 window with respect to the bottom edge of the screen. A positive value
317 of @var{pos} counts toward the top. @strong{Reminder:} if the
318 parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
321 Some window managers ignore program-specified positions. If you want to
322 be sure the position you specify is not ignored, specify a
323 non-@code{nil} value for the @code{user-position} parameter as well.
326 The screen position of the left edge @emph{of the frame's icon}, in
327 pixels, counting from the left edge of the screen. This takes effect if
328 and when the frame is iconified.
331 The screen position of the top edge @emph{of the frame's icon}, in
332 pixels, counting from the top edge of the screen. This takes effect if
333 and when the frame is iconified.
336 When you create a frame and specify its screen position with the
337 @code{left} and @code{top} parameters, use this parameter to say whether
338 the specified position was user-specified (explicitly requested in some
339 way by a human user) or merely program-specified (chosen by a program).
340 A non-@code{nil} value says the position was user-specified.
342 Window managers generally heed user-specified positions, and some heed
343 program-specified positions too. But many ignore program-specified
344 positions, placing the window in a default fashion or letting the user
345 place it with the mouse. Some window managers, including @code{twm},
346 let the user specify whether to obey program-specified positions or
349 When you call @code{make-frame}, you should specify a non-@code{nil}
350 value for this parameter if the values of the @code{left} and @code{top}
351 parameters represent the user's stated preference; otherwise, use
355 The height of the frame contents, in characters. (To get the height in
356 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
359 The width of the frame contents, in characters. (To get the height in
360 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
363 The number of the window-system window used by the frame.
366 Whether this frame has its own minibuffer. The value @code{t} means
367 yes, @code{nil} means no, @code{only} means this frame is just a
368 minibuffer. If the value is a minibuffer window (in some other frame),
369 the new frame uses that minibuffer.
371 @item buffer-predicate
372 The buffer-predicate function for this frame. The function
373 @code{other-buffer} uses this predicate (from the selected frame) to
374 decide which buffers it should consider, if the predicate is not
375 @code{nil}. It calls the predicate with one argument, a buffer, once for
376 each buffer; if the predicate returns a non-@code{nil} value, it
377 considers that buffer.
380 A list of buffers that have been selected in this frame,
381 ordered most-recently-selected first.
384 The name of the font for displaying text in the frame. This is a
385 string, either a valid font name for your system or the name of an Emacs
386 fontset (@pxref{Fontsets}).
389 Whether selecting the frame raises it (non-@code{nil} means yes).
392 Whether deselecting the frame lowers it (non-@code{nil} means yes).
394 @item vertical-scroll-bars
395 Whether the frame has scroll bars for vertical scrolling, and which side
396 of the frame they should be on. The possible values are @code{left},
397 @code{right}, and @code{nil} for no scroll bars.
399 @item horizontal-scroll-bars
400 Whether the frame has scroll bars for horizontal scrolling
401 (non-@code{nil} means yes). (Horizontal scroll bars are not currently
404 @item scroll-bar-width
405 The width of the vertical scroll bar, in pixels.
408 The type of icon to use for this frame when it is iconified. If the
409 value is a string, that specifies a file containing a bitmap to use.
410 Any other non-@code{nil} value specifies the default bitmap icon (a
411 picture of a gnu); @code{nil} specifies a text icon.
414 The name to use in the icon for this frame, when and if the icon
415 appears. If this is @code{nil}, the frame's title is used.
417 @item foreground-color
418 The color to use for the image of a character. This is a string; the
419 window system defines the meaningful color names.
421 @item background-color
422 The color to use for the background of characters.
425 The color for the mouse pointer.
428 The color for the cursor that shows point.
431 The color for the border of the frame.
434 The way to display the cursor. The legitimate values are @code{bar},
435 @code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
436 specifies an ordinary black box overlaying the character after point;
437 that is the default. The symbol @code{bar} specifies a vertical bar
438 between characters as the cursor. @code{(bar . @var{width})} specifies
439 a bar @var{width} pixels wide.
442 The width in pixels of the window border.
444 @item internal-border-width
445 The distance in pixels between text and border.
448 If non-@code{nil}, this frame's window is never split automatically.
451 The state of visibility of the frame. There are three possibilities:
452 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
453 iconified. @xref{Visibility of Frames}.
456 The number of lines to allocate at the top of the frame for a menu bar.
457 The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
458 toolkit, there is only one menu bar line; all that matters about the
459 number you specify is whether it is greater than zero.)
463 @c ??? Not yet working.
464 The X window number of the window that should be the parent of this one.
465 Specifying this lets you create an Emacs window inside some other
466 application's window. (It is not certain this will be implemented; try
467 it and see if it works.)
471 @node Size and Position
472 @subsection Frame Size And Position
474 You can read or change the size and position of a frame using the
475 frame parameters @code{left}, @code{top}, @code{height}, and
476 @code{width}. Whatever geometry parameters you don't specify are chosen
477 by the window manager in its usual fashion.
479 Here are some special features for working with sizes and positions:
481 @defun set-frame-position frame left top
482 This function sets the position of the top left corner of @var{frame} to
483 @var{left} and @var{top}. These arguments are measured in pixels, and
484 count from the top left corner of the screen. Negative parameter values
485 count up or rightward from the top left corner of the screen.
488 @defun frame-height &optional frame
489 @defunx frame-width &optional frame
490 These functions return the height and width of @var{frame}, measured in
491 characters. If you don't supply @var{frame}, they use the selected
495 @defun frame-pixel-height &optional frame
496 @defunx frame-pixel-width &optional frame
497 These functions return the height and width of @var{frame}, measured in
498 pixels. If you don't supply @var{frame}, they use the selected frame.
501 @defun frame-char-height &optional frame
502 @defunx frame-char-width &optional frame
503 These functions return the height and width of a character in
504 @var{frame}, measured in pixels. The values depend on the choice of
505 font. If you don't supply @var{frame}, these functions use the selected
509 @defun set-frame-size frame cols rows
510 This function sets the size of @var{frame}, measured in characters;
511 @var{cols} and @var{rows} specify the new width and height.
513 To set the size based on values measured in pixels, use
514 @code{frame-char-height} and @code{frame-char-width} to convert
515 them to units of characters.
518 The old-fashioned functions @code{set-screen-height} and
519 @code{set-screen-width}, which were used to specify the height and width
520 of the screen in Emacs versions that did not support multiple frames,
521 are still usable. They apply to the selected frame. @xref{Screen
524 @defun x-parse-geometry geom
525 @cindex geometry specification
526 The function @code{x-parse-geometry} converts a standard X Windows
527 geometry string to an alist that you can use as part of the argument to
530 The alist describes which parameters were specified in @var{geom}, and
531 gives the values specified for them. Each element looks like
532 @code{(@var{parameter} . @var{value})}. The possible @var{parameter}
533 values are @code{left}, @code{top}, @code{width}, and @code{height}.
535 For the size parameters, the value must be an integer. The position
536 parameter names @code{left} and @code{top} are not totally accurate,
537 because some values indicate the position of the right or bottom edges
538 instead. These are the @var{value} possibilities for the position
543 A positive integer relates the left edge or top edge of the window to
544 the left or top edge of the screen. A negative integer relates the
545 right or bottom edge of the window to the right or bottom edge of the
548 @item @code{(+ @var{position})}
549 This specifies the position of the left or top edge of the window
550 relative to the left or top edge of the screen. The integer
551 @var{position} may be positive or negative; a negative value specifies a
552 position outside the screen.
554 @item @code{(- @var{position})}
555 This specifies the position of the right or bottom edge of the window
556 relative to the right or bottom edge of the screen. The integer
557 @var{position} may be positive or negative; a negative value specifies a
558 position outside the screen.
564 (x-parse-geometry "35x70+0-0")
565 @result{} ((width . 35) (height . 70)
566 (left . 0) (top - 0))
571 New functions @code{set-frame-height} and @code{set-frame-width} set the
572 size of a specified frame. The frame is the first argument; the size is
577 @section Frame Titles
579 Every frame has a @code{name} parameter; this serves as the default
580 for the frame title which window systems typically display at the top of
581 the frame. You can specify a name explicitly by setting the @code{name}
584 Normally you don't specify the name explicitly, and Emacs computes the
585 frame name automatically based on a template stored in the variable
586 @code{frame-title-format}. Emacs recomputes the name each time the
587 frame is redisplayed.
589 @defvar frame-title-format
590 This variable specifies how to compute a name for a frame when you have
591 not explicitly specified one. The variable's value is actually a mode
592 line construct, just like @code{mode-line-format}. @xref{Mode Line
596 @defvar icon-title-format
597 This variable specifies how to compute the name for an iconified frame,
598 when you have not explicitly specified the frame title. This title
599 appears in the icon itself.
602 @defvar multiple-frames
603 This variable is set automatically by Emacs. Its value is @code{t} when
604 there are two or more frames (not counting minibuffer-only frames or
605 invisible frames). The default value of @code{frame-title-format} uses
606 @code{multiple-frames} so as to put the buffer name in the frame title
607 only when there is more than one frame.
610 @node Deleting Frames
611 @section Deleting Frames
612 @cindex deletion of frames
614 Frames remain potentially visible until you explicitly @dfn{delete}
615 them. A deleted frame cannot appear on the screen, but continues to
616 exist as a Lisp object until there are no references to it. There is no
617 way to cancel the deletion of a frame aside from restoring a saved frame
618 configuration (@pxref{Frame Configurations}); this is similar to the
621 @deffn Command delete-frame &optional frame
622 This function deletes the frame @var{frame}. By default, @var{frame} is
626 @defun frame-live-p frame
627 The function @code{frame-live-p} returns non-@code{nil} if the frame
628 @var{frame} has not been deleted.
631 Some window managers provide a command to delete a window. These work
632 by sending a special message to the program that operates the window.
633 When Emacs gets one of these commands, it generates a
634 @code{delete-frame} event, whose normal definition is a command that
635 calls the function @code{delete-frame}. @xref{Misc Events}.
637 @node Finding All Frames
638 @section Finding All Frames
641 The function @code{frame-list} returns a list of all the frames that
642 have not been deleted. It is analogous to @code{buffer-list} for
643 buffers. The list that you get is newly created, so modifying the list
644 doesn't have any effect on the internals of Emacs.
647 @defun visible-frame-list
648 This function returns a list of just the currently visible frames.
649 @xref{Visibility of Frames}. (Terminal frames always count as
650 ``visible'', even though only the selected one is actually displayed.)
653 @defun next-frame &optional frame minibuf
654 The function @code{next-frame} lets you cycle conveniently through all
655 the frames from an arbitrary starting point. It returns the ``next''
656 frame after @var{frame} in the cycle. If @var{frame} is omitted or
657 @code{nil}, it defaults to the selected frame.
659 The second argument, @var{minibuf}, says which frames to consider:
663 Exclude minibuffer-only frames.
665 Consider all visible frames.
667 Consider all visible or iconified frames.
669 Consider only the frames using that particular window as their
676 @defun previous-frame &optional frame minibuf
677 Like @code{next-frame}, but cycles through all frames in the opposite
681 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
684 @node Frames and Windows
685 @section Frames and Windows
687 Each window is part of one and only one frame; you can get the frame
688 with @code{window-frame}.
690 @defun window-frame window
691 This function returns the frame that @var{window} is on.
694 All the non-minibuffer windows in a frame are arranged in a cyclic
695 order. The order runs from the frame's top window, which is at the
696 upper left corner, down and to the right, until it reaches the window at
697 the lower right corner (always the minibuffer window, if the frame has
698 one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
700 @defun frame-top-window frame
701 This returns the topmost, leftmost window of frame @var{frame}.
704 At any time, exactly one window on any frame is @dfn{selected within the
705 frame}. The significance of this designation is that selecting the
706 frame also selects this window. You can get the frame's current
707 selected window with @code{frame-selected-window}.
709 @defun frame-selected-window frame
710 This function returns the window on @var{frame} that is selected within
714 Conversely, selecting a window for Emacs with @code{select-window} also
715 makes that window selected within its frame. @xref{Selecting Windows}.
717 Another function that (usually) returns one of the windows in a given
718 frame is @code{minibuffer-window}. @xref{Minibuffer Misc}.
720 @node Minibuffers and Frames
721 @section Minibuffers and Frames
723 Normally, each frame has its own minibuffer window at the bottom, which
724 is used whenever that frame is selected. If the frame has a minibuffer,
725 you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
727 However, you can also create a frame with no minibuffer. Such a frame
728 must use the minibuffer window of some other frame. When you create the
729 frame, you can specify explicitly the minibuffer window to use (in some
730 other frame). If you don't, then the minibuffer is found in the frame
731 which is the value of the variable @code{default-minibuffer-frame}. Its
732 value should be a frame that does have a minibuffer.
734 If you use a minibuffer-only frame, you might want that frame to raise
735 when you enter the minibuffer. If so, set the variable
736 @code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
738 @defvar default-minibuffer-frame
739 This variable specifies the frame to use for the minibuffer window, by
740 default. It is always local to the current terminal and cannot be
741 buffer-local. @xref{Multiple Displays}.
747 @cindex selected frame
749 At any time, one frame in Emacs is the @dfn{selected frame}. The selected
750 window always resides on the selected frame.
752 @defun selected-frame
753 This function returns the selected frame.
756 Some window systems and window managers direct keyboard input to the
757 window object that the mouse is in; others require explicit clicks or
758 commands to @dfn{shift the focus} to various window objects. Either
759 way, Emacs automatically keeps track of which frame has the focus.
761 Lisp programs can also switch frames ``temporarily'' by calling the
762 function @code{select-frame}. This does not alter the window system's
763 concept of focus; rather, it escapes from the window manager's control
764 until that control is somehow reasserted.
766 When using a text-only terminal, only the selected terminal frame is
767 actually displayed on the terminal. @code{switch-frame} is the only way
768 to switch frames, and the change lasts until overridden by a subsequent
769 call to @code{switch-frame}. Each terminal screen except for the
770 initial one has a number, and the number of the selected frame appears
771 in the mode line after the word @samp{Emacs} (@pxref{Mode Line
774 @c ??? This is not yet implemented properly.
775 @defun select-frame frame
776 This function selects frame @var{frame}, temporarily disregarding the
777 focus of the X server if any. The selection of @var{frame} lasts until
778 the next time the user does something to select a different frame, or
779 until the next time this function is called.
782 Emacs cooperates with the window system by arranging to select frames as
783 the server and window manager request. It does so by generating a
784 special kind of input event, called a @dfn{focus} event, when
785 appropriate. The command loop handles a focus event by calling
786 @code{handle-switch-frame}. @xref{Focus Events}.
788 @deffn Command handle-switch-frame frame
789 This function handles a focus event by selecting frame @var{frame}.
791 Focus events normally do their job by invoking this command.
792 Don't call it for any other reason.
795 @defun redirect-frame-focus frame focus-frame
796 This function redirects focus from @var{frame} to @var{focus-frame}.
797 This means that @var{focus-frame} will receive subsequent keystrokes and
798 events intended for @var{frame}. After such an event, the value of
799 @code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
800 events specifying @var{frame} will instead select @var{focus-frame}.
802 If @var{focus-frame} is @code{nil}, that cancels any existing
803 redirection for @var{frame}, which therefore once again receives its own
806 One use of focus redirection is for frames that don't have minibuffers.
807 These frames use minibuffers on other frames. Activating a minibuffer
808 on another frame redirects focus to that frame. This puts the focus on
809 the minibuffer's frame, where it belongs, even though the mouse remains
810 in the frame that activated the minibuffer.
812 Selecting a frame can also change focus redirections. Selecting frame
813 @code{bar}, when @code{foo} had been selected, changes any redirections
814 pointing to @code{foo} so that they point to @code{bar} instead. This
815 allows focus redirection to work properly when the user switches from
816 one frame to another using @code{select-window}.
818 This means that a frame whose focus is redirected to itself is treated
819 differently from a frame whose focus is not redirected.
820 @code{select-frame} affects the former but not the latter.
822 The redirection lasts until @code{redirect-frame-focus} is called to
826 @defopt focus-follows-mouse
827 @tindex focus-follows-mouse
828 This option is how you inform Emacs whether the window manager transfers
829 focus when the user moves the mouse. Non-@code{nil} says that it does.
830 When this is so, the command @code{other-frame} moves the mouse to a
831 position consistent with the new selected frame.
834 @node Visibility of Frames
835 @section Visibility of Frames
836 @cindex visible frame
837 @cindex invisible frame
838 @cindex iconified frame
839 @cindex frame visibility
841 A window frame may be @dfn{visible}, @dfn{invisible}, or
842 @dfn{iconified}. If it is visible, you can see its contents. If it is
843 iconified, the frame's contents do not appear on the screen, but an icon
844 does. If the frame is invisible, it doesn't show on the screen, not
847 Visibility is meaningless for terminal frames, since only the selected
848 one is actually displayed in any case.
850 @deffn Command make-frame-visible &optional frame
851 This function makes frame @var{frame} visible. If you omit @var{frame},
852 it makes the selected frame visible.
855 @deffn Command make-frame-invisible &optional frame
856 This function makes frame @var{frame} invisible. If you omit
857 @var{frame}, it makes the selected frame invisible.
860 @deffn Command iconify-frame &optional frame
861 This function iconifies frame @var{frame}. If you omit @var{frame}, it
862 iconifies the selected frame.
865 @defun frame-visible-p frame
866 This returns the visibility status of frame @var{frame}. The value is
867 @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
868 @code{icon} if it is iconified.
871 The visibility status of a frame is also available as a frame
872 parameter. You can read or change it as such. @xref{Window Frame
875 The user can iconify and deiconify frames with the window manager.
876 This happens below the level at which Emacs can exert any control, but
877 Emacs does provide events that you can use to keep track of such
878 changes. @xref{Misc Events}.
880 @node Raising and Lowering
881 @section Raising and Lowering Frames
883 Most window systems use a desktop metaphor. Part of this metaphor is
884 the idea that windows are stacked in a notional third dimension
885 perpendicular to the screen surface, and thus ordered from ``highest''
886 to ``lowest''. Where two windows overlap, the one higher up covers
887 the one underneath. Even a window at the bottom of the stack can be
888 seen if no other window overlaps it.
890 @cindex raising a frame
891 @cindex lowering a frame
892 A window's place in this ordering is not fixed; in fact, users tend
893 to change the order frequently. @dfn{Raising} a window means moving
894 it ``up'', to the top of the stack. @dfn{Lowering} a window means
895 moving it to the bottom of the stack. This motion is in the notional
896 third dimension only, and does not change the position of the window
899 You can raise and lower Emacs frame Windows with these functions:
901 @deffn Command raise-frame &optional frame
902 This function raises frame @var{frame} (default, the selected frame).
905 @deffn Command lower-frame &optional frame
906 This function lowers frame @var{frame} (default, the selected frame).
909 @defopt minibuffer-auto-raise
910 If this is non-@code{nil}, activation of the minibuffer raises the frame
911 that the minibuffer window is in.
914 You can also enable auto-raise (raising automatically when a frame is
915 selected) or auto-lower (lowering automatically when it is deselected)
916 for any frame using frame parameters. @xref{Window Frame Parameters}.
918 @node Frame Configurations
919 @section Frame Configurations
920 @cindex frame configuration
922 A @dfn{frame configuration} records the current arrangement of frames,
923 all their properties, and the window configuration of each one.
924 (@xref{Window Configurations}.)
926 @defun current-frame-configuration
927 This function returns a frame configuration list that describes
928 the current arrangement of frames and their contents.
931 @defun set-frame-configuration configuration
932 This function restores the state of frames described in
937 @section Mouse Tracking
938 @cindex mouse tracking
939 @cindex tracking the mouse
941 Sometimes it is useful to @dfn{track} the mouse, which means to display
942 something to indicate where the mouse is and move the indicator as the
943 mouse moves. For efficient mouse tracking, you need a way to wait until
944 the mouse actually moves.
946 The convenient way to track the mouse is to ask for events to represent
947 mouse motion. Then you can wait for motion by waiting for an event. In
948 addition, you can easily handle any other sorts of events that may
949 occur. That is useful, because normally you don't want to track the
950 mouse forever---only until some other event, such as the release of a
953 @defspec track-mouse body@dots{}
954 This special form executes @var{body}, with generation of mouse motion
955 events enabled. Typically @var{body} would use @code{read-event} to
956 read the motion events and modify the display accordingly. @xref{Motion
957 Events}, for the format of mouse motion events.
959 The value of @code{track-mouse} is that of the last form in @var{body}.
960 You should design @var{body} to return when it sees the up-event that
961 indicates the release of the button, or whatever kind of event means
962 it is time to stop tracking.
965 The usual purpose of tracking mouse motion is to indicate on the screen
966 the consequences of pushing or releasing a button at the current
969 In many cases, you can avoid the need to track the mouse by using
970 the @code{mouse-face} text property (@pxref{Special Properties}).
971 That works at a much lower level and runs more smoothly than
972 Lisp-level mouse tracking.
975 @c These are not implemented yet.
977 These functions change the screen appearance instantaneously. The
978 effect is transient, only until the next ordinary Emacs redisplay. That
979 is OK for mouse tracking, since it doesn't make sense for mouse tracking
980 to change the text, and the body of @code{track-mouse} normally reads
981 the events itself and does not do redisplay.
983 @defun x-contour-region window beg end
984 This function draws lines to make a box around the text from @var{beg}
985 to @var{end}, in window @var{window}.
988 @defun x-uncontour-region window beg end
989 This function erases the lines that would make a box around the text
990 from @var{beg} to @var{end}, in window @var{window}. Use it to remove
991 a contour that you previously made by calling @code{x-contour-region}.
994 @defun x-draw-rectangle frame left top right bottom
995 This function draws a hollow rectangle on frame @var{frame} with the
996 specified edge coordinates, all measured in pixels from the inside top
997 left corner. It uses the cursor color, the one used for indicating the
1001 @defun x-erase-rectangle frame left top right bottom
1002 This function erases a hollow rectangle on frame @var{frame} with the
1003 specified edge coordinates, all measured in pixels from the inside top
1004 left corner. Erasure means redrawing the text and background that
1005 normally belong in the specified rectangle.
1009 @node Mouse Position
1010 @section Mouse Position
1011 @cindex mouse position
1012 @cindex position of mouse
1014 The functions @code{mouse-position} and @code{set-mouse-position}
1015 give access to the current position of the mouse.
1017 @defun mouse-position
1018 This function returns a description of the position of the mouse. The
1019 value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1020 and @var{y} are integers giving the position in characters relative to
1021 the top left corner of the inside of @var{frame}.
1024 @defun set-mouse-position frame x y
1025 This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1026 frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1027 giving the position in characters relative to the top left corner of the
1028 inside of @var{frame}. If @var{frame} is not visible, this function
1029 does nothing. The return value is not significant.
1032 @defun mouse-pixel-position
1033 This function is like @code{mouse-position} except that it returns
1034 coordinates in units of pixels rather than units of characters.
1037 @defun set-mouse-pixel-position frame x y
1038 This function warps the mouse like @code{set-mouse-position} except that
1039 @var{x} and @var{y} are in units of pixels rather than units of
1040 characters. These coordinates are not required to be within the frame.
1042 If @var{frame} is not visible, this function does nothing. The return
1043 value is not significant.
1049 @section Pop-Up Menus
1051 When using a window system, a Lisp program can pop up a menu so that
1052 the user can choose an alternative with the mouse.
1054 @defun x-popup-menu position menu
1055 This function displays a pop-up menu and returns an indication of
1056 what selection the user makes.
1058 The argument @var{position} specifies where on the screen to put the
1059 menu. It can be either a mouse button event (which says to put the menu
1060 where the user actuated the button) or a list of this form:
1063 ((@var{xoffset} @var{yoffset}) @var{window})
1067 where @var{xoffset} and @var{yoffset} are coordinates, measured in
1068 pixels, counting from the top left corner of @var{window}'s frame.
1070 If @var{position} is @code{t}, it means to use the current mouse
1071 position. If @var{position} is @code{nil}, it means to precompute the
1072 key binding equivalents for the keymaps specified in @var{menu},
1073 without actually displaying or popping up the menu.
1075 The argument @var{menu} says what to display in the menu. It can be a
1076 keymap or a list of keymaps (@pxref{Menu Keymaps}). Alternatively, it
1077 can have the following form:
1080 (@var{title} @var{pane1} @var{pane2}...)
1084 where each pane is a list of form
1087 (@var{title} (@var{line} . @var{item})...)
1090 Each @var{line} should be a string, and each @var{item} should be the
1091 value to return if that @var{line} is chosen.
1094 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1095 if you could do the job with a prefix key defined with a menu keymap.
1096 If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1097 a} can see the individual items in that menu and provide help for them.
1098 If instead you implement the menu by defining a command that calls
1099 @code{x-popup-menu}, the help facilities cannot know what happens inside
1100 that command, so they cannot give any help for the menu's items.
1102 The menu bar mechanism, which lets you switch between submenus by
1103 moving the mouse, cannot look within the definition of a command to see
1104 that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1105 submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1106 an integrated fashion. This is why all menu bar submenus are
1107 implemented with menu keymaps within the parent menu, and never with
1108 @code{x-popup-menu}. @xref{Menu Bar},
1110 If you want a menu bar submenu to have contents that vary, you should
1111 still use a menu keymap to implement it. To make the contents vary, add
1112 a hook function to @code{menu-bar-update-hook} to update the contents of
1113 the menu keymap as necessary.
1116 @section Dialog Boxes
1117 @cindex dialog boxes
1119 A dialog box is a variant of a pop-up menu---it looks a little
1120 different, it always appears in the center of a frame, and it has just
1121 one level and one pane. The main use of dialog boxes is for asking
1122 questions that the user can answer with ``yes'', ``no'', and a few other
1123 alternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} use
1124 dialog boxes instead of the keyboard, when called from commands invoked
1127 @defun x-popup-dialog position contents
1128 This function displays a pop-up dialog box and returns an indication of
1129 what selection the user makes. The argument @var{contents} specifies
1130 the alternatives to offer; it has this format:
1133 (@var{title} (@var{string} . @var{value})@dots{})
1137 which looks like the list that specifies a single pane for
1138 @code{x-popup-menu}.
1140 The return value is @var{value} from the chosen alternative.
1142 An element of the list may be just a string instead of a cons cell
1143 @code{(@var{string} . @var{value})}. That makes a box that cannot
1146 If @code{nil} appears in the list, it separates the left-hand items from
1147 the right-hand items; items that precede the @code{nil} appear on the
1148 left, and items that follow the @code{nil} appear on the right. If you
1149 don't include a @code{nil} in the list, then approximately half the
1150 items appear on each side.
1152 Dialog boxes always appear in the center of a frame; the argument
1153 @var{position} specifies which frame. The possible values are as in
1154 @code{x-popup-menu}, but the precise coordinates don't matter; only the
1157 In some configurations, Emacs cannot display a real dialog box; so
1158 instead it displays the same items in a pop-up menu in the center of the
1162 @node Pointer Shapes
1163 @section Pointer Shapes
1164 @cindex pointer shape
1165 @cindex mouse pointer shape
1167 These variables specify which shape to use for the mouse pointer in
1168 various situations, when using the X Window System:
1171 @item x-pointer-shape
1172 @vindex x-pointer-shape
1173 This variable specifies the pointer shape to use ordinarily in the Emacs
1176 @item x-sensitive-text-pointer-shape
1177 @vindex x-sensitive-text-pointer-shape
1178 This variable specifies the pointer shape to use when the mouse
1179 is over mouse-sensitive text.
1182 These variables affect newly created frames. They do not normally
1183 affect existing frames; however, if you set the mouse color of a frame,
1184 that also updates its pointer shapes based on the current values of
1185 these variables. @xref{Window Frame Parameters}.
1187 The values you can use, to specify either of these pointer shapes, are
1188 defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1189 @key{RET} x-pointer @key{RET}} to see a list of them.
1191 @node Window System Selections
1192 @section Window System Selections
1193 @cindex selection (for X windows)
1195 The X server records a set of @dfn{selections} which permit transfer of
1196 data between application programs. The various selections are
1197 distinguished by @dfn{selection types}, represented in Emacs by
1198 symbols. X clients including Emacs can read or set the selection for
1201 @defun x-set-selection type data
1202 This function sets a ``selection'' in the X server. It takes two
1203 arguments: a selection type @var{type}, and the value to assign to it,
1204 @var{data}. If @var{data} is @code{nil}, it means to clear out the
1205 selection. Otherwise, @var{data} may be a string, a symbol, an integer
1206 (or a cons of two integers or list of two integers), an overlay, or a
1207 cons of two markers pointing to the same buffer. An overlay or a pair
1208 of markers stands for text in the overlay or between the markers.
1210 The argument @var{data} may also be a vector of valid non-vector
1213 Each possible @var{type} has its own selection value, which changes
1214 independently. The usual values of @var{type} are @code{PRIMARY} and
1215 @code{SECONDARY}; these are symbols with upper-case names, in accord
1216 with X Window System conventions. The default is @code{PRIMARY}.
1219 @defun x-get-selection &optional type data-type
1220 This function accesses selections set up by Emacs or by other X
1221 clients. It takes two optional arguments, @var{type} and
1222 @var{data-type}. The default for @var{type}, the selection type, is
1225 The @var{data-type} argument specifies the form of data conversion to
1226 use, to convert the raw data obtained from another X client into Lisp
1227 data. Meaningful values include @code{TEXT}, @code{STRING},
1228 @code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
1229 @code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
1230 @code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
1231 @code{NAME}, @code{ATOM}, and @code{INTEGER}. (These are symbols with
1232 upper-case names in accord with X conventions.) The default for
1233 @var{data-type} is @code{STRING}.
1237 The X server also has a set of numbered @dfn{cut buffers} which can
1238 store text or other data being moved between applications. Cut buffers
1239 are considered obsolete, but Emacs supports them for the sake of X
1240 clients that still use them.
1242 @defun x-get-cut-buffer n
1243 This function returns the contents of cut buffer number @var{n}.
1246 @defun x-set-cut-buffer string
1247 This function stores @var{string} into the first cut buffer (cut buffer
1248 0), moving the other values down through the series of cut buffers, much
1249 like the way successive kills in Emacs move down the kill ring.
1253 @section Looking up Font Names
1255 @defun x-list-font pattern &optional face frame maximum
1256 This function returns a list of available font names that match
1257 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
1258 specified, then the list is limited to fonts that are the same size as
1259 @var{face} currently is on @var{frame}.
1261 The argument @var{pattern} should be a string, perhaps with wildcard
1262 characters: the @samp{*} character matches any substring, and the
1263 @samp{?} character matches any single character. Pattern matching
1264 of font names ignores case.
1266 If you specify @var{face} and @var{frame}, @var{face} should be a face name
1267 (a symbol) and @var{frame} should be a frame.
1269 The optional argument @var{maximum} sets a limit on how many fonts to
1270 return. If this is non-@code{nil}, then the return value is truncated
1271 after the first @var{maximum} matching fonts. Specifying a small value
1272 for @var{maximum} can make this function much faster, in cases where
1273 many fonts match the pattern.
1279 A @dfn{fontset} is a list of fonts, each assigned to a range of
1280 character codes. An individual font cannot display the whole range of
1281 characters that Emacs supports, but a fontset can. Fontsets have names,
1282 just as fonts do, and you can use a fontset name in place of a font name
1283 when you specify the ``font'' for a frame or a face. Here is
1284 information about defining a fontset under Lisp program control.
1286 @defun create-fontset-from-fontset-spec fontset-spec &optional style noerror
1287 This function defines a new fontset according to the specification
1288 string @var{fontset-spec}. The string should have this format:
1291 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
1295 Whitespace characters before and after the commas are ignored.
1297 The first part of the string, @var{fontpattern}, should have the form of
1298 a standard X font name, except that the last two fields should be
1299 @samp{fontset-@var{alias}}.
1301 Each fontset has two names, one long and one short. The long name is
1302 @var{fontpattern} in its entirety. The short name is
1303 @samp{fontset-@var{alias}}. You can refer to the fontset by either
1304 name. If a fontset with the same name already exists, an error is
1305 signaled, unless @var{noerror} is non-@code{nil}, in which case this
1306 function does nothing.
1308 The specification string also says which fonts to use in the fontset.
1309 See below for the details.
1312 If optional argument @var{style} is specified, it specifies a way to
1313 modify the fontset. It should be one of @code{bold}, @code{italic}, and
1314 @code{bold-italic}, and it says to find the bold, italic or bold-italic
1315 version of each font if possible.
1317 The construct @samp{@var{charset}:@var{font}} specifies which font to
1318 use (in this fontset) for one particular character set. Here,
1319 @var{charset} is the name of a character set, and @var{font} is the font
1320 to use for that character set. You can use this construct any number of
1321 times in the specification string.
1323 For the remaining character sets, those that you don't specify
1324 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
1325 @samp{fontset-@var{alias}} with a value that names one character set.
1326 For the @sc{ASCII} character set, @samp{fontset-@var{alias}} is replaced
1327 with @samp{ISO8859-1}.
1329 In addition, when several consecutive fields are wildcards, Emacs
1330 collapses them into a single wildcard. This is to prevent use of
1331 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
1332 for editing, and scaling a smaller font is not useful because it is
1333 better to use the smaller font in its own size, which Emacs does.
1335 Thus if @var{fontpattern} is this,
1338 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
1342 the font specification for ASCII characters would be this:
1345 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
1349 and the font specification for Chinese GB2312 characters would be this:
1352 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
1355 You may not have any Chinese font matching the above font
1356 specification. Most X distributions include only Chinese fonts that
1357 have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In
1358 such a case, @samp{Fontset-@var{n}} can be specified as below:
1361 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
1362 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
1366 Then, the font specifications for all but Chinese GB2312 characters have
1367 @samp{fixed} in the @var{family} field, and the font specification for
1368 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
1372 @section Color Names
1374 @defun x-color-defined-p color &optional frame
1375 This function reports whether a color name is meaningful. It returns
1376 @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
1377 which frame's display to ask about; if @var{frame} is omitted or
1378 @code{nil}, the selected frame is used.
1380 Note that this does not tell you whether the display you are using
1381 really supports that color. You can ask for any defined color on any
1382 kind of display, and you will get some result---that is how the X server
1383 works. Here's an approximate way to test whether your display supports
1384 the color @var{color}:
1387 (defun x-color-supported-p (color &optional frame)
1388 (and (x-color-defined-p color frame)
1389 (or (x-display-color-p frame)
1390 (member color '("black" "white"))
1391 (and (> (x-display-planes frame) 1)
1392 (equal color "gray")))))
1396 @defun x-color-values color &optional frame
1397 This function returns a value that describes what @var{color} should
1398 ideally look like. If @var{color} is defined, the value is a list of
1399 three integers, which give the amount of red, the amount of green, and
1400 the amount of blue. Each integer ranges in principle from 0 to 65535,
1401 but in practice no value seems to be above 65280. If @var{color} is not
1402 defined, the value is @code{nil}.
1405 (x-color-values "black")
1407 (x-color-values "white")
1408 @result{} (65280 65280 65280)
1409 (x-color-values "red")
1410 @result{} (65280 0 0)
1411 (x-color-values "pink")
1412 @result{} (65280 49152 51968)
1413 (x-color-values "hungry")
1417 The color values are returned for @var{frame}'s display. If @var{frame}
1418 is omitted or @code{nil}, the information is return for the selected
1423 @section X Resources
1425 @defun x-get-resource attribute class &optional component subclass
1426 The function @code{x-get-resource} retrieves a resource value from the X
1427 Windows defaults database.
1429 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
1430 This function searches using a key of the form
1431 @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
1432 under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
1435 The optional arguments @var{component} and @var{subclass} add to the key
1436 and the class, respectively. You must specify both of them or neither.
1437 If you specify them, the key is
1438 @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
1439 @samp{Emacs.@var{class}.@var{subclass}}.
1442 @defvar x-resource-class
1443 This variable specifies the application name that @code{x-get-resource}
1444 should look up. The default value is @code{"Emacs"}. You can examine X
1445 resources for application names other than ``Emacs'' by binding this
1446 variable to some other string, around a call to @code{x-get-resource}.
1449 @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
1452 @section Data about the X Server
1454 This section describes functions you can use to get information about
1455 the capabilities and origin of an X display that Emacs is using. Each
1456 of these functions lets you specify the display you are interested in:
1457 the @var{display} argument can be either a display name, or a frame
1458 (meaning use the display that frame is on). If you omit the
1459 @var{display} argument, or specify @code{nil}, that means to use the
1460 selected frame's display.
1462 @defun x-display-screens &optional display
1463 This function returns the number of screens associated with the display.
1466 @defun x-server-version &optional display
1467 This function returns the list of version numbers of the X server
1468 running the display.
1471 @defun x-server-vendor &optional display
1472 This function returns the vendor that provided the X server software.
1475 @defun x-display-pixel-height &optional display
1476 This function returns the height of the screen in pixels.
1479 @defun x-display-mm-height &optional display
1480 This function returns the height of the screen in millimeters.
1483 @defun x-display-pixel-width &optional display
1484 This function returns the width of the screen in pixels.
1487 @defun x-display-mm-width &optional display
1488 This function returns the width of the screen in millimeters.
1491 @defun x-display-backing-store &optional display
1492 This function returns the backing store capability of the screen.
1493 Values can be the symbols @code{always}, @code{when-mapped}, or
1497 @defun x-display-save-under &optional display
1498 This function returns non-@code{nil} if the display supports the
1502 @defun x-display-planes &optional display
1503 This function returns the number of planes the display supports.
1506 @defun x-display-visual-class &optional display
1507 This function returns the visual class for the screen. The value is one
1508 of the symbols @code{static-gray}, @code{gray-scale},
1509 @code{static-color}, @code{pseudo-color}, @code{true-color}, and
1510 @code{direct-color}.
1513 @defun x-display-grayscale-p &optional display
1514 This function returns @code{t} if the screen can display shades of gray.
1517 @defun x-display-color-p &optional display
1518 This function returns @code{t} if the screen is a color screen.
1521 @defun x-display-color-cells &optional display
1522 This function returns the number of color cells the screen supports.
1526 @defvar x-no-window-manager
1527 This variable's value is @code{t} if no X window manager is in use.
1533 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
1534 width and height of an X Window frame, measured in pixels.