frames.texi 96.3 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2 3
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
Glenn Morris's avatar
Glenn Morris committed
4
@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009  Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@setfilename ../../info/frames
Glenn Morris's avatar
Glenn Morris committed
7 8 9 10
@node Frames, Positions, Windows, Top
@chapter Frames
@cindex frame

11 12 13 14 15 16
  A @dfn{frame} is a screen object that contains one or more Emacs
windows (@pxref{Windows}).  It is the kind of object called a
``window'' in the terminology of graphical environments; but we can't
call it a ``window'' here, because Emacs uses that word in a different
way.  In Emacs Lisp, a @dfn{frame object} is a Lisp object that
represents a frame on the screen.  @xref{Frame Type}.
Glenn Morris's avatar
Glenn Morris committed
17 18 19

  A frame initially contains a single main window and/or a minibuffer
window; you can subdivide the main window vertically or horizontally
20
into smaller windows.  @xref{Splitting Windows}.
Glenn Morris's avatar
Glenn Morris committed
21

22
@cindex terminal
23
  A @dfn{terminal} is a display device capable of displaying one or
24 25
more Emacs frames.  In Emacs Lisp, a @dfn{terminal object} is a Lisp
object that represents a terminal.  @xref{Terminal Type}.
26

Glenn Morris's avatar
Glenn Morris committed
27 28
@cindex terminal frame
@cindex window frame
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
  There are two classes of terminals: text-only terminals and
graphical terminals.  Text-only terminals are non-graphics-capable
display devices, including ``terminal emulators'' such as xterm.  On
text-only terminals, each frame occupies the entire terminal screen;
although you can create additional frames and switch between them,
only one frame can be shown at any given time.  We refer to frames on
text-only terminals as @dfn{terminal frames}.  Graphical terminals, on
the other hand, are graphics-capable windowing systems, such as the X
Window System.  On a graphical terminal, Emacs can display multiple
frames simultaneously.  We refer to such frames as @dfn{window
frames}.

  On GNU and Unix systems, you can create additional frames on any
available terminal, within a single Emacs session, regardless of
whether Emacs was started on a text-only or graphical terminal.  Emacs
can display on both graphical and text-only terminals simultaneously.
This comes in handy, for instance, when you connect to the same
session from several remote locations.  @xref{Multiple Terminals}.
Glenn Morris's avatar
Glenn Morris committed
47 48 49 50 51 52 53 54 55 56 57 58 59

@defun framep object
This predicate returns a non-@code{nil} value if @var{object} is a
frame, and @code{nil} otherwise.  For a frame, the value indicates which
kind of display the frame uses:

@table @code
@item x
The frame is displayed in an X window.
@item t
A terminal frame on a character display.
@item w32
The frame is displayed on MS-Windows 9X/NT.
60 61
@item ns
The frame is displayed on a GNUstep or Macintosh Cocoa display.
Glenn Morris's avatar
Glenn Morris committed
62 63 64 65 66
@item pc
The frame is displayed on an MS-DOS terminal.
@end table
@end defun

67
@defun frame-terminal &optional frame
68 69 70
This function returns the terminal object that displays @var{frame}.
If @var{frame} is @code{nil} or unspecified, it defaults to the
selected frame.
71 72 73 74 75 76 77 78 79 80
@end defun

@defun terminal-live-p object
This predicate returns a non-@code{nil} value if @var{object} is a
terminal that is alive (i.e.@: was not deleted), and @code{nil}
otherwise.  For live terminals, the return value indicates what kind
of frames are displayed on that terminal; the list of possible values
is the same as for @code{framep} above.
@end defun

Glenn Morris's avatar
Glenn Morris committed
81
@menu
82
* Creating Frames::             Creating additional frames.
83
* Multiple Terminals::          Displaying on several different devices.
84
* Frame Parameters::            Controlling frame size, position, font, etc.
85
* Terminal Parameters::         Parameters common for all frames on terminal.
Glenn Morris's avatar
Glenn Morris committed
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
* Frame Titles::                Automatic updating of frame titles.
* Deleting Frames::		Frames last until explicitly deleted.
* Finding All Frames::		How to examine all existing frames.
* Frames and Windows::		A frame contains windows;
				  display of text always works through windows.
* Minibuffers and Frames::	How a frame finds the minibuffer to use.
* Input Focus::			Specifying the selected frame.
* Visibility of Frames::	Frames may be visible or invisible, or icons.
* Raising and Lowering::	Raising a frame makes it hide other windows;
				  lowering it makes the others hide it.
* Frame Configurations::	Saving the state of all frames.
* Mouse Tracking::		Getting events that say when the mouse moves.
* Mouse Position::		Asking where the mouse is, or moving it.
* Pop-Up Menus::		Displaying a menu for the user to select from.
* Dialog Boxes::                Displaying a box to ask yes or no.
* Pointer Shape::               Specifying the shape of the mouse pointer.
* Window System Selections::    Transferring text to and from other X clients.
* Drag and Drop::               Internals of Drag-and-Drop implementation.
* Color Names::	                Getting the definitions of color names.
* Text Terminal Colors::        Defining colors for text-only terminals.
* Resources::		        Getting resource values from the server.
* Display Feature Testing::     Determining the features of a terminal.
@end menu

@node Creating Frames
@section Creating Frames

To create a new frame, call the function @code{make-frame}.

@defun make-frame &optional alist
This function creates and returns a new frame, displaying the current
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
buffer.

The @var{alist} argument is an alist that specifies frame parameters
for the new frame.  @xref{Frame Parameters}.  If you specify the
@code{terminal} parameter in @var{alist}, the new frame is created on
that terminal.  Otherwise, if you specify the @code{window-system}
frame parameter in @var{alist}, that determines whether the frame
should be displayed on a text-only or graphical terminal.
@xref{Window Systems}.  If neither is specified, the new frame is
created in the same terminal as the selected frame.

Any parameters not mentioned in @var{alist} default to the values in
the alist @code{default-frame-alist} (@pxref{Initial Parameters});
parameters not specified there default from the X resources or its
equivalent on your operating system (@pxref{X Resources,, X Resources,
emacs, The GNU Emacs Manual}).  After the frame is created, Emacs
applies any parameters listed in @code{frame-inherited-parameters}
(see below) and not present in the argument, taking the values from
the frame that was selected when @code{make-frame} was called.
Glenn Morris's avatar
Glenn Morris committed
136 137 138

This function itself does not make the new frame the selected frame.
@xref{Input Focus}.  The previously selected frame remains selected.
139 140
On graphical terminals, however, the windowing system may select the
new frame for its own reasons.
Glenn Morris's avatar
Glenn Morris committed
141 142 143
@end defun

@defvar before-make-frame-hook
144
A normal hook run by @code{make-frame} before it creates the frame.
Glenn Morris's avatar
Glenn Morris committed
145 146 147 148 149 150 151 152
@end defvar

@defvar after-make-frame-functions
An abnormal hook run by @code{make-frame} after it creates the frame.
Each function in @code{after-make-frame-functions} receives one argument, the
frame just created.
@end defvar

153 154 155 156 157 158 159 160 161
@defvar frame-inherited-parameters
This variable specifies the list of frame parameters that a newly
created frame inherits from the currently selected frame.  For each
parameter (a symbol) that is an element in the list and is not present
in the argument to @code{make-frame}, the function sets the value of
that parameter in the created frame to its value in the selected
frame.
@end defvar

162 163 164 165
@node Multiple Terminals
@section Multiple Terminals
@cindex multiple terminals
@cindex multi-tty
Glenn Morris's avatar
Glenn Morris committed
166 167 168
@cindex multiple X displays
@cindex displays, multiple

169 170 171 172 173 174 175 176 177 178 179 180 181 182
  Emacs represents each terminal, whether graphical or text-only, as a
@dfn{terminal object} data type (@pxref{Terminal Type}).  On GNU and
Unix systems, Emacs can use multiple terminals simultaneously in each
session.  On other systems, it can only use a single terminal.  Each
terminal object has the following attributes:

@itemize @bullet
@item
The name of the device used by the terminal (e.g., @samp{:0.0} or
@file{/dev/tty}).

@item
The terminal and keyboard coding systems used on the terminal.
@xref{Terminal I/O Encoding}.
Glenn Morris's avatar
Glenn Morris committed
183

184 185 186 187
@item
The kind of display associated with the terminal.  This is the symbol
returned by the function @code{terminal-live-p} (i.e., @code{x},
@code{t}, @code{w32}, @code{ns}, or @code{pc}).  @xref{Frames}.
Glenn Morris's avatar
Glenn Morris committed
188

189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243
@item
A list of terminal parameters.  @xref{Terminal Parameters}.
@end itemize

  There is no primitive for creating terminal objects.  Emacs creates
them as needed, such as when you call @code{make-frame-on-display}
(which is described below).

@defun terminal-name &optional terminal
This function returns the file name of the device used by
@var{terminal}.  If @var{terminal} is omitted or @code{nil}, it
defaults to the selected frame's terminal.  @var{terminal} can also be
a frame, meaning that frame's terminal.
@end defun

@defun terminal-list
This function returns a list of all terminal objects currently in use.
@end defun

@defun get-device-terminal device
This function returns a terminal whose device name is given by
@var{device}.  If @var{device} is a string, it can be either the file
name of a terminal device, or the name of an X display of the form
@samp{@var{host}:@var{server}.@var{screen}}.  If @var{device} is a
frame, this function returns that frame's terminal; @code{nil} means
the selected frame.  Finally, if @var{device} is a terminal object
that represents a live terminal, that terminal is returned.  The
function signals an error if its argument is none of the above.
@end defun

@defun delete-terminal &optional terminal force
This function deletes all frames on @var{terminal} and frees the
resources used by it.  It runs the abnormal hook
@code{delete-terminal-functions}, passing @var{terminal} as the
argument to each function.

If @var{terminal} is omitted or @code{nil}, it defaults to the
selected frame's terminal.  @var{terminal} can also be a frame,
meaning that frame's terminal.

Normally, this function signals an error if you attempt to delete the
sole active terminal, but if @var{force} is non-@code{nil}, you are
allowed to do so.  Emacs automatically calls this function when the
last frame on a terminal is deleted (@pxref{Deleting Frames}).
@end defun

@defvar delete-terminal-functions
An abnormal hook run by @code{delete-terminal}.  Each function
receives one argument, the @var{terminal} argument passed to
@code{delete-terminal}.  Due to technical details, the functions may
be called either just before the terminal is deleted, or just
afterwards.
@end defvar

@cindex terminal-local variables
Glenn Morris's avatar
Glenn Morris committed
244 245 246 247 248
  A few Lisp variables are @dfn{terminal-local}; that is, they have a
separate binding for each terminal.  The binding in effect at any time
is the one for the terminal that the currently selected frame belongs
to.  These variables include @code{default-minibuffer-frame},
@code{defining-kbd-macro}, @code{last-kbd-macro}, and
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274
@code{system-key-alist}.  They are always terminal-local, and can
never be buffer-local (@pxref{Buffer-Local Variables}).

  On GNU and Unix systems, each X display is a separate graphical
terminal.  When Emacs is started from within the X window system, it
uses the X display chosen with the @code{DISPLAY} environment
variable, or with the @samp{--display} option.  @xref{Initial
Options,,, emacs, The GNU Emacs Manual}.  Emacs can connect to other X
displays via the command @code{make-frame-on-display}.  Each X display
has its own selected frame and its own minibuffer windows; however,
only one of those frames is ``@emph{the} selected frame'' at any given
moment (@pxref{Input Focus}).  Emacs can even connect to other
text-only terminals, by interacting with the @command{emacsclient}
program.  @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.

  A single X server can handle more than one display.  Each X display
has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
The first two parts, @var{host} and @var{server}, identify the X
server; the third part, @var{screen}, identifies a screen number on
that X server.  When you use two or more screens belonging to one
server, Emacs knows by the similarity in their names that they share a
single keyboard.

  On some ``multi-monitor'' setups, a single X display outputs to more
than one monitor.  Currently, there is no way for Emacs to distinguish
between the different physical monitors.
Glenn Morris's avatar
Glenn Morris committed
275 276

@deffn Command make-frame-on-display display &optional parameters
277 278 279 280 281 282 283 284 285
This function creates and returns a new frame on @var{display}, taking
the other frame parameters from the alist @var{parameters}.
@var{display} should be the name of an X display (a string).

Before creating the frame, this function ensures that Emacs is ``set
up'' to display graphics.  For instance, if Emacs has not processed X
resources (e.g., if it was started on a text-only terminal), it does
so at this time.  In all other respects, this function behaves like
@code{make-frame} (@pxref{Creating Frames}).
Glenn Morris's avatar
Glenn Morris committed
286 287 288
@end deffn

@defun x-display-list
289 290 291
This function returns a list that indicates which X displays Emacs has
a connection to.  The elements of the list are strings, and each one
is a display name.
Glenn Morris's avatar
Glenn Morris committed
292 293 294
@end defun

@defun x-open-connection display &optional xrm-string must-succeed
295 296 297 298 299 300 301 302 303 304 305 306
This function opens a connection to the X display @var{display},
without creating a frame on that display.  Normally, Emacs Lisp
programs need not call this function, as @code{make-frame-on-display}
calls it automatically.  The only reason for calling it is to check
whether communication can be established with a given X display.

The optional argument @var{xrm-string}, if not @code{nil}, is a string
of resource names and values, in the same format used in the
@file{.Xresources} file.  @xref{X Resources,, X Resources, emacs, The
GNU Emacs Manual}.  These values apply to all Emacs frames created on
this display, overriding the resource values recorded in the X server.
Here's an example of what this string might look like:
Glenn Morris's avatar
Glenn Morris committed
307 308 309 310 311 312 313 314 315 316 317

@example
"*BorderWidth: 3\n*InternalBorder: 2\n"
@end example

If @var{must-succeed} is non-@code{nil}, failure to open the connection
terminates Emacs.  Otherwise, it is an ordinary Lisp error.
@end defun

@defun x-close-connection display
This function closes the connection to display @var{display}.  Before
318 319
you can do this, you must first delete all the frames that were open
on that display (@pxref{Deleting Frames}).
320 321
@end defun

Glenn Morris's avatar
Glenn Morris committed
322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
@node Frame Parameters
@section Frame Parameters
@cindex frame parameters

  A frame has many parameters that control its appearance and behavior.
Just what parameters a frame has depends on what display mechanism it
uses.

  Frame parameters exist mostly for the sake of window systems.  A
terminal frame has a few parameters, mostly for compatibility's sake;
only the @code{height}, @code{width}, @code{name}, @code{title},
@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
parameters do something special.  If the terminal supports colors, the
parameters @code{foreground-color}, @code{background-color},
@code{background-mode} and @code{display-type} are also meaningful.
337 338
If the terminal supports frame transparency, the parameter
@code{alpha} is also meaningful.
Glenn Morris's avatar
Glenn Morris committed
339

340 341 342
  You can use frame parameters to define frame-local bindings for
variables.  @xref{Frame-Local Variables}.

Glenn Morris's avatar
Glenn Morris committed
343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376
@menu
* Parameter Access::       How to change a frame's parameters.
* Initial Parameters::	   Specifying frame parameters when you make a frame.
* Window Frame Parameters:: List of frame parameters for window systems.
* Size and Position::      Changing the size and position of a frame.
* Geometry::               Parsing geometry specifications.
@end menu

@node Parameter Access
@subsection Access to Frame Parameters

These functions let you read and change the parameter values of a
frame.

@defun frame-parameter frame parameter
This function returns the value of the parameter @var{parameter} (a
symbol) of @var{frame}.  If @var{frame} is @code{nil}, it returns the
selected frame's parameter.  If @var{frame} has no setting for
@var{parameter}, this function returns @code{nil}.
@end defun

@defun frame-parameters &optional frame
The function @code{frame-parameters} returns an alist listing all the
parameters of @var{frame} and their values.  If @var{frame} is
@code{nil} or omitted, this returns the selected frame's parameters
@end defun

@defun modify-frame-parameters frame alist
This function alters the parameters of frame @var{frame} based on the
elements of @var{alist}.  Each element of @var{alist} has the form
@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
parameter.  If you don't mention a parameter in @var{alist}, its value
doesn't change.  If @var{frame} is @code{nil}, it defaults to the selected
frame.
377 378 379

You can use this function to define frame-local bindings for
variables, see @ref{Frame-Local Variables}.
Glenn Morris's avatar
Glenn Morris committed
380 381
@end defun

382
@defun set-frame-parameter frame parm value
383
This function sets the frame parameter @var{parm} to the specified
384 385 386 387
@var{value}.  If @var{frame} is @code{nil}, it defaults to the
selected frame.
@end defun

Glenn Morris's avatar
Glenn Morris committed
388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449
@defun modify-all-frames-parameters alist
This function alters the frame parameters of all existing frames
according to @var{alist}, then modifies @code{default-frame-alist}
(and, if necessary, @code{initial-frame-alist}) to apply the same
parameter values to frames that will be created henceforth.
@end defun

@node Initial Parameters
@subsection Initial Frame Parameters

You can specify the parameters for the initial startup frame
by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).

@defvar initial-frame-alist
This variable's value is an alist of parameter values used when creating
the initial window frame.  You can set this variable to specify the
appearance of the initial frame without altering subsequent frames.
Each element has the form:

@example
(@var{parameter} . @var{value})
@end example

Emacs creates the initial frame before it reads your init
file.  After reading that file, Emacs checks @code{initial-frame-alist},
and applies the parameter settings in the altered value to the already
created initial frame.

If these settings affect the frame geometry and appearance, you'll see
the frame appear with the wrong ones and then change to the specified
ones.  If that bothers you, you can specify the same geometry and
appearance with X resources; those do take effect before the frame is
created.  @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.

X resource settings typically apply to all frames.  If you want to
specify some X resources solely for the sake of the initial frame, and
you don't want them to apply to subsequent frames, here's how to achieve
this.  Specify parameters in @code{default-frame-alist} to override the
X resources for subsequent frames; then, to prevent these from affecting
the initial frame, specify the same parameters in
@code{initial-frame-alist} with values that match the X resources.
@end defvar

If these parameters specify a separate minibuffer-only frame with
@code{(minibuffer . nil)}, and you have not created one, Emacs creates
one for you.

@defvar minibuffer-frame-alist
This variable's value is an alist of parameter values used when creating
an initial minibuffer-only frame---if such a frame is needed, according
to the parameters for the main initial frame.
@end defvar

@defvar default-frame-alist
This is an alist specifying default values of frame parameters for all
Emacs frames---the first frame, and subsequent frames.  When using the X
Window System, you can get the same results by means of X resources
in many cases.

Setting this variable does not affect existing frames.
@end defvar

450 451 452
Functions that display a buffer in a separate frame can override the
default parameters by supplying their own parameters.  @xref{Definition
of special-display-frame-alist}.
Glenn Morris's avatar
Glenn Morris committed
453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479

If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to @code{default-frame-alist}.  One
exception is @samp{-geometry}, which adds the specified position to
@code{initial-frame-alist} instead.  @xref{Emacs Invocation,, Command
Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.

@node Window Frame Parameters
@subsection Window Frame Parameters

  Just what parameters a frame has depends on what display mechanism
it uses.  This section describes the parameters that have special
meanings on some or all kinds of terminals.  Of these, @code{name},
@code{title}, @code{height}, @code{width}, @code{buffer-list} and
@code{buffer-predicate} provide meaningful information in terminal
frames, and @code{tty-color-mode} is meaningful @emph{only} in
terminal frames.

@menu
* Basic Parameters::            Parameters that are fundamental.
* Position Parameters::         The position of the frame on the screen.
* Size Parameters::             Frame's size.
* Layout Parameters::           Size of parts of the frame, and
                                  enabling or disabling some parts.
* Buffer Parameters::           Which buffers have been or should be shown.
* Management Parameters::       Communicating with the window manager.
* Cursor Parameters::           Controlling the cursor appearance.
480
* Font and Color Parameters::   Fonts and colors for the frame text.
Glenn Morris's avatar
Glenn Morris committed
481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500
@end menu

@node Basic Parameters
@subsubsection Basic Parameters

  These frame parameters give the most basic information about the
frame.  @code{title} and @code{name} are meaningful on all terminals.

@table @code
@item display
The display on which to open this frame.  It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@code{DISPLAY} environment variable.

@item display-type
This parameter describes the range of possible colors that can be used
in this frame.  Its value is @code{color}, @code{grayscale} or
@code{mono}.

@item title
501 502 503 504 505 506
If a frame has a non-@code{nil} title, it appears in the window
system's title bar at the top of the frame, and also in the mode line
of windows in that frame if @code{mode-line-frame-identification} uses
@samp{%F} (@pxref{%-Constructs}).  This is normally the case when
Emacs is not using a window system, and can only display one frame at
a time.  @xref{Frame Titles}.
Glenn Morris's avatar
Glenn Morris committed
507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526

@item name
The name of the frame.  The frame name serves as a default for the frame
title, if the @code{title} parameter is unspecified or @code{nil}.  If
you don't specify a name, Emacs sets the frame name automatically
(@pxref{Frame Titles}).

If you specify the frame name explicitly when you create the frame, the
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
@end table

@node Position Parameters
@subsubsection Position Parameters

  Position parameters' values are normally measured in pixels, but on
text-only terminals they count characters or lines instead.

@table @code
@item left
Glenn Morris's avatar
Glenn Morris committed
527 528
The position, in pixels, of the left (or right) edge of the frame with
respect to the left (or right) edge of the screen.  The value may be:
529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545

@table @asis
@item an integer
A positive integer relates the left edge of the frame to the left edge
of the screen.  A negative integer relates the right frame edge to the
right screen edge.

@item @code{(+ @var{pos})}
This specifies the position of the left frame edge relative to the left
screen edge.  The integer @var{pos} may be positive or negative; a
negative value specifies a position outside the screen.

@item @code{(- @var{pos})}
This specifies the position of the right frame edge relative to the right
screen edge.  The integer @var{pos} may be positive or negative; a
negative value specifies a position outside the screen.
@end table
Glenn Morris's avatar
Glenn Morris committed
546 547 548 549 550 551

Some window managers ignore program-specified positions.  If you want to
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.

@item top
552 553 554
The screen position of the top (or bottom) edge, in pixels, with respect
to the top (or bottom) edge of the screen.  It works just like
@code{left}, except vertically instead of horizontally.
Glenn Morris's avatar
Glenn Morris committed
555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601

@item icon-left
The screen position of the left edge @emph{of the frame's icon}, in
pixels, counting from the left edge of the screen.  This takes effect if
and when the frame is iconified.

If you specify a value for this parameter, then you must also specify
a value for @code{icon-top} and vice versa.  The window manager may
ignore these two parameters.

@item icon-top
The screen position of the top edge @emph{of the frame's icon}, in
pixels, counting from the top edge of the screen.  This takes effect if
and when the frame is iconified.

@item user-position
When you create a frame and specify its screen position with the
@code{left} and @code{top} parameters, use this parameter to say whether
the specified position was user-specified (explicitly requested in some
way by a human user) or merely program-specified (chosen by a program).
A non-@code{nil} value says the position was user-specified.

Window managers generally heed user-specified positions, and some heed
program-specified positions too.  But many ignore program-specified
positions, placing the window in a default fashion or letting the user
place it with the mouse.  Some window managers, including @code{twm},
let the user specify whether to obey program-specified positions or
ignore them.

When you call @code{make-frame}, you should specify a non-@code{nil}
value for this parameter if the values of the @code{left} and @code{top}
parameters represent the user's stated preference; otherwise, use
@code{nil}.
@end table

@node Size Parameters
@subsubsection Size Parameters

  Size parameters' values are normally measured in pixels, but on
text-only terminals they count characters or lines instead.

@table @code
@item height
The height of the frame contents, in characters.  (To get the height in
pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)

@item width
602
The width of the frame contents, in characters.  (To get the width in
Glenn Morris's avatar
Glenn Morris committed
603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)

@item user-size
This does for the size parameters @code{height} and @code{width} what
the @code{user-position} parameter (see above) does for the position
parameters @code{top} and @code{left}.

@item fullscreen
Specify that width, height or both shall be set to the size of the screen.
The value @code{fullwidth} specifies that width shall be the size of the
screen.  The value @code{fullheight} specifies that height shall be the
size of the screen.  The value @code{fullboth} specifies that both the
width and the height shall be set to the size of the screen.
@end table

@node Layout Parameters
@subsubsection Layout Parameters

  These frame parameters enable or disable various parts of the
frame, or control their sizes.

@table @code
@item border-width
The width in pixels of the frame's border.

@item internal-border-width
The distance in pixels between text (or fringe) and the frame's border.

@item vertical-scroll-bars
Whether the frame has scroll bars for vertical scrolling, and which side
of the frame they should be on.  The possible values are @code{left},
@code{right}, and @code{nil} for no scroll bars.

@ignore
@item horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling
(non-@code{nil} means yes).  Horizontal scroll bars are not currently
implemented.
@end ignore

@item scroll-bar-width
The width of vertical scroll bars, in pixels, or @code{nil} meaning to
use the default width.

@item left-fringe
@itemx right-fringe
The default width of the left and right fringes of windows in this
frame (@pxref{Fringes}).  If either of these is zero, that effectively
removes the corresponding fringe.  A value of @code{nil} stands for
the standard fringe width, which is the width needed to display the
fringe bitmaps.

The combined fringe widths must add up to an integral number of
columns, so the actual default fringe widths for the frame may be
larger than the specified values.  The extra width needed to reach an
acceptable total is distributed evenly between the left and right
fringe.  However, you can force one fringe or the other to a precise
width by specifying that width as a negative integer.  If both widths are
negative, only the left fringe gets the specified width.

@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu
bar.  The default is 1.  A value of @code{nil} means don't display a
menu bar.  @xref{Menu Bar}.  (The X toolkit and GTK allow at most one
menu bar line; they treat larger values as 1.)

@item tool-bar-lines
The number of lines to use for the tool bar.  A value of @code{nil}
671 672
means don't display a tool bar.  (GTK and Nextstep allow at most one
tool bar line; they treat larger values as 1.)
Glenn Morris's avatar
Glenn Morris committed
673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801

@item line-spacing
Additional space to leave below each text line, in pixels (a positive
integer).  @xref{Line Height}, for more information.
@end table

@node Buffer Parameters
@subsubsection Buffer Parameters

  These frame parameters, meaningful on all kinds of terminals, deal
with which buffers have been, or should, be displayed in the frame.

@table @code
@item minibuffer
Whether this frame has its own minibuffer.  The value @code{t} means
yes, @code{nil} means no, @code{only} means this frame is just a
minibuffer.  If the value is a minibuffer window (in some other frame),
the new frame uses that minibuffer.

@item buffer-predicate
The buffer-predicate function for this frame.  The function
@code{other-buffer} uses this predicate (from the selected frame) to
decide which buffers it should consider, if the predicate is not
@code{nil}.  It calls the predicate with one argument, a buffer, once for
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.

@item buffer-list
A list of buffers that have been selected in this frame,
ordered most-recently-selected first.

@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.
@end table

@node Management Parameters
@subsubsection Window Management Parameters
@cindex window manager, and frame parameters

  These frame parameters, meaningful only on window system displays,
interact with the window manager.

@table @code
@item visibility
The state of visibility of the frame.  There are three possibilities:
@code{nil} for invisible, @code{t} for visible, and @code{icon} for
iconified.  @xref{Visibility of Frames}.

@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).

@item auto-lower
Whether deselecting the frame lowers it (non-@code{nil} means yes).

@item icon-type
The type of icon to use for this frame when it is iconified.  If the
value is a string, that specifies a file containing a bitmap to use.
Any other non-@code{nil} value specifies the default bitmap icon (a
picture of a gnu); @code{nil} specifies a text icon.

@item icon-name
The name to use in the icon for this frame, when and if the icon
appears.  If this is @code{nil}, the frame's title is used.

@item window-id
The number of the window-system window used by the frame
to contain the actual Emacs windows.

@item outer-window-id
The number of the outermost window-system window used for the whole frame.

@item wait-for-wm
If non-@code{nil}, tell Xt to wait for the window manager to confirm
geometry changes.  Some window managers, including versions of Fvwm2
and KDE, fail to confirm, so Xt hangs.  Set this to @code{nil} to
prevent hanging with those window managers.

@ignore
@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
Specifying this lets you create an Emacs window inside some other
application's window.  (It is not certain this will be implemented; try
it and see if it works.)
@end ignore
@end table

@node Cursor Parameters
@subsubsection Cursor Parameters

  This frame parameter controls the way the cursor looks.

@table @code
@item cursor-type
How to display the cursor.  Legitimate values are:

@table @code
@item box
Display a filled box.  (This is the default.)
@item hollow
Display a hollow box.
@item nil
Don't display a cursor.
@item bar
Display a vertical bar between characters.
@item (bar . @var{width})
Display a vertical bar @var{width} pixels wide between characters.
@item hbar
Display a horizontal bar.
@item (hbar . @var{height})
Display a horizontal bar @var{height} pixels high.
@end table
@end table

@vindex cursor-type
The buffer-local variable @code{cursor-type} overrides the value of
the @code{cursor-type} frame parameter, but if it is @code{t}, that
means to use the cursor specified for the frame.

@defvar blink-cursor-alist
This variable specifies how to blink the cursor.  Each element has the
form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
type equals @var{on-state} (comparing using @code{equal}), the
corresponding @var{off-state} specifies what the cursor looks like
when it blinks ``off.''  Both @var{on-state} and @var{off-state}
should be suitable values for the @code{cursor-type} frame parameter.

There are various defaults for how to blink each type of cursor, if
the type is not mentioned as an @var{on-state} here.  Changes in this
802 803 804 805 806 807 808 809 810 811 812
variable do not take effect immediately, only when you specify the
@code{cursor-type} frame parameter.
@end defvar

@defvar cursor-in-non-selected-windows
This variable controls how the cursor looks in a window that is not
selected.  It supports the same values as the @code{cursor-type} frame
parameter; also, @code{nil} means don't display a cursor in
nonselected windows, and @code{t} (the default) means use a standard
modificatoin of the usual cursor type (solid box becomes hollow box,
and bar becomes a narrower bar).
Glenn Morris's avatar
Glenn Morris committed
813 814
@end defvar

815 816
@node Font and Color Parameters
@subsubsection Font and Color Parameters
Glenn Morris's avatar
Glenn Morris committed
817

818
  These frame parameters control the use of fonts and colors.
Glenn Morris's avatar
Glenn Morris committed
819 820

@table @code
821 822 823 824 825 826 827 828
@item font-backend
A list of symbols, specifying the @dfn{font backends} to use for
drawing fonts in the frame, in order of priority.  On X, there are
currently two available font backends: @code{x} (the X core font
driver) and @code{xft} (the Xft font driver).  On other systems, there
is only one available font backend, so it does not make sense to
modify this frame parameter.

Glenn Morris's avatar
Glenn Morris committed
829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865
@item background-mode
This parameter is either @code{dark} or @code{light}, according
to whether the background color is a light one or a dark one.

@item tty-color-mode
@cindex standard colors for character terminals
This parameter overrides the terminal's color support as given by the
system's terminal capabilities database in that this parameter's value
specifies the color mode to use in terminal frames.  The value can be
either a symbol or a number.  A number specifies the number of colors
to use (and, indirectly, what commands to issue to produce each
color).  For example, @code{(tty-color-mode . 8)} specifies use of the
ANSI escape sequences for 8 standard text colors.  A value of -1 turns
off color support.

If the parameter's value is a symbol, it specifies a number through
the value of @code{tty-color-mode-alist}, and the associated number is
used instead.

@item screen-gamma
@cindex gamma correction
If this is a number, Emacs performs ``gamma correction'' which adjusts
the brightness of all colors.  The value should be the screen gamma of
your display, a floating point number.

Usual PC monitors have a screen gamma of 2.2, so color values in
Emacs, and in X windows generally, are calibrated to display properly
on a monitor with that gamma value.  If you specify 2.2 for
@code{screen-gamma}, that means no correction is needed.  Other values
request correction, designed to make the corrected colors appear on
your screen the way they would have appeared without correction on an
ordinary monitor with a gamma value of 2.2.

If your monitor displays colors too light, you should specify a
@code{screen-gamma} value smaller than 2.2.  This requests correction
that makes colors darker.  A screen gamma value of 1.5 may give good
results for LCD color displays.
866 867 868 869 870 871 872 873 874 875 876 877

@item alpha
@cindex opacity, frame
@cindex transparency, frame
@vindex frame-alpha-lower-limit
This parameter specifies the opacity of the frame, on graphical
displays that support variable opacity.  It should be an integer
between 0 and 100, where 0 means completely transparent and 100 means
completely opaque.  It can also have a @code{nil} value, which tells
Emacs not to set the frame opacity (leaving it to the window manager).

To prevent the frame from disappearing completely from view, the
878
variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
879 880
If the value of the frame parameter is less than the value of this
variable, Emacs uses the latter.  By default,
881
@code{frame-alpha-lower-limit} is 20.
882 883 884 885 886

The @code{alpha} frame parameter can also be a cons cell
@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
opacity of the frame when it is selected, and @samp{inactive} is the
opactity when it is not selected.
Glenn Morris's avatar
Glenn Morris committed
887 888
@end table

Chong Yidong's avatar
Chong Yidong committed
889 890 891
The following frame parameters are semi-obsolete in that they are
automatically equivalent to particular face attributes of particular
faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
Glenn Morris's avatar
Glenn Morris committed
892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975

@table @code
@item font
The name of the font for displaying text in the frame.  This is a
string, either a valid font name for your system or the name of an Emacs
fontset (@pxref{Fontsets}).  It is equivalent to the @code{font}
attribute of the @code{default} face.

@item foreground-color
The color to use for the image of a character.  It is equivalent to
the @code{:foreground} attribute of the @code{default} face.

@item background-color
The color to use for the background of characters.  It is equivalent to
the @code{:background} attribute of the @code{default} face.

@item mouse-color
The color for the mouse pointer.  It is equivalent to the @code{:background}
attribute of the @code{mouse} face.

@item cursor-color
The color for the cursor that shows point.  It is equivalent to the
@code{:background} attribute of the @code{cursor} face.

@item border-color
The color for the border of the frame.  It is equivalent to the
@code{:background} attribute of the @code{border} face.

@item scroll-bar-foreground
If non-@code{nil}, the color for the foreground of scroll bars.  It is
equivalent to the @code{:foreground} attribute of the
@code{scroll-bar} face.

@item scroll-bar-background
If non-@code{nil}, the color for the background of scroll bars.  It is
equivalent to the @code{:background} attribute of the
@code{scroll-bar} face.
@end table

@node Size and Position
@subsection Frame Size And Position
@cindex size of frame
@cindex screen size
@cindex frame size
@cindex resize frame

  You can read or change the size and position of a frame using the
frame parameters @code{left}, @code{top}, @code{height}, and
@code{width}.  Whatever geometry parameters you don't specify are chosen
by the window manager in its usual fashion.

  Here are some special features for working with sizes and positions.
(For the precise meaning of ``selected frame'' used by these functions,
see @ref{Input Focus}.)

@defun set-frame-position frame left top
This function sets the position of the top left corner of @var{frame} to
@var{left} and @var{top}.  These arguments are measured in pixels, and
normally count from the top left corner of the screen.

Negative parameter values position the bottom edge of the window up from
the bottom edge of the screen, or the right window edge to the left of
the right edge of the screen.  It would probably be better if the values
were always counted from the left and top, so that negative arguments
would position the frame partly off the top or left edge of the screen,
but it seems inadvisable to change that now.
@end defun

@defun frame-height &optional frame
@defunx frame-width &optional frame
These functions return the height and width of @var{frame}, measured in
lines and columns.  If you don't supply @var{frame}, they use the
selected frame.
@end defun

@defun screen-height
@defunx screen-width
These functions are old aliases for @code{frame-height} and
@code{frame-width}.  When you are using a non-window terminal, the size
of the frame is normally the same as the size of the terminal screen.
@end defun

@defun frame-pixel-height &optional frame
@defunx frame-pixel-width &optional frame
976 977 978 979 980 981 982 983
These functions return the height and width of the main display area
of @var{frame}, measured in pixels.  If you don't supply @var{frame},
they use the selected frame.

These values include the internal borders, and windows' scroll bars
and fringes (which belong to individual windows, not to the frame
itself), but do not include menu bars or tool bars (except when using
X without an X toolkit).
Glenn Morris's avatar
Glenn Morris committed
984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051
@end defun

@defun frame-char-height &optional frame
@defunx frame-char-width &optional frame
These functions return the height and width of a character in
@var{frame}, measured in pixels.  The values depend on the choice of
font.  If you don't supply @var{frame}, these functions use the selected
frame.
@end defun

@defun set-frame-size frame cols rows
This function sets the size of @var{frame}, measured in characters;
@var{cols} and @var{rows} specify the new width and height.

To set the size based on values measured in pixels, use
@code{frame-char-height} and @code{frame-char-width} to convert
them to units of characters.
@end defun

@defun set-frame-height frame lines &optional pretend
This function resizes @var{frame} to a height of @var{lines} lines.  The
sizes of existing windows in @var{frame} are altered proportionally to
fit.

If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
lines of output in @var{frame}, but does not change its value for the
actual height of the frame.  This is only useful for a terminal frame.
Using a smaller height than the terminal actually implements may be
useful to reproduce behavior observed on a smaller screen, or if the
terminal malfunctions when using its whole screen.  Setting the frame
height ``for real'' does not always work, because knowing the correct
actual size may be necessary for correct cursor positioning on a
terminal frame.
@end defun

@defun set-frame-width frame width &optional pretend
This function sets the width of @var{frame}, measured in characters.
The argument @var{pretend} has the same meaning as in
@code{set-frame-height}.
@end defun

@findex set-screen-height
@findex set-screen-width
  The older functions @code{set-screen-height} and
@code{set-screen-width} were used to specify the height and width of the
screen, in Emacs versions that did not support multiple frames.  They
are semi-obsolete, but still work; they apply to the selected frame.

@node Geometry
@subsection Geometry

  Here's how to examine the data in an X-style window geometry
specification:

@defun x-parse-geometry geom
@cindex geometry specification
The function @code{x-parse-geometry} converts a standard X window
geometry string to an alist that you can use as part of the argument to
@code{make-frame}.

The alist describes which parameters were specified in @var{geom}, and
gives the values specified for them.  Each element looks like
@code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
values are @code{left}, @code{top}, @code{width}, and @code{height}.

For the size parameters, the value must be an integer.  The position
parameter names @code{left} and @code{top} are not totally accurate,
because some values indicate the position of the right or bottom edges
1052 1053 1054
instead.  The @var{value} possibilities for the position parameters are:
an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})};
as previously described (@pxref{Position Parameters}).
Glenn Morris's avatar
Glenn Morris committed
1055 1056 1057 1058 1059 1060 1061 1062 1063 1064

Here is an example:

@example
(x-parse-geometry "35x70+0-0")
     @result{} ((height . 70) (width . 35)
         (top - 0) (left . 0))
@end example
@end defun

1065 1066 1067 1068
@node Terminal Parameters
@section Terminal Parameters
@cindex terminal parameters

1069 1070 1071 1072 1073 1074 1075 1076 1077
  Each terminal has a list of associated parameters.  These
@dfn{terminal parameters} are mostly a convenient way of storage for
terminal-local variables, but some terminal parameters have a special
meaning.

  This section describes functions to read and change the parameter values
of a terminal.  They all accept as their argument either a terminal or
a frame; the latter means use that frame's terminal.  An argument of
@code{nil} means the selected frame's terminal.
1078 1079

@defun terminal-parameters &optional terminal
1080 1081
This function returns an alist listing all the parameters of
@var{terminal} and their values.
1082 1083 1084
@end defun

@defun terminal-parameter terminal parameter
1085 1086 1087
This function returns the value of the parameter @var{parameter} (a
symbol) of @var{terminal}.  If @var{terminal} has no setting for
@var{parameter}, this function returns @code{nil}.
1088 1089 1090
@end defun

@defun set-terminal-parameter terminal parameter value
1091 1092 1093
This function sets the parameter @var{parm} of @var{terminal} to the
specified @var{value}, and returns the previous value of that
parameter.
1094 1095
@end defun

1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111
Here's a list of a few terminal parameters that have a special
meaning:

@table @code
@item background-mode
The classification of the terminal's background color, either
@code{light} or @code{dark}.
@item normal-erase-is-backspace
Value is either 1 or 0, depending on whether
@code{normal-erase-is-backspace-mode} is turned on or off on this
terminal.  @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
@item terminal-initted
After the terminal is initialized, this is set to the
terminal-specific initialization function.
@end table

Glenn Morris's avatar
Glenn Morris committed
1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168
@node Frame Titles
@section Frame Titles
@cindex frame title

  Every frame has a @code{name} parameter; this serves as the default
for the frame title which window systems typically display at the top of
the frame.  You can specify a name explicitly by setting the @code{name}
frame property.

  Normally you don't specify the name explicitly, and Emacs computes the
frame name automatically based on a template stored in the variable
@code{frame-title-format}.  Emacs recomputes the name each time the
frame is redisplayed.

@defvar frame-title-format
This variable specifies how to compute a name for a frame when you have
not explicitly specified one.  The variable's value is actually a mode
line construct, just like @code{mode-line-format}, except that the
@samp{%c} and @samp{%l} constructs are ignored.  @xref{Mode Line
Data}.
@end defvar

@defvar icon-title-format
This variable specifies how to compute the name for an iconified frame,
when you have not explicitly specified the frame title.  This title
appears in the icon itself.
@end defvar

@defvar multiple-frames
This variable is set automatically by Emacs.  Its value is @code{t} when
there are two or more frames (not counting minibuffer-only frames or
invisible frames).  The default value of @code{frame-title-format} uses
@code{multiple-frames} so as to put the buffer name in the frame title
only when there is more than one frame.

The value of this variable is not guaranteed to be accurate except
while processing @code{frame-title-format} or
@code{icon-title-format}.
@end defvar

@node Deleting Frames
@section Deleting Frames
@cindex deleting frames

Frames remain potentially visible until you explicitly @dfn{delete}
them.  A deleted frame cannot appear on the screen, but continues to
exist as a Lisp object until there are no references to it.

@deffn Command delete-frame &optional frame force
@vindex delete-frame-functions
This function deletes the frame @var{frame}.  Unless @var{frame} is a
tooltip, it first runs the hook @code{delete-frame-functions} (each
function gets one argument, @var{frame}).  By default, @var{frame} is
the selected frame.

A frame cannot be deleted if its minibuffer is used by other frames.
Normally, you cannot delete a frame if all other frames are invisible,
1169
but if @var{force} is non-@code{nil}, then you are allowed to do so.
Glenn Morris's avatar
Glenn Morris committed
1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188
@end deffn

@defun frame-live-p frame
The function @code{frame-live-p} returns non-@code{nil} if the frame
@var{frame} has not been deleted.  The possible non-@code{nil} return
values are like those of @code{framep}.  @xref{Frames}.
@end defun

  Some window managers provide a command to delete a window.  These work
by sending a special message to the program that operates the window.
When Emacs gets one of these commands, it generates a
@code{delete-frame} event, whose normal definition is a command that
calls the function @code{delete-frame}.  @xref{Misc Events}.

@node Finding All Frames
@section Finding All Frames
@cindex frames, scanning all

@defun frame-list
1189 1190 1191 1192 1193
The function @code{frame-list} returns a list of all the live frames,
i.e.@: those that have not been deleted.  It is analogous to
@code{buffer-list} for buffers, and includes frames on all terminals.
The list that you get is newly created, so modifying the list doesn't
have any effect on the internals of Emacs.
Glenn Morris's avatar
Glenn Morris committed
1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236
@end defun

@defun visible-frame-list
This function returns a list of just the currently visible frames.
@xref{Visibility of Frames}.  (Terminal frames always count as
``visible,'' even though only the selected one is actually displayed.)
@end defun

@defun next-frame &optional frame minibuf
The function @code{next-frame} lets you cycle conveniently through all
the frames on the current display from an arbitrary starting point.  It
returns the ``next'' frame after @var{frame} in the cycle.  If
@var{frame} is omitted or @code{nil}, it defaults to the selected frame
(@pxref{Input Focus}).

The second argument, @var{minibuf}, says which frames to consider:

@table @asis
@item @code{nil}
Exclude minibuffer-only frames.
@item @code{visible}
Consider all visible frames.
@item 0
Consider all visible or iconified frames.
@item a window
Consider only the frames using that particular window as their
minibuffer.
@item anything else
Consider all frames.
@end table
@end defun

@defun previous-frame &optional frame minibuf
Like @code{next-frame}, but cycles through all frames in the opposite
direction.
@end defun

  See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
Window Ordering}.

@node Frames and Windows
@section Frames and Windows

1237
  Each window is part of one and only one frame; you can get that frame
Glenn Morris's avatar
Glenn Morris committed
1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256
with @code{window-frame}.

@defun window-frame window
This function returns the frame that @var{window} is on.
@end defun

  All the non-minibuffer windows in a frame are arranged in a cyclic
order.  The order runs from the frame's top window, which is at the
upper left corner, down and to the right, until it reaches the window at
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top.  @xref{Cyclic Window Ordering}.

@defun frame-first-window &optional frame
This returns the topmost, leftmost window of frame @var{frame}.
If omitted or @code{nil}, @var{frame} defaults to the selected frame.
@end defun

At any time, exactly one window on any frame is @dfn{selected within the
frame}.  The significance of this designation is that selecting the
1257 1258 1259
frame also selects this window.  Conversely, selecting a window for
Emacs with @code{select-window} also makes that window selected within
its frame.  @xref{Selecting Windows}.
Glenn Morris's avatar
Glenn Morris committed
1260 1261 1262 1263 1264 1265 1266

@defun frame-selected-window  &optional frame
This function returns the window on @var{frame} that is selected
within @var{frame}.  If omitted or @code{nil}, @var{frame} defaults to
the selected frame.
@end defun

1267
@defun set-frame-selected-window frame window &optional norecord
Glenn Morris's avatar
Glenn Morris committed
1268 1269 1270 1271 1272
This sets the selected window of frame @var{frame} to @var{window}.
If @var{frame} is @code{nil}, it operates on the selected frame.  If
@var{frame} is the selected frame, this makes @var{window} the
selected window.  This function returns @var{window}.

1273 1274 1275 1276
Optional argument @var{norecord} non-@code{nil} means to neither change
the order of recently selected windows nor the buffer list (@pxref{The
Buffer List}).
@end defun
Glenn Morris's avatar
Glenn Morris committed
1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303

  Another function that (usually) returns one of the windows in a given
frame is @code{minibuffer-window}.  @xref{Definition of minibuffer-window}.

@node Minibuffers and Frames
@section Minibuffers and Frames

Normally, each frame has its own minibuffer window at the bottom, which
is used whenever that frame is selected.  If the frame has a minibuffer,
you can get it with @code{minibuffer-window} (@pxref{Definition of
minibuffer-window}).

However, you can also create a frame with no minibuffer.  Such a frame
must use the minibuffer window of some other frame.  When you create the
frame, you can specify explicitly the minibuffer window to use (in some
other frame).  If you don't, then the minibuffer is found in the frame
which is the value of the variable @code{default-minibuffer-frame}.  Its
value should be a frame that does have a minibuffer.

If you use a minibuffer-only frame, you might want that frame to raise
when you enter the minibuffer.  If so, set the variable
@code{minibuffer-auto-raise} to @code{t}.  @xref{Raising and Lowering}.

@defvar default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by
default.  It does not affect existing frames.  It is always local to
the current terminal and cannot be buffer-local.  @xref{Multiple
1304
Terminals}.
Glenn Morris's avatar
Glenn Morris committed
1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315
@end defvar

@node Input Focus
@section Input Focus
@cindex input focus
@c @cindex selected frame    Duplicates selected-frame

At any time, one frame in Emacs is the @dfn{selected frame}.  The selected
window always resides on the selected frame.

When Emacs displays its frames on several terminals (@pxref{Multiple
1316 1317 1318 1319 1320 1321 1322 1323 1324
Terminals}), each terminal has its own selected frame.  But only one
of these is ``@emph{the} selected frame'': it's the frame that belongs
to the terminal from which the most recent input came.  That is, when
Emacs runs a command that came from a certain terminal, the selected
frame is the one of that terminal.  Since Emacs runs only a single
command at any given time, it needs to consider only one selected
frame at a time; this frame is what we call @dfn{the selected frame}
in this manual.  The display on which the selected frame is shown is
the @dfn{selected frame's display}.
Glenn Morris's avatar
Glenn Morris committed
1325 1326 1327 1328 1329 1330 1331 1332 1333

@defun selected-frame
This function returns the selected frame.
@end defun

Some window systems and window managers direct keyboard input to the
window object that the mouse is in; others require explicit clicks or
commands to @dfn{shift the focus} to various window objects.  Either
way, Emacs automatically keeps track of which frame has the focus.  To
1334
explicitly switch to a different frame from a Lisp function, call
Glenn Morris's avatar
Glenn Morris committed
1335 1336 1337 1338 1339 1340 1341 1342 1343 1344
@code{select-frame-set-input-focus}.

Lisp programs can also switch frames ``temporarily'' by calling the
function @code{select-frame}.  This does not alter the window system's
concept of focus; rather, it escapes from the window manager's control
until that control is somehow reasserted.

When using a text-only terminal, only one frame can be displayed at a
time on the terminal, so after a call to @code{select-frame}, the next
redisplay actually displays the newly selected frame.  This frame
1345 1346 1347
remains selected until a subsequent call to @code{select-frame}.  Each
terminal frame has a number which appears in the mode line before the
buffer name (@pxref{Mode Line Variables}).
Glenn Morris's avatar
Glenn Morris committed
1348 1349

@defun select-frame-set-input-focus frame
1350 1351 1352 1353 1354
This function selects @var{frame}, raises it (should it happen to be
obscured by other frames) and tries to give it the X server's focus.  On
a text-only terminal, the next redisplay displays the new frame on the
entire terminal screen.  The return value of this function is not
significant.
Glenn Morris's avatar
Glenn Morris committed
1355 1356 1357
@end defun

@c ??? This is not yet implemented properly.
1358
@defun select-frame frame &optional norecord
Glenn Morris's avatar
Glenn Morris committed
1359 1360 1361 1362 1363 1364
This function selects frame @var{frame}, temporarily disregarding the
focus of the X server if any.  The selection of @var{frame} lasts until
the next time the user does something to select a different frame, or
until the next time this function is called.  (If you are using a
window system, the previously selected frame may be restored as the
selected frame after return to the command loop, because it still may
1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375
have the window system's input focus.)

The specified @var{frame} becomes the selected frame, as explained
above, and the terminal that @var{frame} is on becomes the selected
terminal.  The window selected within @var{frame} becomes the selected
window.  This function returns @var{frame}, or @code{nil} if @var{frame}
has been deleted.

Optional argument @var{norecord} non-@code{nil} means to neither change
the order of recently selected windows nor the buffer list.  @xref{The
Buffer List}.
Glenn Morris's avatar
Glenn Morris committed
1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428

In general, you should never use @code{select-frame} in a way that could
switch to a different terminal without switching back when you're done.
@end defun

Emacs cooperates with the window system by arranging to select frames as
the server and window manager request.  It does so by generating a
special kind of input event, called a @dfn{focus} event, when
appropriate.  The command loop handles a focus event by calling
@code{handle-switch-frame}.  @xref{Focus Events}.

@deffn Command handle-switch-frame frame
This function handles a focus event by selecting frame @var{frame}.

Focus events normally do their job by invoking this command.
Don't call it for any other reason.
@end deffn

@defun redirect-frame-focus frame &optional focus-frame
This function redirects focus from @var{frame} to @var{focus-frame}.
This means that @var{focus-frame} will receive subsequent keystrokes and
events intended for @var{frame}.  After such an event, the value of
@code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
events specifying @var{frame} will instead select @var{focus-frame}.

If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
redirection for @var{frame}, which therefore once again receives its own
events.

One use of focus redirection is for frames that don't have minibuffers.
These frames use minibuffers on other frames.  Activating a minibuffer
on another frame redirects focus to that frame.  This puts the focus on
the minibuffer's frame, where it belongs, even though the mouse remains
in the frame that activated the minibuffer.

Selecting a frame can also change focus redirections.  Selecting frame
@code{bar}, when @code{foo} had been selected, changes any redirections
pointing to @code{foo} so that they point to @code{bar} instead.  This
allows focus redirection to work properly when the user switches from
one frame to another using @code{select-window}.

This means that a frame whose focus is redirected to itself is treated
differently from a frame whose focus is not redirected.
@code{select-frame} affects the former but not the latter.

The redirection lasts until @code{redirect-frame-focus} is called to
change it.
@end defun

@defopt focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers
focus when the user moves the mouse.  Non-@code{nil} says that it does.
When this is so, the command @code{other-frame} moves the mouse to a
1429
position consistent with the new selected frame.
Glenn Morris's avatar
Glenn Morris committed
1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441
@end defopt

@node Visibility of Frames
@section Visibility of Frames
@cindex visible frame
@cindex invisible frame
@cindex iconified frame
@cindex frame visibility

A window frame may be @dfn{visible}, @dfn{invisible}, or
@dfn{iconified}.  If it is visible, you can see its contents, unless
other windows cover it.  If it is iconified, the frame's contents do
1442 1443 1444 1445 1446
not appear on the screen, but an icon does.  (Note: because of the
way in which some window managers implement the concept of multiple
workspaces, or desktops, all frames on other workspaces may appear to
Emacs to be iconified.)  If the frame is invisible, it doesn't show on
the screen, not even as an icon.
Glenn Morris's avatar
Glenn Morris committed
1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508

Visibility is meaningless for terminal frames, since only the selected
one is actually displayed in any case.

@deffn Command make-frame-visible &optional frame
This function makes frame @var{frame} visible.  If you omit
@var{frame}, it makes the selected frame visible.  This does not raise
the frame, but you can do that with @code{raise-frame} if you wish
(@pxref{Raising and Lowering}).
@end deffn

@deffn Command make-frame-invisible &optional frame force
This function makes frame @var{frame} invisible.  If you omit
@var{frame}, it makes the selected frame invisible.

Unless @var{force} is non-@code{nil}, this function refuses to make
@var{frame} invisible if all other frames are invisible..
@end deffn

@deffn Command iconify-frame &optional frame
This function iconifies frame @var{frame}.  If you omit @var{frame}, it
iconifies the selected frame.
@end deffn

@defun frame-visible-p frame
This returns the visibility status of frame @var{frame}.  The value is
@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
@code{icon} if it is iconified.

On a text-only terminal, all frames are considered visible, whether
they are currently being displayed or not, and this function returns
@code{t} for all frames.
@end defun

  The visibility status of a frame is also available as a frame
parameter.  You can read or change it as such.  @xref{Management
Parameters}.

  The user can iconify and deiconify frames with the window manager.
This happens below the level at which Emacs can exert any control, but
Emacs does provide events that you can use to keep track of such
changes.  @xref{Misc Events}.

@node Raising and Lowering
@section Raising and Lowering Frames

  Most window systems use a desktop metaphor.  Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from ``highest''
to ``lowest.''  Where two windows overlap, the one higher up covers
the one underneath.  Even a window at the bottom of the stack can be
seen if no other window overlaps it.

@c @cindex raising a frame  redundant with raise-frame
@cindex lowering a frame
  A window's place in this ordering is not fixed; in fact, users tend
to change the order frequently.  @dfn{Raising} a window means moving
it ``up,'' to the top of the stack.  @dfn{Lowering} a window means
moving it to the bottom of the stack.  This motion is in the notional
third dimension only, and does not change the position of the window
on the screen.

1509 1510
  With Emacs, frames constitute the windows in the metaphor sketched
above. You can raise and lower frames using these functions:
Glenn Morris's avatar
Glenn Morris committed
1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571

@deffn Command raise-frame &optional frame
This function raises frame @var{frame} (default, the selected frame).
If @var{frame} is invisible or iconified, this makes it visible.
@end deffn

@deffn Command lower-frame &optional frame
This function lowers frame @var{frame} (default, the selected frame).
@end deffn

@defopt minibuffer-auto-raise
If this is non-@code{nil}, activation of the minibuffer raises the frame
that the minibuffer window is in.
@end defopt

You can also enable auto-raise (raising automatically when a frame is
selected) or auto-lower (lowering automatically when it is deselected)
for any frame using frame parameters.  @xref{Management Parameters}.

@node Frame Configurations
@section Frame Configurations
@cindex frame configuration

  A @dfn{frame configuration} records the current arrangement of frames,
all their properties, and the window configuration of each one.
(@xref{Window Configurations}.)

@defun current-frame-configuration
This function returns a frame configuration list that describes
the current arrangement of frames and their contents.
@end defun

@defun set-frame-configuration configuration &optional nodelete
This function restores the state of frames described in
@var{configuration}.  However, this function does not restore deleted
frames.

Ordinarily, this function deletes all existing frames not listed in
@var{configuration}.  But if @var{nodelete} is non-@code{nil}, the
unwanted frames are iconified instead.
@end defun

@node Mouse Tracking
@section Mouse Tracking
@cindex mouse tracking
@c @cindex tracking the mouse   Duplicates track-mouse

  Sometimes it is useful to @dfn{track} the mouse, which means to display
something to indicate where the mouse is and move the indicator as the
mouse moves.  For efficient mouse tracking, you need a way to wait until
the mouse actually moves.

  The convenient way to track the mouse is to ask for events to represent
mouse motion.  Then you can wait for motion by waiting for an event.  In
addition, you can easily handle any other sorts of events that may
occur.  That is useful, because normally you don't want to track the
mouse forever---only until some other event, such as the release of a
button.

@defspec track-mouse body@dots{}
This special form executes @var{body}, with generation of mouse motion
1572
events enabled.  Typically, @var{body} would use @code{read-event} to
Glenn Morris's avatar
Glenn Morris committed
1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838
read the motion events and modify the display accordingly.  @xref{Motion
Events}, for the format of mouse motion events.

The value of @code{track-mouse} is that of the last form in @var{body}.
You should design @var{body} to return when it sees the up-event that
indicates the release of the button, or whatever kind of event means
it is time to stop tracking.
@end defspec

The usual purpose of tracking mouse motion is to indicate on the screen
the consequences of pushing or releasing a button at the current
position.

In many cases, you can avoid the need to track the mouse by using
the @code{mouse-face} text property (@pxref{Special Properties}).
That works at a much lower level and runs more smoothly than
Lisp-level mouse tracking.

@ignore
@c These are not implemented yet.

These functions change the screen appearance instantaneously.  The
effect is transient, only until the next ordinary Emacs redisplay.  That
is OK for mouse tracking, since it doesn't make sense for mouse tracking
to change the text, and the body of @code{track-mouse} normally reads
the events itself and does not do redisplay.

@defun x-contour-region window beg end
This function draws lines to make a box around the text from @var{beg}
to @var{end}, in window @var{window}.
@end defun

@defun x-uncontour-region window beg end
This function erases the lines that would make a box around the text
from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
a contour that you previously made by calling @code{x-contour-region}.
@end defun

@defun x-draw-rectangle frame left top right bottom
This function draws a hollow rectangle on frame @var{frame} with the
specified edge coordinates, all measured in pixels from the inside top
left corner.  It uses the cursor color, the one used for indicating the
location of point.
@end defun

@defun x-erase-rectangle frame left top right bottom
This function erases a hollow rectangle on frame @var{frame} with the
specified edge coordinates, all measured in pixels from the inside top
left corner.  Erasure means redrawing the text and background that
normally belong in the specified rectangle.
@end defun
@end ignore

@node Mouse Position
@section Mouse Position
@cindex mouse position
@cindex position of mouse

  The functions @code{mouse-position} and @code{set-mouse-position}
give access to the current position of the mouse.

@defun mouse-position
This function returns a description of the position of the mouse.  The
value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
and @var{y} are integers giving the position in characters relative to
the top left corner of the inside of @var{frame}.
@end defun

@defvar mouse-position-function
If non-@code{nil}, the value of this variable is a function for
@code{mouse-position} to call.  @code{mouse-position} calls this
function just before returning, with its normal return value as the
sole argument, and it returns whatever this function returns to it.

This abnormal hook exists for the benefit of packages like
@file{xt-mouse.el} that need to do mouse handling at the Lisp level.
@end defvar

@defun set-mouse-position frame x y
This function @dfn{warps the mouse} to position @var{x}, @var{y} in
frame @var{frame}.  The arguments @var{x} and @var{y} are integers,
giving the position in characters relative to the top left corner of the
inside of @var{frame}.  If @var{frame} is not visible, this function
does nothing.  The return value is not significant.
@end defun

@defun mouse-pixel-position
This function is like @code{mouse-position} except that it returns
coordinates in units of pixels rather than units of characters.
@end defun

@defun set-mouse-pixel-position frame x y
This function warps the mouse like @code{set-mouse-position} except that
@var{x} and @var{y} are in units of pixels rather than units of
characters.  These coordinates are not required to be within the frame.

If @var{frame} is not visible, this function does nothing.  The return
value is not significant.
@end defun

@need 3000

@node Pop-Up Menus
@section Pop-Up Menus

  When using a window system, a Lisp program can pop up a menu so that
the user can choose an alternative with the mouse.

@defun x-popup-menu position menu
This function displays a pop-up menu and returns an indication of
what selection the user makes.

The argument @var{position} specifies where on the screen to put the
top left corner of the menu.  It can be either a mouse button event
(which says to put the menu where the user actuated the button) or a
list of this form:

@example
((@var{xoffset} @var{yoffset}) @var{window})
@end example

@noindent
where @var{xoffset} and @var{yoffset} are coordinates, measured in
pixels, counting from the top left corner of @var{window}.  @var{window}
may be a window or a frame.

If @var{position} is @code{t}, it means to use the current mouse
position.  If @var{position} is @code{nil}, it means to precompute the
key binding equivalents for the keymaps specified in @var{menu},
without actually displaying or popping up the menu.

The argument @var{menu} says what to display in the menu.  It can be a
keymap or a list of keymaps (@pxref{Menu Keymaps}).  In this case, the
return value is the list of events corresponding to the user's choice.
(This list has more than one element if the choice occurred in a
submenu.)  Note that @code{x-popup-menu} does not actually execute the
command bound to that sequence of events.

Alternatively, @var{menu} can have the following form:

@example
(@var{title} @var{pane1} @var{pane2}...)
@end example

@noindent
where each pane is a list of form

@example
(@var{title} @var{item1} @var{item2}...)
@end example

Each item should normally be a cons cell @code{(@var{line} . @var{value})},
where @var{line} is a string, and @var{value} is the value to return if
that @var{line} is chosen.  An item can also be a string; this makes a
non-selectable line in the menu.

If the user gets rid of the menu without making a valid choice, for
instance by clicking the mouse away from a valid choice or by typing
keyboard input, then this normally results in a quit and
@code{x-popup-menu} does not return.  But if @var{position} is a mouse
button event (indicating that the user invoked the menu with the
mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
@end defun

  @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
if you could do the job with a prefix key defined with a menu keymap.
If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
a} can see the individual items in that menu and provide help for them.
If instead you implement the menu by defining a command that calls
@code{x-popup-menu}, the help facilities cannot know what happens inside
that command, so they cannot give any help for the menu's items.

  The menu bar mechanism, which lets you switch between submenus by
moving the mouse, cannot look within the definition of a command to see
that it calls @code{x-popup-menu}.  Therefore, if you try to implement a
submenu using @code{x-popup-menu}, it cannot work with the menu bar in
an integrated fashion.  This is why all menu bar submenus are
implemented with menu keymaps within the parent menu, and never with
@code{x-popup-menu}.  @xref{Menu Bar}.

  If you want a menu bar submenu to have contents that vary, you should
still use a menu keymap to implement it.  To make the contents vary, add
a hook function to @code{menu-bar-update-hook} to update the contents of
the menu keymap as necessary.

@node Dialog Boxes
@section Dialog Boxes
@cindex dialog boxes

  A dialog box is a variant of a pop-up menu---it looks a little
different, it always appears in the center of a frame, and it has just
one level and one or more buttons.  The main use of dialog boxes is
for asking questions that the user can answer with ``yes,'' ``no,''
and a few other alternatives.  With a single button, they can also
force the user to acknowledge important information.  The functions
@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
keyboard, when called from commands invoked by mouse clicks.

@defun x-popup-dialog position contents &optional header
This function displays a pop-up dialog box and returns an indication of
what selection the user makes.  The argument @var{contents} specifies
the alternatives to offer; it has this format:

@example
(@var{title} (@var{string} . @var{value})@dots{})
@end example

@noindent
which looks like the list that specifies a single pane for
@code{x-popup-menu}.

The return value is @var{value} from the chosen alternative.

As for @code{x-popup-menu}, an element of the list may be just a
string instead of a cons cell @code{(@var{string} . @var{value})}.
That makes a box that cannot be selected.

If @code{nil} appears in the list, it separates the left-hand items from
the right-hand items; items that precede the @code{nil} appear on the
left, and items that follow the @code{nil} appear on the right.  If you
don't include a @code{nil} in the list, then approximately half the
items appear on each side.

Dialog boxes always appear in the center of a frame; the argument
@var{position} specifies which frame.  The possible values are as in
@code{x-popup-menu}, but the precise coordinates or the individual
window don't matter; only the frame matters.

If @var{header} is non-@code{nil}, the frame title for the box is
@samp{Information}, otherwise it is @samp{Question}.  The former is used
for @code{message-box} (@pxref{message-box}).

In some configurations, Emacs cannot display a real dialog box; so
instead it displays the same items in a pop-up menu in the center of the
frame.

If the user gets rid of the dialog box without making a valid choice,
for instance using the window manager, then this produces a quit and
@code{x-popup-dialog} does not return.
@end defun

@node Pointer Shape
@section Pointer Shape
@cindex pointer shape
@cindex mouse pointer shape

  You can specify the mouse pointer style for particular text or
images using the @code{pointer} text property, and for images with the
@code{:pointer} and @code{:map} image properties.  The values you can
use in these properties are @code{text} (or @code{nil}), @code{arrow},
@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
@code{hourglass}.  @code{text} stands for the usual mouse pointer
style used over text.

  Over void parts of the window (parts that do not correspond to any
of the buffer contents), the mouse pointer usually uses the
@code{arrow} style, but you can specify a different style (one of
those above) by setting @code{void-text-area-pointer}.

@defvar void-text-area-pointer
This variable specifies the mouse pointer style for void text areas.
These include the areas after the end of a line or below the last line
in the buffer.  The default is to use the @code{arrow} (non-text)
pointer style.
@end defvar

1839 1840
  When using X, you can specify what the @code{text} pointer style
really looks like by setting the variable @code{x-pointer-shape}.
Glenn Morris's avatar
Glenn Morris committed
1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854

@defvar x-pointer-shape
This variable specifies the pointer shape to use ordinarily in the
Emacs frame, for the @code{text} pointer style.
@end defvar

@defvar x-sensitive-text-pointer-shape
This variable specifies the pointer shape to use when the mouse
is over mouse-sensitive text.
@end defvar

  These variables affect newly created frames.  They do not normally
affect existing frames; however, if you set the mouse color of a
frame, that also installs the current value of those two variables.
1855
@xref{Font and Color Parameters}.
Glenn Morris's avatar
Glenn Morris committed
1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950

  The values you can use, to specify either of these pointer shapes, are
defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
@key{RET} x-pointer @key{RET}} to see a list of them.

@node Window System Selections
@section Window System Selections
@cindex selection (for window systems)

The X server records a set of @dfn{selections} which permit transfer of
data between application programs.  The various selections are
distinguished by @dfn{selection types}, represented in Emacs by
symbols.  X clients including Emacs can read or set the selection for
any given type.

@deffn Command x-set-selection type data
This function sets a ``selection'' in the X server.  It takes two
arguments: a selection type @var{type}, and the value to assign to it,
@var{data}.  If @var{data} is @code{nil}, it means to clear out the
selection.  Otherwise, @var{data} may be a string, a symbol, an integer
(or a cons of two integers or list of two integers), an overlay, or a
cons of two markers pointing to the same buffer.  An overlay or a pair
of markers stands for text in the overlay or between the markers.

The argument @var{data} may also be a vector of valid non-vector
selection values.

Each possible @var{type} has its own selection value, which changes
independently.  The usual values of @var{type} are @code{PRIMARY},
@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
names, in accord with X Window System conventions.  If @var{type} is
@code{nil}, that stands for @code{PRIMARY}.

This function returns @var{data}.
@end deffn

@defun x-get-selection &optional type data-type
This function accesses selections set up by Emacs or by other X
clients.  It takes two optional arguments, @var{type} and
@var{data-type}.  The default for @var{type}, the selection type, is
@code{PRIMARY}.

The @var{data-type} argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into Lisp
data.  Meaningful values include @code{TEXT}, @code{STRING},
@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
@code{INTEGER}.  (These are symbols with upper-case names in accord
with X conventions.)  The default for @var{data-type} is
@code{STRING}.
@end defun

@cindex cut buffer
The X server also has a set of eight numbered @dfn{cut buffers} which can
store text or other data being moved between applications.  Cut buffers
are considered obsolete, but Emacs supports them for the sake of X
clients that still use them.  Cut buffers are numbered from 0 to 7.

@defun x-get-cut-buffer &optional n
This function returns the contents of cut buffer number @var{n}.
If omitted @var{n} defaults to 0.
@end defun

@defun x-set-cut-buffer string &optional push
@anchor{Definition of x-set-cut-buffer}
This function stores @var{string} into the first cut buffer (cut buffer
0).  If @var{push} is @code{nil}, only the first cut buffer is changed.
If @var{push} is non-@code{nil}, that says to move the values down
through the series of cut buffers, much like the way successive kills in
Emacs move down the kill ring.  In other words, the previous value of
the first cut buffer moves into the second cut buffer, and the second to
the third, and so on through all eight cut buffers.
@end defun

@defvar selection-coding-system
This variable specifies the coding system to use when reading and
writing selections or the clipboard.  @xref{Coding
Systems}.  The default is @code{compound-text-with-extensions}, which
converts to the text representation that X11 normally uses.
@end defvar

@cindex clipboard support (for MS-Windows)
When Emacs runs on MS-Windows, it does not implement X selections in
general, but it does support the clipboard.  @code{x-get-selection}
and @code{x-set-selection} on MS-Windows support the text data type
only; if the clipboard holds other types of data, Emacs treats the
clipboard as empty.

@defopt x-select-enable-clipboard
If this is non-@code{nil}, the Emacs yank functions consult the
clipboard before the primary selection, and the kill functions store in
the clipboard as well as the primary selection.  Otherwise they do not
access the clipboard at all.  The default is @code{nil} on most systems,
1951
but @code{t} on MS-Windows.
Glenn Morris's avatar
Glenn Morris committed
1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006
@end defopt

@node Drag and Drop
@section Drag and Drop

@vindex x-dnd-test-function
@vindex x-dnd-known-types
  When a user drags something from another application over Emacs, that other
application expects Emacs to tell it if Emacs can handle the data that is
dragged.  The variable @code{x-dnd-test-function} is used by Emacs to determine
what to reply.  The default value is @code{x-dnd-default-test-function}
which accepts drops if the type of the data to be dropped is present in
@code{x-dnd-known-types}.  You can customize @code{x-dnd-test-function} and/or
@code{x-dnd-known-types} if you want Emacs to accept or reject drops based
on some other criteria.

@vindex x-dnd-types-alist
  If you want to change the way Emacs handles drop of different types
or add a new type, customize @code{x-dnd-types-alist}.  This requires
detailed knowledge of what types other applications use for drag and
drop.

@vindex dnd-protocol-alist
  When an URL is dropped on Emacs it may be a file, but it may also be
another URL type (ftp, http, etc.).  Emacs first checks
@code{dnd-protocol-alist} to determine what to do with the URL.  If
there is no match there and if @code{browse-url-browser-function} is
an alist, Emacs looks for a match there.  If no match is found the
text for the URL is inserted.  If you want to alter Emacs behavior,
you can customize these variables.

@node Color Names
@section Color Names

@cindex color names
@cindex specify color
@cindex numerical RGB color specification
  A color name is text (usually in a string) that specifies a color.
Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
are allowed; use @kbd{M-x list-colors-display} to see a list of
defined names.  You can also specify colors numerically in forms such
as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
@var{r} specifies the red level, @var{g} specifies the green level,
and @var{b} specifies the blue level.  You can use either one, two,
three, or four hex digits for @var{r}; then you must use the same
number of hex digits for all @var{g} and @var{b} as well, making
either 3, 6, 9 or 12 hex digits in all.  (See the documentation of the
X Window System for more details about numerical RGB specification of
colors.)

  These functions provide a way to determine which color names are
valid, and what they look like.  In some cases, the value depends on the
@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
meaning of the term ``selected frame.''

2007 2008 2009
  To read user input of color names with completion, use
@code{read-color} (@pxref{High-Level Completion, read-color}).

Glenn Morris's avatar
Glenn Morris committed
2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310
@defun color-defined-p color &optional frame
This function reports whether a color name is meaningful.  It returns
@code{t} if so; otherwise, @code{nil}.  The argument @var{frame} says
which frame's display to ask about; if @var{frame} is omitted or
@code{nil}, the selected frame is used.

Note that this does not tell you whether the display you are using