* lisp/info.el (Info-mode-syntax-table): New variable.
[bpt/emacs.git] / doc / lispref / frames.texi
CommitLineData
b8d4c8d0
GM
1@c -*-texinfo-*-
2@c This is part of the GNU Emacs Lisp Reference Manual.
73b0cd50 3@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
5feb0b73 4@c Free Software Foundation, Inc.
b8d4c8d0 5@c See the file elisp.texi for copying conditions.
6336d8c3 6@setfilename ../../info/frames
b8d4c8d0
GM
7@node Frames, Positions, Windows, Top
8@chapter Frames
9@cindex frame
10
3ec61d4e
CY
11 A @dfn{frame} is a screen object that contains one or more Emacs
12windows (@pxref{Windows}). It is the kind of object called a
13``window'' in the terminology of graphical environments; but we can't
14call it a ``window'' here, because Emacs uses that word in a different
15way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that
16represents a frame on the screen. @xref{Frame Type}.
b8d4c8d0
GM
17
18 A frame initially contains a single main window and/or a minibuffer
19window; you can subdivide the main window vertically or horizontally
6a4cfb0c 20into smaller windows. @xref{Splitting Windows}.
b8d4c8d0 21
3ec61d4e 22@cindex terminal
20cb6c9b 23 A @dfn{terminal} is a display device capable of displaying one or
3ec61d4e
CY
24more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp
25object that represents a terminal. @xref{Terminal Type}.
20cb6c9b 26
b8d4c8d0 27@cindex terminal frame
b8d4c8d0 28@cindex window frame
3ec61d4e
CY
29 There are two classes of terminals: text-only terminals and
30graphical terminals. Text-only terminals are non-graphics-capable
31display devices, including ``terminal emulators'' such as xterm. On
32text-only terminals, each frame occupies the entire terminal screen;
33although you can create additional frames and switch between them,
34only one frame can be shown at any given time. We refer to frames on
35text-only terminals as @dfn{terminal frames}. Graphical terminals, on
36the other hand, are graphics-capable windowing systems, such as the X
37Window System. On a graphical terminal, Emacs can display multiple
38frames simultaneously. We refer to such frames as @dfn{window
39frames}.
40
41 On GNU and Unix systems, you can create additional frames on any
42available terminal, within a single Emacs session, regardless of
43whether Emacs was started on a text-only or graphical terminal. Emacs
44can display on both graphical and text-only terminals simultaneously.
45This comes in handy, for instance, when you connect to the same
46session from several remote locations. @xref{Multiple Terminals}.
b8d4c8d0
GM
47
48@defun framep object
49This predicate returns a non-@code{nil} value if @var{object} is a
50frame, and @code{nil} otherwise. For a frame, the value indicates which
51kind of display the frame uses:
52
53@table @code
54@item x
55The frame is displayed in an X window.
56@item t
57A terminal frame on a character display.
b8d4c8d0
GM
58@item w32
59The frame is displayed on MS-Windows 9X/NT.
3ec61d4e
CY
60@item ns
61The frame is displayed on a GNUstep or Macintosh Cocoa display.
b8d4c8d0
GM
62@item pc
63The frame is displayed on an MS-DOS terminal.
64@end table
65@end defun
66
20cb6c9b 67@defun frame-terminal &optional frame
3ec61d4e
CY
68This function returns the terminal object that displays @var{frame}.
69If @var{frame} is @code{nil} or unspecified, it defaults to the
70selected frame.
20cb6c9b
EZ
71@end defun
72
73@defun terminal-live-p object
74This predicate returns a non-@code{nil} value if @var{object} is a
75terminal that is alive (i.e.@: was not deleted), and @code{nil}
76otherwise. For live terminals, the return value indicates what kind
77of frames are displayed on that terminal; the list of possible values
78is the same as for @code{framep} above.
79@end defun
80
b8d4c8d0 81@menu
b4022203 82* Creating Frames:: Creating additional frames.
20cb6c9b 83* Multiple Terminals:: Displaying on several different devices.
b4022203 84* Frame Parameters:: Controlling frame size, position, font, etc.
20cb6c9b 85* Terminal Parameters:: Parameters common for all frames on terminal.
b8d4c8d0 86* Frame Titles:: Automatic updating of frame titles.
d24880de
GM
87* Deleting Frames:: Frames last until explicitly deleted.
88* Finding All Frames:: How to examine all existing frames.
89* Frames and Windows:: A frame contains windows;
90 display of text always works through windows.
91* Minibuffers and Frames:: How a frame finds the minibuffer to use.
92* Input Focus:: Specifying the selected frame.
93* Visibility of Frames:: Frames may be visible or invisible, or icons.
94* Raising and Lowering:: Raising a frame makes it hide other windows;
95 lowering it makes the others hide it.
96* Frame Configurations:: Saving the state of all frames.
97* Mouse Tracking:: Getting events that say when the mouse moves.
98* Mouse Position:: Asking where the mouse is, or moving it.
99* Pop-Up Menus:: Displaying a menu for the user to select from.
b8d4c8d0
GM
100* Dialog Boxes:: Displaying a box to ask yes or no.
101* Pointer Shape:: Specifying the shape of the mouse pointer.
102* Window System Selections:: Transferring text to and from other X clients.
103* Drag and Drop:: Internals of Drag-and-Drop implementation.
d24880de 104* Color Names:: Getting the definitions of color names.
b8d4c8d0 105* Text Terminal Colors:: Defining colors for text-only terminals.
d24880de 106* Resources:: Getting resource values from the server.
b8d4c8d0
GM
107* Display Feature Testing:: Determining the features of a terminal.
108@end menu
109
b8d4c8d0
GM
110@node Creating Frames
111@section Creating Frames
112
113To create a new frame, call the function @code{make-frame}.
114
115@defun make-frame &optional alist
116This function creates and returns a new frame, displaying the current
3ec61d4e
CY
117buffer.
118
119The @var{alist} argument is an alist that specifies frame parameters
120for the new frame. @xref{Frame Parameters}. If you specify the
121@code{terminal} parameter in @var{alist}, the new frame is created on
122that terminal. Otherwise, if you specify the @code{window-system}
123frame parameter in @var{alist}, that determines whether the frame
124should be displayed on a text-only or graphical terminal.
125@xref{Window Systems}. If neither is specified, the new frame is
126created in the same terminal as the selected frame.
127
128Any parameters not mentioned in @var{alist} default to the values in
129the alist @code{default-frame-alist} (@pxref{Initial Parameters});
130parameters not specified there default from the X resources or its
131equivalent on your operating system (@pxref{X Resources,, X Resources,
132emacs, The GNU Emacs Manual}). After the frame is created, Emacs
133applies any parameters listed in @code{frame-inherited-parameters}
134(see below) and not present in the argument, taking the values from
135the frame that was selected when @code{make-frame} was called.
b8d4c8d0
GM
136
137This function itself does not make the new frame the selected frame.
138@xref{Input Focus}. The previously selected frame remains selected.
3ec61d4e
CY
139On graphical terminals, however, the windowing system may select the
140new frame for its own reasons.
b8d4c8d0
GM
141@end defun
142
143@defvar before-make-frame-hook
3ec61d4e 144A normal hook run by @code{make-frame} before it creates the frame.
b8d4c8d0
GM
145@end defvar
146
147@defvar after-make-frame-functions
148An abnormal hook run by @code{make-frame} after it creates the frame.
149Each function in @code{after-make-frame-functions} receives one argument, the
150frame just created.
151@end defvar
152
4fb04348
EZ
153@defvar frame-inherited-parameters
154This variable specifies the list of frame parameters that a newly
155created frame inherits from the currently selected frame. For each
156parameter (a symbol) that is an element in the list and is not present
157in the argument to @code{make-frame}, the function sets the value of
158that parameter in the created frame to its value in the selected
159frame.
160@end defvar
161
3ec61d4e
CY
162@node Multiple Terminals
163@section Multiple Terminals
164@cindex multiple terminals
165@cindex multi-tty
b8d4c8d0
GM
166@cindex multiple X displays
167@cindex displays, multiple
168
3ec61d4e
CY
169 Emacs represents each terminal, whether graphical or text-only, as a
170@dfn{terminal object} data type (@pxref{Terminal Type}). On GNU and
171Unix systems, Emacs can use multiple terminals simultaneously in each
172session. On other systems, it can only use a single terminal. Each
173terminal object has the following attributes:
174
175@itemize @bullet
176@item
177The name of the device used by the terminal (e.g., @samp{:0.0} or
178@file{/dev/tty}).
179
180@item
181The terminal and keyboard coding systems used on the terminal.
182@xref{Terminal I/O Encoding}.
b8d4c8d0 183
3ec61d4e
CY
184@item
185The kind of display associated with the terminal. This is the symbol
186returned by the function @code{terminal-live-p} (i.e., @code{x},
187@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.
b8d4c8d0 188
3ec61d4e
CY
189@item
190A list of terminal parameters. @xref{Terminal Parameters}.
191@end itemize
192
193 There is no primitive for creating terminal objects. Emacs creates
194them as needed, such as when you call @code{make-frame-on-display}
195(which is described below).
196
197@defun terminal-name &optional terminal
198This function returns the file name of the device used by
199@var{terminal}. If @var{terminal} is omitted or @code{nil}, it
200defaults to the selected frame's terminal. @var{terminal} can also be
201a frame, meaning that frame's terminal.
202@end defun
203
204@defun terminal-list
205This function returns a list of all terminal objects currently in use.
206@end defun
207
208@defun get-device-terminal device
209This function returns a terminal whose device name is given by
210@var{device}. If @var{device} is a string, it can be either the file
211name of a terminal device, or the name of an X display of the form
212@samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a
213frame, this function returns that frame's terminal; @code{nil} means
214the selected frame. Finally, if @var{device} is a terminal object
215that represents a live terminal, that terminal is returned. The
216function signals an error if its argument is none of the above.
217@end defun
218
219@defun delete-terminal &optional terminal force
220This function deletes all frames on @var{terminal} and frees the
221resources used by it. It runs the abnormal hook
222@code{delete-terminal-functions}, passing @var{terminal} as the
223argument to each function.
224
225If @var{terminal} is omitted or @code{nil}, it defaults to the
226selected frame's terminal. @var{terminal} can also be a frame,
227meaning that frame's terminal.
228
229Normally, this function signals an error if you attempt to delete the
230sole active terminal, but if @var{force} is non-@code{nil}, you are
231allowed to do so. Emacs automatically calls this function when the
232last frame on a terminal is deleted (@pxref{Deleting Frames}).
233@end defun
234
235@defvar delete-terminal-functions
236An abnormal hook run by @code{delete-terminal}. Each function
237receives one argument, the @var{terminal} argument passed to
238@code{delete-terminal}. Due to technical details, the functions may
239be called either just before the terminal is deleted, or just
240afterwards.
241@end defvar
242
243@cindex terminal-local variables
b8d4c8d0
GM
244 A few Lisp variables are @dfn{terminal-local}; that is, they have a
245separate binding for each terminal. The binding in effect at any time
246is the one for the terminal that the currently selected frame belongs
247to. These variables include @code{default-minibuffer-frame},
248@code{defining-kbd-macro}, @code{last-kbd-macro}, and
3ec61d4e
CY
249@code{system-key-alist}. They are always terminal-local, and can
250never be buffer-local (@pxref{Buffer-Local Variables}).
251
252 On GNU and Unix systems, each X display is a separate graphical
253terminal. When Emacs is started from within the X window system, it
254uses the X display chosen with the @code{DISPLAY} environment
255variable, or with the @samp{--display} option. @xref{Initial
256Options,,, emacs, The GNU Emacs Manual}. Emacs can connect to other X
257displays via the command @code{make-frame-on-display}. Each X display
258has its own selected frame and its own minibuffer windows; however,
259only one of those frames is ``@emph{the} selected frame'' at any given
260moment (@pxref{Input Focus}). Emacs can even connect to other
261text-only terminals, by interacting with the @command{emacsclient}
262program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
263
264 A single X server can handle more than one display. Each X display
265has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
266The first two parts, @var{host} and @var{server}, identify the X
267server; the third part, @var{screen}, identifies a screen number on
268that X server. When you use two or more screens belonging to one
269server, Emacs knows by the similarity in their names that they share a
270single keyboard.
271
272 On some ``multi-monitor'' setups, a single X display outputs to more
273than one monitor. Currently, there is no way for Emacs to distinguish
274between the different physical monitors.
b8d4c8d0
GM
275
276@deffn Command make-frame-on-display display &optional parameters
3ec61d4e
CY
277This function creates and returns a new frame on @var{display}, taking
278the other frame parameters from the alist @var{parameters}.
279@var{display} should be the name of an X display (a string).
280
281Before creating the frame, this function ensures that Emacs is ``set
282up'' to display graphics. For instance, if Emacs has not processed X
283resources (e.g., if it was started on a text-only terminal), it does
284so at this time. In all other respects, this function behaves like
285@code{make-frame} (@pxref{Creating Frames}).
b8d4c8d0
GM
286@end deffn
287
288@defun x-display-list
3ec61d4e
CY
289This function returns a list that indicates which X displays Emacs has
290a connection to. The elements of the list are strings, and each one
291is a display name.
b8d4c8d0
GM
292@end defun
293
294@defun x-open-connection display &optional xrm-string must-succeed
3ec61d4e
CY
295This function opens a connection to the X display @var{display},
296without creating a frame on that display. Normally, Emacs Lisp
297programs need not call this function, as @code{make-frame-on-display}
298calls it automatically. The only reason for calling it is to check
299whether communication can be established with a given X display.
300
301The optional argument @var{xrm-string}, if not @code{nil}, is a string
302of resource names and values, in the same format used in the
303@file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The
304GNU Emacs Manual}. These values apply to all Emacs frames created on
305this display, overriding the resource values recorded in the X server.
306Here's an example of what this string might look like:
b8d4c8d0
GM
307
308@example
309"*BorderWidth: 3\n*InternalBorder: 2\n"
310@end example
311
b8d4c8d0
GM
312If @var{must-succeed} is non-@code{nil}, failure to open the connection
313terminates Emacs. Otherwise, it is an ordinary Lisp error.
314@end defun
315
316@defun x-close-connection display
317This function closes the connection to display @var{display}. Before
3ec61d4e
CY
318you can do this, you must first delete all the frames that were open
319on that display (@pxref{Deleting Frames}).
20cb6c9b
EZ
320@end defun
321
b8d4c8d0
GM
322@node Frame Parameters
323@section Frame Parameters
324@cindex frame parameters
325
326 A frame has many parameters that control its appearance and behavior.
327Just what parameters a frame has depends on what display mechanism it
328uses.
329
330 Frame parameters exist mostly for the sake of window systems. A
331terminal frame has a few parameters, mostly for compatibility's sake;
332only the @code{height}, @code{width}, @code{name}, @code{title},
333@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
334parameters do something special. If the terminal supports colors, the
335parameters @code{foreground-color}, @code{background-color},
336@code{background-mode} and @code{display-type} are also meaningful.
d9ce48d6
CY
337If the terminal supports frame transparency, the parameter
338@code{alpha} is also meaningful.
b8d4c8d0
GM
339
340@menu
341* Parameter Access:: How to change a frame's parameters.
d24880de 342* Initial Parameters:: Specifying frame parameters when you make a frame.
b8d4c8d0
GM
343* Window Frame Parameters:: List of frame parameters for window systems.
344* Size and Position:: Changing the size and position of a frame.
345* Geometry:: Parsing geometry specifications.
346@end menu
347
348@node Parameter Access
349@subsection Access to Frame Parameters
350
351These functions let you read and change the parameter values of a
352frame.
353
354@defun frame-parameter frame parameter
355This function returns the value of the parameter @var{parameter} (a
356symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
357selected frame's parameter. If @var{frame} has no setting for
358@var{parameter}, this function returns @code{nil}.
359@end defun
360
361@defun frame-parameters &optional frame
362The function @code{frame-parameters} returns an alist listing all the
363parameters of @var{frame} and their values. If @var{frame} is
364@code{nil} or omitted, this returns the selected frame's parameters
365@end defun
366
367@defun modify-frame-parameters frame alist
368This function alters the parameters of frame @var{frame} based on the
369elements of @var{alist}. Each element of @var{alist} has the form
370@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
371parameter. If you don't mention a parameter in @var{alist}, its value
372doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
373frame.
374@end defun
375
4fb04348 376@defun set-frame-parameter frame parm value
3c1f4619 377This function sets the frame parameter @var{parm} to the specified
4fb04348
EZ
378@var{value}. If @var{frame} is @code{nil}, it defaults to the
379selected frame.
380@end defun
381
b8d4c8d0
GM
382@defun modify-all-frames-parameters alist
383This function alters the frame parameters of all existing frames
384according to @var{alist}, then modifies @code{default-frame-alist}
385(and, if necessary, @code{initial-frame-alist}) to apply the same
386parameter values to frames that will be created henceforth.
387@end defun
388
389@node Initial Parameters
390@subsection Initial Frame Parameters
391
392You can specify the parameters for the initial startup frame
393by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
394
01f17ae2 395@defopt initial-frame-alist
b8d4c8d0
GM
396This variable's value is an alist of parameter values used when creating
397the initial window frame. You can set this variable to specify the
398appearance of the initial frame without altering subsequent frames.
399Each element has the form:
400
401@example
402(@var{parameter} . @var{value})
403@end example
404
405Emacs creates the initial frame before it reads your init
406file. After reading that file, Emacs checks @code{initial-frame-alist},
407and applies the parameter settings in the altered value to the already
408created initial frame.
409
410If these settings affect the frame geometry and appearance, you'll see
411the frame appear with the wrong ones and then change to the specified
412ones. If that bothers you, you can specify the same geometry and
413appearance with X resources; those do take effect before the frame is
414created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
415
416X resource settings typically apply to all frames. If you want to
417specify some X resources solely for the sake of the initial frame, and
418you don't want them to apply to subsequent frames, here's how to achieve
419this. Specify parameters in @code{default-frame-alist} to override the
420X resources for subsequent frames; then, to prevent these from affecting
421the initial frame, specify the same parameters in
422@code{initial-frame-alist} with values that match the X resources.
01f17ae2 423@end defopt
b8d4c8d0
GM
424
425If these parameters specify a separate minibuffer-only frame with
426@code{(minibuffer . nil)}, and you have not created one, Emacs creates
427one for you.
428
01f17ae2 429@defopt minibuffer-frame-alist
0a65633e
CY
430This variable's value is an alist of parameter values used when
431creating an initial minibuffer-only frame. This is the
432minibuffer-only frame that Emacs creates if @code{initial-frame-alist}
433specifies a frame with no minibuffer.
01f17ae2 434@end defopt
b8d4c8d0 435
01f17ae2 436@defopt default-frame-alist
b8d4c8d0
GM
437This is an alist specifying default values of frame parameters for all
438Emacs frames---the first frame, and subsequent frames. When using the X
439Window System, you can get the same results by means of X resources
440in many cases.
441
442Setting this variable does not affect existing frames.
01f17ae2 443@end defopt
b8d4c8d0 444
6a4cfb0c
MR
445Functions that display a buffer in a separate frame can override the
446default parameters by supplying their own parameters. @xref{Definition
447of special-display-frame-alist}.
b8d4c8d0
GM
448
449If you use options that specify window appearance when you invoke Emacs,
450they take effect by adding elements to @code{default-frame-alist}. One
451exception is @samp{-geometry}, which adds the specified position to
452@code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command
453Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
454
455@node Window Frame Parameters
456@subsection Window Frame Parameters
4abe5bf6 457@cindex frame parameters for windowed displays
b8d4c8d0
GM
458
459 Just what parameters a frame has depends on what display mechanism
460it uses. This section describes the parameters that have special
461meanings on some or all kinds of terminals. Of these, @code{name},
462@code{title}, @code{height}, @code{width}, @code{buffer-list} and
463@code{buffer-predicate} provide meaningful information in terminal
464frames, and @code{tty-color-mode} is meaningful @emph{only} in
465terminal frames.
466
467@menu
468* Basic Parameters:: Parameters that are fundamental.
469* Position Parameters:: The position of the frame on the screen.
470* Size Parameters:: Frame's size.
471* Layout Parameters:: Size of parts of the frame, and
472 enabling or disabling some parts.
473* Buffer Parameters:: Which buffers have been or should be shown.
474* Management Parameters:: Communicating with the window manager.
475* Cursor Parameters:: Controlling the cursor appearance.
80be4dd7 476* Font and Color Parameters:: Fonts and colors for the frame text.
b8d4c8d0
GM
477@end menu
478
479@node Basic Parameters
480@subsubsection Basic Parameters
481
482 These frame parameters give the most basic information about the
483frame. @code{title} and @code{name} are meaningful on all terminals.
484
485@table @code
4abe5bf6 486@vindex display, a frame parameter
b8d4c8d0
GM
487@item display
488The display on which to open this frame. It should be a string of the
489form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
490@code{DISPLAY} environment variable.
491
4abe5bf6 492@vindex display-type, a frame parameter
b8d4c8d0
GM
493@item display-type
494This parameter describes the range of possible colors that can be used
495in this frame. Its value is @code{color}, @code{grayscale} or
496@code{mono}.
497
4abe5bf6 498@vindex title, a frame parameter
b8d4c8d0 499@item title
7f9e0c04
RS
500If a frame has a non-@code{nil} title, it appears in the window
501system's title bar at the top of the frame, and also in the mode line
502of windows in that frame if @code{mode-line-frame-identification} uses
503@samp{%F} (@pxref{%-Constructs}). This is normally the case when
504Emacs is not using a window system, and can only display one frame at
505a time. @xref{Frame Titles}.
b8d4c8d0 506
4abe5bf6 507@vindex name, a frame parameter
b8d4c8d0
GM
508@item name
509The name of the frame. The frame name serves as a default for the frame
510title, if the @code{title} parameter is unspecified or @code{nil}. If
511you don't specify a name, Emacs sets the frame name automatically
512(@pxref{Frame Titles}).
513
514If you specify the frame name explicitly when you create the frame, the
515name is also used (instead of the name of the Emacs executable) when
516looking up X resources for the frame.
8862ffd5
LMI
517
518@item explicit-name
519If the frame name was specified explicitly when the frame was created,
520this parameter will be that name. If the frame wasn't explicitly
521named, this parameter will be @code{nil}.
b8d4c8d0
GM
522@end table
523
524@node Position Parameters
525@subsubsection Position Parameters
4abe5bf6 526@cindex window position on display
b8d4c8d0
GM
527
528 Position parameters' values are normally measured in pixels, but on
529text-only terminals they count characters or lines instead.
530
531@table @code
4abe5bf6 532@vindex left, a frame parameter
b8d4c8d0 533@item left
88076fba
GM
534The position, in pixels, of the left (or right) edge of the frame with
535respect to the left (or right) edge of the screen. The value may be:
875fc30c
GM
536
537@table @asis
538@item an integer
539A positive integer relates the left edge of the frame to the left edge
540of the screen. A negative integer relates the right frame edge to the
541right screen edge.
542
543@item @code{(+ @var{pos})}
544This specifies the position of the left frame edge relative to the left
545screen edge. The integer @var{pos} may be positive or negative; a
546negative value specifies a position outside the screen.
547
548@item @code{(- @var{pos})}
549This specifies the position of the right frame edge relative to the right
550screen edge. The integer @var{pos} may be positive or negative; a
551negative value specifies a position outside the screen.
552@end table
b8d4c8d0
GM
553
554Some window managers ignore program-specified positions. If you want to
555be sure the position you specify is not ignored, specify a
556non-@code{nil} value for the @code{user-position} parameter as well.
557
4abe5bf6 558@vindex top, a frame parameter
b8d4c8d0 559@item top
875fc30c
GM
560The screen position of the top (or bottom) edge, in pixels, with respect
561to the top (or bottom) edge of the screen. It works just like
562@code{left}, except vertically instead of horizontally.
b8d4c8d0 563
4abe5bf6 564@vindex icon-left, a frame parameter
b8d4c8d0
GM
565@item icon-left
566The screen position of the left edge @emph{of the frame's icon}, in
567pixels, counting from the left edge of the screen. This takes effect if
568and when the frame is iconified.
569
570If you specify a value for this parameter, then you must also specify
571a value for @code{icon-top} and vice versa. The window manager may
572ignore these two parameters.
573
4abe5bf6 574@vindex icon-top, a frame parameter
b8d4c8d0
GM
575@item icon-top
576The screen position of the top edge @emph{of the frame's icon}, in
577pixels, counting from the top edge of the screen. This takes effect if
578and when the frame is iconified.
579
4abe5bf6 580@vindex user-position, a frame parameter
b8d4c8d0
GM
581@item user-position
582When you create a frame and specify its screen position with the
583@code{left} and @code{top} parameters, use this parameter to say whether
584the specified position was user-specified (explicitly requested in some
585way by a human user) or merely program-specified (chosen by a program).
586A non-@code{nil} value says the position was user-specified.
587
4abe5bf6 588@cindex window positions and window managers
b8d4c8d0
GM
589Window managers generally heed user-specified positions, and some heed
590program-specified positions too. But many ignore program-specified
591positions, placing the window in a default fashion or letting the user
592place it with the mouse. Some window managers, including @code{twm},
593let the user specify whether to obey program-specified positions or
594ignore them.
595
596When you call @code{make-frame}, you should specify a non-@code{nil}
597value for this parameter if the values of the @code{left} and @code{top}
598parameters represent the user's stated preference; otherwise, use
599@code{nil}.
600@end table
601
602@node Size Parameters
603@subsubsection Size Parameters
4abe5bf6 604@cindex window size on display
b8d4c8d0
GM
605
606 Size parameters' values are normally measured in pixels, but on
607text-only terminals they count characters or lines instead.
608
609@table @code
4abe5bf6 610@vindex height, a frame parameter
b8d4c8d0
GM
611@item height
612The height of the frame contents, in characters. (To get the height in
613pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
614
4abe5bf6 615@vindex width, a frame parameter
b8d4c8d0 616@item width
101a6cea 617The width of the frame contents, in characters. (To get the width in
b8d4c8d0
GM
618pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
619
4abe5bf6 620@vindex user-size, a frame parameter
b8d4c8d0
GM
621@item user-size
622This does for the size parameters @code{height} and @code{width} what
4abe5bf6
EZ
623the @code{user-position} parameter (@pxref{Position Parameters,
624user-position}) does for the position parameters @code{top} and
625@code{left}.
b8d4c8d0 626
4abe5bf6
EZ
627@cindex full-screen frames
628@vindex fullscreen, a frame parameter
b8d4c8d0 629@item fullscreen
16d1ff5f
CY
630Specify that width, height or both shall be maximized. The value
631@code{fullwidth} specifies that width shall be as wide as possible.
3f1c6666 632The value @code{fullheight} specifies that height shall be as tall as
16d1ff5f
CY
633possible. The value @code{fullboth} specifies that both the width and
634the height shall be set to the size of the screen. The value
635@code{maximized} specifies that the frame shall be maximized. The
636difference between @code{maximized} and @code{fullboth} is that the
637former still has window manager decorations while the latter really
638covers the whole screen.
b8d4c8d0
GM
639@end table
640
641@node Layout Parameters
642@subsubsection Layout Parameters
4abe5bf6
EZ
643@cindex layout parameters of frames
644@cindex frame layout parameters
b8d4c8d0
GM
645
646 These frame parameters enable or disable various parts of the
647frame, or control their sizes.
648
649@table @code
4abe5bf6 650@vindex border-width, a frame parameter
b8d4c8d0
GM
651@item border-width
652The width in pixels of the frame's border.
653
4abe5bf6 654@vindex internal-border-width, a frame parameter
b8d4c8d0
GM
655@item internal-border-width
656The distance in pixels between text (or fringe) and the frame's border.
657
4abe5bf6 658@vindex vertical-scroll-bars, a frame parameter
b8d4c8d0
GM
659@item vertical-scroll-bars
660Whether the frame has scroll bars for vertical scrolling, and which side
661of the frame they should be on. The possible values are @code{left},
662@code{right}, and @code{nil} for no scroll bars.
663
664@ignore
4abe5bf6 665@vindex horizontal-scroll-bars, a frame parameter
b8d4c8d0
GM
666@item horizontal-scroll-bars
667Whether the frame has scroll bars for horizontal scrolling
668(non-@code{nil} means yes). Horizontal scroll bars are not currently
669implemented.
670@end ignore
671
4abe5bf6 672@vindex scroll-bar-width, a frame parameter
b8d4c8d0
GM
673@item scroll-bar-width
674The width of vertical scroll bars, in pixels, or @code{nil} meaning to
675use the default width.
676
4abe5bf6
EZ
677@vindex left-fringe, a frame parameter
678@vindex right-fringe, a frame parameter
b8d4c8d0
GM
679@item left-fringe
680@itemx right-fringe
681The default width of the left and right fringes of windows in this
682frame (@pxref{Fringes}). If either of these is zero, that effectively
40954368
CY
683removes the corresponding fringe.
684
685When you use @code{frame-parameter} to query the value of either of
686these two frame parameters, the return value is always an integer.
687When using @code{set-frame-parameter}, passing a @code{nil} value
688imposes an actual default value of 8 pixels.
b8d4c8d0
GM
689
690The combined fringe widths must add up to an integral number of
40954368
CY
691columns, so the actual default fringe widths for the frame, as
692reported by @code{frame-parameter}, may be larger than what you
693specify. Any extra width is distributed evenly between the left and
694right fringe. However, you can force one fringe or the other to a
695precise width by specifying that width as a negative integer. If both
696widths are negative, only the left fringe gets the specified width.
b8d4c8d0 697
ddb54206 698@vindex menu-bar-lines frame parameter
b8d4c8d0
GM
699@item menu-bar-lines
700The number of lines to allocate at the top of the frame for a menu
ddb54206
CY
701bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
702@xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
b8d4c8d0 703
ddb54206 704@vindex tool-bar-lines frame parameter
b8d4c8d0 705@item tool-bar-lines
ddb54206
CY
706The number of lines to use for the tool bar. The default is 1 if Tool
707Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The
708GNU Emacs Manual}.
b8d4c8d0 709
ddb54206 710@vindex tool-bar-position frame parameter
8b2dd508
JD
711@item tool-bar-position
712The position of the tool bar. Currently only for the GTK tool bar.
713Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
714The default is @code{top}.
715
4abe5bf6 716@vindex line-spacing, a frame parameter
b8d4c8d0
GM
717@item line-spacing
718Additional space to leave below each text line, in pixels (a positive
719integer). @xref{Line Height}, for more information.
720@end table
721
722@node Buffer Parameters
723@subsubsection Buffer Parameters
724
725 These frame parameters, meaningful on all kinds of terminals, deal
726with which buffers have been, or should, be displayed in the frame.
727
728@table @code
4abe5bf6 729@vindex minibuffer, a frame parameter
b8d4c8d0
GM
730@item minibuffer
731Whether this frame has its own minibuffer. The value @code{t} means
732yes, @code{nil} means no, @code{only} means this frame is just a
05be46d7
CY
733minibuffer. If the value is a minibuffer window (in some other
734frame), the frame uses that minibuffer.
735
736This frame parameter takes effect when the frame is created, and can
737not be changed afterwards.
b8d4c8d0 738
4abe5bf6 739@vindex buffer-predicate, a frame parameter
b8d4c8d0
GM
740@item buffer-predicate
741The buffer-predicate function for this frame. The function
742@code{other-buffer} uses this predicate (from the selected frame) to
743decide which buffers it should consider, if the predicate is not
744@code{nil}. It calls the predicate with one argument, a buffer, once for
745each buffer; if the predicate returns a non-@code{nil} value, it
746considers that buffer.
747
4abe5bf6 748@vindex buffer-list, a frame parameter
b8d4c8d0 749@item buffer-list
4abe5bf6
EZ
750A list of buffers that have been selected in this frame, ordered
751most-recently-selected first.
b8d4c8d0 752
4abe5bf6 753@vindex unsplittable, a frame parameter
b8d4c8d0
GM
754@item unsplittable
755If non-@code{nil}, this frame's window is never split automatically.
756@end table
757
758@node Management Parameters
759@subsubsection Window Management Parameters
4abe5bf6 760@cindex window manager interaction, and frame parameters
b8d4c8d0
GM
761
762 These frame parameters, meaningful only on window system displays,
763interact with the window manager.
764
765@table @code
4abe5bf6 766@vindex visibility, a frame parameter
b8d4c8d0
GM
767@item visibility
768The state of visibility of the frame. There are three possibilities:
769@code{nil} for invisible, @code{t} for visible, and @code{icon} for
770iconified. @xref{Visibility of Frames}.
771
4abe5bf6 772@vindex auto-raise, a frame parameter
b8d4c8d0
GM
773@item auto-raise
774Whether selecting the frame raises it (non-@code{nil} means yes).
775
4abe5bf6 776@vindex auto-lower, a frame parameter
b8d4c8d0
GM
777@item auto-lower
778Whether deselecting the frame lowers it (non-@code{nil} means yes).
779
4abe5bf6 780@vindex icon-type, a frame parameter
b8d4c8d0
GM
781@item icon-type
782The type of icon to use for this frame when it is iconified. If the
783value is a string, that specifies a file containing a bitmap to use.
784Any other non-@code{nil} value specifies the default bitmap icon (a
785picture of a gnu); @code{nil} specifies a text icon.
786
4abe5bf6 787@vindex icon-name, a frame parameter
b8d4c8d0
GM
788@item icon-name
789The name to use in the icon for this frame, when and if the icon
790appears. If this is @code{nil}, the frame's title is used.
791
4abe5bf6 792@vindex window-id, a frame parameter
b8d4c8d0
GM
793@item window-id
794The number of the window-system window used by the frame
795to contain the actual Emacs windows.
796
4abe5bf6 797@vindex outer-window-id, a frame parameter
b8d4c8d0
GM
798@item outer-window-id
799The number of the outermost window-system window used for the whole frame.
800
4abe5bf6 801@vindex wait-for-wm, a frame parameter
b8d4c8d0
GM
802@item wait-for-wm
803If non-@code{nil}, tell Xt to wait for the window manager to confirm
804geometry changes. Some window managers, including versions of Fvwm2
805and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
806prevent hanging with those window managers.
807
4abe5bf6 808@vindex sticky, a frame parameter
17db8e10
JD
809@item sticky
810If non-@code{nil}, the frame is visible on all virtual desktops on systems
811with virtual desktops.
812
b8d4c8d0 813@ignore
4abe5bf6 814@vindex parent-id, a frame parameter
b8d4c8d0
GM
815@item parent-id
816@c ??? Not yet working.
817The X window number of the window that should be the parent of this one.
818Specifying this lets you create an Emacs window inside some other
819application's window. (It is not certain this will be implemented; try
820it and see if it works.)
821@end ignore
822@end table
823
824@node Cursor Parameters
825@subsubsection Cursor Parameters
4abe5bf6 826@cindex cursor, and frame parameters
b8d4c8d0
GM
827
828 This frame parameter controls the way the cursor looks.
829
830@table @code
4abe5bf6 831@vindex cursor-type, a frame parameter
b8d4c8d0
GM
832@item cursor-type
833How to display the cursor. Legitimate values are:
834
835@table @code
836@item box
837Display a filled box. (This is the default.)
838@item hollow
839Display a hollow box.
840@item nil
841Don't display a cursor.
842@item bar
843Display a vertical bar between characters.
844@item (bar . @var{width})
845Display a vertical bar @var{width} pixels wide between characters.
846@item hbar
847Display a horizontal bar.
848@item (hbar . @var{height})
849Display a horizontal bar @var{height} pixels high.
850@end table
851@end table
852
853@vindex cursor-type
854The buffer-local variable @code{cursor-type} overrides the value of
855the @code{cursor-type} frame parameter, but if it is @code{t}, that
856means to use the cursor specified for the frame.
857
01f17ae2 858@defopt blink-cursor-alist
b8d4c8d0
GM
859This variable specifies how to blink the cursor. Each element has the
860form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
861type equals @var{on-state} (comparing using @code{equal}), the
862corresponding @var{off-state} specifies what the cursor looks like
863when it blinks ``off.'' Both @var{on-state} and @var{off-state}
864should be suitable values for the @code{cursor-type} frame parameter.
865
866There are various defaults for how to blink each type of cursor, if
867the type is not mentioned as an @var{on-state} here. Changes in this
36c763fd
RS
868variable do not take effect immediately, only when you specify the
869@code{cursor-type} frame parameter.
01f17ae2 870@end defopt
36c763fd 871
01f17ae2 872@defopt cursor-in-non-selected-windows
36c763fd
RS
873This variable controls how the cursor looks in a window that is not
874selected. It supports the same values as the @code{cursor-type} frame
875parameter; also, @code{nil} means don't display a cursor in
876nonselected windows, and @code{t} (the default) means use a standard
c333f279 877modification of the usual cursor type (solid box becomes hollow box,
36c763fd 878and bar becomes a narrower bar).
01f17ae2 879@end defopt
b8d4c8d0 880
80be4dd7
CY
881@node Font and Color Parameters
882@subsubsection Font and Color Parameters
4abe5bf6 883@cindex font and color, frame parameters
b8d4c8d0 884
80be4dd7 885 These frame parameters control the use of fonts and colors.
b8d4c8d0
GM
886
887@table @code
4abe5bf6 888@vindex font-backend, a frame parameter
80be4dd7
CY
889@item font-backend
890A list of symbols, specifying the @dfn{font backends} to use for
891drawing fonts in the frame, in order of priority. On X, there are
892currently two available font backends: @code{x} (the X core font
893driver) and @code{xft} (the Xft font driver). On other systems, there
894is only one available font backend, so it does not make sense to
895modify this frame parameter.
896
4abe5bf6 897@vindex background-mode, a frame parameter
b8d4c8d0
GM
898@item background-mode
899This parameter is either @code{dark} or @code{light}, according
900to whether the background color is a light one or a dark one.
901
4abe5bf6 902@vindex tty-color-mode, a frame parameter
b8d4c8d0
GM
903@item tty-color-mode
904@cindex standard colors for character terminals
905This parameter overrides the terminal's color support as given by the
906system's terminal capabilities database in that this parameter's value
907specifies the color mode to use in terminal frames. The value can be
908either a symbol or a number. A number specifies the number of colors
909to use (and, indirectly, what commands to issue to produce each
910color). For example, @code{(tty-color-mode . 8)} specifies use of the
911ANSI escape sequences for 8 standard text colors. A value of -1 turns
912off color support.
913
914If the parameter's value is a symbol, it specifies a number through
915the value of @code{tty-color-mode-alist}, and the associated number is
916used instead.
917
4abe5bf6 918@vindex screen-gamma, a frame parameter
b8d4c8d0
GM
919@item screen-gamma
920@cindex gamma correction
921If this is a number, Emacs performs ``gamma correction'' which adjusts
922the brightness of all colors. The value should be the screen gamma of
923your display, a floating point number.
924
925Usual PC monitors have a screen gamma of 2.2, so color values in
926Emacs, and in X windows generally, are calibrated to display properly
927on a monitor with that gamma value. If you specify 2.2 for
928@code{screen-gamma}, that means no correction is needed. Other values
929request correction, designed to make the corrected colors appear on
930your screen the way they would have appeared without correction on an
931ordinary monitor with a gamma value of 2.2.
932
933If your monitor displays colors too light, you should specify a
934@code{screen-gamma} value smaller than 2.2. This requests correction
935that makes colors darker. A screen gamma value of 1.5 may give good
936results for LCD color displays.
d9ce48d6 937
4abe5bf6 938@vindex alpha, a frame parameter
d9ce48d6
CY
939@item alpha
940@cindex opacity, frame
941@cindex transparency, frame
942@vindex frame-alpha-lower-limit
943This parameter specifies the opacity of the frame, on graphical
944displays that support variable opacity. It should be an integer
945between 0 and 100, where 0 means completely transparent and 100 means
946completely opaque. It can also have a @code{nil} value, which tells
947Emacs not to set the frame opacity (leaving it to the window manager).
948
949To prevent the frame from disappearing completely from view, the
3ec61d4e 950variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
d9ce48d6
CY
951If the value of the frame parameter is less than the value of this
952variable, Emacs uses the latter. By default,
3ec61d4e 953@code{frame-alpha-lower-limit} is 20.
d9ce48d6
CY
954
955The @code{alpha} frame parameter can also be a cons cell
956@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
957opacity of the frame when it is selected, and @samp{inactive} is the
958opactity when it is not selected.
b8d4c8d0
GM
959@end table
960
8999d86f
CY
961The following frame parameters are semi-obsolete in that they are
962automatically equivalent to particular face attributes of particular
963faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
b8d4c8d0
GM
964
965@table @code
4abe5bf6 966@vindex font, a frame parameter
b8d4c8d0
GM
967@item font
968The name of the font for displaying text in the frame. This is a
969string, either a valid font name for your system or the name of an Emacs
970fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
971attribute of the @code{default} face.
972
4abe5bf6 973@vindex foreground-color, a frame parameter
b8d4c8d0
GM
974@item foreground-color
975The color to use for the image of a character. It is equivalent to
976the @code{:foreground} attribute of the @code{default} face.
977
4abe5bf6 978@vindex background-color, a frame parameter
b8d4c8d0
GM
979@item background-color
980The color to use for the background of characters. It is equivalent to
981the @code{:background} attribute of the @code{default} face.
982
4abe5bf6 983@vindex mouse-color, a frame parameter
b8d4c8d0
GM
984@item mouse-color
985The color for the mouse pointer. It is equivalent to the @code{:background}
986attribute of the @code{mouse} face.
987
4abe5bf6 988@vindex cursor-color, a frame parameter
b8d4c8d0
GM
989@item cursor-color
990The color for the cursor that shows point. It is equivalent to the
991@code{:background} attribute of the @code{cursor} face.
992
4abe5bf6 993@vindex border-color, a frame parameter
b8d4c8d0
GM
994@item border-color
995The color for the border of the frame. It is equivalent to the
996@code{:background} attribute of the @code{border} face.
997
4abe5bf6 998@vindex scroll-bar-foreground, a frame parameter
b8d4c8d0
GM
999@item scroll-bar-foreground
1000If non-@code{nil}, the color for the foreground of scroll bars. It is
1001equivalent to the @code{:foreground} attribute of the
1002@code{scroll-bar} face.
1003
4abe5bf6 1004@vindex scroll-bar-background, a frame parameter
b8d4c8d0
GM
1005@item scroll-bar-background
1006If non-@code{nil}, the color for the background of scroll bars. It is
1007equivalent to the @code{:background} attribute of the
1008@code{scroll-bar} face.
1009@end table
1010
1011@node Size and Position
1012@subsection Frame Size And Position
1013@cindex size of frame
1014@cindex screen size
1015@cindex frame size
1016@cindex resize frame
1017
1018 You can read or change the size and position of a frame using the
1019frame parameters @code{left}, @code{top}, @code{height}, and
1020@code{width}. Whatever geometry parameters you don't specify are chosen
1021by the window manager in its usual fashion.
1022
1023 Here are some special features for working with sizes and positions.
1024(For the precise meaning of ``selected frame'' used by these functions,
1025see @ref{Input Focus}.)
1026
1027@defun set-frame-position frame left top
1028This function sets the position of the top left corner of @var{frame} to
1029@var{left} and @var{top}. These arguments are measured in pixels, and
1030normally count from the top left corner of the screen.
1031
1032Negative parameter values position the bottom edge of the window up from
1033the bottom edge of the screen, or the right window edge to the left of
1034the right edge of the screen. It would probably be better if the values
1035were always counted from the left and top, so that negative arguments
1036would position the frame partly off the top or left edge of the screen,
1037but it seems inadvisable to change that now.
1038@end defun
1039
1040@defun frame-height &optional frame
1041@defunx frame-width &optional frame
1042These functions return the height and width of @var{frame}, measured in
1043lines and columns. If you don't supply @var{frame}, they use the
1044selected frame.
1045@end defun
1046
b8d4c8d0
GM
1047@defun frame-pixel-height &optional frame
1048@defunx frame-pixel-width &optional frame
041817a4
RS
1049These functions return the height and width of the main display area
1050of @var{frame}, measured in pixels. If you don't supply @var{frame},
5feb0b73
GM
1051they use the selected frame. For a text-only terminal, the results are
1052in characters rather than pixels.
1053
1054These values include the internal borders, and windows' scroll bars and
1055fringes (which belong to individual windows, not to the frame itself).
1056The exact value of the heights depends on the window-system and toolkit
1057in use. With Gtk+, the height does not include any tool bar or menu
1058bar. With the Motif or Lucid toolkits, it includes the tool bar but
1059not the menu bar. In a graphical version with no toolkit, it includes
1060both the tool bar and menu bar. For a text-only terminal, the result
1061includes the menu bar.
b8d4c8d0
GM
1062@end defun
1063
1064@defun frame-char-height &optional frame
1065@defunx frame-char-width &optional frame
1066These functions return the height and width of a character in
1067@var{frame}, measured in pixels. The values depend on the choice of
1068font. If you don't supply @var{frame}, these functions use the selected
1069frame.
1070@end defun
1071
1072@defun set-frame-size frame cols rows
1073This function sets the size of @var{frame}, measured in characters;
1074@var{cols} and @var{rows} specify the new width and height.
1075
1076To set the size based on values measured in pixels, use
1077@code{frame-char-height} and @code{frame-char-width} to convert
1078them to units of characters.
1079@end defun
1080
1081@defun set-frame-height frame lines &optional pretend
1082This function resizes @var{frame} to a height of @var{lines} lines. The
1083sizes of existing windows in @var{frame} are altered proportionally to
1084fit.
1085
1086If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
1087lines of output in @var{frame}, but does not change its value for the
1088actual height of the frame. This is only useful for a terminal frame.
1089Using a smaller height than the terminal actually implements may be
1090useful to reproduce behavior observed on a smaller screen, or if the
1091terminal malfunctions when using its whole screen. Setting the frame
1092height ``for real'' does not always work, because knowing the correct
1093actual size may be necessary for correct cursor positioning on a
1094terminal frame.
1095@end defun
1096
1097@defun set-frame-width frame width &optional pretend
1098This function sets the width of @var{frame}, measured in characters.
1099The argument @var{pretend} has the same meaning as in
1100@code{set-frame-height}.
1101@end defun
1102
1103@findex set-screen-height
1104@findex set-screen-width
1105 The older functions @code{set-screen-height} and
1106@code{set-screen-width} were used to specify the height and width of the
1107screen, in Emacs versions that did not support multiple frames. They
1108are semi-obsolete, but still work; they apply to the selected frame.
1109
1110@node Geometry
1111@subsection Geometry
1112
1113 Here's how to examine the data in an X-style window geometry
1114specification:
1115
1116@defun x-parse-geometry geom
1117@cindex geometry specification
1118The function @code{x-parse-geometry} converts a standard X window
1119geometry string to an alist that you can use as part of the argument to
1120@code{make-frame}.
1121
1122The alist describes which parameters were specified in @var{geom}, and
1123gives the values specified for them. Each element looks like
1124@code{(@var{parameter} . @var{value})}. The possible @var{parameter}
1125values are @code{left}, @code{top}, @code{width}, and @code{height}.
1126
1127For the size parameters, the value must be an integer. The position
1128parameter names @code{left} and @code{top} are not totally accurate,
1129because some values indicate the position of the right or bottom edges
875fc30c
GM
1130instead. The @var{value} possibilities for the position parameters are:
1131an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
1132as previously described (@pxref{Position Parameters}).
b8d4c8d0
GM
1133
1134Here is an example:
1135
1136@example
1137(x-parse-geometry "35x70+0-0")
1138 @result{} ((height . 70) (width . 35)
1139 (top - 0) (left . 0))
1140@end example
1141@end defun
1142
20cb6c9b
EZ
1143@node Terminal Parameters
1144@section Terminal Parameters
1145@cindex terminal parameters
1146
2b6ae648
EZ
1147 Each terminal has a list of associated parameters. These
1148@dfn{terminal parameters} are mostly a convenient way of storage for
1149terminal-local variables, but some terminal parameters have a special
1150meaning.
1151
1152 This section describes functions to read and change the parameter values
1153of a terminal. They all accept as their argument either a terminal or
1154a frame; the latter means use that frame's terminal. An argument of
1155@code{nil} means the selected frame's terminal.
20cb6c9b
EZ
1156
1157@defun terminal-parameters &optional terminal
2b6ae648
EZ
1158This function returns an alist listing all the parameters of
1159@var{terminal} and their values.
20cb6c9b
EZ
1160@end defun
1161
1162@defun terminal-parameter terminal parameter
2b6ae648
EZ
1163This function returns the value of the parameter @var{parameter} (a
1164symbol) of @var{terminal}. If @var{terminal} has no setting for
1165@var{parameter}, this function returns @code{nil}.
20cb6c9b
EZ
1166@end defun
1167
1168@defun set-terminal-parameter terminal parameter value
2b6ae648
EZ
1169This function sets the parameter @var{parm} of @var{terminal} to the
1170specified @var{value}, and returns the previous value of that
1171parameter.
20cb6c9b
EZ
1172@end defun
1173
2b6ae648
EZ
1174Here's a list of a few terminal parameters that have a special
1175meaning:
1176
1177@table @code
1178@item background-mode
1179The classification of the terminal's background color, either
1180@code{light} or @code{dark}.
1181@item normal-erase-is-backspace
1182Value is either 1 or 0, depending on whether
1183@code{normal-erase-is-backspace-mode} is turned on or off on this
1184terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
1185@item terminal-initted
1186After the terminal is initialized, this is set to the
1187terminal-specific initialization function.
1188@end table
1189
b8d4c8d0
GM
1190@node Frame Titles
1191@section Frame Titles
1192@cindex frame title
1193
1194 Every frame has a @code{name} parameter; this serves as the default
1195for the frame title which window systems typically display at the top of
1196the frame. You can specify a name explicitly by setting the @code{name}
1197frame property.
1198
1199 Normally you don't specify the name explicitly, and Emacs computes the
1200frame name automatically based on a template stored in the variable
1201@code{frame-title-format}. Emacs recomputes the name each time the
1202frame is redisplayed.
1203
1204@defvar frame-title-format
1205This variable specifies how to compute a name for a frame when you have
1206not explicitly specified one. The variable's value is actually a mode
1207line construct, just like @code{mode-line-format}, except that the
1208@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
1209Data}.
1210@end defvar
1211
1212@defvar icon-title-format
1213This variable specifies how to compute the name for an iconified frame,
1214when you have not explicitly specified the frame title. This title
1215appears in the icon itself.
1216@end defvar
1217
1218@defvar multiple-frames
1219This variable is set automatically by Emacs. Its value is @code{t} when
1220there are two or more frames (not counting minibuffer-only frames or
1221invisible frames). The default value of @code{frame-title-format} uses
1222@code{multiple-frames} so as to put the buffer name in the frame title
1223only when there is more than one frame.
1224
1225The value of this variable is not guaranteed to be accurate except
1226while processing @code{frame-title-format} or
1227@code{icon-title-format}.
1228@end defvar
1229
1230@node Deleting Frames
1231@section Deleting Frames
1232@cindex deleting frames
1233
1234Frames remain potentially visible until you explicitly @dfn{delete}
1235them. A deleted frame cannot appear on the screen, but continues to
1236exist as a Lisp object until there are no references to it.
1237
1238@deffn Command delete-frame &optional frame force
1239@vindex delete-frame-functions
1240This function deletes the frame @var{frame}. Unless @var{frame} is a
1241tooltip, it first runs the hook @code{delete-frame-functions} (each
1242function gets one argument, @var{frame}). By default, @var{frame} is
1243the selected frame.
1244
1245A frame cannot be deleted if its minibuffer is used by other frames.
1246Normally, you cannot delete a frame if all other frames are invisible,
6a4cfb0c 1247but if @var{force} is non-@code{nil}, then you are allowed to do so.
b8d4c8d0
GM
1248@end deffn
1249
1250@defun frame-live-p frame
1251The function @code{frame-live-p} returns non-@code{nil} if the frame
1252@var{frame} has not been deleted. The possible non-@code{nil} return
1253values are like those of @code{framep}. @xref{Frames}.
1254@end defun
1255
1256 Some window managers provide a command to delete a window. These work
1257by sending a special message to the program that operates the window.
1258When Emacs gets one of these commands, it generates a
1259@code{delete-frame} event, whose normal definition is a command that
1260calls the function @code{delete-frame}. @xref{Misc Events}.
1261
1262@node Finding All Frames
1263@section Finding All Frames
1264@cindex frames, scanning all
1265
1266@defun frame-list
c15dfb29
SM
1267The function @code{frame-list} returns a list of all the live frames,
1268i.e.@: those that have not been deleted. It is analogous to
1269@code{buffer-list} for buffers, and includes frames on all terminals.
1270The list that you get is newly created, so modifying the list doesn't
1271have any effect on the internals of Emacs.
b8d4c8d0
GM
1272@end defun
1273
1274@defun visible-frame-list
1275This function returns a list of just the currently visible frames.
1276@xref{Visibility of Frames}. (Terminal frames always count as
1277``visible,'' even though only the selected one is actually displayed.)
1278@end defun
1279
1280@defun next-frame &optional frame minibuf
1281The function @code{next-frame} lets you cycle conveniently through all
1282the frames on the current display from an arbitrary starting point. It
1283returns the ``next'' frame after @var{frame} in the cycle. If
1284@var{frame} is omitted or @code{nil}, it defaults to the selected frame
1285(@pxref{Input Focus}).
1286
1287The second argument, @var{minibuf}, says which frames to consider:
1288
1289@table @asis
1290@item @code{nil}
1291Exclude minibuffer-only frames.
1292@item @code{visible}
1293Consider all visible frames.
1294@item 0
1295Consider all visible or iconified frames.
1296@item a window
1297Consider only the frames using that particular window as their
1298minibuffer.
1299@item anything else
1300Consider all frames.
1301@end table
1302@end defun
1303
1304@defun previous-frame &optional frame minibuf
1305Like @code{next-frame}, but cycles through all frames in the opposite
1306direction.
1307@end defun
1308
1309 See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
1310Window Ordering}.
1311
1312@node Frames and Windows
1313@section Frames and Windows
1314
6a4cfb0c 1315 Each window is part of one and only one frame; you can get that frame
b8d4c8d0
GM
1316with @code{window-frame}.
1317
1318@defun window-frame window
1319This function returns the frame that @var{window} is on.
1320@end defun
1321
1322 All the non-minibuffer windows in a frame are arranged in a cyclic
1323order. The order runs from the frame's top window, which is at the
1324upper left corner, down and to the right, until it reaches the window at
1325the lower right corner (always the minibuffer window, if the frame has
1326one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
1327
1328@defun frame-first-window &optional frame
1329This returns the topmost, leftmost window of frame @var{frame}.
1330If omitted or @code{nil}, @var{frame} defaults to the selected frame.
1331@end defun
1332
1333At any time, exactly one window on any frame is @dfn{selected within the
1334frame}. The significance of this designation is that selecting the
6a4cfb0c
MR
1335frame also selects this window. Conversely, selecting a window for
1336Emacs with @code{select-window} also makes that window selected within
1337its frame. @xref{Selecting Windows}.
b8d4c8d0
GM
1338
1339@defun frame-selected-window &optional frame
1340This function returns the window on @var{frame} that is selected
1341within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to
1342the selected frame.
1343@end defun
1344
6a4cfb0c 1345@defun set-frame-selected-window frame window &optional norecord
b8d4c8d0
GM
1346This sets the selected window of frame @var{frame} to @var{window}.
1347If @var{frame} is @code{nil}, it operates on the selected frame. If
1348@var{frame} is the selected frame, this makes @var{window} the
1349selected window. This function returns @var{window}.
b8d4c8d0 1350
6a4cfb0c
MR
1351Optional argument @var{norecord} non-@code{nil} means to neither change
1352the order of recently selected windows nor the buffer list (@pxref{The
1353Buffer List}).
1354@end defun
b8d4c8d0
GM
1355
1356 Another function that (usually) returns one of the windows in a given
1357frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
1358
1359@node Minibuffers and Frames
1360@section Minibuffers and Frames
1361
1362Normally, each frame has its own minibuffer window at the bottom, which
1363is used whenever that frame is selected. If the frame has a minibuffer,
1364you can get it with @code{minibuffer-window} (@pxref{Definition of
1365minibuffer-window}).
1366
1367However, you can also create a frame with no minibuffer. Such a frame
1368must use the minibuffer window of some other frame. When you create the
35a30759 1369frame, you can explicitly specify the minibuffer window to use (in some
b8d4c8d0
GM
1370other frame). If you don't, then the minibuffer is found in the frame
1371which is the value of the variable @code{default-minibuffer-frame}. Its
1372value should be a frame that does have a minibuffer.
1373
1374If you use a minibuffer-only frame, you might want that frame to raise
1375when you enter the minibuffer. If so, set the variable
1376@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
1377
1378@defvar default-minibuffer-frame
1379This variable specifies the frame to use for the minibuffer window, by
1380default. It does not affect existing frames. It is always local to
1381the current terminal and cannot be buffer-local. @xref{Multiple
3ec61d4e 1382Terminals}.
b8d4c8d0
GM
1383@end defvar
1384
1385@node Input Focus
1386@section Input Focus
1387@cindex input focus
1388@c @cindex selected frame Duplicates selected-frame
1389
1390At any time, one frame in Emacs is the @dfn{selected frame}. The selected
1391window always resides on the selected frame.
1392
1393When Emacs displays its frames on several terminals (@pxref{Multiple
3ec61d4e
CY
1394Terminals}), each terminal has its own selected frame. But only one
1395of these is ``@emph{the} selected frame'': it's the frame that belongs
1396to the terminal from which the most recent input came. That is, when
1397Emacs runs a command that came from a certain terminal, the selected
1398frame is the one of that terminal. Since Emacs runs only a single
1399command at any given time, it needs to consider only one selected
1400frame at a time; this frame is what we call @dfn{the selected frame}
1401in this manual. The display on which the selected frame is shown is
1402the @dfn{selected frame's display}.
b8d4c8d0
GM
1403
1404@defun selected-frame
1405This function returns the selected frame.
1406@end defun
1407
1408Some window systems and window managers direct keyboard input to the
1409window object that the mouse is in; others require explicit clicks or
1410commands to @dfn{shift the focus} to various window objects. Either
1411way, Emacs automatically keeps track of which frame has the focus. To
6a4cfb0c 1412explicitly switch to a different frame from a Lisp function, call
b8d4c8d0
GM
1413@code{select-frame-set-input-focus}.
1414
1415Lisp programs can also switch frames ``temporarily'' by calling the
1416function @code{select-frame}. This does not alter the window system's
1417concept of focus; rather, it escapes from the window manager's control
1418until that control is somehow reasserted.
1419
1420When using a text-only terminal, only one frame can be displayed at a
1421time on the terminal, so after a call to @code{select-frame}, the next
1422redisplay actually displays the newly selected frame. This frame
6a4cfb0c
MR
1423remains selected until a subsequent call to @code{select-frame}. Each
1424terminal frame has a number which appears in the mode line before the
1425buffer name (@pxref{Mode Line Variables}).
b8d4c8d0
GM
1426
1427@defun select-frame-set-input-focus frame
6a4cfb0c
MR
1428This function selects @var{frame}, raises it (should it happen to be
1429obscured by other frames) and tries to give it the X server's focus. On
1430a text-only terminal, the next redisplay displays the new frame on the
1431entire terminal screen. The return value of this function is not
1432significant.
b8d4c8d0
GM
1433@end defun
1434
1435@c ??? This is not yet implemented properly.
6a4cfb0c 1436@defun select-frame frame &optional norecord
b8d4c8d0
GM
1437This function selects frame @var{frame}, temporarily disregarding the
1438focus of the X server if any. The selection of @var{frame} lasts until
1439the next time the user does something to select a different frame, or
1440until the next time this function is called. (If you are using a
1441window system, the previously selected frame may be restored as the
1442selected frame after return to the command loop, because it still may
6a4cfb0c
MR
1443have the window system's input focus.)
1444
1445The specified @var{frame} becomes the selected frame, as explained
1446above, and the terminal that @var{frame} is on becomes the selected
1447terminal. The window selected within @var{frame} becomes the selected
1448window. This function returns @var{frame}, or @code{nil} if @var{frame}
1449has been deleted.
1450
1451Optional argument @var{norecord} non-@code{nil} means to neither change
1452the order of recently selected windows nor the buffer list. @xref{The
1453Buffer List}.
b8d4c8d0
GM
1454
1455In general, you should never use @code{select-frame} in a way that could
1456switch to a different terminal without switching back when you're done.
1457@end defun
1458
1459Emacs cooperates with the window system by arranging to select frames as
1460the server and window manager request. It does so by generating a
1461special kind of input event, called a @dfn{focus} event, when
1462appropriate. The command loop handles a focus event by calling
1463@code{handle-switch-frame}. @xref{Focus Events}.
1464
1465@deffn Command handle-switch-frame frame
1466This function handles a focus event by selecting frame @var{frame}.
1467
1468Focus events normally do their job by invoking this command.
1469Don't call it for any other reason.
1470@end deffn
1471
1472@defun redirect-frame-focus frame &optional focus-frame
1473This function redirects focus from @var{frame} to @var{focus-frame}.
1474This means that @var{focus-frame} will receive subsequent keystrokes and
1475events intended for @var{frame}. After such an event, the value of
1476@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
1477events specifying @var{frame} will instead select @var{focus-frame}.
1478
1479If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
1480redirection for @var{frame}, which therefore once again receives its own
1481events.
1482
1483One use of focus redirection is for frames that don't have minibuffers.
1484These frames use minibuffers on other frames. Activating a minibuffer
1485on another frame redirects focus to that frame. This puts the focus on
1486the minibuffer's frame, where it belongs, even though the mouse remains
1487in the frame that activated the minibuffer.
1488
1489Selecting a frame can also change focus redirections. Selecting frame
1490@code{bar}, when @code{foo} had been selected, changes any redirections
1491pointing to @code{foo} so that they point to @code{bar} instead. This
1492allows focus redirection to work properly when the user switches from
1493one frame to another using @code{select-window}.
1494
1495This means that a frame whose focus is redirected to itself is treated
1496differently from a frame whose focus is not redirected.
1497@code{select-frame} affects the former but not the latter.
1498
1499The redirection lasts until @code{redirect-frame-focus} is called to
1500change it.
1501@end defun
1502
1503@defopt focus-follows-mouse
1504This option is how you inform Emacs whether the window manager transfers
1505focus when the user moves the mouse. Non-@code{nil} says that it does.
1506When this is so, the command @code{other-frame} moves the mouse to a
6a4cfb0c 1507position consistent with the new selected frame.
b8d4c8d0
GM
1508@end defopt
1509
1510@node Visibility of Frames
1511@section Visibility of Frames
1512@cindex visible frame
1513@cindex invisible frame
1514@cindex iconified frame
1515@cindex frame visibility
1516
1517A window frame may be @dfn{visible}, @dfn{invisible}, or
1518@dfn{iconified}. If it is visible, you can see its contents, unless
1519other windows cover it. If it is iconified, the frame's contents do
c8736212
GM
1520not appear on the screen, but an icon does. (Note: because of the
1521way in which some window managers implement the concept of multiple
1522workspaces, or desktops, all frames on other workspaces may appear to
1523Emacs to be iconified.) If the frame is invisible, it doesn't show on
1524the screen, not even as an icon.
b8d4c8d0
GM
1525
1526Visibility is meaningless for terminal frames, since only the selected
1527one is actually displayed in any case.
1528
1529@deffn Command make-frame-visible &optional frame
1530This function makes frame @var{frame} visible. If you omit
1531@var{frame}, it makes the selected frame visible. This does not raise
1532the frame, but you can do that with @code{raise-frame} if you wish
1533(@pxref{Raising and Lowering}).
1534@end deffn
1535
1536@deffn Command make-frame-invisible &optional frame force
1537This function makes frame @var{frame} invisible. If you omit
1538@var{frame}, it makes the selected frame invisible.
1539
1540Unless @var{force} is non-@code{nil}, this function refuses to make
1541@var{frame} invisible if all other frames are invisible..
1542@end deffn
1543
1544@deffn Command iconify-frame &optional frame
1545This function iconifies frame @var{frame}. If you omit @var{frame}, it
1546iconifies the selected frame.
1547@end deffn
1548
1549@defun frame-visible-p frame
1550This returns the visibility status of frame @var{frame}. The value is
1551@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
1552@code{icon} if it is iconified.
1553
1554On a text-only terminal, all frames are considered visible, whether
1555they are currently being displayed or not, and this function returns
1556@code{t} for all frames.
1557@end defun
1558
1559 The visibility status of a frame is also available as a frame
1560parameter. You can read or change it as such. @xref{Management
1561Parameters}.
1562
1563 The user can iconify and deiconify frames with the window manager.
1564This happens below the level at which Emacs can exert any control, but
1565Emacs does provide events that you can use to keep track of such
1566changes. @xref{Misc Events}.
1567
1568@node Raising and Lowering
1569@section Raising and Lowering Frames
1570
1571 Most window systems use a desktop metaphor. Part of this metaphor is
1572the idea that windows are stacked in a notional third dimension
1573perpendicular to the screen surface, and thus ordered from ``highest''
1574to ``lowest.'' Where two windows overlap, the one higher up covers
1575the one underneath. Even a window at the bottom of the stack can be
1576seen if no other window overlaps it.
1577
1578@c @cindex raising a frame redundant with raise-frame
1579@cindex lowering a frame
1580 A window's place in this ordering is not fixed; in fact, users tend
1581to change the order frequently. @dfn{Raising} a window means moving
1582it ``up,'' to the top of the stack. @dfn{Lowering} a window means
1583moving it to the bottom of the stack. This motion is in the notional
1584third dimension only, and does not change the position of the window
1585on the screen.
1586
6a4cfb0c
MR
1587 With Emacs, frames constitute the windows in the metaphor sketched
1588above. You can raise and lower frames using these functions:
b8d4c8d0
GM
1589
1590@deffn Command raise-frame &optional frame
1591This function raises frame @var{frame} (default, the selected frame).
1592If @var{frame} is invisible or iconified, this makes it visible.
1593@end deffn
1594
1595@deffn Command lower-frame &optional frame
1596This function lowers frame @var{frame} (default, the selected frame).
1597@end deffn
1598
1599@defopt minibuffer-auto-raise
1600If this is non-@code{nil}, activation of the minibuffer raises the frame
1601that the minibuffer window is in.
1602@end defopt
1603
1604You can also enable auto-raise (raising automatically when a frame is
1605selected) or auto-lower (lowering automatically when it is deselected)
1606for any frame using frame parameters. @xref{Management Parameters}.
1607
1608@node Frame Configurations
1609@section Frame Configurations
1610@cindex frame configuration
1611
1612 A @dfn{frame configuration} records the current arrangement of frames,
1613all their properties, and the window configuration of each one.
1614(@xref{Window Configurations}.)
1615
1616@defun current-frame-configuration
1617This function returns a frame configuration list that describes
1618the current arrangement of frames and their contents.
1619@end defun
1620
1621@defun set-frame-configuration configuration &optional nodelete
1622This function restores the state of frames described in
1623@var{configuration}. However, this function does not restore deleted
1624frames.
1625
1626Ordinarily, this function deletes all existing frames not listed in
1627@var{configuration}. But if @var{nodelete} is non-@code{nil}, the
1628unwanted frames are iconified instead.
1629@end defun
1630
1631@node Mouse Tracking
1632@section Mouse Tracking
1633@cindex mouse tracking
1634@c @cindex tracking the mouse Duplicates track-mouse
1635
1636 Sometimes it is useful to @dfn{track} the mouse, which means to display
1637something to indicate where the mouse is and move the indicator as the
1638mouse moves. For efficient mouse tracking, you need a way to wait until
1639the mouse actually moves.
1640
1641 The convenient way to track the mouse is to ask for events to represent
1642mouse motion. Then you can wait for motion by waiting for an event. In
1643addition, you can easily handle any other sorts of events that may
1644occur. That is useful, because normally you don't want to track the
1645mouse forever---only until some other event, such as the release of a
1646button.
1647
1648@defspec track-mouse body@dots{}
1649This special form executes @var{body}, with generation of mouse motion
6a4cfb0c 1650events enabled. Typically, @var{body} would use @code{read-event} to
b8d4c8d0
GM
1651read the motion events and modify the display accordingly. @xref{Motion
1652Events}, for the format of mouse motion events.
1653
1654The value of @code{track-mouse} is that of the last form in @var{body}.
1655You should design @var{body} to return when it sees the up-event that
1656indicates the release of the button, or whatever kind of event means
1657it is time to stop tracking.
1658@end defspec
1659
1660The usual purpose of tracking mouse motion is to indicate on the screen
1661the consequences of pushing or releasing a button at the current
1662position.
1663
1664In many cases, you can avoid the need to track the mouse by using
1665the @code{mouse-face} text property (@pxref{Special Properties}).
1666That works at a much lower level and runs more smoothly than
1667Lisp-level mouse tracking.
1668
1669@ignore
1670@c These are not implemented yet.
1671
1672These functions change the screen appearance instantaneously. The
1673effect is transient, only until the next ordinary Emacs redisplay. That
1674is OK for mouse tracking, since it doesn't make sense for mouse tracking
1675to change the text, and the body of @code{track-mouse} normally reads
1676the events itself and does not do redisplay.
1677
1678@defun x-contour-region window beg end
1679This function draws lines to make a box around the text from @var{beg}
1680to @var{end}, in window @var{window}.
1681@end defun
1682
1683@defun x-uncontour-region window beg end
1684This function erases the lines that would make a box around the text
1685from @var{beg} to @var{end}, in window @var{window}. Use it to remove
1686a contour that you previously made by calling @code{x-contour-region}.
1687@end defun
1688
1689@defun x-draw-rectangle frame left top right bottom
1690This function draws a hollow rectangle on frame @var{frame} with the
1691specified edge coordinates, all measured in pixels from the inside top
1692left corner. It uses the cursor color, the one used for indicating the
1693location of point.
1694@end defun
1695
1696@defun x-erase-rectangle frame left top right bottom
1697This function erases a hollow rectangle on frame @var{frame} with the
1698specified edge coordinates, all measured in pixels from the inside top
1699left corner. Erasure means redrawing the text and background that
1700normally belong in the specified rectangle.
1701@end defun
1702@end ignore
1703
1704@node Mouse Position
1705@section Mouse Position
1706@cindex mouse position
1707@cindex position of mouse
1708
1709 The functions @code{mouse-position} and @code{set-mouse-position}
1710give access to the current position of the mouse.
1711
1712@defun mouse-position
1713This function returns a description of the position of the mouse. The
1714value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
1715and @var{y} are integers giving the position in characters relative to
1716the top left corner of the inside of @var{frame}.
1717@end defun
1718
1719@defvar mouse-position-function
1720If non-@code{nil}, the value of this variable is a function for
1721@code{mouse-position} to call. @code{mouse-position} calls this
1722function just before returning, with its normal return value as the
1723sole argument, and it returns whatever this function returns to it.
1724
1725This abnormal hook exists for the benefit of packages like
1726@file{xt-mouse.el} that need to do mouse handling at the Lisp level.
1727@end defvar
1728
1729@defun set-mouse-position frame x y
1730This function @dfn{warps the mouse} to position @var{x}, @var{y} in
1731frame @var{frame}. The arguments @var{x} and @var{y} are integers,
1732giving the position in characters relative to the top left corner of the
1733inside of @var{frame}. If @var{frame} is not visible, this function
1734does nothing. The return value is not significant.
1735@end defun
1736
1737@defun mouse-pixel-position
1738This function is like @code{mouse-position} except that it returns
1739coordinates in units of pixels rather than units of characters.
1740@end defun
1741
1742@defun set-mouse-pixel-position frame x y
1743This function warps the mouse like @code{set-mouse-position} except that
1744@var{x} and @var{y} are in units of pixels rather than units of
1745characters. These coordinates are not required to be within the frame.
1746
1747If @var{frame} is not visible, this function does nothing. The return
1748value is not significant.
1749@end defun
1750
c978536f
JD
1751@defun frame-pointer-visible-p &optional frame
1752This predicate function returns non-@code{nil} if the mouse pointer
1753displayed on @var{frame} is visible; otherwise it returns @code{nil}.
1754@var{frame} omitted or @code{nil} means the selected frame. This is
1755useful when @code{make-pointer-invisible} is set to @code{t}: it
1756allows to know if the pointer has been hidden.
1757@xref{Mouse Avoidance,,,emacs}.
1758@end defun
1759
b8d4c8d0
GM
1760@need 3000
1761
1762@node Pop-Up Menus
1763@section Pop-Up Menus
1764
1765 When using a window system, a Lisp program can pop up a menu so that
1766the user can choose an alternative with the mouse.
1767
1768@defun x-popup-menu position menu
1769This function displays a pop-up menu and returns an indication of
1770what selection the user makes.
1771
1772The argument @var{position} specifies where on the screen to put the
1773top left corner of the menu. It can be either a mouse button event
1774(which says to put the menu where the user actuated the button) or a
1775list of this form:
1776
1777@example
1778((@var{xoffset} @var{yoffset}) @var{window})
1779@end example
1780
1781@noindent
1782where @var{xoffset} and @var{yoffset} are coordinates, measured in
1783pixels, counting from the top left corner of @var{window}. @var{window}
1784may be a window or a frame.
1785
1786If @var{position} is @code{t}, it means to use the current mouse
1787position. If @var{position} is @code{nil}, it means to precompute the
1788key binding equivalents for the keymaps specified in @var{menu},
1789without actually displaying or popping up the menu.
1790
1791The argument @var{menu} says what to display in the menu. It can be a
1792keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
1793return value is the list of events corresponding to the user's choice.
28a88153
CY
1794This list has more than one element if the choice occurred in a
1795submenu. (Note that @code{x-popup-menu} does not actually execute the
1796command bound to that sequence of events.) On toolkits that support
1797menu titles, the title is taken from the prompt string of @var{menu}
1798if @var{menu} is a keymap, or from the prompt string of the first
1799keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
1800Menus}).
b8d4c8d0
GM
1801
1802Alternatively, @var{menu} can have the following form:
1803
1804@example
1805(@var{title} @var{pane1} @var{pane2}...)
1806@end example
1807
1808@noindent
1809where each pane is a list of form
1810
1811@example
1812(@var{title} @var{item1} @var{item2}...)
1813@end example
1814
1815Each item should normally be a cons cell @code{(@var{line} . @var{value})},
1816where @var{line} is a string, and @var{value} is the value to return if
1817that @var{line} is chosen. An item can also be a string; this makes a
1818non-selectable line in the menu.
1819
1820If the user gets rid of the menu without making a valid choice, for
1821instance by clicking the mouse away from a valid choice or by typing
1822keyboard input, then this normally results in a quit and
1823@code{x-popup-menu} does not return. But if @var{position} is a mouse
1824button event (indicating that the user invoked the menu with the
1825mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
1826@end defun
1827
1828 @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
1829if you could do the job with a prefix key defined with a menu keymap.
1830If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
1831a} can see the individual items in that menu and provide help for them.
1832If instead you implement the menu by defining a command that calls
1833@code{x-popup-menu}, the help facilities cannot know what happens inside
1834that command, so they cannot give any help for the menu's items.
1835
1836 The menu bar mechanism, which lets you switch between submenus by
1837moving the mouse, cannot look within the definition of a command to see
1838that it calls @code{x-popup-menu}. Therefore, if you try to implement a
1839submenu using @code{x-popup-menu}, it cannot work with the menu bar in
1840an integrated fashion. This is why all menu bar submenus are
1841implemented with menu keymaps within the parent menu, and never with
1842@code{x-popup-menu}. @xref{Menu Bar}.
1843
1844 If you want a menu bar submenu to have contents that vary, you should
1845still use a menu keymap to implement it. To make the contents vary, add
1846a hook function to @code{menu-bar-update-hook} to update the contents of
1847the menu keymap as necessary.
1848
1849@node Dialog Boxes
1850@section Dialog Boxes
1851@cindex dialog boxes
1852
1853 A dialog box is a variant of a pop-up menu---it looks a little
1854different, it always appears in the center of a frame, and it has just
1855one level and one or more buttons. The main use of dialog boxes is
1856for asking questions that the user can answer with ``yes,'' ``no,''
1857and a few other alternatives. With a single button, they can also
1858force the user to acknowledge important information. The functions
1859@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
1860keyboard, when called from commands invoked by mouse clicks.
1861
1862@defun x-popup-dialog position contents &optional header
1863This function displays a pop-up dialog box and returns an indication of
1864what selection the user makes. The argument @var{contents} specifies
1865the alternatives to offer; it has this format:
1866
1867@example
1868(@var{title} (@var{string} . @var{value})@dots{})
1869@end example
1870
1871@noindent
1872which looks like the list that specifies a single pane for
1873@code{x-popup-menu}.
1874
1875The return value is @var{value} from the chosen alternative.
1876
1877As for @code{x-popup-menu}, an element of the list may be just a
1878string instead of a cons cell @code{(@var{string} . @var{value})}.
1879That makes a box that cannot be selected.
1880
1881If @code{nil} appears in the list, it separates the left-hand items from
1882the right-hand items; items that precede the @code{nil} appear on the
1883left, and items that follow the @code{nil} appear on the right. If you
1884don't include a @code{nil} in the list, then approximately half the
1885items appear on each side.
1886
1887Dialog boxes always appear in the center of a frame; the argument
1888@var{position} specifies which frame. The possible values are as in
1889@code{x-popup-menu}, but the precise coordinates or the individual
1890window don't matter; only the frame matters.
1891
1892If @var{header} is non-@code{nil}, the frame title for the box is
1893@samp{Information}, otherwise it is @samp{Question}. The former is used
1894for @code{message-box} (@pxref{message-box}).
1895
1896In some configurations, Emacs cannot display a real dialog box; so
1897instead it displays the same items in a pop-up menu in the center of the
1898frame.
1899
1900If the user gets rid of the dialog box without making a valid choice,
1901for instance using the window manager, then this produces a quit and
1902@code{x-popup-dialog} does not return.
1903@end defun
1904
1905@node Pointer Shape
1906@section Pointer Shape
1907@cindex pointer shape
1908@cindex mouse pointer shape
1909
1910 You can specify the mouse pointer style for particular text or
1911images using the @code{pointer} text property, and for images with the
1912@code{:pointer} and @code{:map} image properties. The values you can
1913use in these properties are @code{text} (or @code{nil}), @code{arrow},
1914@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
1915@code{hourglass}. @code{text} stands for the usual mouse pointer
1916style used over text.
1917
1918 Over void parts of the window (parts that do not correspond to any
1919of the buffer contents), the mouse pointer usually uses the
1920@code{arrow} style, but you can specify a different style (one of
1921those above) by setting @code{void-text-area-pointer}.
1922
1923@defvar void-text-area-pointer
1924This variable specifies the mouse pointer style for void text areas.
1925These include the areas after the end of a line or below the last line
1926in the buffer. The default is to use the @code{arrow} (non-text)
1927pointer style.
1928@end defvar
1929
3568e767
JR
1930 When using X, you can specify what the @code{text} pointer style
1931really looks like by setting the variable @code{x-pointer-shape}.
b8d4c8d0
GM
1932
1933@defvar x-pointer-shape
1934This variable specifies the pointer shape to use ordinarily in the
1935Emacs frame, for the @code{text} pointer style.
1936@end defvar
1937
1938@defvar x-sensitive-text-pointer-shape
1939This variable specifies the pointer shape to use when the mouse
1940is over mouse-sensitive text.
1941@end defvar
1942
1943 These variables affect newly created frames. They do not normally
1944affect existing frames; however, if you set the mouse color of a
1945frame, that also installs the current value of those two variables.
80be4dd7 1946@xref{Font and Color Parameters}.
b8d4c8d0
GM
1947
1948 The values you can use, to specify either of these pointer shapes, are
1949defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
1950@key{RET} x-pointer @key{RET}} to see a list of them.
1951
1952@node Window System Selections
1953@section Window System Selections
1954@cindex selection (for window systems)
963578d3
CY
1955@cindex clipboard
1956@cindex primary selection
1957@cindex secondary selection
1958
1959 In the X window system, data can be transferred between different
1960applications by means of @dfn{selections}. X defines an arbitrary
1961number of @dfn{selection types}, each of which can store its own data;
1962however, only three are commonly used: the @dfn{clipboard},
1963@dfn{primary selection}, and @dfn{secondary selection}. @xref{Cut and
1964Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
1965commands that make use of these selections. This section documents
1966the low-level functions for reading and setting X selections.
b8d4c8d0
GM
1967
1968@deffn Command x-set-selection type data
963578d3
CY
1969This function sets an X selection. It takes two arguments: a
1970selection type @var{type}, and the value to assign to it, @var{data}.
1971
1972@var{type} should be a symbol; it is usually one of @code{PRIMARY},
1973@code{SECONDARY} or @code{CLIPBOARD}. These are symbols with
1974upper-case names, in accord with X Window System conventions. If
1975@var{type} is @code{nil}, that stands for @code{PRIMARY}.
1976
1977If @var{data} is @code{nil}, it means to clear out the selection.
1978Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
1979of two integers or list of two integers), an overlay, or a cons of two
1980markers pointing to the same buffer. An overlay or a pair of markers
1981stands for text in the overlay or between the markers. The argument
1982@var{data} may also be a vector of valid non-vector selection values.
b8d4c8d0
GM
1983
1984This function returns @var{data}.
1985@end deffn
1986
1987@defun x-get-selection &optional type data-type
1988This function accesses selections set up by Emacs or by other X
1989clients. It takes two optional arguments, @var{type} and
1990@var{data-type}. The default for @var{type}, the selection type, is
1991@code{PRIMARY}.
1992
1993The @var{data-type} argument specifies the form of data conversion to
1994use, to convert the raw data obtained from another X client into Lisp
1995data. Meaningful values include @code{TEXT}, @code{STRING},
1996@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
1997@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
1998@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
1999@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
2000@code{INTEGER}. (These are symbols with upper-case names in accord
2001with X conventions.) The default for @var{data-type} is
2002@code{STRING}.
2003@end defun
2004
01f17ae2 2005@defopt selection-coding-system
b8d4c8d0
GM
2006This variable specifies the coding system to use when reading and
2007writing selections or the clipboard. @xref{Coding
2008Systems}. The default is @code{compound-text-with-extensions}, which
2009converts to the text representation that X11 normally uses.
01f17ae2 2010@end defopt
b8d4c8d0
GM
2011
2012@cindex clipboard support (for MS-Windows)
2013When Emacs runs on MS-Windows, it does not implement X selections in
2014general, but it does support the clipboard. @code{x-get-selection}
2015and @code{x-set-selection} on MS-Windows support the text data type
2016only; if the clipboard holds other types of data, Emacs treats the
2017clipboard as empty.
2018
b8d4c8d0
GM
2019@node Drag and Drop
2020@section Drag and Drop
2021
2022@vindex x-dnd-test-function
2023@vindex x-dnd-known-types
2024 When a user drags something from another application over Emacs, that other
2025application expects Emacs to tell it if Emacs can handle the data that is
2026dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
2027what to reply. The default value is @code{x-dnd-default-test-function}
2028which accepts drops if the type of the data to be dropped is present in
2029@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
2030@code{x-dnd-known-types} if you want Emacs to accept or reject drops based
2031on some other criteria.
2032
2033@vindex x-dnd-types-alist
2034 If you want to change the way Emacs handles drop of different types
2035or add a new type, customize @code{x-dnd-types-alist}. This requires
2036detailed knowledge of what types other applications use for drag and
2037drop.
2038
2039@vindex dnd-protocol-alist
2040 When an URL is dropped on Emacs it may be a file, but it may also be
2041another URL type (ftp, http, etc.). Emacs first checks
2042@code{dnd-protocol-alist} to determine what to do with the URL. If
2043there is no match there and if @code{browse-url-browser-function} is
2044an alist, Emacs looks for a match there. If no match is found the
2045text for the URL is inserted. If you want to alter Emacs behavior,
2046you can customize these variables.
2047
2048@node Color Names
2049@section Color Names
2050
2051@cindex color names
2052@cindex specify color
2053@cindex numerical RGB color specification
2054 A color name is text (usually in a string) that specifies a color.
2055Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
2056are allowed; use @kbd{M-x list-colors-display} to see a list of
2057defined names. You can also specify colors numerically in forms such
2058as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
2059@var{r} specifies the red level, @var{g} specifies the green level,
2060and @var{b} specifies the blue level. You can use either one, two,
2061three, or four hex digits for @var{r}; then you must use the same
2062number of hex digits for all @var{g} and @var{b} as well, making
2063either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
2064X Window System for more details about numerical RGB specification of
2065colors.)
2066
2067 These functions provide a way to determine which color names are
2068valid, and what they look like. In some cases, the value depends on the
2069@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
2070meaning of the term ``selected frame.''
2071
73b7530a
EZ
2072 To read user input of color names with completion, use
2073@code{read-color} (@pxref{High-Level Completion, read-color}).
2074
b8d4c8d0
GM
2075@defun color-defined-p color &optional frame
2076This function reports whether a color name is meaningful. It returns
2077@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
2078which frame's display to ask about; if @var{frame} is omitted or
2079@code{nil}, the selected frame is used.
2080
2081Note that this does not tell you whether the display you are using
2082really supports that color. When using X, you can ask for any defined
2083color on any kind of display, and you will get some result---typically,
2084the closest it can do. To determine whether a frame can really display
2085a certain color, use @code{color-supported-p} (see below).
2086
2087@findex x-color-defined-p
2088This function used to be called @code{x-color-defined-p},
2089and that name is still supported as an alias.
2090@end defun
2091
2092@defun defined-colors &optional frame
2093This function returns a list of the color names that are defined
2094and supported on frame @var{frame} (default, the selected frame).
2095If @var{frame} does not support colors, the value is @code{nil}.
2096
2097@findex x-defined-colors
2098This function used to be called @code{x-defined-colors},
2099and that name is still supported as an alias.
2100@end defun
2101
2102@defun color-supported-p color &optional frame background-p
2103This returns @code{t} if @var{frame} can really display the color
2104@var{color} (or at least something close to it). If @var{frame} is
2105omitted or @code{nil}, the question applies to the selected frame.
2106
2107Some terminals support a different set of colors for foreground and
2108background. If @var{background-p} is non-@code{nil}, that means you are
2109asking whether @var{color} can be used as a background; otherwise you
2110are asking whether it can be used as a foreground.
2111
2112The argument @var{color} must be a valid color name.
2113@end defun
2114
2115@defun color-gray-p color &optional frame
2116This returns @code{t} if @var{color} is a shade of gray, as defined on
2117@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
2118question applies to the selected frame. If @var{color} is not a valid
2119color name, this function returns @code{nil}.
2120@end defun
2121
2122@defun color-values color &optional frame
2123@cindex rgb value
2124This function returns a value that describes what @var{color} should
2125ideally look like on @var{frame}. If @var{color} is defined, the
2126value is a list of three integers, which give the amount of red, the
2127amount of green, and the amount of blue. Each integer ranges in
2128principle from 0 to 65535, but some displays may not use the full
2129range. This three-element list is called the @dfn{rgb values} of the
2130color.
2131
2132If @var{color} is not defined, the value is @code{nil}.
2133
2134@example
2135(color-values "black")
2136 @result{} (0 0 0)
2137(color-values "white")
2138 @result{} (65280 65280 65280)
2139(color-values "red")
2140 @result{} (65280 0 0)
2141(color-values "pink")
2142 @result{} (65280 49152 51968)
2143(color-values "hungry")
2144 @result{} nil
2145@end example
2146
2147The color values are returned for @var{frame}'s display. If
2148@var{frame} is omitted or @code{nil}, the information is returned for
2149the selected frame's display. If the frame cannot display colors, the
2150value is @code{nil}.
2151
2152@findex x-color-values
2153This function used to be called @code{x-color-values},
2154and that name is still supported as an alias.
2155@end defun
2156
2157@node Text Terminal Colors
2158@section Text Terminal Colors
2159@cindex colors on text-only terminals
2160
2161 Text-only terminals usually support only a small number of colors,
2162and the computer uses small integers to select colors on the terminal.
2163This means that the computer cannot reliably tell what the selected
2164color looks like; instead, you have to inform your application which
2165small integers correspond to which colors. However, Emacs does know
2166the standard set of colors and will try to use them automatically.
2167
2168 The functions described in this section control how terminal colors
2169are used by Emacs.
2170
2171 Several of these functions use or return @dfn{rgb values}, described
2172in @ref{Color Names}.
2173
2174 These functions accept a display (either a frame or the name of a
ee1b1917
CY
2175terminal) as an optional argument. We hope in the future to make
2176Emacs support different colors on different text-only terminals; then
2177this argument will specify which terminal to operate on (the default
2178being the selected frame's terminal; @pxref{Input Focus}). At
2179present, though, the @var{frame} argument has no effect.
b8d4c8d0
GM
2180
2181@defun tty-color-define name number &optional rgb frame
2182This function associates the color name @var{name} with
2183color number @var{number} on the terminal.
2184
2185The optional argument @var{rgb}, if specified, is an rgb value, a list
2186of three numbers that specify what the color actually looks like.
2187If you do not specify @var{rgb}, then this color cannot be used by
2188@code{tty-color-approximate} to approximate other colors, because
2189Emacs will not know what it looks like.
2190@end defun
2191
2192@defun tty-color-clear &optional frame
2193This function clears the table of defined colors for a text-only terminal.
2194@end defun
2195
2196@defun tty-color-alist &optional frame
2197This function returns an alist recording the known colors supported by a
2198text-only terminal.
2199
2200Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
2201or @code{(@var{name} @var{number})}. Here, @var{name} is the color
2202name, @var{number} is the number used to specify it to the terminal.
2203If present, @var{rgb} is a list of three color values (for red, green,
2204and blue) that says what the color actually looks like.
2205@end defun
2206
2207@defun tty-color-approximate rgb &optional frame
2208This function finds the closest color, among the known colors
2209supported for @var{display}, to that described by the rgb value
2210@var{rgb} (a list of color values). The return value is an element of
2211@code{tty-color-alist}.
2212@end defun
2213
2214@defun tty-color-translate color &optional frame
2215This function finds the closest color to @var{color} among the known
2216colors supported for @var{display} and returns its index (an integer).
2217If the name @var{color} is not defined, the value is @code{nil}.
2218@end defun
2219
2220@node Resources
2221@section X Resources
2222
16d1ff5f
CY
2223This section describes some of the functions and variables for
2224querying and using X resources, or their equivalent on your operating
2225system. @xref{X Resources,, X Resources, emacs, The GNU Emacs
2226Manual}, for more information about X resources.
2227
b8d4c8d0
GM
2228@defun x-get-resource attribute class &optional component subclass
2229The function @code{x-get-resource} retrieves a resource value from the X
2230Window defaults database.
2231
2232Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
2233This function searches using a key of the form
2234@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
2235under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
2236the class.
2237
2238The optional arguments @var{component} and @var{subclass} add to the key
2239and the class, respectively. You must specify both of them or neither.
2240If you specify them, the key is
2241@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
2242@samp{Emacs.@var{class}.@var{subclass}}.
2243@end defun
2244
2245@defvar x-resource-class
2246This variable specifies the application name that @code{x-get-resource}
2247should look up. The default value is @code{"Emacs"}. You can examine X
2248resources for application names other than ``Emacs'' by binding this
2249variable to some other string, around a call to @code{x-get-resource}.
2250@end defvar
2251
2252@defvar x-resource-name
2253This variable specifies the instance name that @code{x-get-resource}
2254should look up. The default value is the name Emacs was invoked with,
2255or the value specified with the @samp{-name} or @samp{-rn} switches.
2256@end defvar
2257
2258To illustrate some of the above, suppose that you have the line:
2259
2260@example
2261xterm.vt100.background: yellow
2262@end example
2263
2264@noindent
2265in your X resources file (whose name is usually @file{~/.Xdefaults}
2266or @file{~/.Xresources}). Then:
2267
2268@example
2269@group
2270(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2271 (x-get-resource "vt100.background" "VT100.Background"))
2272 @result{} "yellow"
2273@end group
2274@group
2275(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
2276 (x-get-resource "background" "VT100" "vt100" "Background"))
2277 @result{} "yellow"
2278@end group
2279@end example
2280
16d1ff5f
CY
2281@defvar inhibit-x-resources
2282If this variable is non-@code{nil}, Emacs does not look up X
2283resources, and X resources do not have any effect when creating new
2284frames.
2285@end defvar
b8d4c8d0
GM
2286
2287@node Display Feature Testing
2288@section Display Feature Testing
2289@cindex display feature testing
2290
2291 The functions in this section describe the basic capabilities of a
2292particular display. Lisp programs can use them to adapt their behavior
2293to what the display can do. For example, a program that ordinarily uses
2294a popup menu could use the minibuffer if popup menus are not supported.
2295
2296 The optional argument @var{display} in these functions specifies which
2297display to ask the question about. It can be a display name, a frame
2298(which designates the display that frame is on), or @code{nil} (which
2299refers to the selected frame's display, @pxref{Input Focus}).
2300
2301 @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
2302obtain information about displays.
2303
2304@defun display-popup-menus-p &optional display
2305This function returns @code{t} if popup menus are supported on
2306@var{display}, @code{nil} if not. Support for popup menus requires that
2307the mouse be available, since the user cannot choose menu items without
2308a mouse.
2309@end defun
2310
2311@defun display-graphic-p &optional display
2312This function returns @code{t} if @var{display} is a graphic display
2313capable of displaying several frames and several different fonts at
2314once. This is true for displays that use a window system such as X, and
2315false for text-only terminals.
2316@end defun
2317
2318@defun display-mouse-p &optional display
2319@cindex mouse, availability
2320This function returns @code{t} if @var{display} has a mouse available,
2321@code{nil} if not.
2322@end defun
2323
2324@defun display-color-p &optional display
2325@findex x-display-color-p
2326This function returns @code{t} if the screen is a color screen.
2327It used to be called @code{x-display-color-p}, and that name
2328is still supported as an alias.
2329@end defun
2330
2331@defun display-grayscale-p &optional display
2332This function returns @code{t} if the screen can display shades of gray.
2333(All color displays can do this.)
2334@end defun
2335
2336@defun display-supports-face-attributes-p attributes &optional display
2337@anchor{Display Face Attribute Testing}
2338This function returns non-@code{nil} if all the face attributes in
2339@var{attributes} are supported (@pxref{Face Attributes}).
2340
2341The definition of `supported' is somewhat heuristic, but basically
2342means that a face containing all the attributes in @var{attributes},
2343when merged with the default face for display, can be represented in a
2344way that's
2345
2346@enumerate
2347@item
2348different in appearance than the default face, and
2349
2350@item
2351`close in spirit' to what the attributes specify, if not exact.
2352@end enumerate
2353
2354Point (2) implies that a @code{:weight black} attribute will be
2355satisfied by any display that can display bold, as will
2356@code{:foreground "yellow"} as long as some yellowish color can be
2357displayed, but @code{:slant italic} will @emph{not} be satisfied by
2358the tty display code's automatic substitution of a `dim' face for
2359italic.
2360@end defun
2361
2362@defun display-selections-p &optional display
2363This function returns @code{t} if @var{display} supports selections.
2364Windowed displays normally support selections, but they may also be
2365supported in some other cases.
2366@end defun
2367
2368@defun display-images-p &optional display
2369This function returns @code{t} if @var{display} can display images.
2370Windowed displays ought in principle to handle images, but some
2371systems lack the support for that. On a display that does not support
2372images, Emacs cannot display a tool bar.
2373@end defun
2374
2375@defun display-screens &optional display
2376This function returns the number of screens associated with the display.
2377@end defun
2378
2379@defun display-pixel-height &optional display
2380This function returns the height of the screen in pixels.
2381On a character terminal, it gives the height in characters.
2382
2383For graphical terminals, note that on ``multi-monitor'' setups this
2384refers to the pixel width for all physical monitors associated with
3ec61d4e 2385@var{display}. @xref{Multiple Terminals}.
b8d4c8d0
GM
2386@end defun
2387
2388@defun display-pixel-width &optional display
2389This function returns the width of the screen in pixels.
2390On a character terminal, it gives the width in characters.
2391
2392For graphical terminals, note that on ``multi-monitor'' setups this
2393refers to the pixel width for all physical monitors associated with
3ec61d4e 2394@var{display}. @xref{Multiple Terminals}.
b8d4c8d0
GM
2395@end defun
2396
2397@defun display-mm-height &optional display
2398This function returns the height of the screen in millimeters,
2399or @code{nil} if Emacs cannot get that information.
2400@end defun
2401
2402@defun display-mm-width &optional display
2403This function returns the width of the screen in millimeters,
2404or @code{nil} if Emacs cannot get that information.
2405@end defun
2406
01f17ae2 2407@defopt display-mm-dimensions-alist
b8d4c8d0
GM
2408This variable allows the user to specify the dimensions of graphical
2409displays returned by @code{display-mm-height} and
2410@code{display-mm-width} in case the system provides incorrect values.
01f17ae2 2411@end defopt
b8d4c8d0
GM
2412
2413@defun display-backing-store &optional display
2414This function returns the backing store capability of the display.
2415Backing store means recording the pixels of windows (and parts of
2416windows) that are not exposed, so that when exposed they can be
2417displayed very quickly.
2418
2419Values can be the symbols @code{always}, @code{when-mapped}, or
2420@code{not-useful}. The function can also return @code{nil}
2421when the question is inapplicable to a certain kind of display.
2422@end defun
2423
2424@defun display-save-under &optional display
2425This function returns non-@code{nil} if the display supports the
2426SaveUnder feature. That feature is used by pop-up windows
2427to save the pixels they obscure, so that they can pop down
2428quickly.
2429@end defun
2430
2431@defun display-planes &optional display
2432This function returns the number of planes the display supports.
2433This is typically the number of bits per pixel.
2434For a tty display, it is log to base two of the number of colors supported.
2435@end defun
2436
2437@defun display-visual-class &optional display
7261e1cf
LMI
2438This function returns the visual class for the screen. The value is
2439one of the symbols @code{static-gray} (a limited, unchangeable number
2440of grays), @code{gray-scale} (a full range of grays),
2441@code{static-color} (a limited, unchangeable number of colors),
2442@code{pseudo-color} (a limited number of colors), @code{true-color} (a
2443full range of colors), and @code{direct-color} (a full range of
2444colors).
b8d4c8d0
GM
2445@end defun
2446
2447@defun display-color-cells &optional display
2448This function returns the number of color cells the screen supports.
2449@end defun
2450
2451 These functions obtain additional information specifically
2452about X displays.
2453
2454@defun x-server-version &optional display
2455This function returns the list of version numbers of the X server
2456running the display. The value is a list of three integers: the major
2457and minor version numbers of the X protocol, and the
2458distributor-specific release number of the X server software itself.
2459@end defun
2460
2461@defun x-server-vendor &optional display
2462This function returns the ``vendor'' that provided the X server
2463software (as a string). Really this means whoever distributes the X
2464server.
2465
2466When the developers of X labelled software distributors as
2467``vendors,'' they showed their false assumption that no system could
2468ever be developed and distributed noncommercially.
2469@end defun
2470
2471@ignore
2472@defvar x-no-window-manager
2473This variable's value is @code{t} if no X window manager is in use.
2474@end defvar
2475@end ignore
2476
2477@ignore
2478@item
2479The functions @code{x-pixel-width} and @code{x-pixel-height} return the
2480width and height of an X Window frame, measured in pixels.
2481@end ignore
2482